Ruby Annotation

1.1 What is ruby?

Ruby is the term used for a run of text that is associated with another run of text, referred to as the base text. Ruby text is used to provide a short annotation of the associated base text. It is most often used to provide a reading (pronunciation guide). Ruby annotations are used frequently in Japan in many kinds of publications, including books and magazines. Ruby is also used in China, especially in schoolbooks.

Ruby text is usually presented alongside the base text, using a smaller typeface. 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. Figure 1.1 shows an example, with three ideographs (kanji) as base text, and six hiragana giving the reading (shinkansen - Japanese bullet train).

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

This specification defines such markup, designed to be usable with XHTML, so that ruby text is available on the Web without using special workarounds or graphics. Although this specification gives examples of actual rendering to make it easier for most readers to understand the markup, all such examples are informational only. This document does not specify any mechanisms for presentation or styling; this is part of the respective style sheet languages.

Sometimes more than one ruby text is associated with the same base text. A typical example is to indicate both meaning as well as reading for the same base text. In such cases, ruby texts may appear on both sides of the base text. Ruby text before the base text is often used to indicate reading; ruby text after the base text is often used to indicate meaning. Figure 1.2 shows an example of base text with two ruby texts, giving reading using hiragana and Latin letters.

In addition, each ruby text may be associated with different, but overlapping, parts of the base text, such as in the following example:

In this example, the base text is the date "10 31 2002". One ruby text is the phrase "Expiration Date". This ruby text is associated with the entire base text. The other ruby text has 3 parts: "Month", "Day" and "Year". Each part is associated with a different part of the base text. "Month" is associated with "10", "Day" is associated with "31", and "Year" is associated with "2002".

1.2 Ruby markup overview

The markup defined in this specification is designed to cover all the above cases, namely markup for one or two ruby texts associated with the same base text and markup for associations of substrings of the ruby text(s) with components of the base text.

There are two variants of ruby markup, called simple ruby markup and complex ruby markup. Simple ruby markup associates a single ruby text with a run of base text. Simple ruby markup can also specify a fallback mechanism to allow display of ruby text by (older) browsers that do not know about ruby markup. Complex ruby markup can associate two ruby texts with one base text, and can define a more fine-grained association between components of the ruby text and the base text. However, complex ruby markup does not provide a fallback mechanism for browsers that do not understand ruby markup.

This section gives an overview of the markup for ruby defined in this specification. A full formal definition can be found in Section 2.

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

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

<ruby>
  <rbc>
    <rb>10</rb>
    <rb>31</rb>
    <rb>2002</rb>
  </rbc>
  <rtc>
    <rt>Month</rt>
    <rt>Day</rt>
    <rt>Year</rt>
  </rtc>
  <rtc>
    <rt rbspan="3">Expiration Date</rt>
  </rtc>
</ruby>

3.1 Ruby on the Web vs. traditional typographic usage

The term "ruby" in Japanese is only used for text visually rendered alongside the base text. Considerations for such cases are given in section 3.2 (font size), section 3.3 (positioning), and section 3.4 (presentation of ruby markup). This kind of presentation should be used wherever possible. However, introducing ruby to the Web may lead to some phenomena and problems that are not present in traditional typography. Structural markup for ruby, as defined in this specification, cannot guarantee that ruby text will always be rendered alongside the base text. There are 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:

• On non-visual user agents such as voice browsers and braille user agents, only sequential rendering is possible. See section 3.5 for more consideration on non-visual rendering.
• On display devices with low resolution, displaying ruby text at the usual size may not be feasible. Fallbacks may be used. See section 3.6 for additional details.
• For educational purposes, it may in some cases 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.

3.2 Font size of ruby text

In typical usage, the font size of ruby text is normally about half the font size of the base text. In fact, the name "ruby" 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.

3.3 Positioning of ruby text

There are several positions where the ruby text can appear relative to its base text. Because East Asian text may be rendered vertically as well as horizontally, the terms "before" and "after" are used here rather than "above" and "below" or "right side" and "left side". The words "before" and "after" should be understood as "before"/"after" the line containing the base text. The correspondence is shown in the following table:

Ruby texts are most frequently placed before the base text (see figure 1.1 and figure 3.2). Sometimes, especially in horizontal educational documents, ruby text may appear after the base text, i.e. below (see figure 3.1). In Chinese, it is rather common that Pinyin ruby text appears after the base text. Ruby text may also appear after the base text in vertical layout (see figure 3.3). In all these cases, the writing direction of the ruby text is the same as that of its base text, that is vertical if the base text is vertical, and horizontal if the base text is horizontal.

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

Note that Bopomofo tone marks (in the above example shown in red for clarity) seem to appear in a separate column (along the right side of the Bopomofo ruby text) and therefore might be seen as "ruby on ruby". However, they are simply encoded as part of the ruby text. The details of this encoding are not addressed in this document.

3.4 Presentation of ruby markup

This specification does not prescribe how ruby markup will be displayed. Style sheets, in general, will be used to specify the exact behavior of ruby markup.

In order for style sheets to be able to apply styling, or for other mechanisms to render ruby text appropriately, it is very important to provide enough information on the function of each component. The following example illustrates the use of the class attribute to allow style sheets to define the exact presentation of the ruby text. The class "reading" is used for a ruby text that indicates reading. The class "annotation" is used to indicate ruby text that is used for annotation. The xml:lang attribute indicates the language of the text.

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

Using a style sheet specifying horizontal text, rendering of the reading before the base text, and rendering of the annotation after the base text, the markup above could be rendered like this:

3.5 Considerations for non-visual rendering

Documents containing ruby markup may in some cases need to be rendered by non-visual user agents such as voice browsers and braille user agents. For such rendering scenarios, it is important to understand that:

• Depending on the user and the situation, different ways of rendering may be appropriate.
• Ruby text that represents reading may have to be treated differently from ruby text that contains other information.
• For appropriate non-visual rendering, it is important to indicate the function of each ruby text.
• There often are some differences between the reading indicated by the ruby text and the actual pronunciation.
• The reader may be interested in getting information about the (ideographic) base text.

Depending on a user's needs, the way a text should be read may vary from very quick and 'cursory' reading to very careful and detailed reading. This may lead to different ways of treating ruby text in non-visual rendering, from skipping ruby text in fast reading to detailed exploration of the ruby structure and the actual characters used in careful reading.

In the frequent case that ruby texts represent reading, rendering both the base text and the ruby text may produce annoying duplications. A speech synthesizer may be able to correctly pronounce the base text based on a large dictionary, or it may in other cases be able to select the right pronunciation based on the reading given by the ruby text.

Not all ruby texts represent pronunciations. Authors should distinguish ruby texts used for different purposes by using the class attribute. This is demonstrated above by using class="reading" for ruby text used to indicate reading.

Ruby text indicating reading may not produce the correct pronunciation even in cases where the script used at first glance seems perfectly phonetic. For example, Bopomofo is associated independently for each character of the base text; context-dependent sound or tone changes are not reflected. Similarly, in Japanese, spelling irregularities can occur, such as using "は" (hiragana ha) for the topic suffix pronounced "わ" (wa), or using vowels for indicating lengthening. For such cases, authors may want to supply the actual pronunciation with special markup designed for that purpose, or may rely on the aural rendering system being able to handle such cases correctly.

3.6 Alternatives to the rp element

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.

Nevertheless, it is possible to parenthesize ruby text as a fallback if for example the device resolution is not appropriate for traditional ruby rendering. Using [CSS2], 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 fragment:

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].