1. Introduction
1.1. What is ruby?
This subsection is not normative.
Ruby is the commonly-used name for a run of text that appears alongside another run of text (referred to as the “base”) and serves as an annotation or a pronunciation guide associated with that run of text.
The following figures show two examples of Ruby, a simple case and one with more complicated structure.
Example of ruby used in Japanese (simple case)
In Japanese typography, this case is sometimes called taigo ruby (Japanese: 対語ルビ, i.e. per-word ruby) or group-ruby, because the annotation as a whole is associated with multi-character word (as a whole).
Complex ruby with annotation text over and under the base characters
Notice that to reflect the correct association of hiragana characters and their corresponding Kanji base characters, the spacing within the base-level text is adjusted. (This happens around the fourth Kanji character in the figure above, which has a three-character phonetic gloss.) To avoid variable spacing of the base text in the example above, the hiragana annotations can be styled as a merged annotation, which will look more like the group-ruby example earlier. However because the base-annotation pairings are recorded in the ruby structure, if the text breaks across lines, the annotation characters will stay correctly paired with their respective base characters.
In HTML, ruby structure and markup to represent it is described in the Ruby Markup Extension specification. This module describes the CSS rendering model and formatting controls relevant to ruby layout of such markup.
A more in-depth introduction to Ruby and its formatting can be found in the “What is Ruby“ article [QA-RUBY]. Extensive information about the main ways ruby has traditionally been formatted in Japanese can be found in JIS X-4051 [JIS4051] (in Japanese) and in “Ruby and Emphasis Dots” in Requirements for Japanese Text Layout [JLREQ] (in English and Japanese); Rules for Simple Placement of Japanese Ruby [SIMPLE-RUBY] also describes (in English) one possible approach for Japanese ruby formatting. “Interlinear annotations” in Requirements for Chinese Text Layout [CLREQ] describes the related practices for Chinese typography (in Chinese and English).
1.2. Module interactions
This module extends the inline box model of CSS Level 2 [CSS2] to support ruby.
None of the properties in this module apply to the ::first-line or ::first-letter pseudo-elements; however ruby-position can inherit through ::first-line to affect ruby annotations on the first line.
1.3. Value Definitions
This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.
In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the CSS-wide keywords keywords as their property value. For readability they have not been repeated explicitly.
1.4. Diagram conventions
This subsection is not normative.
Many typographical conventions in East Asian typography depend on whether the character rendered is wide (CJK) or narrow (non-CJK). There are a number of illustrations in this document for which the following legend is used:
- Wide-cell glyph (e.g. Han) that is the nth character in the text sequence. They are typically sized to 50% when used as annotations.
- Narrow-cell glyph (e.g. Roman) which is the nth glyph in the text sequence.
The orientation which the above symbols assume in the diagrams corresponds to the orientation that the glyphs they represent are intended to assume when rendered by the user agent. Spacing between these characters in the diagrams is incidental, unless intentionally changed to make a point.
2. Ruby Box Model
The CSS ruby model is based on the W3C HTML5 Ruby Markup model and the XHTML Ruby Annotation Recommendation [RUBY]. In this model, a ruby structure consists of one or more ruby base elements representing the base (annotated) text, associated with one or more levels of ruby annotation elements representing the annotations. The structure of ruby is similar to that of a table: there are “rows” (the base text level, each