H62: Using the ruby element

Applicability

User Agent and Assistive Technology Support Notes

Ruby markup includes the rp element as a fallback mechanism for user agents that do not
support XHTML 1.1. Although ruby markup is only defined in XHTML 1.1, IE 5.0 and later
supports the ruby, rt, and rp elements even if they are
used in HTML 4.01 or XHTML 1.0.

Description

The objective of this technique is to use ruby annotation to provide information about
the pronunciation and meaning of a run of text where meaning is determined by
pronunciation.

There are many languages in which a run of text may mean different things depending on
how the text is pronounced. This is common in East Asian languages as well as Hebrew,
Arabic, and other languages; it also occurs in English and other Western European
languages.

Ruby Annotation allows the author to annotate a "base text," providing a guide to
pronunciation and, in some cases, a definition as well. Ruby is commonly used for text
in Japanese and other East Asian languages. Ruby Annotation is defined as a module for
XHTML 1.1.

There are two types of Ruby markup: simple and complex. Simple Ruby markup applies to a
run of text such as a complete word or phrase. This is known as the "base" text
(rb element). The Ruby annotation that indicates how to pronounce the term (the
rt element, or Ruby text) is shown in a smaller font. (The term "Ruby" is
derived from a small font used for this purpose in printed texts.) The Ruby text is
usually rendered above or immediately before the base text, that is, immediately above
horizontal text or immediately to the right of vertical text. Sometimes Japanese uses
Ruby to provide the meaning of text on the other side of the base text (visually) from
the phonetic annotation. Simple Ruby markup also provides a "fallback" option for user
agents that do not support Ruby markup (that is, user agents that do not support XHTML
1.1).

Complex Ruby markup makes it possible to divide the base text into smaller units, each
of which may be associated with a separate Ruby annotation. Complex Ruby markup does not
support the fallback option.

Ruby annotation is uncommon in languages such as Hebrew, where Unicode fonts can
include diacritical marks that convey pronunciation. It is also uncommon in English and
European languages.

Note: The primary reason for indicating pronunciation through Ruby or any other means
is to make the content accessible to people with disabilities who could read and
understand the language of the content if information about pronunciation were provided.
It is not necessary to provide information about pronunciation for use by people who are
not familiar with the language of the content.

Examples

This example uses Ruby annotation to give the pronunciation of the initialism
(acronym) formed by the first letters of the words Web Content Accessibility
Guidelines. The letters WCAG are the base (the rb element), and the pronunciation
information is shown by the Ruby text (the rt element). The Ruby parenthesis element
rp is used for user agents that do not support Ruby annotations to
indicate that the text in the rt element provides the pronunciation
information. The pronunciation information is rendered in parentheses immediately
following the base text. (User agents that support Ruby do not show the
parentheses.)

Example Code:

<p>When we talk about these guidelines, we often just call them
<ruby>
<rb>WCAG</rb>
<rp>(</rp>
<rt>Wuh-KAG</rt>
<rp>)</rp>
</ruby>.
</p>

Example 2: Ruby annotation for Japanese

The following is an example in Japanese. For Japanese, the Ruby is used to give
the reading of Han characters(Kanji). the Ruby parenthesis element rp is
used for user agents that do not support Ruby annotations to indicate that the text
in the rt element provides the pronunciation information. The pronunciation
information is rendered in parentheses immediately following the base text. (User
agents that support Ruby do not show the parentheses.)

Related Techniques

Tests

Procedure

For each run of text where a Ruby annotation is used to provide pronunciation
information:

Check that a rt element contains pronunciation information for each
run of text defined by the rb element.

If simple Ruby markup is used, check that the rp element is present
to indicate to user agents that do not support Ruby annotations that the text in
the rt element provides the pronunciation information. .