Ruby Annotation

1.  Introduction

This section is informative.

1.1  What is ruby?

"Ruby" is the commonly used name for a run of text that appears in the immediate vicinity of another run of text, referred to as the "base". Ruby serve as a pronunciation guide or a short annotation associated with the base text. Ruby are used frequently in Japan in most kinds of publications, such as books and magazines, but also in China, especially in schoolbooks. Figure 1.1.1 shows an example.

East Asian typography has developed various elements that do not appear in western typography. Most of these can be addressed appropriately with style sheet languages such as CSS or XSL. Ruby, however, require markup in order to define the association between the base text and the ruby text.

This specification defines such markup, designed to be usable with XHTML, in order to make ruby available on the Web without using special workarounds or graphics. This section gives some background on ruby. Section 1.2 gives an overview of the markup for ruby. Section 2 contains the formal definition of ruby markup in the context of the XHTML Modularization framework [XHTMLMOD].

The remainder of this section gives some background on the structure and use of ruby. Because presentation is part of this background, it is discussed here. However, it should be noted that this document does not specify any mechanisms for presentation/styling of ruby; this is part of the respective stylesheet languages.

The font size of ruby text is normally about half the font size of the base text (see Figure 1.1.1). The name "ruby" in fact originated from the name of the 5.5pt font size in British printing, which is about half the 10pt font size commonly used for normal text.

There are several positions where the ruby text can appear relative to its base. For horizontal layout, where text appears along horizontal lines, ruby are most frequently placed above the base text (see Figure 1.1.1), i.e. before the line containing the base text. Sometimes, especially in educational texts, ruby may appear below, i.e. after, the base text. In Chinese, it is rather common that Pinyin ruby appear after the base text.

In typical vertical layout, where text appears along vertical lines starting on the right, ruby appear on the right side of (i.e. again before) the vertical line if they appear above in horizontal layout. The writing direction of the ruby text is the same as that of its base, that is vertical if the base is vertical, and horizontal if the base is horizontal.

Ruby text appears on the left side of the base in vertical layout if it appears below it in horizontal layout.

Because East Asian text may be rendered vertically as well as horizontally, the terms "before" and "after" are used in this document rather than "above" and "below" or "right side" and "left side". In this specification, the term "before" means "above" in horizontal layout / "right side" in vertical (in this context, top-to-bottom, right-to-left) layout, and the term "after" means "below" in horizontal layout / "left side" in vertical layout.

Ruby before the base text are often used to indicate pronunciation; ruby after the base text are often used to indicate meaning. In this and other cases, it can happen that ruby appear on both sides of the base text.

In some cases, it is desirable to give more details about which parts of the ruby base and which parts of the ruby text are associated together. Such a structure is called group ruby. This can be used for finetuning of the display or for other operations. Using fine-grained associations, and in particular showing the association with each single character of the base text, is mainly used in educational texts and other cases where the exact association is important or potentially unknown.

More coarse-grained association is used when the actual details of the association on a lower level are assumed to be known to the reader anyway, or unknown because the pronunciation or annotation only applies to the whole unit and cannot be split into pieces. Because in such cases longer spans of ruby text are set with the same spacing, better readability and more even layout may be achieved. For example, a person name can be decomposed into family name and given name. Or a kanji compound or phrase can be decomposed to show semantic subparts, as in the following example:

In the above example, the ruby text before the base text is made of two sequences: the hiragana sequence p"でんわ" (denwa) for "phone", and the hiragana sequence "ばんごう" (bango) for "number"; the ruby text after the base text is a single English sequence: "Phone number". Note that the space in the base text in Figure 1.1.6 and similar figures was added to make the structure of the examples clearer; in general, no space is used between ideographs in the base text.

In the following example, the ruby text after, "University", relates to the second base sequence while the ruby texts before, "けいおうぎじゅく" and "だいがく" (keiou gijyuku daigaku; Keio University in hiragana) refer to the two base sequences.

Details of ruby formating in a Japanese print context can be found in JIS-X-4051 [JIS].

In traditional Chinese, "Bopomofo" ruby can appear along the right side of the ruby base, even in horizontal layout.

Note that Bopomofo tone marks (in the above example shown in red for clarity) appear in a separate column (along the right side of the Bopomofo ruby) and therefore might be seen as "ruby on ruby". However, they are encoded as combining characters that are simply part of the ruby text.

Introducing ruby to the Web leads to some phenomena and problems that are not present in traditional typography where the term "ruby" is taken from. The term "ruby" in Japanese is only used for text alongside the base text, for example as shown in the various figures above. However, once structural markup for ruby is defined as done in this specification, there is no guarantee that the associations defined by this markup will always be rendered alongside the base text. There is and will be a very wide variety of current and future output devices for documents marked up with XHTML. The following are possible scenarios and reasons for different rendering:

• Some user agents might not understand ruby markup, and may not be able to render ruby appropriately. In this case, it is preferable to nevertheless render the contents of ruby elements, in order not to lose information. The most acceptable fallback will be to place the ruby text immediately after the base text, and to enclose the ruby text in parentheses to reduce the potential for confusion (see Figure 1.1.9 below). However, it should be noted that this is only a fallback, and text in parentheses in Japanese typography is never called "ruby". Also, when ruby are rendered alongside the base text, they are not enclosed in parentheses.
• On display devices with low resolution, displaying ruby at half the point size of the base text may not be feasible. Again, a fallback with parentheses may be used.
• For educational purposes, it may be interesting to hide the ruby text and make it available as a pop-up. This is impossible on paper, but easily possible on a dynamic display device.
• On non-visual user agents such as voice browsers and braille user agents, only sequential rendering is possible. Depending on the function of the annotations, both the base text and the annotations, or only the annotations, may be rendered.

Using parentheses for the fallback may lead to confusion between runs of text intended to be the ruby text and others that happen to be enclosed within parentheses. The document or style sheet author should be aware of the potential for that confusion and is advised to choose an unambiguous delimiter for the fallback, if this is a concern.

1.2  Ruby markup

This section gives an overview of the markup for ruby defined in this specification. A formal definition can be found in Section 2. The markup is written in XML [XML].

The core of the markup is the ruby element. The ruby element encloses all the text and markup necessary for defining the association between the base text and the ruby texts.

Note. The name of this enclosing element, "ruby", should be interpreted to mean that what follows is associating ruby with base text. It must not be misunderstood to mean that everything inside, including the base text, is ruby. The name of the enclosing element was choosen to compactly and clearly identify the function of the markup construct; the names for the other elements were choosen to keep the overall length short.

The ruby element serves as a container for one of the following:

• a combination of rb, rt and possibly rp elements (for simple cases)
• a combination of a single rbc and one or two rtc elements (for more complicated cases, such as group ruby).

In the following, these two cases are discussed in more detail.

1.2.1  Simple Ruby markup

For the simple case, the rb element contains the base text, the rt element contains the ruby text, and the optional rp elements contain the parenthesis characters used in the fallback case. rb stands for "ruby base", rt for "ruby text", and rp for "ruby parenthesis". This allows a simple association between one base text and one ruby text, and is sufficient for most cases.

For example, the following simple ruby:

can be represented as follows:

<ruby>
  <rb>WWW</rb>
  <rp>(</rp><rt>World Wide Web</rt><rp>)</rp>
</ruby>

The rp elements and the parentheses inside them are provided for fallback only. Some user agents, which ignore unknown elements but render their contents, will render the above markup as "WWW (World Wide Web)". The rp element identifies the parentheses (or whatever else that may be used in their place) to user agents that know about the markup defined in this specification so that the parentheses can be removed. If the author is not concerned about fallbacks for user agents that neither know about ruby markup nor support CSS2 [CSS2] or XSL [XSL] style sheets, then the rp elements are not needed:

<ruby>
  <rb>WWW</rb>
  <rt>World Wide Web</rt>
</ruby>

In [CSS2], if necessary, the parentheses can be generated using the 'content' property ([CSS2], section 12.2) with the :before and :after pseudo-elements ([CSS2], section 12.1), as for example in the following style declaration:

rt:before { content: "(" }
rt:after { content: ")" }

In the above example, parentheses will be automatically generated around the rt element. It is assumed that the above style rules are used together with style rules that position the ruby text inline. Generation of parentheses is straightforward with XSLT [XSLT].

1.2.2  Group Ruby markup

For more complicated cases of associations between a base text and some ruby texts, a combination of rbc and rtc elements is used. This includes associating more than one ruby texts with the same base text (typically rendered on both sides of the base text) and fine-grained associations of the base text and the ruby text (group ruby). The ruby element contains one rbc element followed by one or two rtc elements. The rbc element contains rb elements, the rtc element contains rt elements. Several rb elements inside an rbc element, combined with several rt elements inside an rtc element, are used for group ruby. The rt element may use the rbspan attribute to indicate that a single rt element spans (is associated with) multiple rb elements. This is similar to the colspan attribute of the th/td elements in tables. The rbc stands for "ruby base component", and the rtc for "ruby text component".

An example of group ruby is shown in the following figure:

can be represented as follows:

<ruby xml:lang="ja" class="pronunciation annotation">
  <rbc>
    <rb>斎</rb>
    <rb>藤</rb>
    <rb>信</rb>
    <rb>男</rb>
  </rbc>
  <rtc class="pronunciation">
    <rt>さい</rt>
    <rt>とう</rt>
    <rt>のぶ</rt>
    <rt>お</rt>
  </rtc>
  <rtc class="annotation">
    <rt rbspan="4" xml:lang="en">W3C Associate Chairman</rt>
  </rtc>
</ruby>

In this case, the rtc element with the class "pronunciation" should be associated with the style information that places the ruby texts before the ruby bases, and the rtc element with the class "annotation" should be associated with the style information that places the ruby texts after the ruby bases.

The rp element is not available in this representation. This has two reasons. First, the rp element is for fallback only, and it was considered that this is much more important for the more frequent simple case. Second, for the more complex cases, it is in many cases very difficult to come up with a reasonable fallback display, and constructing markup for such cases can be even more difficult if not impossible.

1.2.3  Notes on styling ruby

This specification only defines ruby markup. Formatting properties for styling ruby are under development for CSS and XSL. See "International Layout" [I18N-FORMAT] (work in progress) for more details.

Note that for non-visual rendering such as speech synthesis, rendering both the base text and the ruby text can be annoying. This is in particular the case if the ruby represent a pronunciation. In this case, a speech synthesizer may either be able to correctly pronounce the base text, in which case the same text is spoken twice, or it may not know the correct pronounciation of the text and make up a pronounciation, in which case the result may be quite confusing.

As an example, in the case of Figure 1.2.2.2, the ruby bases "斎", "藤", "信", "男" are less useful than the ruby texts "さい" (sai), "とう" (tou), "のぶ" (nobu), "お" (o) for non-visual rendering, and it does not make sense to render both the ruby bases and the ruby texts. Because in this case, the ruby texts are used to represent pronunciation, so it is straightforward to use them for non-visual rendering. In such cases, something like the following style information may help.

@media aural {
  ruby[class~="pronunciation"] rb { speak: none }
}

The above style sheet will suppress aural rendering of the ruby base when the rb element is a descendant element of the ruby element with the class "pronunciation". See [CSS2] for more details.

Note that ruby used as a pronunciation guide may be different from the actual pronunciation even in cases where the script used for indicating the pronunciation at first glance seems perfectly phonetic. For example, Bopomofo is associated independently for each base character; context-dependent sound or tone changes are not reflected in ruby. Similarly, in Japanese, spelling irregularities can occur, such as using "は" (ha) for the topic suffix pronounced "わ" (wa). For such cases, authors may want to supply two variants, distinguished by the value of the class attribute, or may rely on the aural rendering system being able to handle such cases correctly.

It is also important to note that not all ruby are pronunciations. Authors should distinguish ruby used for different purposes by using the class attribute, as done above by assuming class="pronunciation" for ruby used to indicate pronunciation. Also, it should be noted that somebody listening to aural rendering may be interested in accessing the skipped base text to check the characters used.

A.  Ruby module for XHTML

This appendix is informative.

The following is a link to the Ruby DTD module that will be part of the XHTML 1.1 DTD modules [XHTML11].

• XHTML 1.1 Ruby Module

B.  Notes on backwards compatibility

This appendix is informative.

For historical reason, some authoring tools might generate ruby markup without the start and end tags of the rb element, like:

<ruby>
  A
  <rp>(</rp><rt>aaa</rt><rp>)</rp>
</ruby>

rather than the following:

<ruby>
  <rb>A</rb>
  <rp>(</rp><rt>aaa</rt><rp>)</rp>
</ruby>

The former markup is not conforming to this specification, but user agents that care about compatibility with documents generated by such authoring tools may treat the former markup as if it were written like the latter.

C.  Glossary

This appendix is informative.

Bopomofo

37 characters and 4 tone marks used as phonetics in Chinese, especially standard Mandarin.

Group ruby

A set of ruby that uses fine-grained associations between the ruby bases and the ruby texts.

Hiragana

Subset of the Japanese writing system consisting of phonetic characters to represent Japanese words.

Kana

Syllabic subset of the Japanese system of writing that can be used exclusively for writing foreign words or in combination with kanji.

Kanji

Subset of the Japanese writing system that utilizes ideographic characters borrowed or adapted from Chinese writing.

Ruby base

Run of text that has a ruby text associated with it.

Ruby text

Run of text that appears in the immediate vicinity of another run of text (called "ruby base") and serves as an annotation or a pronunciation guide associated with the base.

D.  Changes from previous public Working Draft

This appendix is informative.

Acknowledgements

This section is informative.

The model presented in this specification was originally inspired by the work done by Martin Dürst [DUR97].

This specification would also not have been possible without the help from:

Murray Altheim, Mark Davis, Laurie Anna Edlund, Arye Gittelma, Hideki Hiura (樋浦 秀樹), Koji Ishii, Rick Jelliffe, Eric LeVine, Chris Lilley, Charles McCathieNevile, Shigeki Moro (師 茂樹), Chris Pratley, Nobuo Saito (斎藤 信男), Rahul Sonnad, Takao Suzuki (鈴木 孝雄), Chris Thrasher, Chris Wilson, Masafumi Yabe (家辺 勝文).