One or more hiragana or katakana characters (the ruby annotation) are placed with each - ideographic character (the base text). This is used to provide readings of kanji characters. - -
<ruby>B<rt>annotation</ruby>In this example, notice how each annotation corresponds to a single base character. -
<ruby>君<rt>くん</ruby><ruby>子<rt>し</ruby>は<ruby>和<rt>わ</ruby>して<ruby>同<rt>どう</ruby>ぜず。君子は和して同ぜず。 -
This example can also be written as follows, using one ruby element with two
- segments of base text and two annotations (one for each) rather than two back-to-back
- ruby elements each with one base text segment and annotation (as in the markup
- above):
-
<ruby>君<rt>くん</rt>子<rt>し</ruby>は<ruby>和<rt>わ</ruby>して<ruby>同<rt>どう</ruby>ぜず。This is similar to the previous case: each ideographic character in the compound word (the - base text) has its reading given in hiragana or katakana characters (the ruby annotation). The - difference is that the base text segments form a compound word rather than being separate from - each other. - -
<ruby>B<rt>annotation</rt>B<rt>annotation</ruby>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 ruby element.
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.
-<ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する鬼門の方角を凝視する - -
This is semantically identical to the previous case (each individual ideographic character in - the base compound word has its reading given in an annotation in hiragana or katakana - characters), but the rendering is the more complicated Jukugo Ruby rendering. - -
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.
-<ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>するFor more details on Jukugo Ruby rendering, see - Appendix F in the Requirements for Japanese Text Layout.
-The annotation describes the meaning of the base text, rather than (or in addition to) the - pronunciation. As such, both the base text and the annotation can be multiple characters long. - -
<ruby>BASE<rt>annotation</ruby>Here a compound ideographic word has its corresponding katakana given as an annotation. -
<ruby>境界面<rt>インターフェース</ruby>境界面 -
Here a compound ideographic word has its translation in English provided as an annotation. -
<ruby lang="ja">編集者<rt lang="en">editor</ruby>編集者 -
A phonetic reading that corresponds to multiple base characters, because a one-to-one mapping - would be difficult. (In English, the words "Colonel" and "Lieutenant" are examples of words - where a direct mapping of pronunciation to individual letters is, in some dialects, rather - unclear.) +
This example shows Japanese text, with ruby markup used to annotate the ideographs with their + pronunciation.
-In this example, the name of a species of flowers has a phonetic reading provided using group ruby: -
<ruby>紫陽花<rt>あじさい</ruby>紫陽花 -
<ruby>霧<rt>きり</rt></ruby>とも<ruby>霞<rt>かすみ</rt></ruby>ともA typical rendering would be something akin to the following image:
-
Sometimes, ruby styles described above are combined. +
The content model of ruby elements consists of one or more of the following
+ ruby segment sequences:
If this results in two annotations covering the same single base segment, then the - annotations can just be placed back to back. +
-
+
- One or more phrasing content nodes or
rbelements (or a + combination) representing the base-level content being annotated + (the ruby base range).
- - One or more
rtorrtcelements (or a combination) representing any annotations associated with the preceding base + content, where eachrtcelement or sequence ofrtelements represents one independent level of annotation (a ruby + annotation range) and can be preceded / followed by an optionalrpelement. + (The optionalrpelement can be used to add presentational content such as + parentheses, which can be useful when falling back to inline rendering for when ruby layout is + not supported.)
+
<ruby>BASE<rt>annotation 1<rt>annotation 2</ruby><ruby>B<rt>a<rt>a</ruby><ruby>A<rt>a<rt>a</ruby><ruby>S<rt>a<rt>a</ruby><ruby>E<rt>a<rt>a</ruby>For authoring convenience, the internal ruby elements rb,
+ rt, rtc, and rp have optional end
+ tags.
In Taiwan, phonetic annotations for Chinese text are typically provided using Zhuyin + characters (also known as Bopomofo). In mainland China, phonetic annotations are typically + provided using Latin characters using Pinyin transcription. In this example, both are + provided:
-In this contrived example, some symbols are given names in English and French. +
<ruby>
- ♥ <rt> Heart <rt lang=fr> Cœur </rt>
- ☘ <rt> Shamrock <rt lang=fr> Trèfle </rt>
- ✶ <rt> Star <rt lang=fr> Étoile </rt>
+ <ruby lang=zh-TW>
+ <rb>電</rb><rtc><rt>ㄉㄧㄢˋ</rt></rtc><rtc lang=zh-Latn><rt>diàn</rt></rtc>
+ <rb>腦</rb><rtc><rt>ㄋㄠˇ</rt></rtc><rtc lang=zh-Latn><rt>nǎo</rt></rtc>
</ruby>
- In more complication situations such as following examples, a nested ruby
- element is used to give the inner annotations, and then that whole ruby is then
- given an annotation at the "outer" level.
-
-
<ruby><ruby>B<rt>a</rt>A<rt>n</rt>S<rt>t</rt>E<rt>n</rt></ruby><rt>annotation</ruby>Here both a phonetic reading and the meaning are given in ruby annotations. The annotation on the nested ruby element gives a mono-ruby phonetic annotation for each base character, while the annotation in the rt element that is a child of the outer ruby element gives the meaning using hiragana.
-
<ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt>たつみ</rt></ruby>の方角東南の方角 -
This is the same example, but the meaning is given in English instead of Japanese: -
<ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt lang=en>Southeast</rt></ruby>の方角東南の方角 -
- -
Within a ruby element that does not have a ruby element ancestor,
- content is segmented and segments are placed into three categories: base text segments, annotation
- segments, and ignored segments. Ignored segments do not form part of the document's semantics
- (they consist of some inter-element whitespace and rp elements, the
- latter of which are used for legacy user agents that do not support ruby at all). Base text
- segments can overlap (with a limit of two segments overlapping any one position in the DOM, and
- with any segment having an earlier start point than an overlapping segment also having an equal or
- later end point, and any segment have a later end point than an overlapping segment also having an
- equal or earlier start point). Annotation segments correspond to rt elements. Each annotation
- segment can be associated with a base text segment, and each base text segment can have annotation
- segments associated with it. (In a conforming document, each base text segment is associated with
- at least one annotation segment, and each annotation segment is associated with one base text
- segment.) A ruby element represents the union of the segments of base
- text it contains, along with the mapping from those base text segments to annotation segments.
- Segments are described in terms of DOM ranges; annotation segment ranges always
- consist of exactly one element.
At any particular time, the segmentation and categorization of content of a ruby
- element is the result that would be obtained from running the following algorithm:
-
-
Let base text segments be an empty list of base text segments, each - potentially with a list of base text subsegments.
-
- Let annotation segments be an empty list of annotation segments, each - potentially being associated with a base text segment or subsegment.
-
- Let root be the
rubyelement for which the algorithm is - being run.
+ If root has a
rubyelement ancestor, then jump to the - step labeled end.
-
- Let current parent be root.
-
- Let index be 0.
-
- Let start index be null.
-
- Let parent start index be null.
-
- Let current base text be null.
-
-
-
-
-
- Start mode: If index is equal to or greater than the number of - child nodes in current parent, then jump to the step labeled end - mode.
- -If the indexth node in current parent is an -
rtorrpelement, jump to the step labeled annotation - mode.
-
-
-
- Set start index to the value of index.
-
- Base mode: If the indexth node in current - parent is a
rubyelement, and if current parent is the - same element as root, then push a ruby level and then jump to - the step labeled start mode.
-
- If the indexth node in current parent is an -
rtorrpelement, then set the current base text and then - jump to the step labeled annotation mode.
-
- Increment index by one.
-
- Base mode post-increment: If index is equal to or greater than - the number of child nodes in current parent, then jump to the step labeled - end mode.
-
- Jump back to the step labeled base mode.
-
-
- Annotation mode: If the indexth node in current - parent is an
rtelement, then push a ruby annotation and jump to - the step labeled annotation mode increment.
-
- If the indexth node in current parent is an -
rpelement, jump to the step labeled annotation mode increment.
+ - End tags can be omitted. -
If the indexth node in current parent is not a -
Textnode, or is aTextnode that is not inter-element - whitespace, then jump to the step labeled base mode.
+ - Text contained directly by a
rubyelement implicitly represents a ruby + base unit (as if it were contained in anrbelement).
-
+ - Consecutive
rtchildren of arubyelement are implicitly grouped + into a ruby annotation range (as if they were contained in anrtc+ element).
- Annotation mode increment: Let lookahead index be index plus one.
+ - Text contained directly by an
rtcelement implicity represents a ruby + annotation unit.
+ Annotation mode white-space skipper: If lookahead index is - equal to the number of child nodes in current parent then jump to the step - labeled end mode.
+
Certain features of HTML ruby allow for simpler markup:
--
+
In effect, the above example is equivalent (in meaning, though not in the DOM it produces) to the following:
+<ruby lang=zh-TW>
+ 電<rt>ㄉㄧㄢˋ<rtc lang=zh-Latn>diàn</rtc>
+ 腦<rt>ㄋㄠˇ<rtc lang=zh-Latn>nǎo
+</ruby>If the lookahead indexth node in current parent is
- an rt element or an rp element, then set index to
- lookahead index and jump to the step labeled annotation mode.
The CSS Ruby Module Level 1 enables authors to control the rendering
+ of the HTML ruby element and its contents, supporting a variety of layouts based on
+ the same markup.
If the lookahead indexth node in current parent is
- not a Text node, or is a Text node that is not inter-element
- whitespace, then jump to the step labeled base mode (without further incrementing
- index, so the inter-element whitespace seen so far becomes part
- of the next base text segment).
Three rendering styles are commonly used with Zhuyin (Bopomofo) characters. (Annotations here + are shown in blue for clarity, though in actual uses there would be no color distinction.)
-Increment lookahead index by one.
When the text is written vertically, the phonetic annotations are rendered to the right, along + the base text:
-Jump to the step labeled annotation mode white-space skipper.
In horizontal writing, they are frequently also typeset to the right, in this case sandwiched + between individual base characters:
-End mode: If current parent is not the same element as root, then pop a ruby level and jump to the step labeled base mode - post-increment.
End: Return base text segments and annotation
- segments. Any content of the ruby element not described by segments in either
- of those lists is implicitly in an ignored segment.
However, sometimes Zhuyin annotations are instead typeset above horizontal base text:
+
When the steps above say to set the current base text, it means to run the following - steps at that point in the algorithm:
+These differences are stylistic, not semantic, and therefore share the same markup:
--
-
Let text range be a DOM range whose start is the boundary - point (current parent, start index) and whose - end is the boundary - point (current parent, index).
+
<ruby lang=zh-TW>電<rt>ㄉㄧㄢˋ</rt>腦<rt>ㄋㄠˇ</ruby>Let new text segment be a base text segment described by the range - annotation range.
+Ruby Segmentation and Pairing
-Add new text segment to base text - segments.
Within a ruby element, content is parcelled into a series of ruby segments. Ignoring
+ inter-element whitespace and rp elements, each ruby segment
+ consists of:
Let current base text be new text - segment.
-
+
One ruby base range: zero or more ruby base + units, each of which is either a DOM range containing a single child
rb+ element or a maximal DOM range of child content that does not contain a childrb+ element.
- Let start index be null.
-
+ Zero or more ruby annotation ranges, each a + DOM range corresponding to either a single
rtcelement or to a maximal sequence of + consecutivertelements. The ruby annotation range is further parcelled + into a sequence of ruby annotation units: if it + consists of a sequence ofrtelements then each such element is an individual + ruby annotation unit; if it consists of anrtcelement, then each of + its childrtelements and each maximal DOM range of non-rtchild + content is a ruby annotation unit.
+
Annotating text character by character is also typical in Chinese. In this example, each
+ character is individually annotated in its own ruby element:
<ruby>千<rt>qiān</ruby><ruby>里<rt>lǐ</ruby><ruby>之<rt>zhī</ruby><ruby>行<rt>xíng</ruby>﹐<ruby>始<rt>shǐ</ruby><ruby>於<rt>yú</ruby><ruby>足<rt>zú</ruby><ruby>下<rt>xià</ruby>。
Multiple adjacent ruby segments can also be combined into the same ruby parent:
<ruby>千<rt>qiān</rt>里<rt>lǐ</rt>之<rt>zhī</rt>行<rt>xíng</ruby>﹐<ruby>始<rt>shǐ</rt>於<rt>yú</rt>足<rt>zú</rt>下<rt>xià</ruby>。The process of annotation pairing associates ruby annotation units with ruby base units.
+ Within each ruby segment, each ruby base unit is paired with one
+ ruby annotation unit from each ruby annotation range. If a ruby
+ annotation range consists of an rtc element that contains no rt
+ elements, the single ruby annotation unit represented by its contents spans (is
+ paired with) every ruby base unit in the ruby segment. Otherwise, each
+ ruby annotation unit in the ruby annotation range is paired, in order,
+ with the corresponding ruby base unit in the segment’s ruby base range.
+ If there are not enough ruby base units, any
+ remaining ruby annotation units are assumed to be
+ associated with empty, hypothetical bases inserted at the end of the ruby base range.
+ If there are not enough ruby annotation units in a
+ ruby annotation range, the remaining ruby base
+ units are assumed to not have an annotation from that annotation level.
In some contexts, for example when the font size or line height are too small for interlinear + ruby to be readable, it is desirable to inline the ruby annotation such that it appears in + parentheses after the text it annotates. This also provides an appropriate fallback rendering for + user agents that do not support ruby layout. + +
However, for compound words in Japanese particularly, per-character inlined phonetics are
+ awkward. Instead the more natural rendering is to place the annotation of an entire word together
+ after its base text. For example, when typeset inline, 京都市
+ (“Kyoto City”) is expected to be rendered as “京都市（きょうとし）”, not “京（きょう）都（と）市（し）”. This can be marked up using consecutive
+ rb elements followed by consecutive rt elements:
<ruby><rb>京<rb>都<rb>市<rt>きょう<rt>と<rt>し<ruby>If each base character was immediately followed by its annotation in the markup (each + base-annotation pair forming its own segment), inlining would result in the undesirable and + awkward “京（きょう）都（と）市（し）”.
+ +Note that the markup above does not automatically provide the parentheses. Parentheses can be
+ inserted using CSS generated content when intentionally typesetting inline, however they would be
+ missing when a UA that does not support ruby falls back to inline layout automatically from
+ interlinear layout. The rp element can be inserted to provide the appropriate
+ punctuation for when ruby is not supported:
<ruby><rb>京<rb>都<rb>市<rp>（<rt>きょう<rt>と<rt>し<rp>）<ruby>Markup Patterns for Multi-Character Ruby
-When the steps above say to push a ruby level, it means to run the following steps - at that point in the algorithm:
+ --
-
Let current parent be the indexth node in current parent.
+ Let index be 0.
+ Set saved start index to the value of start - index.
+ Let start index be null.
-
+ Let index be the position of current parent in - root.
+ Let current parent be root.
+ Increment index by one.
+ Set start index to the value of saved start - index.
+ Let saved start index be null.
-
+ Let rt be the
rtelement that is the indexth node of current parent.
+ Let annotation range be a DOM range whose start is the boundary - point (current parent, index) and whose end is the boundary point - (current parent, index plus one) (i.e. that contains only - rt).
+ Let new annotation segment be an annotation segment described by the - range annotation range.
+ If current base text is not null, associate new - annotation segment with current base text.
+ Add new annotation segment to annotation - segments.
- - Categories: +
- None. +
- Contexts in which this element can be used: +
- As a child of a
rubyelement.
+ - Content model: +
- Phrasing content. +
- Content attributes: +
- Global attributes +
- DOM interface: +
- Uses
HTMLElement.
+ - Categories:
- None.
- Contexts in which this element can be used: -
- As a child of a
rubyelement.
+ - As a child of a
rubyor of anrtcelement. - Content model:
- Phrasing content.
- Content attributes: @@ -21495,18 +21402,84 @@ this specification: the <abbr>WHATWG</abbr> and the
- Uses
HTMLElement. - Categories: +
- None. +
- Contexts in which this element can be used: +
- As a child of a
rubyelement.
+ - Content model: +
- Either phrasing content or a sequence of
rtelements, + optionally preceded and optionally followed by a singlerpelement.
+ - Content attributes: +
- Global attributes +
- DOM interface: +
- Uses
HTMLElement.
+ - Categories:
- None.
- Contexts in which this element can be used: -
- As a child of a
rubyelement, either immediately before or immediately after anrtelement.
+ - As a child of a
rubyorrtcelement, either immediately before or + immediately after anrtorrtcelement. - Content model:
- Text.
- Content attributes: @@ -21527,49 +21501,41 @@ this specification: the <abbr>WHATWG</abbr> and the
- Uses
HTMLElement.
- plaintextUse the "
text/plain" MIME type instead.
- rb
- rtc
- Providing the ruby base directly inside the
rubyelement or using nested -rubyelements is sufficient.
-
strikeUse
delinstead if the element is marking an edit, otherwise usesinstead.
@@ -122310,6 +122288,16 @@ interface External {
- [CHARMODNORM]
- (Non-normative) Character Model for the World Wide Web: String Matching, A. Phillips. W3C. +
- [CLREQ] +
- Requirements for Chinese Text Layout. W3C. +
- [COMPOSITE]
- Compositing and Blending, R. Cabanier, N. Andronikos. W3C. @@ -125801,7 +125814,7 @@ INSERT INTERFACES HERE
- CSS Pseudo-Elements, D. Glazman, E. Etemad, A. Stearns. W3C.
- [CSSRUBY] -
- CSS3 Ruby Module, R. Ishida. W3C. +
- CSS Ruby Module Level 1, E. Etemad, K. Ishii, X. Quan, F. Rivoal. W3C.
- [CSSSCOPING]
- CSS Scoping Module, T. Atkins. W3C. @@ -126047,6 +126060,9 @@ INSERT INTERFACES HERE
- [PRESENTATION]
- Presentation API, M. Foltz, D. Röttsches. W3C. +
- [QA-RUBY] +
- (Non-normative) What is ruby?, R. Ishida. W3C. +
- [REFERRERPOLICY]
- Referrer Policy, J. Eisinger, E. Stark. W3C. @@ -126128,6 +126144,9 @@ INSERT INTERFACES HERE
- [SELECTORS]
- Selectors, E. Etemad, T. Çelik, D. Glazman, I. Hickson, P. Linss, J. Williams. W3C. +
- [SIMPLE-RUBY] +
- (Non-normative) Rules for Simple Placement of Japanese Ruby, T. Kobayashi, F. Rivoal, A. Shimono, R. Ishida. W3C. +
- [SMS]
- (Non-normative) URI Scheme for Global System for Mobile Communications (GSM) Short Message Service (SMS), E. Wilde, A. Vaha-Sipila. IETF. @@ -126625,6 +126644,7 @@ INSERT INTERFACES HERE Félix Sanz, Felix Sasaki, Fernando Altomare Serboncini, + Florian Rivoal, Forbes Lindesay, Francesco Schwarz, Francis Brosnan Blazquez,
In the simplest examples, each ruby base unit contains only a single character, + a pattern often used for character-per-character phonetic annotations. However, ruby base units are not restricted to containing a single + character. In some cases it may be impossible to map an annotation to the base characters + individually, and the annotation may need to jointly apply to a group of characters.
-For example, the Japanese word for “today” is written with the characters 今日, literally + “this”+“day”. But it's pronounced きょう (kyō), which can't be broken down into a “this” part + and a “day” part.
-Therefore phonetic ruby indicating the reading of 今日:
-
Would be marked up as follows:
-When the steps above say to pop a ruby level, it means to run the following steps at - that point in the algorithm:
+<ruby>今日<rt>きょう</ruby>-
-
Ruby can also be used to describe the meaning of the base text, rather than (or in addition + to) the pronunciation. In such cases, both the base text and the annotation are typically made + of multiple characters, with no meaningful subdivision possible.
-Here a compound ideographic word has an English-derived synonym (written in katakana) given as + an annotation:
-<ruby>境界面<rt>インターフェース</ruby>境界面
Here a compound ideographic word has its English equivalent directly provided as an + annotation:
-<ruby lang="ja">編集者<rt lang="en">editor</ruby>編集者
In compound words, although phonetic annotations might correspond to individual characters, + they are sometimes nonetheless typeset to share space above the base text, rendering similar to + annotations on multi-character bases. However, there are subtle distinctions in their rendering + that require encoding the pairing relationships within the compound word as well as its + identification as a word. Furthermore, sharing space in this way versus rendering each pair in + its own visual “column” is a stylistic preference: the markup needs to provide enough information + to allow for both renderings (as well as correct inlining).
-When the steps above say to push a ruby annotation, it means to run the following - steps at that point in the algorithm:
+In this example, we will use the Japanese noun “京都市”, + meaning “Kyoto City”. Its characters are pronounced “きょう”, “と”, and “し”, respectively. + (Distinct colors shown in these examples for clarity: in actual usage there would be no color + distinction.)
--
-
Such compound words could be rendered with phonetic annotations placed over each character + one by one. In this style, when an annotation is visually longer than the character it annotates, + surrounding text is pushed apart, to make the correspondance between each character and its + annotation clear.
-
However, it is common to present such a word with its annotations sharing space together when + they would otherwise create a separation in the base text, to preserve the implication that it is + a single word. This style is called “jukugo ruby“ (“jukugo” meaning “compound word”).
-
Even when presenting as “jukugo ruby“ though, the annotation are not always merged. If a line + break occurs in the middle of the word, the annotations are expected to remain associated with + the correct base character.
-
Whether—and how much—the annotations are merged can vary, and can depend on the font size, as + “jukugo ruby“ only merges annotations when at least one of them is longer than its base.
- - +
In this example, each ideograph in the Japanese text 漢字 is annotated with its reading in hiragana.
+
...
-<ruby>漢<rt>かん</rt>字<rt>じ</rt></ruby>
-...
This might be rendered as:
+Since choosing to render as “jukugo ruby” or not is a stylistic choice, the same markup needs + to enable both—and it needs to encode both the pairing information within the word as well as the + grouping of these pairs as a single word:
-
<ruby><rb>京<rb>都<rb>市<rt>きょう<rt>と<rt>し<ruby>Correct “jukugo ruby” is not be possible if all the base characters are part of a single
+ rb element and all the annotation text in a single rt element, as
+ their individual pairings would be lost.
For more details on Japanese and Chinese ruby usage and rendering, see + Requirements for Japanese Text Layout (particularly Ruby and Emphasis Dots and Appendix F), Rules for + Simple Placement of Japanese Ruby, and the section on Interlinear annotations of + Requirements for Chinese Text Layout.
-In this example, each ideograph in the traditional Chinese text 漢字 is annotated with its bopomofo reading.
+The rb element
- <ruby>漢<rt>ㄏㄢˋ</rt>字<rt>ㄗˋ</rt></ruby>This might be rendered as:
+-
+
An rb (“ruby base”) element that is the child of a ruby
+ element represents a ruby base unit: a unitary component of
+ base-level text annotated by any ruby annotation(s) to which it is paired.
An rb element that is not a child of a ruby element
+ represents the same thing as its children.
When no rb element is used, the base is implied:
In this example, each ideograph in the simplified Chinese text 汉字 is annotated with its pinyin reading.
+<ruby>base<rt>annotation</ruby>...<ruby>汉<rt>hàn</rt>字<rt>zì</rt></ruby>...The element can also be made explicit:
-This might be rendered as:
- -
<ruby><rb>base<rt>annotation</ruby>Both markup patterns have identical semantics. Explicit rb elements can be useful
+ for styling, and are necessary when marking up consecutive bases to pair with consecutive
+ annotations (for example, when representing a compound word; see 京都市 inlining and jukugo
+ ruby examples above).
In this more contrived example, the acronym "HTML" has four annotations: one for the whole - acronym, briefly describing what it is, one for the letters "HT" expanding them to "Hypertext", - one for the letter "M" expanding it to "Markup", and one for the letter "L" expanding it to - "Language".
- -<ruby>
- <ruby>HT<rt>Hypertext</rt>M<rt>Markup</rt>L<rt>Language</rt></ruby>
- <rt>An abstract language for describing documents and applications
-</ruby>The rt element
The rt element marks the ruby text component of a ruby annotation. When it is the
- child of a ruby element, it doesn't represent
- anything itself, but the ruby element uses it as part of determining what it
- represents.
An rt (“ruby text”) element that is the child of a ruby element or of
+ an rtc element that is itself the child of a ruby element
+ represents a ruby annotation unit: a unitary annotation of the ruby
+ base unit to which it is paired.
An rt element that is not a child of a ruby element nor of an
+ rtc element that is itself the child of a ruby element
+ represents the same thing as its children.
The rtc element
+
+ -
+
An rtc (“ruby text container”) element that is the child of a ruby
+ element represents one level of annotation (a ruby annotation
+ range) for the preceding sequence of ruby base units
+ (its ruby base range).
-
An rt element that is not a child of a ruby element
- represents the same thing as its children.
Note: In simple cases, rtc elements can be omitted as a ruby
+ annotation range is implied by consecutive rt elements. However, they are
+ necessary in order to associate multiple levels of annotation with a single ruby base
+ range, for example to provide both phonetic and semantic information, phonetic information
+ in different scripts, or semantic information in different languages.
In this example, the Japanese compound word 上手 ("skillful") has phonetic annotations in + both kana and romaji phonetics while at the same time maintaining the pairing to + bases and annotation grouping information.
+ +
This enabled by the following markup:
+ +<ruby><rb>上<rb>手<rt>じよう<rt>ず<rtc><rt>jou<rt>zu</ruby>Note: Text that is a direct child of the rtc element implicitly
+ represents a ruby annotation unit as if it were contained in an rt element, except
+ that this annotation spans all the bases in the segment.
In this example, the Chinese word for San Francisco (旧金山, i.e. “old gold mountain”) is annotated both using pinyin to give + the pronunciation, and with the original English.
+ +
Which is marked up as follows:
+ +<ruby><rb>旧<rb>金<rb>山<rt>jiù<rt>jīn<rt>shān<rtc>San Francisco</ruby>Here, a single base run of three base characters is annotated with three pinyin ruby text
+ segments in a first (implicit) container, and an rtc element is introduced in order
+ to provide a second single ruby annotation being the city's English name.
An rtc element that is not a child of a ruby element
+ represents the same thing as its children.
The rp element
@@ -21514,7 +21487,8 @@ this specification: the <abbr>WHATWG</abbr> and the
The rp element can be used to provide parentheses or other content around a ruby
- text component of a ruby annotation, to be shown by user agents that don't support ruby
- annotations.
An rp element that is a child of a ruby
- element represents nothing. An rp element
- whose parent element is not a ruby element represents its
- children.
The rp (“ruby parenthetical”) element represents nothing. It is used to
+ provide fallback presentational content (such as parentheses) to be shown by user agents that do
+ not support ruby layout, and is typically not displayed by user agents that do support ruby
+ layout.
In this example, each ideograph in the text 漢字
+ is annotated with its phonetic reading. Furthermore, it uses rp so that in legacy
+ user agents the readings are in parentheses:
The example above, in which each ideograph in the text 漢字 is annotated with its phonetic reading, could be expanded to
- use rp so that in legacy user agents the readings are in parentheses:
...
-<ruby>漢<rp>（</rp><rt>かん</rt><rp>）</rp>字<rp>（</rp><rt>じ</rt><rp>）</rp></ruby>
-...
+...<ruby>漢<rb>字<rp>（<rt>かん<rt>じ<rp>）</ruby>...In conforming user agents the rendering would be as above, but in user agents that do not - support ruby, the rendering would be:
- -... 漢（かん）字（じ）...
+ In user agents that support ruby layout, the rendering ommit the parentheses, but in user + agents that do not, the rendering would be:
+...漢字（かんじ）...
Here a contrived example showing some symbols with names given in English and French using
+ double-sided annotations, with rp elements as well:
+<ruby>
+ <rb>♥<rp>: <rt>Heart<rp>, <rtc lang=fr>Cœur</rtc><rp>.</rp>
+ <rb>☘<rp>: <rt>Shamrock<rp>, <rtc lang=fr>Trèfle</rtc><rp>.</rp>
+ <rb>✶<rp>: <rt>Star<rp>, <rtc lang=fr>Étoile</rtc><rp>.</rp>
+</ruby>
+ When there are multiple annotations for a segment, rp elements can also be placed
- between the annotations. Here is another copy of an earlier contrived example showing some
- symbols with names given in English and French, but this time with rp elements as
- well:
-
-
<ruby>
-♥<rp>: </rp><rt>Heart</rt><rp>, </rp><rt lang=fr>Cœur</rt><rp>.</rp>
-☘<rp>: </rp><rt>Shamrock</rt><rp>, </rp><rt lang=fr>Trèfle</rt><rp>.</rp>
-✶<rp>: </rp><rt>Star</rt><rp>, </rp><rt lang=fr>Étoile</rt><rp>.</rp>
-</ruby>This would make the example render as follows in non-ruby-capable user agents: - -
♥: Heart, Cœur. ☘: Shamrock, Trèfle. ✶: Star, Étoile.+
This would make the example render as follows in non-ruby-capable user agents:
+♥: Heart, Cœur. ☘: Shamrock, Trèfle. ✶: Star, Étoile.
Organic food in Ireland is certified by the <abbr title="Irish Organic Farmers and Growers Association">IOFGA</abbr>.ruby, rt, rp
+ ruby, rb, rt, rtc, rp
<ruby> OJ <rp>(<rt>Orange Juice<rp>)</ruby><ruby><rb>OJ&<rp>(<rtc><rt>Orange Juice</rtc><rp>)</ruby>data
@@ -105199,15 +105165,28 @@ dictionary StorageEventInit : EventInit {
+
+ An rb element's end tag may be omitted if the
+ rb element is immediately followed by an rb, rt,
+ rtc or rp element, or if there is no more content in the parent
+ element.
An rt element's end tag may be omitted if the
- rt element is immediately followed by an rt or rp element,
- or if there is no more content in the parent element.
rt element is immediately followed by an rb, rt,
+ rtc or rp element, or if there is no more content in the parent
+ element.
+
+
+ An rtc element's end tag may be omitted if the
+ rtc element is immediately followed by an rb or rtc
+ element, or if there is no more content in the parent element.
An rp element's end tag may be omitted if the
- rp element is immediately followed by an rt or rp element,
- or if there is no more content in the parent element.
rp element is immediately followed by an rb, rt,
+ rtc or rp element, or if there is no more content in the parent
+ element.
@@ -116153,7 +116132,24 @@ sup { vertical-align: super; }
sub, sup { line-height: normal; font-size: smaller; }
ruby { display: ruby; }
+rb { display: ruby-base; white-space: nowrap; }
+rbc { display: ruby-base-container; } /* For compatibility with XHTML-inspired markup */
+rp { display: none; }
rt { display: ruby-text; }
+rtc { display: ruby-text-container; }
+ruby, rb, rbc, rt, rtc { unicode-bidi: isolate; }
+rtc, rt {
+ font-variant-east-asian: ruby;
+ text-emphasis: none;
+ white-space: nowrap;
+ line-height: 1;
+}
+rtc, :not(rtc) > rt {
+ font-size: 50%;
+}
+rtc:lang(zh-TW), :not(rtc) > rt:lang(zh-TW) {
+ font-size: 30%;
+}
:link { color: #0000EE; }
:visited { color: #551A8B; }
@@ -116185,22 +116181,9 @@ br[clear=left i] { clear: left; }
br[clear=right i] { clear: right; }
br[clear=all i], br[clear=both i] { clear: both; }
- For the purposes of the CSS ruby model, runs of children of ruby elements that are
- not rt or rp elements are expected to be wrapped in anonymous boxes
- whose 'display' property has the value 'ruby-base'.
When a particular part of a ruby has more than one annotation, the annotations should be - distributed on both sides of the base text so as to minimize the stacking of ruby annotations on - one side.
- -When it becomes possible to do so, the preceding requirement will be updated to be
- expressed in terms of CSS ruby. (Currently, CSS ruby does not handle nested ruby
- elements or multiple sequential rt elements, which is how this semantic is
- expressed.)
User agents that do not support correct ruby rendering are expected to render parentheses
- around the text of rt elements in the absence of rp elements.
rt elements in the absence of rp elements.
@@ -118945,11 +118928,6 @@ if (s = prompt('What is your name?')) {
HTMLQuoteElementrbrubyHTMLElementrprtrubyruby;
+ rtcHTMLElementrtcrubyrtHTMLElementrubyrb;
rt;
+ rtc;
rp*HTMLElementq
HTMLQuoteElement : HTMLElement
+ rb
+ HTMLElement
+
rp
HTMLElement
@@ -125081,6 +125087,10 @@ interface External {
rt
HTMLElement
+ rtc
+ HTMLElement
+
ruby
HTMLElement
@@ -125701,6 +125711,9 @@ INSERT INTERFACES HERE