"Ruby" are short runs of text alongside the base text, typically used in
East Asian documents to indicate pronunciation or to provide a short
annotation. This specification defines markup for ruby, in the form of an
XHTML module [XHTMLMOD].

This section describes the status of this document at the time of its
publication. Other documents may supersede this document. The latest status of this series of
documents is maintained at the W3C.

This document has been reviewed by W3C Members and other interested
parties and has been endorsed by the Director as a W3C Recommendation. It is
a stable document and may be used as reference material or cited as a
normative reference from another document. W3C's role in making the
Recommendation is to draw attention to the specification and to promote its
widespread deployment. This enhances the functionality and interoperability
of the Web.

Due to its subject matter, and to make the examples more realistic, this
document includes examples using a wide range of characters. Not all user
agents may be able to display all characters. Depending on the user agent,
changing the configuration can improve the situation. Also, great care has
been taken to serve this document in various character
encodings to cover a wide range of user agents and configurations.

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 annotation; this
is part of the respective style sheet languages.

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

Figure 1.1: Ruby text giving the reading of each
character of the base text.

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.

Figure 1.2: Two ruby texts applied to the same base
text.

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

Month

Day

Year

10

31

2002

Expiration Date

Figure 1.3: Base text with two ruby texts using different
associations

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

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.

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:

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.

Some user agents might not understand ruby markup, or may not be able to
render ruby text appropriately. In either situation, it is generally
preferable to render ruby text, so that 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.

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.

Complex ruby markup is used to associate more than one ruby text with a
base text, 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.

Figure 1.9: Complex ruby markup to associate two ruby
texts with different parts of the same base text.

In this example, the first ruby text container encloses 3 components
("Month", "Day", "Year"). Each of these components is associated with a
corresponding component in the base text ("10", "31", "2002"). The second
ruby text container ("Expiration Date") consists of a single ruby text, 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.

This section contains the formal syntax definition and the specification
of the functionality of the ruby markup. Some familiarity with the XHTML Modularization
framework, in particular the "Modularization of XHTML" [XHTMLMOD] specification, is assumed.

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

The ruby element is an inline (or text-level) element that
serves as an overall container. It contains either the rb, rt and
optional rp elements (simple ruby markup) or
the rbc and rtc elements (complex ruby markup).

In the case of simple ruby markup, the ruby element contains
either an rb element followed by an rt element, or a sequence of an rb element, an rp
element, an rt element and another rp element. The content of the rt element is taken as ruby text and associated
with the content of the rb
element as the base text. The content of the rp elements, if present, is ignored.

In the case of complex ruby markup, the ruby element contains
an rbc element followed by one or two rtc elements. The content of the subelements of
each rtc element is taken as ruby text and
associated with the content of the subelements of the rbc element as the base text.

The ruby element has common attributes only. Examples of
common attributes include: id, class or
xml:lang. Common attributes depend on the markup language with
which ruby markup is used. In the case of [XHTML 1.1],
these are defined in XHTML
Modularization, Section 5.1 [XHTMLMOD].

The rtc (ruby text container) element serves as the container
for rt elements in the case of complex ruby
markup. One or two rtc elements may appear inside a ruby element to associate ruby texts with a
single base text, represented by an rbc
element. More than two rtc elements MUST NOT appear inside a ruby element.

The rb (ruby base) element serves to markup the base text.
For simple ruby markup, only one rb element may appear. For
complex ruby markup, multiple rb elements may appear inside an
rbc element. Each rb element is
associated with a corresponding rt element,
for fine-grained control of ruby presentation.

The rb element may contain inline elements or character data
as its content, but the ruby element is not
allowed as its descendant element.

The rt element is the markup for ruby text. For simple ruby
markup, only one rt element may appear. For complex ruby markup,
multiple rt elements may appear inside an rtc element, and each rt element
contains the ruby text for the relevant base text, represented by the
corresponding rb element.

The rt element may contain inline elements or character data
as its content, but the ruby element is not
allowed as its descendant element.

The rt element has common attributes and the
rbspan attribute. In complex ruby markup, 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"). The rbspan attribute should not be used in simple
ruby markup, and user agents should ignore the rbspan attribute
when it appears in simple ruby markup.

The rp element can be used in the case of simple ruby markup
to specify characters that can denote the beginning and end of ruby text when
user agents do not have other ways to present ruby text distinctively from
the base text. Parentheses (or similar characters) can provide an acceptable
fallback. In this situation, ruby text will only degrade to be rendered
inline and enclosed in the fallback parentheses. This is the least
inappropriate rendering under the condition that only inline rendering is
available. The rp element cannot be used with complex ruby
markup.

The rp element has common attributes only.

Using parentheses for the fallback may lead to confusion between runs of
text intended to be ruby text and other runs 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.

This section discusses various aspects of rendering and styling in the
context of ruby markup as defined in this document. However, this document
does not specify any mechanisms for presentation/styling; this is left to the
respective style sheet languages. Formatting properties for styling ruby are
under development for CSS
and XSL. See for example
"CSS3 module: Ruby" [CSS3-RUBY]
(work in progress) for more details.

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

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.

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.

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:

terminology

Horizontal Layout
(left-to-right, top-to-bottom)

Vertical Layout
(top-to-bottom, right-to-left)

before

above

right-side

after

below

left-side

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.

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.

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.

Note. Although the rendering of the ruby texts should be
controlled by style sheets, in case no style information is provided by the
author or the user, it is recommended that visual user agents place the ruby
text before the base text when only one ruby text is used. This is also the
case for simple ruby. When there are two ruby texts, the first ruby text
should be placed before the base text, and the second ruby text should be
placed after the base text. A sample user agent default style sheet which
describes this formatting will be provided by [CSS3-RUBY] or its successor document.

For non-visual rendering, in the absence of style sheet information, it is
recommended that both the base text and the ruby text(s) should be rendered,
with an indication (e.g. different voice, different pitch, ...) of the status
of each.

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.

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

Within the context of this specification, conformance can be claimed for
markup, document types, module implementations, documents, generators, and
interpreters. In most of these cases, two levels of conformance are
available: simple conformance and full conformance. Simple conformance means
that the conforming object supports the minimal content model of the ruby
element in section
2.1, i.e. only simple ruby markup. Full conformance means that the
conforming object supports the maximal content model of the ruby element in
section 2.1,
i.e. that both simple and complex ruby markup are supported.

Markup is conforming simple ruby markup if it contains one or
more ruby elements and the content of all those elements
(including their children) conforms to the minimal content model in section 2.1 (i.e.
only simple ruby markup is allowed). Markup is conforming full ruby
markup if it contains one or more ruby elements and the
content of all those elements (including their children) conforms to the
maximal content model in section 2.1 (i.e.
both simple and complex ruby markup is allowed).

A document type is a conforming simple ruby markup document type
if it integrates conforming simple ruby markup by adding the
ruby element to the appropriate elements (such as inline
elements) and by defining the necessary elements and attributes. A document
type is a conforming full ruby markup document type if it integrates
conforming full ruby markup by adding the ruby element to the
appropriate elements (such as inline elements) and by defining the necessary
elements and attributes.

A module implementation (e.g. with DTD or XML Schema technology) is a
conforming simple ruby module implementation if it is designed to
integrate simple ruby markup with other modules into document types as
described above. A module implementation is a conforming complex ruby
module implementation if it is designed to integrate full ruby markup
with other modules into document types as described above. A module
implementation is a conforming full ruby module implementation if it
is designed to integrate either simple or full ruby markup with other modules
into document types as described above (e.g. by providing a switch, or by
providing two separate module implementations).

A document is a conforming simple ruby markup document if it
contains conforming simple ruby markup and does not contain complex ruby
markup or non-conforming ruby markup. A document is a conforming full
ruby markup document if it contains conforming full ruby markup and does
not contain non-conforming ruby markup.

A generator is a conforming simple ruby markup generator if it
generates conforming simple ruby markup and does not generate complex ruby
markup or non-conforming ruby markup. A generator is a conforming full
ruby markup generator if it generates conforming full ruby markup and
does not generate non-conforming ruby markup.

An interpreter is a conforming simple ruby markup interpreter if
it rejects nonconforming simple ruby markup, accepts conforming simple ruby
markup, and, where it interprets ruby markup, does so in accordance with this
specification. An interpreter is a conforming full ruby markup
interpreter if it rejects nonconforming ruby markup, accepts conforming
full ruby markup, and, where it interprets ruby markup, does so in accordance
with this specification. Examples of interpreters are server-side analysis or
transformation tools and renderers.

For XHTML Modularization conformance, please see section 3 of [XHTMLMOD].

This appendix is informative. This appendix contains some notes
on design decisions, based on questions and comments received during the Last
Call review.

There were proposals to change e.g. <rbc><rb>...</rbc>
to <rb><rbc>...</rb> (and similar for rt/rtc). This looks
in some way more natural. However, in XML, the content of an element is
either mixed content (both character data and elements, without sequence or
occurrence restrictions) or element content (only elements, with
restrictions). This means that it is impossible to say that <rb>
contains either only <rbc> elements or only character data and inline
elements.

There were various proposals for removing the rp element from the minimal content model. They were
considered, but rejected for the following reasons:

Recognition and removal of the rp
elements by a receiver understanding ruby markup is extremely simple to
implement; the burden on implementations is minimal. Both CSS and XSL
provide easy mechanisms to remove the rp
elements or to avoid displaying them.

Displaying ruby text in parentheses is not desirable, because it can be
confused with ordinary parenthesized text, but such a confusion is highly
preferable to the confusion created should ruby text appear inline, as
part of the actual text, without any distinguishing features.

It was suggested to change the names of the elements, in particular to
change <ruby> to <gloss>. However, while ruby markup is indeed
in some way similar to the markup that would be needed for glosses, it is not
designed for that purpose.

For historical reasons, 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.

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.

A 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,...).

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.

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.

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.