ruby
elementHTMLElement
.The ruby
element allows one or more spans of
phrasing content to be marked with ruby annotations. Ruby
annotations are short runs of text presented alongside base text,
primarily used in East Asian typography as a guide for
pronunciation or to include other annotations. In Japanese, this
form of typography is also known as furigana.
The content model of ruby
elements consists of one or more of the
following sequences:
ruby
elements and with no ruby
element descendantsruby
element, but with no further
ruby
element descendantsThe ruby
and rt
elements can be used for a variety of kinds of
annotations, including in particular those described below. For
more details on Japanese Ruby in particular, and how to render Ruby
for Japanese, see Requirements for Japanese Text
Layout. [JLREQ]
At the time of writing, CSS does not yet provide a
way to fully control the rendering of the HTML ruby
element. It is hoped that CSS will be
extended to support the styles described below in due course.
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 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. [JLREQ]
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.)
In this example, the name of a species of flowers has a phonetic reading provided using group ruby:
<ruby>紫陽花<rt>あじさい</ruby>
紫陽花
Sometimes, ruby styles described above are combined.
<ruby>BASE<rt>annotation 1<rt>annotation 2</ruby>
<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. [DOMCORE]
At any particular time, the segmentation and categorisation 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 ruby
element for which the algorithm is
being run.
If root has a ruby
element 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 rt
or rp
element, 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 ruby
element, 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 rt
or rp
element, 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 rt
element, then push a ruby annotation and jump
to the step labeled annotation mode increment.
If the indexth node in current
parent is an rp
element, jump to the step labeled
annotation mode increment.
If the 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.
Annotation mode increment: Let lookahead index be index plus one.
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.
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.
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).
Increment lookahead index by one.
Jump to the step labeled annotation mode white-space skipper.
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 thost lists is implicitly in an ignored
segment.
When the steps above say to set the current base text, it means to run the following steps at that point in the algorithm:
Let text range a DOM range whose start is the boundary point (current parent, start index) and whose end is the boundary point (current parent, index).
Let new text segment be a base text segment described by the range annotation range.
Add new text segment to base text segments.
Let current base text be new text segment.
Let start index be null.
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.
When the steps above say to pop a ruby level, it means to run the following steps at that point in the algorithm:
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.
When the steps above say to push a ruby annotation, it means to run the following steps at that point in the algorithm:
Let rt be the rt
element that is the indexth node of current parent.
Let annotation range 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.
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:
In this example, each ideograph in the traditional Chinese text 漢字 is annotated with its bopomofo reading.
<ruby>漢<rt>ㄏㄢˋ</rt>字<rt>ㄗˋ</rt></ruby>
This might be rendered as:
In this example, each ideograph in the simplified Chinese text 汉字 is annotated with its pinyin reading.
...<ruby>汉<rt>hàn</rt>字<rt>zì</rt></ruby>...
This might be rendered as:
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>