Ruby Annotation

1.  Introduction

This section is informative.

This document presents an overview of ruby annotation and defines the markup for it. Several examples are provided. However, this document does not specify any mechanisms for presentation or styling of ruby; this is part of the respective stylesheet languages.

This document is organized as follows:

Section 1.1 gives an overview of Ruby.

Section 1.2 gives an overview of the markup for Ruby.

Section 2 provides the normative definition of ruby syntax. It contains the formal definition of ruby markup in the context of the XHTML Modularization framework [XHTMLMOD].

Section 3 discusses typical rendering and styling of ruby text.

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. 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 annotation 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 of ruby, 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 of ruby to make it easier for most readers to understand the markup defined, all such examples are informational only. This document does not specify any mechanisms for presentation or styling of ruby; this is part of the respective stylesheet languages.

Sometimes more than one ruby annotation is associated with the same base. A typical example is to indicate both meaning as well as reading for the same base text. In such cases, ruby annotations 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 some cases, where a base text has two ruby annotations, each ruby annotation 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 of the ruby annotations is the phrase "Expiration Date". This ruby text is associated with the entire base text. The other ruby annotation 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.

1.2.1 Simple ruby markup

In the simplest case, ruby markup defines a ruby element which contains one rb element for the base text and one rt element for the ruby text. This ruby element therefore creates an association between the base text and the ruby text, and is sufficient for most cases. Here is an example of simple ruby markup:

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

This may be rendered as follows:

Note: The name of this enclosing element, "ruby", should be interpreted to mean that its contents are associating ruby text 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 chosen to compactly and clearly identify the function of the markup construct; the names for the other elements were chosen to keep the overall length short.

1.2.2 Simple ruby markup with parentheses

Some user agents might not understand ruby markup, or may not be able to render ruby appropriately. In either situation, it is generally preferable to render the contents of ruby elements, so information is not lost. A generally acceptable fallback is to place the ruby text immediately after the base text, and to enclose the ruby text in parentheses. The parentheses reduce the potential for confusing the ruby text with other text. (It should be noted that text in parentheses in Japanese typography is never called "ruby".)

For compatibility with older user agents that do not understand ruby markup and simply render the content of elements they do not understand, rp elements can be added to simple ruby markup to distinguish ruby text.

The element name rp stands for "ruby parenthesis". The rp elements and the parentheses (or other characters) inside them are provided as a fallback mechanism only. User agents that ignore unknown elements, but render their contents, will display the contents of each rp element. Therefore the rp element can be used to denote both the beginning and end of ruby text.

User agents that do know about ruby markup will recognize the rp element, and intentionally not display its contents. Instead, they will render the simple ruby markup in a more appropriate way.

The following example demonstrates the use of the ruby parenthesis element:

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

User agents that either:

• do not know about ruby markup but render the contents of unknown elements, or
• cannot render the ruby text alongside the base,

will render the above markup as:

User agents that do know about ruby markup, and that have more sophisticated presentation styles for ruby text, will choose to not render the parentheses. For example, the markup of figure 1.6 can be rendered as shown in the next figure.

1.2.3 Complex ruby markup

Complex ruby markup is used to associate more than one ruby annotation with a base element, or to associate parts of ruby text with parts of base text.

Complex ruby markup provides for multiple rb and rt elements. This specification defines container elements that make the association between the individual elements clear. The ruby base container element, rbc, encloses rb elements. There can be one or two ruby text container elements, rtc, that enclose rt elements. This allows association of two ruby text containers with the same base text. With complex ruby markup it is also possible to associate parts of the base text with parts of a ruby text by using a number of rb elements, and a corresponding number of rt elements. In addition, 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 and td elements in tables ([HTML4], section 11.2.6).

Where and how each part of complex ruby markup is rendered is defined as part of the respective style sheet languages; see also section 3 for further information.

The following example shows all these features.

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

In this example, the first ruby text container encloses 3 components ("Month", "Day", "Year"). Each of these ruby components is associated with a corresponding component in the base text ("10", "31", "2002"). The second ruby container ("Expiration Date") consists of a single ruby element, and is associated with the entire base text ("10 31 2002"). It may be rendered as shown in figure 1.10.

The example shows that the association of ruby text with base text can be more or less granular as needed. For example, the ruby text can be associated with the entire base text in cases where:

• a more detailed relationship is unknown, or
• when the reading or annotation only applies to the whole unit and cannot be split into pieces.

More fine-grained associations can also be made when the relationships are known. For these situations, an improved rendering can therefore be provided. For example, a person's name can be decomposed into family name and given name, or a kanji compound or phrase can be decomposed into semantic subparts or individual characters. With either fine or course granularity, the spans of the ruby text can be set with the corresponding spacing in the base text, and better readability and a more balanced layout may be achieved.

The rp element is not available in the case of complex ruby markup. There are two reasons for this. First, the rp element is only a fallback mechanism, and it was considered that this is much more important for the more frequent simple case. Second, for the more complex cases, it is 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.4 Summary

In summary, the ruby element serves as a container for one of the following:

• a combination of rb, rt and possibly rp elements (simple ruby markup) for:
  • Association of a single ruby text with a single ruby base
  • Fallback in case the ruby markup is not understood.
• a combination of a single rbc and one or two rtc container elements (complex ruby markup) for:
  • Associating two ruby texts with the same ruby base
  • Defining more fine-grained associations between parts of a ruby text and parts of the ruby base.

A.  Ruby module for XHTML

This appendix is informative.

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

• XHTML Ruby Module

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

Complex ruby markup

In this specification: Ruby markup that allows association of two ruby texts with a single ruby base as well as finegrained associations between parts of the ruby texts and the ruby base.

Group ruby

In Japanese typography: Ruby text associated with more than one base character.

Hiragana

Japanese syllabic script, or character of that script. Rounded and cursive in appearance. Subset of the Japanese writing system, used together with kanji and katakana. In recent times, mostly used to write Japanese words when kanji are not available or appropriate, and word endings and particles.

Ideograph

Character that is used to represent an idea, word, or word component, in contrast to a character from an alphabetic or syllabic script. The most well-known ideographic script is used (with some variation) in East Asia (China, Japan, Korea,...).

Kana

Collective term for hiragana and katakana.

Katakana

Japanese syllabic script, or character of that script. Angular in appearance. Subset of the Japanese writing system, used together with kanji and hiragana. In recent times, mainly used to write foreign words.

Kanji

Japanese term for ideographs; ideographs used in Japanese. Subset of the Japanese writing system, used together with hiragana and katakana.

Monoruby

In Japanese typography: Ruby associated with a single base character.

Reading

For ideographs: Technical term; indication of possible pronunciation. Different from pronunciation in various respects: script used may not be fully phonetic; actual pronunciation is speaker-dependent; pronunciation may not be realized when reading a text silently. In Chinese or Korean, some ideographs have several readings. In Japanese, most ideographs have at least two readings, and some have a lot more. Readings also may depend on context.

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.

Simple ruby markup

In this specification: Ruby markup that associates a single ruby text with a single ruby base, optionally providing some delimiters such as parentheses for fallback.

D.  Changes from previous public Working Draft

This appendix is informative.

Changes since http://www.w3.org/TR/2001/WD-ruby-20010216: Minor editorial changes only.

Changes since http://www.w3.org/TR/1999/WD-ruby-19991217:

The only change in the actual markup defined was to change the content model for simple ruby from (rb, rp?, rt, rp?) to (rb, (rt | (rp, rt, rp))) to allow two or zero rp elements, but not a single one.

The whole spec has been rewritten substantially, while keeping to the previous version. The main editorial changes are:

• Creation of Sections 3 (styling and rendering); moving most of the examples and the rendering discussions to this section.
• Change of terminology to use 'simple ruby markup' and 'complex ruby markup' for the markup variants, and avoid confusion with group ruby and monoruby, which have clearly defined meanings in Japanese typography.
• Redesign of the various examples to be more consistent with Japanese typographical practice.

Acknowledgements

This section is informative.

Takao Suzuki (鈴木 孝雄) and Chris Wilson have contributed to previous drafts as editors.

This specification would not have been possible without the help from the members of the W3C I18N WG, in particular Mark Davis and Hideki Hiura (樋浦 秀樹), and the members of the W3C I18N IG.

Additional contributors include Murray Altheim, Laurie Anna Edlund, Arye Gittelma, Koji Ishii, Rick Jelliffe, Eric LeVine, Chris Lilley, Charles McCathieNevile, Shigeki Moro (師 茂樹), Chris Pratley, Nobuo Saito (斎藤 信男), Rahul Sonnad, Chris Thrasher.

The markup defined in this specification was coordinated with the ruby markup in [JIS4052], developed by WG 2 (Typesetting) of the Electronic Document Processing System Standardization Investigation and Research Committee of the Japanese Standards Association. We would like to thank the members of WG 2, in particular Kohji Shibano (芝野 耕司, chair), and Masafumi Yabe (家辺 勝文, liaison), for their collaboration. Technically, the markup for ruby in [JIS4052] differs from the markup in this specification in two points: First, there is an alternative form of markup not compatible with XML, based on special symbols, and second, the rp element is not permitted.

Valuable Last Call comments were also received from: The HTML WG, the CSS WG, the XSL WG, the WAI P&F WG, Steven Pemberton, Trevor Hill, Susan Lesch, and Frank Yung-Fong Tang.

An earlier proposal for markup for ruby, using attributes, is described in [DUR97].