Annotation of html5/spec/the-ruby-element.html, revision 1.195
1.88 mike 1: <!DOCTYPE html>
1.159 sruby 2: <html lang="en-US-x-Hixie"><head><title>4.6.20 The ruby element — HTML5</title><style type="text/css">
1.1 mike 3: pre { margin-left: 2em; white-space: pre-wrap; }
4: h2 { margin: 3em 0 1em 0; }
5: h3 { margin: 2.5em 0 1em 0; }
6: h4 { margin: 2.5em 0 0.75em 0; }
7: h5, h6 { margin: 2.5em 0 1em; }
8: h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
9: h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
10: p { margin: 1em 0; }
11: hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
12: dl, dd { margin-top: 0; margin-bottom: 0; }
13: dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
14: dt + dt { margin-top: 0; }
15: dd dt { margin-top: 0.25em; margin-bottom: 0; }
16: dd p { margin-top: 0; }
17: dd dl + p { margin-top: 1em; }
18: dd table + p { margin-top: 1em; }
19: p + * > li, dd li { margin: 1em 0; }
20: dt, dfn { font-weight: bold; font-style: normal; }
21: i, em { font-style: italic; }
22: dt dfn { font-style: italic; }
23: pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
24: pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
25: pre em { font-weight: bolder; font-style: normal; }
26: @media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
27: var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
28: table { border-collapse: collapse; border-style: hidden hidden none hidden; }
29: table thead, table tbody { border-bottom: solid; }
30: table tbody th:first-child { border-left: solid; }
31: table tbody th { text-align: left; }
32: table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
33: blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
34:
35: .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
36: .matrix, .matrix td { border: none; text-align: right; }
37: .matrix { margin-left: 2em; }
38: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
39: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
40: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
41:
42: .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
43: img.extra, p.overview { float: right; }
44: pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; position: relative; }
45: pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
46: pre.idl::before { content: "IDL"; font: bold small sans-serif; padding: 0.5em; background: white; position: absolute; top: 0; margin: -1px 0 0 -4em; width: 1.5em; border: thin solid; border-radius: 0 0 0 0.5em }
47: pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
48: pre.css:first-line { color: #AAAA50; }
49: dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
50: hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
51: dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
52: dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
53: dl.domintro dd p { margin: 0.5em 0; }
54: dl.domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: black; font-style: italic; border: solid 2px; background: white; padding: 0 0.25em; }
55: dl.switch { padding-left: 2em; }
56: dl.switch > dt { text-indent: -1.5em; }
57: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
58: dl.triple { padding: 0 0 0 1em; }
59: dl.triple dt, dl.triple dd { margin: 0; display: inline }
60: dl.triple dt:after { content: ':'; }
61: dl.triple dd:after { content: '\A'; white-space: pre; }
62: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
63: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
64: a .diff-new { border-bottom: 1px blue solid; }
65:
1.181 sruby 66: figure.diagrams { border: double black; background: white; padding: 1em; }
67: figure.diagrams img { display: block; margin: 1em auto; }
68:
1.1 mike 69: h2 { page-break-before: always; }
70: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
71: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
72:
73: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
74: li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
75:
76: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
77: div.head p { margin: 0; }
78: div.head h1 { margin: 0; }
79: div.head .logo { float: right; margin: 0 1em; }
80: div.head .logo img { border: none } /* remove border from top image */
81: div.head dl { margin: 1em 0; }
82: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
83:
84: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
85: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
86: body > .toc > li > * { margin-bottom: 0.5em; }
87: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
88: .toc, .toc li { list-style: none; }
89:
90: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
91: .brief li { margin: 0; padding: 0; }
92: .brief li p { margin: 0; padding: 0; }
93:
94: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
95: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
96: .category-list li { display: inline; }
97: .category-list li:not(:last-child)::after { content: ', '; }
98: .category-list li > span, .category-list li > a { text-transform: lowercase; }
99: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
100:
101: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
102: .XXX > :first-child { margin-top: 0; }
103: p .XXX { line-height: 3em; }
104: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
105: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
106: .annotation :link, .annotation :visited { color: inherit; }
107: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
108: .annotation span { border: none ! important; }
109: .note { color: green; background: transparent; font-family: sans-serif; }
110: .warning { color: red; background: transparent; }
111: .note, .warning { font-weight: bolder; font-style: italic; }
112: .note em, .warning em, .note i, .warning i { font-style: normal; }
113: p.note, div.note { padding: 0.5em 2em; }
114: span.note { padding: 0 2em; }
115: .note p:first-child, .warning p:first-child { margin-top: 0; }
116: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
117: .warning:before { font-style: normal; }
118: p.note:before { content: 'Note: '; }
119: p.warning:before { content: '\26A0 Warning! '; }
120:
121: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
122: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
123: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
124: .bookkeeping dt { margin: 0.5em 2em 0; }
125: .bookkeeping dd { margin: 0 3em 0.5em; }
126:
127: h4 { position: relative; z-index: 3; }
128: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
129: .element {
130: background: #EEEEFF;
131: color: black;
132: margin: 0 0 1em 0.15em;
133: padding: 0 1em 0.25em 0.75em;
134: border-left: solid #9999FF 0.25em;
135: position: relative;
136: z-index: 1;
137: }
138: .element:before {
139: position: absolute;
140: z-index: 2;
141: top: 0;
142: left: -1.15em;
143: height: 2em;
144: width: 0.9em;
145: background: #EEEEFF;
146: content: ' ';
147: border-style: none none solid solid;
148: border-color: #9999FF;
149: border-width: 0.25em;
150: }
151:
152: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
153: td > .example:only-child { margin: 0 0 0 0.1em; }
154:
155: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
156: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
157: ul.domTree li li { list-style: none; }
158: ul.domTree li:first-child::before { position: absolute; top: 0; height: 0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
159: ul.domTree li:not(:last-child)::after { position: absolute; top: 0; bottom: -0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
160: ul.domTree span { font-style: italic; font-family: serif; }
161: ul.domTree .t1 code { color: purple; font-weight: bold; }
162: ul.domTree .t2 { font-style: normal; font-family: monospace; }
163: ul.domTree .t2 .name { color: black; font-weight: bold; }
164: ul.domTree .t2 .value { color: blue; font-weight: normal; }
165: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
166: ul.domTree .t7 code, .domTree .t8 code { color: green; }
167: ul.domTree .t10 code { color: teal; }
168:
169: body.dfnEnabled dfn { cursor: pointer; }
170: .dfnPanel {
171: display: inline;
172: position: absolute;
173: z-index: 10;
174: height: auto;
175: width: auto;
176: padding: 0.5em 0.75em;
177: font: small sans-serif, Droid Sans Fallback;
178: background: #DDDDDD;
179: color: black;
180: border: outset 0.2em;
181: }
182: .dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
183: .dfnPanel :link, .dfnPanel :visited { color: black; }
184: .dfnPanel p { font-weight: bolder; }
185: .dfnPanel * + p { margin-top: 0.25em; }
186: .dfnPanel li { list-style-position: inside; }
187:
188: #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
189: #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
190: #configUI p label { display: block; }
191: #configUI #updateUI, #configUI .loginUI { text-align: center; }
192: #configUI input[type=button] { display: block; margin: auto; }
193:
194: fieldset { margin: 1em; padding: 0.5em 1em; }
195: fieldset > legend + * { margin-top: 0; }
196: fieldset > :last-child { margin-bottom: 0; }
197: fieldset p { margin: 0.5em 0; }
198:
1.159 sruby 199: </style><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css"><style type="text/css">
1.1 mike 200:
201: .applies thead th > * { display: block; }
202: .applies thead code { display: block; }
203: .applies tbody th { whitespace: nowrap; }
204: .applies td { text-align: center; }
205: .applies .yes { background: yellow; }
206:
207: .matrix, .matrix td { border: hidden; text-align: right; }
208: .matrix { margin-left: 2em; }
209:
210: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
211: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
212: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
213:
214: td.eg { border-width: thin; text-align: center; }
215:
216: #table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
217: #table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
218: #table-example-1 caption { padding-bottom: 0.5em; }
219: #table-example-1 thead, #table-example-1 tbody { border: none; }
220: #table-example-1 th, #table-example-1 td { border: solid thin; }
221: #table-example-1 th { font-weight: normal; }
222: #table-example-1 td { border-style: none solid; vertical-align: top; }
223: #table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
224: #table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
225: #table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
226: #table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
227: #table-example-1 tbody td:first-child::after { content: leader(". "); }
228: #table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
229: #table-example-1 tbody td:first-child + td { width: 10em; }
230: #table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
231: #table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
232:
233: .apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
234: .apple-table-examples * { font-family: "Times", serif; }
235: .apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
236: .apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
237: .apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
238: .apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
239: .apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
240: .apple-table-examples td { text-align: right; vertical-align: top; }
241: .apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
242: .apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
243: .apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
244: .apple-table-examples sup { line-height: 0; }
245:
246: .details-example img { vertical-align: top; }
247:
248: #base64-table {
249: white-space: nowrap;
250: font-size: 0.6em;
251: column-width: 6em;
252: column-count: 5;
253: column-gap: 1em;
254: -moz-column-width: 6em;
255: -moz-column-count: 5;
256: -moz-column-gap: 1em;
257: -webkit-column-width: 6em;
258: -webkit-column-count: 5;
259: -webkit-column-gap: 1em;
260: }
261: #base64-table thead { display: none; }
262: #base64-table * { border: none; }
263: #base64-table tbody td:first-child:after { content: ':'; }
264: #base64-table tbody td:last-child { text-align: right; }
265:
266: #named-character-references-table {
267: white-space: nowrap;
268: font-size: 0.6em;
269: column-width: 30em;
270: column-gap: 1em;
271: -moz-column-width: 30em;
272: -moz-column-gap: 1em;
273: -webkit-column-width: 30em;
274: -webkit-column-gap: 1em;
275: }
276: #named-character-references-table > table > tbody > tr > td:first-child + td,
277: #named-character-references-table > table > tbody > tr > td:last-child { text-align: center; }
278: #named-character-references-table > table > tbody > tr > td:last-child:hover > span { position: absolute; top: auto; left: auto; margin-left: 0.5em; line-height: 1.2; font-size: 5em; border: outset; padding: 0.25em 0.5em; background: white; width: 1.25em; height: auto; text-align: center; }
279: #named-character-references-table > table > tbody > tr#entity-CounterClockwiseContourIntegral > td:first-child { font-size: 0.5em; }
280:
281: .glyph.control { color: red; }
282:
283: @font-face {
284: font-family: 'Essays1743';
1.179 sruby 285: src: url('../fonts/Essays1743.ttf');
1.1 mike 286: }
287: @font-face {
288: font-family: 'Essays1743';
289: font-weight: bold;
1.179 sruby 290: src: url('../fonts/Essays1743-Bold.ttf');
1.1 mike 291: }
292: @font-face {
293: font-family: 'Essays1743';
294: font-style: italic;
1.179 sruby 295: src: url('../fonts/Essays1743-Italic.ttf');
1.1 mike 296: }
297: @font-face {
298: font-family: 'Essays1743';
299: font-style: italic;
300: font-weight: bold;
1.179 sruby 301: src: url('../fonts/Essays1743-BoldItalic.ttf');
1.1 mike 302: }
303:
1.159 sruby 304: </style><link href="data:text/css," id="complete" rel="stylesheet" title="Complete specification"><link href="data:text/css,.impl%20%7B%20display:%20none;%20%7D%0Ahtml%20%7B%20border:%20solid%20yellow;%20%7D%20.domintro:before%20%7B%20display:%20none;%20%7D" id="author" rel="alternate stylesheet" title="Author documentation only"><link href="data:text/css,.impl%20%7B%20background:%20%23FFEEEE;%20%7D%20.domintro:before%20%7B%20background:%20%23FFEEEE;%20%7D" id="highlight" rel="alternate stylesheet" title="Highlight implementation requirements"><script>
1.1 mike 305: function getCookie(name) {
306: var params = location.search.substr(1).split("&");
307: for (var index = 0; index < params.length; index++) {
308: if (params[index] == name)
309: return "1";
310: var data = params[index].split("=");
311: if (data[0] == name)
312: return unescape(data[1]);
313: }
314: var cookies = document.cookie.split("; ");
315: for (var index = 0; index < cookies.length; index++) {
316: var data = cookies[index].split("=");
317: if (data[0] == name)
318: return unescape(data[1]);
319: }
320: return null;
321: }
1.195 ! mike 322: </script>
! 323: <script src="link-fixup.js"></script>
! 324: <link href="the-mark-element.html" title="4.6.19 The mark element" rel="prev">
! 325: <link href="index.html#contents" title="Table of contents" rel="contents">
1.1 mike 326: <link href="the-rt-element.html" title="4.6.21 The rt element" rel="next">
1.22 mike 327: </head><body onload="fixBrokenLink();" class="split chapter"><div class="head" id="head">
1.1 mike 328: <p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
329:
330: <h1>HTML5</h1>
1.195 ! mike 331: <h2 class="no-num no-toc" id="a-vocabulary-and-associated-apis-for-html-and-xhtml">A vocabulary and associated APIs for HTML and XHTML</h2><p>This is revision 1.157.</p>
! 332:
1.194 sruby 333: <h2 class="no-num no-toc" id="editor's-draft-date-1-january-1970">Editor's Draft 10 October 2012</h2>
1.85 mike 334: </div>
1.195 ! mike 335: <nav class="prev_next">
1.1 mike 336: <a href="the-mark-element.html">← 4.6.19 The mark element</a> –
1.195 ! mike 337: <a href="index.html#contents">Table of contents</a> –
1.1 mike 338: <a href="the-rt-element.html">4.6.21 The rt element →</a>
1.195 ! mike 339: </nav>
1.1 mike 340:
1.85 mike 341: <h4 id="the-ruby-element"><span class="secno">4.6.20 </span>The <dfn><code>ruby</code></dfn> element</h4>
342:
343: <dl class="element"><dt><a href="element-definitions.html#element-dfn-categories" title="element-dfn-categories">Categories</a>:</dt>
1.159 sruby 344: <dd><a href="content-models.html#flow-content-1">Flow content</a>.</dd>
345: <dd><a href="content-models.html#phrasing-content-1">Phrasing content</a>.</dd>
346: <dd><a href="content-models.html#palpable-content-0">Palpable content</a>.</dd>
1.25 mike 347: <dt><a href="element-definitions.html#element-dfn-contexts" title="element-dfn-contexts">Contexts in which this element can be used</a>:</dt>
1.159 sruby 348: <dd>Where <a href="content-models.html#phrasing-content-1">phrasing content</a> is expected.</dd>
1.25 mike 349: <dt><a href="element-definitions.html#element-dfn-content-model" title="element-dfn-content-model">Content model</a>:</dt>
1.178 sruby 350: <dd>See prose.</dd>
1.25 mike 351: <dt><a href="element-definitions.html#element-dfn-attributes" title="element-dfn-attributes">Content attributes</a>:</dt>
1.1 mike 352: <dd><a href="global-attributes.html#global-attributes">Global attributes</a></dd>
1.159 sruby 353: <dt><a href="element-definitions.html#element-dfn-dom" title="element-dfn-dom">DOM interface</a>:</dt><!--TOPIC:DOM APIs-->
1.1 mike 354: <dd>Uses <code><a href="elements.html#htmlelement">HTMLElement</a></code>.</dd>
1.159 sruby 355: </dl><!--TOPIC:HTML--><p>The <code><a href="#the-ruby-element">ruby</a></code> element allows one or more spans of
1.1 mike 356: phrasing content to be marked with ruby annotations. Ruby
357: annotations are short runs of text presented alongside base text,
358: primarily used in East Asian typography as a guide for
359: pronunciation or to include other annotations. In Japanese, this
1.85 mike 360: form of typography is also known as <i>furigana</i>.</p>
361:
1.178 sruby 362: <p>The content model of <code><a href="#the-ruby-element">ruby</a></code> elements consists of one
363: or more of the following sequences:</p>
1.85 mike 364:
1.178 sruby 365: <ol class="brief"><li>One or the other of the following:
366: <ul class="brief"><li><a href="content-models.html#phrasing-content-1">Phrasing content</a>, but with no <code><a href="#the-ruby-element">ruby</a></code> elements and with no <code><a href="#the-ruby-element">ruby</a></code> element descendants
367: </li><li>A single <code><a href="#the-ruby-element">ruby</a></code> element, but with no further <code><a href="#the-ruby-element">ruby</a></code> element descendants
368: </li></ul></li><li>One or the other of the following:
369: <ul class="brief"><li>One or more <code><a href="the-rt-element.html#the-rt-element">rt</a></code> elements
370: </li><li>An <code><a href="the-rp-element.html#the-rp-element">rp</a></code> element followed by one or more <code><a href="the-rt-element.html#the-rt-element">rt</a></code> elements, each of which is itself followed by an <code><a href="the-rp-element.html#the-rp-element">rp</a></code> element
371: </li></ul></li></ol><!-- ( ( phrasing-content | <ruby> ) ( <rt>+ | <rp> ( <rt> <rp> )+ ) )+ // with further ruby descendant restrictions --><p>The <code><a href="#the-ruby-element">ruby</a></code> and <code><a href="the-rt-element.html#the-rt-element">rt</a></code> elements can be used
372: for a variety of kinds of annotations, including in particular those
373: described below. For more details on Japanese Ruby in particular,
374: and how to render Ruby for Japanese, see <cite>Requirements for
1.191 sruby 375: Japanese Text Layout</cite>. <a href="textFieldSelection.html#refsJLREQ">[JLREQ]</a></p>
1.178 sruby 376:
377: <p class="note">At the time of writing, CSS does not yet provide a
378: way to fully control the rendering of the HTML <code><a href="#the-ruby-element">ruby</a></code>
379: element. It is hoped that CSS will be extended to support the styles
380: described below in due course.</p>
381:
382: <!-- examples in the following list are mostly based on those in http://www.w3.org/International/datespace/2010/02/jlreq-examples/ -->
383:
384: <dl><dt>Mono-ruby for individual base characters
385:
386: </dt><dd>
387:
388: <p>One or more hiragana or katakana characters (the ruby
389: annotation) are placed with each ideographic character (the base
390: text). This is used to provide readings of kanji characters.
391:
392: </p><div class="example"> <!-- B as in BASE -->
393: <pre><ruby>B<rt>annotation</ruby></pre>
394: </div>
395:
396: <div class="example">
397: <p>In this example, notice how each annotation corresponds to a single base character.
398: </p><pre><ruby>君<rt>くん</ruby><ruby>子<rt>し</ruby>は<ruby>和<rt>わ</ruby>して<ruby>同<rt>どう</ruby>ぜず。</pre>
399: <p lang="ja"><ruby>君<rt>くん</rt></ruby><ruby>子<rt>し</rt></ruby>は<ruby>和<rt>わ</rt></ruby>して<ruby>同<rt>どう</rt></ruby>ぜず。
400: </p></div>
401:
402: </dd>
403:
404:
405: <dt>Mono-ruby for compound words (jukugo)
406:
407: </dt><dd>
408:
409: <p>This is similar to the previous case: each ideographic
410: character in the compound word (the base text) has its reading
411: given in hiragana or katakana characters (the ruby annotation).
412: The difference is that the base text segments form a compound word
413: rather than being separate from each other.
414:
415: </p><div class="example"> <!-- B as in BASE -->
416: <pre><ruby>B<rt>annotation</rt>B<rt>annotation</ruby></pre>
417: </div>
418:
419: <div class="example">
420: <p>In this example, notice again how each annotation corresponds to a single base character. In this example, each compound word (jukugo) corresponds to a single <code><a href="#the-ruby-element">ruby</a></code> element.</p>
421: <p>The rendering here is expected to be that each annotation be placed over (or next to, in vertical text) the corresponding base character, with the annotations not overhanging any of the adjacent characters.</p>
422: <pre><ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する</pre>
423: <p lang="ja"><ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する
424:
425: </p></div>
426:
427: </dd>
428:
429:
430: <dt>Jukugo-ruby
431:
432: </dt><dd>
433:
434: <p>This is semantically identical to the previous case (each
435: individual ideographic character in the base compound word has its
436: reading given in an annotation in hiragana or katakana
437: characters), but the rendering is the more complicated Jukugo Ruby
438: rendering.
439:
440: </p><div class="example">
441: <p>This is the same example as above for mono-ruby for compound words. The different rendering is expected to be achieved using different styling (e.g. in CSS), and is not shown here.</p>
442: <pre><ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する</pre>
443: <!-- Once CSS is updated to describe this, invoke the CSS and unhide this -->
444: <!--
445: <p lang=ja><ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する
446: -->
447: </div>
448:
449: <p class="note">For more details on <a href="http://www.w3.org/TR/jlreq/#positioning_of_jukugoruby">Jukugo
450: Ruby rendering</a>, see Appendix F in the <cite>Requirements for
1.191 sruby 451: Japanese Text Layout</cite>. <a href="textFieldSelection.html#refsJLREQ">[JLREQ]</a></p>
1.178 sruby 452:
453: </dd>
454:
455:
456: <dt>Group ruby for describing meanings
457:
458: </dt><dd>
459:
460: <p>The annotation describes the meaning of the base text, rather
461: than (or in addition to) the pronunciation. As such, both the base
462: text and the annotation can be multiple characters long.
463:
464: </p><div class="example">
465: <pre><ruby>BASE<rt>annotation</ruby></pre>
466: </div>
467:
468: <div class="example">
469: <p>Here a compound ideographic word has its corresponding katakana given as an annotation.
470: </p><pre><ruby>境界面<rt>インターフェース</ruby></pre>
471: <p lang="ja"><ruby>境界面<rt>インターフェース</rt></ruby></p></div>
472:
473: <div class="example">
474: <p>Here a compound ideographic word has its translation in English provided as an annotation.
475: </p><pre><ruby lang="ja">編集者<rt lang="en">editor</ruby></pre>
476: <p><ruby lang="ja">編集者<rt lang="en">editor</rt></ruby></p></div>
477:
478: </dd>
479:
480:
481: <dt>Group ruby for Jukuji readings
482:
483: </dt><dd>
484:
485: <p>A phonetic reading that corresponds to multiple base
486: characters, because a one-to-one mapping would be difficult. (In
487: English, the words "Colonel" and "Lieutenant" are examples of
488: words where a direct mapping of pronunciation to individual
489: letters is, in some dialects, rather unclear.)
490:
491: </p><div class="example">
492: <p>In this example, the name of a species of flowers has a phonetic reading provided using group ruby:
493: </p><pre><ruby>紫陽花<rt>あじさい</ruby></pre>
494: <p lang="ja"><ruby>紫陽花<rt>あじさい</rt></ruby></p></div>
495:
496: </dd>
497:
498:
499: <dt>Text with both phonetic and semantic annotations (double-sided ruby)
500:
501: </dt><dd>
502:
503: <p>Sometimes, ruby styles described above are combined.
504:
505: </p><div class="example">
506: <pre><ruby>BASE<rt>annotation 1<rt>annotation 2</ruby></pre>
507: </div>
508:
509: <div class="example">
510: <pre><ruby><ruby>B<rt>a</rt>A<rt>n</rt>S<rt>t</rt>E<rt>n</rt></ruby><rt>annotation</ruby></pre>
511: </div>
512:
513: <div class="example">
514: <p>Here both a phonetic reading and the meaning are given in ruby annotations. The annotation on the nested <code><a href="#the-ruby-element">ruby</a></code> element gives a mono-ruby phonetic annotation for each base character, while the annotation in the <code><a href="the-rt-element.html#the-rt-element">rt</a></code> element that is a child of the outer <code><a href="#the-ruby-element">ruby</a></code> element gives the meaning using hiragana.
515: </p><pre><ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt>たつみ</rt></ruby>の方角</pre>
516: <p lang="ja"><ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt>たつみ</rt></ruby>の方角
517: </p></div>
518:
519: <div class="example">
520: <p>This is the same example, but the meaning is given in English instead of Japanese:
521: </p><pre><ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt lang=en>Southeast</rt></ruby>の方角</pre>
522: <p lang="ja"><ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt lang="en">Southeast</rt></ruby>の方角
523: </p></div>
524:
525: </dd>
526:
527: </dl><hr><p>Within a <code><a href="#the-ruby-element">ruby</a></code> element that does not have a
528: <code><a href="#the-ruby-element">ruby</a></code> element ancestor, content is segmented and
529: segments are placed into three categories: base text segments,
530: annotation segments, and ignored segments. Ignored segments do not
531: form part of the document's semantics (they consist of some
532: <a href="content-models.html#inter-element-whitespace">inter-element whitespace</a> and <code><a href="the-rp-element.html#the-rp-element">rp</a></code> elements,
533: the latter of which are used for legacy user agents that do not
534: support ruby at all). Base text segments can overlap (with a limit
535: of two segments overlapping any one position in the DOM, and with
536: any segment having an earlier start point than an overlapping
537: segment also having an equal or later end point, and any segment
538: have a later end point than an overlapping segment also having an
539: equal or earlier start point<!-- if anyone can find a better way of
540: phrasing this parenthetical, do let me know! -->). Annotation
541: segments correspond to <code><a href="the-rt-element.html#the-rt-element">rt</a></code> elements. Each annotation
542: segment can be associated with a base text segment, and each base
543: text segment can have annotation segments associated with it. (In a
544: conforming document, each base text segment is associated with at
545: least one annotation segment, and each annotation segment is
546: associated with one base text segment.) A <code><a href="#the-ruby-element">ruby</a></code> element
1.191 sruby 547: <a href="textFieldSelection.html#represents">represents</a> the union of the segments of base text it
1.178 sruby 548: contains, along with the mapping from those base text segments to
549: annotation segments. Segments are described in terms of DOM ranges;
1.191 sruby 550: annotation segment ranges always consist of exactly one element. <a href="textFieldSelection.html#refsDOMCORE">[DOMCORE]</a></p>
1.178 sruby 551:
552: <p>At any particular time, the segmentation and categorisation of
553: content of a <code><a href="#the-ruby-element">ruby</a></code> element is the result that would be
554: obtained from running the following algorithm:</p>
555:
556: <ol><li><p>Let <var title="">base text segments</var> be an empty list
557: of base text segments, each potentially with a list of base text
558: subsegments.</p></li>
559:
560: <li><p>Let <var title="">annotation segments</var> be an empty list
561: of annotation segments, each potentially being associated with a
562: base text segment or subsegment.</p></li>
563:
564: <li><p>Let <var title="">root</var> be the <code><a href="#the-ruby-element">ruby</a></code>
565: element for which the algorithm is being run.</p></li>
566:
567: <li><p>If <var title="">root</var> has a <code><a href="#the-ruby-element">ruby</a></code> element
568: ancestor, then jump to the step labeled <i>end</i>.</p></li>
569:
570: <li><p>Let <var title="">current parent</var> be <var title="">root</var>.</p></li>
571:
572: <li><p>Let <var title="">index</var> be 0.</p></li>
573:
574: <li><p>Let <var title="">start index</var> be null.</p></li>
575:
576: <li><p>Let <var title="">parent start index</var> be null.</p></li>
577:
578: <li><p>Let <var title="">current base text</var> be null.</p></li>
579:
580:
581: <!-- This is spaghetti code. If someone can work out a way to
582: phrase this that is as unambiguous but maps more cleanly to
583: structured code, please let me know. -->
584:
585:
586: <li><p><i>Start mode</i>: If <var title="">index</var> is equal to
587: or greater than the number of child nodes in <var title="">current
588: parent</var>, then jump to the step labeled <i>end mode</i>.</p>
589:
590: </li><li><p>If the <var title="">index</var>th node in <var title="">current parent</var> is an <code><a href="the-rt-element.html#the-rt-element">rt</a></code> or
591: <code><a href="the-rp-element.html#the-rp-element">rp</a></code> element, jump to the step labeled <i>annotation
592: mode</i>.</p></li>
593:
594: <!-- if we get here then the first node in a ruby element or after
595: an <rt> or <rp> is something we want in a base text -->
596:
597: <li><p>Set <var title="">start index</var> to the value of <var title="">index</var>.</p></li>
598:
599: <li><p><i>Base mode</i>: If the <var title="">index</var>th node in
600: <var title="">current parent</var> is a <code><a href="#the-ruby-element">ruby</a></code> element,
601: and if <var title="">current parent</var> is the same element as
602: <var title="">root</var>, then <a href="#push-a-ruby-level">push a ruby level</a> and
603: then jump to the step labeled <i>start mode</i>.</p></li>
604:
605: <li><p>If the <var title="">index</var>th node in <var title="">current parent</var> is an <code><a href="the-rt-element.html#the-rt-element">rt</a></code> or
606: <code><a href="the-rp-element.html#the-rp-element">rp</a></code> element, then <a href="#set-the-current-base-text">set the current base
607: text</a> and then jump to the step labeled <i>annotation
608: mode</i>.</p></li>
609:
610: <li><p>Increment <var title="">index</var> by one.</p></li>
611:
612: <li><p><i>Base mode post-increment</i>: If <var title="">index</var> is equal to or greater than the number of
613: child nodes in <var title="">current parent</var>, then jump to the
614: step labeled <i>end mode</i>.</p></li>
615:
616: <li><p>Jump back to the step labeled <i>base mode</i>.</p></li>
617:
618:
619: <li><p><i>Annotation mode</i>: If the <var title="">index</var>th
620: node in <var title="">current parent</var> is an <code><a href="the-rt-element.html#the-rt-element">rt</a></code>
621: element, then <a href="#push-a-ruby-annotation">push a ruby annotation</a> and jump to the
622: step labeled <i>annotation mode increment</i>.</p></li>
623:
624: <li><p>If the <var title="">index</var>th node in <var title="">current parent</var> is an <code><a href="the-rp-element.html#the-rp-element">rp</a></code> element, jump
625: to the step labeled <i>annotation mode increment</i>.</p></li>
626:
627: <li><p>If the <var title="">index</var>th node in <var title="">current parent</var> is not a <code><a href="infrastructure.html#text-0">Text</a></code> node, or
628: is a <code><a href="infrastructure.html#text-0">Text</a></code> node that is not <a href="content-models.html#inter-element-whitespace">inter-element
629: whitespace</a>, then jump to the step labeled <i>base
630: mode</i>.</p></li>
631:
632: <!-- index points at whitespace -->
633:
634: <li><p><i>Annotation mode increment</i>: Let <var title="">lookahead index</var> be <var title="">index</var> plus
635: one.</p></li>
636:
637: <li><p><i>Annotation mode white-space skipper</i>: If <var title="">lookahead index</var> is equal to the number of child
638: nodes in <var title="">current parent</var> then jump to the step
639: labeled <i>end mode</i>.</p></li>
640:
641: <li><p>If the <var title="">lookahead index</var>th node in <var title="">current parent</var> is an <code><a href="the-rt-element.html#the-rt-element">rt</a></code> element or an
642: <code><a href="the-rp-element.html#the-rp-element">rp</a></code> element, then set <var title="">index</var> to <var title="">lookahead index</var> and jump to the step labeled
643: <i>annotation mode</i>.</p></li>
644:
645: <li><p>If the <var title="">lookahead index</var>th node in <var title="">current parent</var> is not a <code><a href="infrastructure.html#text-0">Text</a></code> node, or
646: is a <code><a href="infrastructure.html#text-0">Text</a></code> node that is not <a href="content-models.html#inter-element-whitespace">inter-element
647: whitespace</a>, then jump to the step labeled <i>base mode</i>
648: (without further incrementing <var title="">index</var>, so the
649: <a href="content-models.html#inter-element-whitespace">inter-element whitespace</a> seen so far becomes part of
650: the next base text segment).</p></li>
651:
652: <li><p>Increment <var title="">lookahead index</var> by
653: one.</p></li>
654:
655: <li><p>Jump to the step labeled <i>annotation mode white-space
656: skipper</i>.</p></li>
657:
658:
659: <li><p><i>End mode</i>: If <var title="">current parent</var> is
660: not the same element as <var title="">root</var>, then <a href="#pop-a-ruby-level">pop a
661: ruby level</a> and jump to the step labeled <i>base mode
662: post-increment</i>.</p></li>
663:
664: <li><p><i>End</i>: Return <var title="">base text segments</var>
665: and <var title="">annotation segments</var>. Any content of the
666: <code><a href="#the-ruby-element">ruby</a></code> element not described by segments in either of
667: thost lists is implicitly in an <i>ignored segment</i>.</p></li>
668:
669: </ol><p>When the steps above say to <dfn id="set-the-current-base-text">set the current base text</dfn>,
670: it means to run the following steps at that point in the
671: algorithm:</p>
672:
673: <ol><li><p>Let <var title="">text range</var> a DOM range whose <a href="infrastructure.html#concept-range-start" title="concept-range-start">start</a> is the <a href="infrastructure.html#concept-range-bp" title="concept-range-bp">boundary point</a> (<var title="">current parent</var>, <var title="">start index</var>) and
674: whose <a href="infrastructure.html#concept-range-end" title="concept-range-end">end</a> is the <a href="infrastructure.html#concept-range-bp" title="concept-range-bp">boundary point</a> (<var title="">current parent</var>, <var title="">index</var>).</p></li>
675:
676: <li><p>Let <var title="">new text segment</var> be a base text
677: segment described by the range <var title="">annotation
678: range</var>.</p>
679:
680: </li><li><p>Add <var title="">new text segment</var> to <var title="">base text segments</var>.</p></li>
681:
682: <li><p>Let <var title="">current base text</var> be <var title="">new text segment</var>.</p></li>
683:
684: <li><p>Let <var title="">start index</var> be null.</p></li>
685:
686: </ol><p>When the steps above say to <dfn id="push-a-ruby-level">push a ruby level</dfn>, it
687: means to run the following steps at that point in the algorithm:</p>
688:
689: <ol><li><p>Let <var title="">current parent</var> be the <var title="">index</var>th node in <var title="">current
690: parent</var>.</p></li>
691:
692: <li><p>Let <var title="">index</var> be 0.</p></li>
693:
694: <li><p>Set <var title="">saved start index</var> to the value of
695: <var title="">start index</var>.</p></li>
696:
697: <li><p>Let <var title="">start index</var> be null.</p></li>
698:
699: </ol><p>When the steps above say to <dfn id="pop-a-ruby-level">pop a ruby level</dfn>, it means
700: to run the following steps at that point in the algorithm:</p>
701:
702: <ol><li><p>Let <var title="">index</var> be the position of <var title="">current parent</var> in <var title="">root</var>.</p></li>
703:
704: <li><p>Let <var title="">current parent</var> be <var title="">root</var>.</p></li>
705:
706: <li><p>Increment <var title="">index</var> by one.</p></li>
707:
708: <li><p>Set <var title="">start index</var> to the value of
709: <var title="">saved start index</var>.</p></li>
710:
711: <li><p>Let <var title="">saved start index</var> be null.</p></li>
712:
713: </ol><p>When the steps above say to <dfn id="push-a-ruby-annotation">push a ruby annotation</dfn>, it
714: means to run the following steps at that point in the algorithm:</p>
715:
716: <ol><li><p>Let <var title="">rt</var> be the <code><a href="the-rt-element.html#the-rt-element">rt</a></code> element
717: that is the <var title="">index</var>th node of <var title="">current parent</var>.</p></li>
718:
719: <li><p>Let <var title="">annotation range</var> a DOM range whose
720: <a href="infrastructure.html#concept-range-start" title="concept-range-start">start</a> is the <a href="infrastructure.html#concept-range-bp" title="concept-range-bp">boundary point</a> (<var title="">current parent</var>, <var title="">index</var>) and whose
721: <a href="infrastructure.html#concept-range-end" title="concept-range-end">end</a> is the <a href="infrastructure.html#concept-range-bp" title="concept-range-bp">boundary point</a> (<var title="">current parent</var>, <var title="">index</var> plus one)
722: (i.e. that contains only <var title="">rt</var>).</p></li>
723:
724: <li><p>Let <var title="">new annotation segment</var> be an
725: annotation segment described by the range <var title="">annotation
726: range</var>.</p></li>
727:
728: <li><p>If <var title="">current base text</var> is not null,
729: associate <var title="">new annotation segment</var> with <var title="">current base text</var>.</p></li>
730:
731: <li><p>Add <var title="">new annotation segment</var> to <var title="">annotation segments</var>.</p></li>
732:
733: </ol><div class="example">
1.1 mike 734:
1.159 sruby 735: <!-- this is the hiragana for the word "kanji" ("chinese character") in japanese -->
736: <!-- in japanese, ruby-like typography is called "furigana" -->
1.1 mike 737:
738: <p>In this example, each ideograph in the Japanese text <span lang="ja" title="">漢字</span> is annotated with its
739: reading in hiragana.</p>
740:
741: <pre lang="ja">...
742: <ruby>漢<rt>かん</rt>字<rt>じ</rt></ruby>
743: ...</pre>
744:
745: <p>This might be rendered as:</p>
746:
1.159 sruby 747: <p><img alt="The two main ideographs, each with its annotation in hiragana rendered in a smaller font above it." height="78" src="images/sample-ruby-ja.png" width="171"></p>
1.1 mike 748:
1.85 mike 749: </div>
750:
751: <div class="example">
1.1 mike 752:
1.178 sruby 753: <!-- this is the zhuyin fuhao (aka bopomofo) for the word "hanzi" ("chinese character") in traditional chinese, as used in taiwan -->
1.1 mike 754:
755: <p>In this example, each ideograph in the traditional Chinese text
756: <span lang="zh-TW" title="">漢字</span> is annotated
757: with its bopomofo reading.</p>
758:
759: <pre lang="zh-TW"><ruby>漢<rt>ㄏㄢˋ</rt>字<rt>ㄗˋ</rt></ruby></pre>
760:
761: <p>This might be rendered as:</p>
762:
1.159 sruby 763: <p><img alt="The two main ideographs, each with its bopomofo annotation rendered in a smaller font next to it." height="100" src="images/sample-ruby-bopomofo.png" width="78"></p>
1.1 mike 764:
1.85 mike 765: </div>
766:
767: <div class="example">
1.1 mike 768:
1.159 sruby 769: <!-- this is the pinyin for the word "hanzi" ("chinese character") in simplified chinese, as used in mainland china -->
1.1 mike 770:
771: <p>In this example, each ideograph in the simplified Chinese text
772: <span lang="zh-CN" title="">汉字</span> is annotated
773: with its pinyin reading.</p>
774:
775: <pre lang="zh-CN">...<ruby>汉<rt>hàn</rt>字<rt>zì</rt></ruby>...</pre>
776:
777: <p>This might be rendered as:</p>
778:
1.159 sruby 779: <p><img alt="The two main ideographs, each with its pinyin annotation rendered in a smaller font above it." height="79" src="images/sample-ruby-pinyin.png" width="173"></p>
1.1 mike 780:
1.85 mike 781: </div>
782:
1.159 sruby 783: <!-- Note: Examples are 32px/16px Stone Sans Sem ITC TT -->
1.85 mike 784:
1.178 sruby 785: <div class="example">
786:
787: <p>In this more contrived example, the acronym "HTML" has four
788: annotations: one for the whole acronym, briefly describing what it
789: is, one for the letters "HT" expanding them to "Hypertext", one for
790: the letter "M" expanding it to "Markup", and one for the letter "L"
791: expanding it to "Language".</p>
792:
793: <pre><ruby>
794: <ruby>HT<rt>Hypertext</rt>M<rt>Markup</rt>L<rt>Language</rt></ruby>
795: <rt>An abstract language for describing documents and applications
796: </ruby></pre>
797:
798: </div>
799:
1.85 mike 800:
801: </body></html>
Webmaster
![[BACK]](/https/dev.w3.org/cvsweb/icons/back.gif){kind=icon}
Return to the-ruby-element.html CVS log ![[TXT]](/https/dev.w3.org/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/https/dev.w3.org/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / html5 / spec