W3C Working Draft 24 September 1999

This version:
Latest version:
Also available for local browsing as a Zipped archive
Previous version:
Marcin Sawicki (Microsoft)
Michel Suignard (Microsoft)
Masayasu Ishikawa (W3C)
Martin Dürst (W3C)
(See Acknowledgements for additional contributors)

Status of This Document

This is a W3C Working Draft for review by W3C members and other interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. The W3C will not allow early implementation to constrain its ability to make changes to this specification prior to final release. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". A list of current W3C Working Drafts can be found at http://www.w3.org/TR.

This W3C Working Draft is published by the Internationalization Working Group (members only). In a future version, this work is intended to be submitted to the HTML Working Group (members only) for inclusion as a module in the XHTML 1.1 [XHTML11].

As is characteristic of a W3C Working Draft, all the proposed tag naming and structure in this document are subject to change.

Please send comments and questions regarding this document to i18n-editor@w3.org (archived for W3C members). Comments in languages other than English, in particular Japanese, are also welcome.


The HyperText Markup Language (HTML) is a simple markup language used to create hypertext documents that are portable from one platform to another. XHTML 1.0 [XHTML1] is a reformulation of HTML 4.0 [HTML4] as an XML 1.0 [XML] application, and the modularization of XHTML [XHTMLMOD] provides a means for subsetting and extending XHTML. This specification extends XHTML to support ruby text typically used in East Asian documents. Some familiarity with HTML 4.0, XHTML 1.0 and the XHTML Modularization framework is assumed.


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 an annotation associated with the base text. Ruby are used frequently in Japan in most kinds of publications, such a books and magazines, but also in China, especially in schoolbooks. Figure 1.1.1 shows an example.

Example showing ruby above the base in horizontal Japanese text

Figure 1.1.1: Ruby giving the pronunciation of the base characters.

East Asian typography has developed various elements that do not appear in western typography. Most of these can be addressed appropriately with facilities in stylesheet languages such as CSS or XSL. Ruby, however, require markup in order to define the association between base text and ruby text. This document defines such markup, designed to be usable with HTML, 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 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, it is 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.

Example of ruby below the base in horizontal mode

Figure 1.1.2: Ruby (in Latin letters) below the base text (in Japanese)

In vertical layout, where lines are placed 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 layout flow 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.

Example showing ruby on the right side of base in vertical Japanese text

Figure 1.1.3: Ruby in vertical text (before/to the right)

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

Example showing ruby on the left side of base in vertical Japanese text

Figure 1.1.4: Ruby in vertical text (after/to the left).

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.

Example showing ruby text applied above and below the base

Figure 1.1.5: Ruby applied above and below a line of Japanese 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. 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 or irrelevant; due to the fact that in such cases, longer spans of ruby text are set with the same spacing, better readability and more even layout may be achieved. Such a structure is called group ruby. 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:

Example showing group ruby, with the Japanese sequences above and the English sequence below

Figure 1.1.6: Group ruby with text below spanning the group

In the example, the ruby text above is made of two sequences: the hiragana sequence 'でんわ' (denwa) for 'phone' and the hiragana sequence 'ばんごう' (bango) for 'number'; the ruby text below is a single English sequence: 'Phone number'.

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

Example showing group ruby, with the Japanese sequences above and the English sequence below only spanning the second part

Figure 1.1.7: Group ruby with text below only spanning the second part

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

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 document, there is no guarantee that the associations defined by this markup will always be rendered alongside the base text. There is a very wide variety of current and future output devices for documents marked up with HTML. The following are possible scenarios and reasons for different rendering:

Example showing ruby within parentheses inline with the base in horizontal Japanese as a fallback

Figure 1.1.8: Inline ruby applied to horizontal Japanese as a fallback

Using parentheses for the fallback may lead to confusion between runs of text intended to be ruby text and others that happen to be enclosed within parentheses. The 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 document. A formal definition can be found in Section 2. The markup is 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 base text and ruby text. 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:

In the following, these two cases are discussed in more detail. For the simple case, the rb element contains the base text, the rt element contains the ruby text, and the rp elements contains the parenthesis characters used in the fallback case. The rb stands for 'ruby base', the rt for 'ruby text', and the rp for 'ruby parenthesis'. This allows a simple association between one base text and one ruby text, and is sufficient for most ruby cases.

For example, the following simple ruby:

Example showing ruby above the base in horizontal English text

Figure 1.2.1: Ruby applied to English

can be represented as follows:

  <rt>World Wide Web</rt>

Figure 1.2.2: Example of simple ruby markup including rp elements for fallbacks

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

  <rt>World Wide Web</rt>

Figure 1.2.3: Example of simple ruby markup without rp elements for fallbacks

In CSS2, if necessary, the parentheses can be generated using the 'content' property of the :before and :after pseudo-elements as for example in the following style declaration:

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

Figure 1.2.4: CSS2 style sheets to generate parentheses around rt element

In the above example, parentheses are automatically generated around the rt element. It is assumed that the style information for positioning the ruby text inline is used together. Generation of parentheses in XSL is straightforward.

For more complicated cases of associations between base text and ruby text, a combination of rbc and rtc elements is used. This includes associating more than one ruby text with the same base text (typically displayed on both sides of the base text) and fine-grained associations of base text and ruby text (group ruby). The ruby element contains one rbc element followed by one or more rtc elements. The rbc element contains rb elements, the rtc element contains rt elements. Several rtc elements are used to associate more than one ruby text with the same base text. 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:

Example showing a group ruby in horizontal Japanese text

Figure 1.2.5: Group ruby with mixed above and below ruby texts

can be represented as following:

<ruby xml:lang="ja" class="pronunciation annotation">
  <rtc class="pronunciation">
  <rtc class="annotation">
    <rt rbspan="4" xml:lang="en">W3C Associate Chairman</rt>

Figure 1.2.6: Ruby markup to achieve both above and below ruby text on the same base.

In this case, the rtc element with the class "pronunciation" should be associated with the style information to place the ruby texts above the ruby bases, and the rtc element with the class "annotation" should be associated with the style information to place the ruby text below the ruby bases.

This document only defines ruby markup. Formatting properties for styling ruby are under development not for HTML/XML, but for CSS/XSL. See "International Layout" [I18N-FORMAT] (work in progress) for more details.

The rp element is not available in this representation. This has two reasons. First, the rp element is for backwards compatibility 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.

Some readers may wonder why two new elements, rbc and rtc, were introduced for this case, instead of using a single new element inside rb and rt. This was done because in XML, it is impossible to express that an element should contain either only text (#PCDATA) or only a certain combination of elements. In XML, as soon as #PCDATA is allowed somewhere directly within an element, this element has mixed content, and #PCDATA is allowed everywhere directly within that element.

Note. For non-visual rendering, such as speech synthesis and braille output, 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.6, the ruby bases "", "", "", "" are less useful than the ruby texts "さい" (sai), "とう" (tou), "のぶ" (nobu), "" (o) for aural or braille rendering, and it does not make sense to render both the ruby bases and the ruby texts, because aural and braille rendering are phonetic-based and in this case 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 }

Figure 1.2.7: CSS2 style sheet to suppress aural rendering of ruby base

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

It is important to note that not all ruby are pronunciations. Authors should distinguish ruby used for different purposes by using the HTML 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 skiped base text to check the characters used.

2.  Formal definition of ruby elements

This section is normative.

This section contains the formal syntax definition and the specification of the functionality of the ruby elements.

2.1  Abstract definition of ruby elements

The following is the abstract definition of ruby elements, which is consistent with the XHTML Modularization framework [XHTMLMOD]. Further definitions of XHTML abstract modules can be found in [XHTMLMOD].

Elements Attributes Minimal Content Model
ruby Common ((rb, rp?, rt, rp?) | (rbc, rtc+))
rbc Common rb+
rtc Common rt+
rb Common (PCDATA | Inline - ruby)*
rt Common, rbspan (CDATA) (PCDATA | Inline - ruby)*
rp Common PCDATA*

Ed. Note. The definition of "Inline" doesn't include ruby element in [XHTMLMOD], but for convenience, the above abstract definition assumes that the ruby element is included as one of inline elements.

An implementation of this abstract definition as the XHTML DTD modules can be found in Appendix A.

2.2  The ruby element

The ruby element is an inline (or text-level) element that serves as the container for either the rb, rp and rt elements or the rbc and rtc elements. It provides the structural association between the ruby base elements and their ruby text elements.

The ruby element does not accept any attributes other than the common ones, such as id, class, xml:lang or style.

In this simplest example, ruby text "aaa" is associated with base "AA":


Figure 2.2.1: Simple usage of the ruby element

2.3  The rbc element

The rbc element is the container for rb elements. This element is not used for simple ruby, and is only used for group ruby. Only one rbc element may appear inside a ruby element.

2.4  The rtc element

The rtc element is the container for rt elements. This element is not used for simple ruby, and is only used for group ruby. Several rtc elements may appear inside a ruby element to associate multiple ruby texts with a single ruby base, represented by an rbc element.

For example, the following markup, utilizing CSS from "International Layout" [I18N-FORMAT] (work in progress) may be used to associate two ruby texts with the same ruby base:

  <rtc style="ruby-position: above">
  <rtc style="ruby-position: below">

Figure 2.4.1: Ruby markup to achieve both above and below ruby on the same base.

The markup above would be rendered as:


Figure 2.4.2: The result of two ruby texts associated to a single ruby base.

2.5  The rb element

The rb element is the container for the text of the ruby base. For simple ruby, only one rb element may appear. For group ruby, multiple rb elements may appear inside an rbc element.

The rb element may contain inline elements or character data as its content, but the ruby element may not appear as its child element.

2.6  The rt element

The rt element is the container for the ruby text. For simple ruby, only one rt element may appear. For group ruby, multiple rt elements may appear inside an rtc element.

The rt element may contain inline elements or character data as its content, but the ruby element may not appear as its child element.

The rbspan attribute allows an rt element to span multiple rb elements. The value shall be an integer value greater than zero ("0"). The default value of this attribute is one ("1"). An example of this is shown in Figures 1.2.5 and 1.2.6.

2.7  The rp element

The rp element is intended to contain parenthesis characters. Parentheses are necessary for the ruby to be rendered correctly when it is inline. The existence of the rp element is necessary especially for UA's that are unable to render ruby text above the ruby base. That way, any ruby will degrade to no worse than a properly formed inline ruby in non-supporting UA's. The rp element cannot be used in group ruby.

Consider the following markup, specifying an above (default) ruby:


Figure 2.7.1: Ruby markup using rp elements

A user agent that supports above ruby would render it as:


Figure 2.7.2: Above ruby rendered by a supporting UA (note the parentheses are not visible)

However, a UA that is unable to render above ruby or does not support ruby HTML, would still correctly show:


Figure 2.7.3: Above ruby rendered by a non-supporting UA (note the parentheses are visible)


A.  Ruby modules in XHTML

This appendix is normative.

The following is the Ruby DTD modules, a DTD driver and a catalog file that can be used with the XHTML 1.1 DTD modules [XHTML11]. These modules are conforming to the Module Conformance requirements as defined in the "Building XHTML Modules" specification [BUILDING].

Ed. Note: These modules are expected to be included in the XHTML 1.1 and are not intended to define a new markup language as an XHTML-family document type, so names are temporary and slightly different from the Naming Rules in the XHTML Family Document Type Conformance.

B.  Ruby usage in SGML

This appendix is informative.

Ed. Note: Do we really need an SGML definition?

Although this specification defines ruby elements in XML, there might be some usage in SGML. This appendix provides a sample ruby DTD fragments in SGML. The functionality of the ruby elements are defined in section 2.

Note that in the SGML DTD, elements and attributes are intended to be case-insensitive, and in some cases, end tags can be omitted. For example, Figure 1.2.2 can be described using the following markup in SGML, where it is possible to omit the end tags of rb, rt and rp:

  <rt>World Wide Web

Figure B.1: Ruby markup example in SGML

For convenience, parameter entities %inline; and %attrs; are used to represent generic inline elements and generic attributes. In the case of HTML [HTML4], these are something like this:

<!-- %inline; covers inline or "text-level" elements -->
<!ENTITY % inline "#PCDATA | %fontstyle; | %phrase; | %special; | %formctrl; | ruby">

<!ENTITY % attrs "%coreattrs; %i18n; %events;">

Further definitions can be found in [HTML4].

B.1  The ruby DTD fragments in SGML

<!ELEMENT ruby - - ((rb, rp?, rt, rp?) | (rbc, rtc+))>
<!ATTLIST ruby %attrs; >

<!ELEMENT rbc - O (rb)+ -- container for rb elements -->
<!ATTLIST rbc %attrs; >

<!ELEMENT rtc - O (rt)+ -- container for rt elements -->
<!ATTLIST rtc %attrs; >

<!ELEMENT rb - O (%inline;)* - (ruby) -- container for ruby base -->
<!ATTLIST rb %attrs; >

<!ELEMENT rt - O (%inline;)* - (ruby) -- container for ruby text -->
  rbspan      NUMBER         1         -- number of rbs spanned by rt -->

<!ELEMENT rp - O (#PCDATA) -- container for parenthesis characters -->
<!ATTLIST rp %attrs; >

C.  Glossary

This appendix is informative.

Group ruby
A set of ruby that uses fine-grained associations between the ruby bases and the ruby texts.
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 ("ruby base") and serves as an annotation or a pronunciation guide associated with the base.

D.  Acknowledgements

This appendix is informative.

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

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

Mark Davis, Laurie Anna Edlund, Arye Gittelman, Hideki Hiura, Koji Ishii, Eric LeVine, Chris Lilley, Charles McCathieNevile, Chris Pratley, Nobuo Saito, Rahul Sonnad, Takao Suzuki, Chris Thrasher, Chris Wilson, Masafumi Yabe.

E.  References

This appendix is informative.

"Building XHTML Modules", W3C Working Draft
Murray Altheim, Shane P. McCarron, 10 September 1999
Available at: http://www.w3.org/TR/xhtml-building
"Cascading Style Sheets, level 2 (CSS2) Specification", W3C Recommendation
Bert Bos, Håkon Wium Lie, Chris Lilley and Ian Jacobs, 12 May 1998
Available at: http://www.w3.org/TR/REC-CSS2
"Ruby in the Hypertext Markup Language", Internet Draft
Martin Dürst, 28 February 1997, expired
Available at: http://www.w3.org/International/draft-duerst-ruby-01
"HTML 4.0 Specification", W3C Recommendation
Dave Raggett, Arnaud Le Hors and Ian Jacobs, 18 December 1997, revised 24 April 1998
Available at: http://www.w3.org/TR/REC-html40
"International Layout", W3C Working Draft
Marcin Sawicki, 10 September 1999
Available at: http://www.w3.org/TR/i18n-format
"Line composition rules for Japanese documents"
JIS X 4051-1995, Japanese Standards Association, 1995 (in Japanese)
"XHTML 1.0: The Extensible HyperText Markup Language — A Reformulation of HTML 4.0 in XML", W3C Proposed Recommendation
Steven Pemberton et al., 24 August 1999
Available at: http://www.w3.org/TR/xhtml1
"XHTML 1.1 — Module-based XHTML", W3C Working Draft
Murray Altheim, Shane McCarron, 10 September 1999
Available at: http://www.w3.org/TR/xhtml11
"Modularization of XHTML", W3C Working Draft
Shane P. McCarron, et. al., 10 September 1999
Available at: http://www.w3.org/TR/xhtml-modularization
"Extensible Markup Language (XML) 1.0 Specification", W3C Recommendation
T. Bray, J. Paoli, C. M. Sperberg-McQueen, 10 February 1998
Available at: http://www.w3.org/TR/REC-xml
"Extensible Style Language (XSL)", W3C Working Draft
Stephen Deach, 21 April 1999
Available at: http://www.w3.org/TR/WD-xsl

F.  Changes from previous public Working Draft

This appendix is informative.

Section Change
Status of This Document
  • Removed mentions of ruby naming and structure control as issues to be discussed at the next WG meeting. This draft is the result of that meeting.
  • Added mention to the expected inclusion into the XHTML 1.1.
  • Rewrote completely. Mentioned relationship with the XHTML Modularization.
1. Introduction
  • Separated the section into "What is ruby?" and "Ruby markup", and marked this section as informative.
  • Introduced the concept of group ruby.
  • Provided several examples of group ruby with syntax.
  • Removed the concept of ruby nesting.
  • Changed top/bottom to above/below to be consistent with style values (for now). Started to introduce before/after.
    Ed. Note. Shall we use before/after to be consistent with the XSL?
  • Added note for non-visual rendering.
2. Formal definition of ruby elements
  • Completely restructured this section; moved SGML definitions to Appendix B, and replaced XML definitions with the abstract definition which is consistent with the XHTML Modularization.
  • Changed ruby element content model to allow group ruby (rbc and rtc).
  • Inserted rbc and rtc definitions.
  • Removed nesting from rb element.
  • Added rbspan attribute to rt element.
Appendix A. Ruby modules in XHTML
  • Added this appendix to include DTD modules that can be used with the XHTML 1.1 DTD modules. This appendix is normative.
Appendix B. Ruby usage in SGML
  • Added this appendix and moved SGML definitions from section 2, and marked as informative.
Appendix C. Glossary
  • Marked this appendix as informative.
  • Added glossary for group ruby.
Appendix D. Acknowledgements
  • Added additional contributors, and marked this appendix as informative.
Appendix E. References
  • Added references to "Building XHTML Modules", "XHTML 1.1", "Modularization of XHTML", "XML 1.0", "XSL" and updated references to "International Layout" and "XHTML 1.0".
  • Marked this appendix as informative.
Appendix F. Changes from previous public Working Draft
  • Marked this appendix as informative.