ruby element
If you don't know what an element is or how you must use it, I recommend you read the "HTML tags and attributes" tutorial that you can find in the HTML tutorials section.
Table of contents
Description
The ruby
element provides the means to apply ruby annotations to a run of text. Ruby annotations are short pieces of text that run alongside base text and provide some type of aid to process it. They are mostly used in asian typography, but can be useful for any type of annotations.
Ruby annotated text is marked with the ruby
element, while rt
provides annotations for all the non-annotated characters found at its left. Additionally, the rp
element provides means to hide additional information used to improve the readability in non-supporting browsers. The text inside ruby
elements is displayed as a single run of text in browsers that doesn't support it, for which it could be reasonable to provide, for example, parenthesis (hidden inside the rp
element) to wrap the annotation.
Ruby annotations are usually rendered with a smaller font size and on top of the base text. For a better comprehension of how things work, in supporting and non-supporting browsers, we'll take a look at the following code and its approximate rendering in both cases. Parenthesis are provided inside the rp
element to aid non-supporting browsers.
This is how the annotation should look in a supporting browser. Note how all the text inside rp
elements is completely ignored.
<ruby>Base text<rp> (</rp><rt>Annotation</rt><rp>)</rp></ruby>
Annotation
Base text
Now, this is how non-supporting browsers display the text, ignoring all elements and just showing the information in a simple run of text.
<ruby>Base text<rp> (</rp><rt>Annotation</rt><rp>)</rp></ruby>
Base text (Annotation)
Note: remember that these are only emulations achieved with other supported elements and basic CSS styling.
Examples
The first example contains the word "Tokio" written in japanese. Annotations are provided in hiragana for each character (kanji), serving as a phonetic aid for the reader. This kind of annotation is one of the most common uses for these elements.
<p><ruby>東<rp>(</rp><rt>とう</rt><rp>)</rp>京<rp>(</rp><rt>きょう</rt><rp>)</rp></ruby></p>
東京
Our second example, shows another type of annotations. In this case, the symbols in a poker deck are annotated in order to provide their names and enhance comprehension.
<p>The four symbols in the poker deck are <ruby>♥<rp> (</rp><rt>heart</rt><rp>)</rp></ruby>, <ruby>♠<rp> (</rp><rt>spade</rt><rp>)</rp></ruby>, <ruby>♣<rp> (</rp><rt>club</rt><rp>)</rp></ruby> and <ruby>♦<rp> (</rp><rt>diamond</rt><rp>)</rp></ruby>.</p>
The four symbols in the poker deck are ♥, ♠, ♣ and ♦.
The third example shows a classical text, where some uncommon or ancient english words are annotated with synonyms to help readers comprehend their meaning easily.
<p>Against the which a <ruby>moiety<rp> (</rp><rt>faction, side</rt><rp>)</rp></ruby> competent<br>Was <ruby>gagèd<rp> (</rp><rt>obliged</rt><rp>)</rp></ruby> by our king, which had returned<br>To the inheritance of Fortinbras</p>
Against the which a moiety competent
Was gagèd by our king, which had returned
To the inheritance of Fortinbras
The fourth example shows an annotation in which the languages are also specified, for the annotated text as well as for the annotation itself.
<p>Hi everybody! I'm finally in <ruby lang="jp">東京<rt lang="en">Tokyo</rt></ruby>!</p>
Hi everybody! I'm finally in 東京!
Attributes
Global attributes
For information about global attributes refer to this list of global attributes in HTML5.
Events
Global events
For information about global events refer to this list of global events in HTML5.