Annotation of html5/spec/the-ruby-element.html, revision 1.186
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.159 sruby 322: </script><link href="the-mark-element.html" title="4.6.19 The mark element" rel="prev">
1.161 sruby 323: <link href="spec.html#contents" title="Table of contents" rel="contents">
1.1 mike 324: <link href="the-rt-element.html" title="4.6.21 The rt element" rel="next">
1.22 mike 325: </head><body onload="fixBrokenLink();" class="split chapter"><div class="head" id="head">
1.1 mike 326: <p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
327:
328: <h1>HTML5</h1>
1.159 sruby 329: <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>
1.186 ! sruby 330: <h2 class="no-num no-toc" id="editor's-draft-date-1-january-1970">Editor's Draft 27 September 2012</h2>
1.85 mike 331: </div>
1.174 sruby 332: <div class="prev_next">
1.1 mike 333: <a href="the-mark-element.html">← 4.6.19 The mark element</a> –
1.161 sruby 334: <a href="spec.html#contents">Table of contents</a> –
1.1 mike 335: <a href="the-rt-element.html">4.6.21 The rt element →</a>
1.159 sruby 336: </div>
1.1 mike 337:
1.85 mike 338: <h4 id="the-ruby-element"><span class="secno">4.6.20 </span>The <dfn><code>ruby</code></dfn> element</h4>
339:
340: <dl class="element"><dt><a href="element-definitions.html#element-dfn-categories" title="element-dfn-categories">Categories</a>:</dt>
1.159 sruby 341: <dd><a href="content-models.html#flow-content-1">Flow content</a>.</dd>
342: <dd><a href="content-models.html#phrasing-content-1">Phrasing content</a>.</dd>
343: <dd><a href="content-models.html#palpable-content-0">Palpable content</a>.</dd>
1.25 mike 344: <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 345: <dd>Where <a href="content-models.html#phrasing-content-1">phrasing content</a> is expected.</dd>
1.25 mike 346: <dt><a href="element-definitions.html#element-dfn-content-model" title="element-dfn-content-model">Content model</a>:</dt>
1.178 sruby 347: <dd>See prose.</dd>
1.25 mike 348: <dt><a href="element-definitions.html#element-dfn-attributes" title="element-dfn-attributes">Content attributes</a>:</dt>
1.1 mike 349: <dd><a href="global-attributes.html#global-attributes">Global attributes</a></dd>
1.159 sruby 350: <dt><a href="element-definitions.html#element-dfn-dom" title="element-dfn-dom">DOM interface</a>:</dt><!--TOPIC:DOM APIs-->
1.1 mike 351: <dd>Uses <code><a href="elements.html#htmlelement">HTMLElement</a></code>.</dd>
1.159 sruby 352: </dl><!--TOPIC:HTML--><p>The <code><a href="#the-ruby-element">ruby</a></code> element allows one or more spans of
1.1 mike 353: phrasing content to be marked with ruby annotations. Ruby
354: annotations are short runs of text presented alongside base text,
355: primarily used in East Asian typography as a guide for
356: pronunciation or to include other annotations. In Japanese, this
1.85 mike 357: form of typography is also known as <i>furigana</i>.</p>
358:
1.178 sruby 359: <p>The content model of <code><a href="#the-ruby-element">ruby</a></code> elements consists of one
360: or more of the following sequences:</p>
1.85 mike 361:
1.178 sruby 362: <ol class="brief"><li>One or the other of the following:
363: <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
364: </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
365: </li></ul></li><li>One or the other of the following:
366: <ul class="brief"><li>One or more <code><a href="the-rt-element.html#the-rt-element">rt</a></code> elements
367: </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
368: </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
369: for a variety of kinds of annotations, including in particular those
370: described below. For more details on Japanese Ruby in particular,
371: and how to render Ruby for Japanese, see <cite>Requirements for
372: Japanese Text Layout</cite>. <a href="references.html#refsJLREQ">[JLREQ]</a></p>
373:
374: <p class="note">At the time of writing, CSS does not yet provide a
375: way to fully control the rendering of the HTML <code><a href="#the-ruby-element">ruby</a></code>
376: element. It is hoped that CSS will be extended to support the styles
377: described below in due course.</p>
378:
379: <!-- examples in the following list are mostly based on those in http://www.w3.org/International/datespace/2010/02/jlreq-examples/ -->
380:
381: <dl><dt>Mono-ruby for individual base characters
382:
383: </dt><dd>
384:
385: <p>One or more hiragana or katakana characters (the ruby
386: annotation) are placed with each ideographic character (the base
387: text). This is used to provide readings of kanji characters.
388:
389: </p><div class="example"> <!-- B as in BASE -->
390: <pre><ruby>B<rt>annotation</ruby></pre>
391: </div>
392:
393: <div class="example">
394: <p>In this example, notice how each annotation corresponds to a single base character.
395: </p><pre><ruby>君<rt>くん</ruby><ruby>子<rt>し</ruby>は<ruby>和<rt>わ</ruby>して<ruby>同<rt>どう</ruby>ぜず。</pre>
396: <p lang="ja"><ruby>君<rt>くん</rt></ruby><ruby>子<rt>し</rt></ruby>は<ruby>和<rt>わ</rt></ruby>して<ruby>同<rt>どう</rt></ruby>ぜず。
397: </p></div>
398:
399: </dd>
400:
401:
402: <dt>Mono-ruby for compound words (jukugo)
403:
404: </dt><dd>
405:
406: <p>This is similar to the previous case: each ideographic
407: character in the compound word (the base text) has its reading
408: given in hiragana or katakana characters (the ruby annotation).
409: The difference is that the base text segments form a compound word
410: rather than being separate from each other.
411:
412: </p><div class="example"> <!-- B as in BASE -->
413: <pre><ruby>B<rt>annotation</rt>B<rt>annotation</ruby></pre>
414: </div>
415:
416: <div class="example">
417: <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>
418: <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>
419: <pre><ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する</pre>
420: <p lang="ja"><ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する
421:
422: </p></div>
423:
424: </dd>
425:
426:
427: <dt>Jukugo-ruby
428:
429: </dt><dd>
430:
431: <p>This is semantically identical to the previous case (each
432: individual ideographic character in the base compound word has its
433: reading given in an annotation in hiragana or katakana
434: characters), but the rendering is the more complicated Jukugo Ruby
435: rendering.
436:
437: </p><div class="example">
438: <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>
439: <pre><ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する</pre>
440: <!-- Once CSS is updated to describe this, invoke the CSS and unhide this -->
441: <!--
442: <p lang=ja><ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する
443: -->
444: </div>
445:
446: <p class="note">For more details on <a href="http://www.w3.org/TR/jlreq/#positioning_of_jukugoruby">Jukugo
447: Ruby rendering</a>, see Appendix F in the <cite>Requirements for
448: Japanese Text Layout</cite>. <a href="references.html#refsJLREQ">[JLREQ]</a></p>
449:
450: </dd>
451:
452:
453: <dt>Group ruby for describing meanings
454:
455: </dt><dd>
456:
457: <p>The annotation describes the meaning of the base text, rather
458: than (or in addition to) the pronunciation. As such, both the base
459: text and the annotation can be multiple characters long.
460:
461: </p><div class="example">
462: <pre><ruby>BASE<rt>annotation</ruby></pre>
463: </div>
464:
465: <div class="example">
466: <p>Here a compound ideographic word has its corresponding katakana given as an annotation.
467: </p><pre><ruby>境界面<rt>インターフェース</ruby></pre>
468: <p lang="ja"><ruby>境界面<rt>インターフェース</rt></ruby></p></div>
469:
470: <div class="example">
471: <p>Here a compound ideographic word has its translation in English provided as an annotation.
472: </p><pre><ruby lang="ja">編集者<rt lang="en">editor</ruby></pre>
473: <p><ruby lang="ja">編集者<rt lang="en">editor</rt></ruby></p></div>
474:
475: </dd>
476:
477:
478: <dt>Group ruby for Jukuji readings
479:
480: </dt><dd>
481:
482: <p>A phonetic reading that corresponds to multiple base
483: characters, because a one-to-one mapping would be difficult. (In
484: English, the words "Colonel" and "Lieutenant" are examples of
485: words where a direct mapping of pronunciation to individual
486: letters is, in some dialects, rather unclear.)
487:
488: </p><div class="example">
489: <p>In this example, the name of a species of flowers has a phonetic reading provided using group ruby:
490: </p><pre><ruby>紫陽花<rt>あじさい</ruby></pre>
491: <p lang="ja"><ruby>紫陽花<rt>あじさい</rt></ruby></p></div>
492:
493: </dd>
494:
495:
496: <dt>Text with both phonetic and semantic annotations (double-sided ruby)
497:
498: </dt><dd>
499:
500: <p>Sometimes, ruby styles described above are combined.
501:
502: </p><div class="example">
503: <pre><ruby>BASE<rt>annotation 1<rt>annotation 2</ruby></pre>
504: </div>
505:
506: <div class="example">
507: <pre><ruby><ruby>B<rt>a</rt>A<rt>n</rt>S<rt>t</rt>E<rt>n</rt></ruby><rt>annotation</ruby></pre>
508: </div>
509:
510: <div class="example">
511: <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.
512: </p><pre><ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt>たつみ</rt></ruby>の方角</pre>
513: <p lang="ja"><ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt>たつみ</rt></ruby>の方角
514: </p></div>
515:
516: <div class="example">
517: <p>This is the same example, but the meaning is given in English instead of Japanese:
518: </p><pre><ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt lang=en>Southeast</rt></ruby>の方角</pre>
519: <p lang="ja"><ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt lang="en">Southeast</rt></ruby>の方角
520: </p></div>
521:
522: </dd>
523:
524: </dl><hr><p>Within a <code><a href="#the-ruby-element">ruby</a></code> element that does not have a
525: <code><a href="#the-ruby-element">ruby</a></code> element ancestor, content is segmented and
526: segments are placed into three categories: base text segments,
527: annotation segments, and ignored segments. Ignored segments do not
528: form part of the document's semantics (they consist of some
529: <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,
530: the latter of which are used for legacy user agents that do not
531: support ruby at all). Base text segments can overlap (with a limit
532: of two segments overlapping any one position in the DOM, and with
533: any segment having an earlier start point than an overlapping
534: segment also having an equal or later end point, and any segment
535: have a later end point than an overlapping segment also having an
536: equal or earlier start point<!-- if anyone can find a better way of
537: phrasing this parenthetical, do let me know! -->). Annotation
538: segments correspond to <code><a href="the-rt-element.html#the-rt-element">rt</a></code> elements. Each annotation
539: segment can be associated with a base text segment, and each base
540: text segment can have annotation segments associated with it. (In a
541: conforming document, each base text segment is associated with at
542: least one annotation segment, and each annotation segment is
543: associated with one base text segment.) A <code><a href="#the-ruby-element">ruby</a></code> element
544: <a href="rendering.html#represents">represents</a> the union of the segments of base text it
545: contains, along with the mapping from those base text segments to
546: annotation segments. Segments are described in terms of DOM ranges;
547: annotation segment ranges always consist of exactly one element. <a href="references.html#refsDOMCORE">[DOMCORE]</a></p>
548:
549: <p>At any particular time, the segmentation and categorisation of
550: content of a <code><a href="#the-ruby-element">ruby</a></code> element is the result that would be
551: obtained from running the following algorithm:</p>
552:
553: <ol><li><p>Let <var title="">base text segments</var> be an empty list
554: of base text segments, each potentially with a list of base text
555: subsegments.</p></li>
556:
557: <li><p>Let <var title="">annotation segments</var> be an empty list
558: of annotation segments, each potentially being associated with a
559: base text segment or subsegment.</p></li>
560:
561: <li><p>Let <var title="">root</var> be the <code><a href="#the-ruby-element">ruby</a></code>
562: element for which the algorithm is being run.</p></li>
563:
564: <li><p>If <var title="">root</var> has a <code><a href="#the-ruby-element">ruby</a></code> element
565: ancestor, then jump to the step labeled <i>end</i>.</p></li>
566:
567: <li><p>Let <var title="">current parent</var> be <var title="">root</var>.</p></li>
568:
569: <li><p>Let <var title="">index</var> be 0.</p></li>
570:
571: <li><p>Let <var title="">start index</var> be null.</p></li>
572:
573: <li><p>Let <var title="">parent start index</var> be null.</p></li>
574:
575: <li><p>Let <var title="">current base text</var> be null.</p></li>
576:
577:
578: <!-- This is spaghetti code. If someone can work out a way to
579: phrase this that is as unambiguous but maps more cleanly to
580: structured code, please let me know. -->
581:
582:
583: <li><p><i>Start mode</i>: If <var title="">index</var> is equal to
584: or greater than the number of child nodes in <var title="">current
585: parent</var>, then jump to the step labeled <i>end mode</i>.</p>
586:
587: </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
588: <code><a href="the-rp-element.html#the-rp-element">rp</a></code> element, jump to the step labeled <i>annotation
589: mode</i>.</p></li>
590:
591: <!-- if we get here then the first node in a ruby element or after
592: an <rt> or <rp> is something we want in a base text -->
593:
594: <li><p>Set <var title="">start index</var> to the value of <var title="">index</var>.</p></li>
595:
596: <li><p><i>Base mode</i>: If the <var title="">index</var>th node in
597: <var title="">current parent</var> is a <code><a href="#the-ruby-element">ruby</a></code> element,
598: and if <var title="">current parent</var> is the same element as
599: <var title="">root</var>, then <a href="#push-a-ruby-level">push a ruby level</a> and
600: then jump to the step labeled <i>start mode</i>.</p></li>
601:
602: <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
603: <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
604: text</a> and then jump to the step labeled <i>annotation
605: mode</i>.</p></li>
606:
607: <li><p>Increment <var title="">index</var> by one.</p></li>
608:
609: <li><p><i>Base mode post-increment</i>: If <var title="">index</var> is equal to or greater than the number of
610: child nodes in <var title="">current parent</var>, then jump to the
611: step labeled <i>end mode</i>.</p></li>
612:
613: <li><p>Jump back to the step labeled <i>base mode</i>.</p></li>
614:
615:
616: <li><p><i>Annotation mode</i>: If the <var title="">index</var>th
617: node in <var title="">current parent</var> is an <code><a href="the-rt-element.html#the-rt-element">rt</a></code>
618: element, then <a href="#push-a-ruby-annotation">push a ruby annotation</a> and jump to the
619: step labeled <i>annotation mode increment</i>.</p></li>
620:
621: <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
622: to the 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 not a <code><a href="infrastructure.html#text-0">Text</a></code> node, or
625: 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
626: whitespace</a>, then jump to the step labeled <i>base
627: mode</i>.</p></li>
628:
629: <!-- index points at whitespace -->
630:
631: <li><p><i>Annotation mode increment</i>: Let <var title="">lookahead index</var> be <var title="">index</var> plus
632: one.</p></li>
633:
634: <li><p><i>Annotation mode white-space skipper</i>: If <var title="">lookahead index</var> is equal to the number of child
635: nodes in <var title="">current parent</var> then jump to the step
636: labeled <i>end mode</i>.</p></li>
637:
638: <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
639: <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
640: <i>annotation mode</i>.</p></li>
641:
642: <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
643: 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
644: whitespace</a>, then jump to the step labeled <i>base mode</i>
645: (without further incrementing <var title="">index</var>, so the
646: <a href="content-models.html#inter-element-whitespace">inter-element whitespace</a> seen so far becomes part of
647: the next base text segment).</p></li>
648:
649: <li><p>Increment <var title="">lookahead index</var> by
650: one.</p></li>
651:
652: <li><p>Jump to the step labeled <i>annotation mode white-space
653: skipper</i>.</p></li>
654:
655:
656: <li><p><i>End mode</i>: If <var title="">current parent</var> is
657: not the same element as <var title="">root</var>, then <a href="#pop-a-ruby-level">pop a
658: ruby level</a> and jump to the step labeled <i>base mode
659: post-increment</i>.</p></li>
660:
661: <li><p><i>End</i>: Return <var title="">base text segments</var>
662: and <var title="">annotation segments</var>. Any content of the
663: <code><a href="#the-ruby-element">ruby</a></code> element not described by segments in either of
664: thost lists is implicitly in an <i>ignored segment</i>.</p></li>
665:
666: </ol><p>When the steps above say to <dfn id="set-the-current-base-text">set the current base text</dfn>,
667: it means to run the following steps at that point in the
668: algorithm:</p>
669:
670: <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
671: 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>
672:
673: <li><p>Let <var title="">new text segment</var> be a base text
674: segment described by the range <var title="">annotation
675: range</var>.</p>
676:
677: </li><li><p>Add <var title="">new text segment</var> to <var title="">base text segments</var>.</p></li>
678:
679: <li><p>Let <var title="">current base text</var> be <var title="">new text segment</var>.</p></li>
680:
681: <li><p>Let <var title="">start index</var> be null.</p></li>
682:
683: </ol><p>When the steps above say to <dfn id="push-a-ruby-level">push a ruby level</dfn>, it
684: means to run the following steps at that point in the algorithm:</p>
685:
686: <ol><li><p>Let <var title="">current parent</var> be the <var title="">index</var>th node in <var title="">current
687: parent</var>.</p></li>
688:
689: <li><p>Let <var title="">index</var> be 0.</p></li>
690:
691: <li><p>Set <var title="">saved start index</var> to the value of
692: <var title="">start index</var>.</p></li>
693:
694: <li><p>Let <var title="">start index</var> be null.</p></li>
695:
696: </ol><p>When the steps above say to <dfn id="pop-a-ruby-level">pop a ruby level</dfn>, it means
697: to run the following steps at that point in the algorithm:</p>
698:
699: <ol><li><p>Let <var title="">index</var> be the position of <var title="">current parent</var> in <var title="">root</var>.</p></li>
700:
701: <li><p>Let <var title="">current parent</var> be <var title="">root</var>.</p></li>
702:
703: <li><p>Increment <var title="">index</var> by one.</p></li>
704:
705: <li><p>Set <var title="">start index</var> to the value of
706: <var title="">saved start index</var>.</p></li>
707:
708: <li><p>Let <var title="">saved start index</var> be null.</p></li>
709:
710: </ol><p>When the steps above say to <dfn id="push-a-ruby-annotation">push a ruby annotation</dfn>, it
711: means to run the following steps at that point in the algorithm:</p>
712:
713: <ol><li><p>Let <var title="">rt</var> be the <code><a href="the-rt-element.html#the-rt-element">rt</a></code> element
714: that is the <var title="">index</var>th node of <var title="">current parent</var>.</p></li>
715:
716: <li><p>Let <var title="">annotation range</var> a DOM range whose
717: <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
718: <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)
719: (i.e. that contains only <var title="">rt</var>).</p></li>
720:
721: <li><p>Let <var title="">new annotation segment</var> be an
722: annotation segment described by the range <var title="">annotation
723: range</var>.</p></li>
724:
725: <li><p>If <var title="">current base text</var> is not null,
726: associate <var title="">new annotation segment</var> with <var title="">current base text</var>.</p></li>
727:
728: <li><p>Add <var title="">new annotation segment</var> to <var title="">annotation segments</var>.</p></li>
729:
730: </ol><div class="example">
1.1 mike 731:
1.159 sruby 732: <!-- this is the hiragana for the word "kanji" ("chinese character") in japanese -->
733: <!-- in japanese, ruby-like typography is called "furigana" -->
1.1 mike 734:
735: <p>In this example, each ideograph in the Japanese text <span lang="ja" title="">漢字</span> is annotated with its
736: reading in hiragana.</p>
737:
738: <pre lang="ja">...
739: <ruby>漢<rt>かん</rt>字<rt>じ</rt></ruby>
740: ...</pre>
741:
742: <p>This might be rendered as:</p>
743:
1.159 sruby 744: <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 745:
1.85 mike 746: </div>
747:
748: <div class="example">
1.1 mike 749:
1.178 sruby 750: <!-- this is the zhuyin fuhao (aka bopomofo) for the word "hanzi" ("chinese character") in traditional chinese, as used in taiwan -->
1.1 mike 751:
752: <p>In this example, each ideograph in the traditional Chinese text
753: <span lang="zh-TW" title="">漢字</span> is annotated
754: with its bopomofo reading.</p>
755:
756: <pre lang="zh-TW"><ruby>漢<rt>ㄏㄢˋ</rt>字<rt>ㄗˋ</rt></ruby></pre>
757:
758: <p>This might be rendered as:</p>
759:
1.159 sruby 760: <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 761:
1.85 mike 762: </div>
763:
764: <div class="example">
1.1 mike 765:
1.159 sruby 766: <!-- this is the pinyin for the word "hanzi" ("chinese character") in simplified chinese, as used in mainland china -->
1.1 mike 767:
768: <p>In this example, each ideograph in the simplified Chinese text
769: <span lang="zh-CN" title="">汉字</span> is annotated
770: with its pinyin reading.</p>
771:
772: <pre lang="zh-CN">...<ruby>汉<rt>hàn</rt>字<rt>zì</rt></ruby>...</pre>
773:
774: <p>This might be rendered as:</p>
775:
1.159 sruby 776: <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 777:
1.85 mike 778: </div>
779:
1.159 sruby 780: <!-- Note: Examples are 32px/16px Stone Sans Sem ITC TT -->
1.85 mike 781:
1.178 sruby 782: <div class="example">
783:
784: <p>In this more contrived example, the acronym "HTML" has four
785: annotations: one for the whole acronym, briefly describing what it
786: is, one for the letters "HT" expanding them to "Hypertext", one for
787: the letter "M" expanding it to "Markup", and one for the letter "L"
788: expanding it to "Language".</p>
789:
790: <pre><ruby>
791: <ruby>HT<rt>Hypertext</rt>M<rt>Markup</rt>L<rt>Language</rt></ruby>
792: <rt>An abstract language for describing documents and applications
793: </ruby></pre>
794:
795: </div>
796:
1.85 mike 797:
798: </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