CSS Ruby Module Level 1

For document languages (such as XML applications) that do not have pre-defined ruby elements, authors must map document language elements to ruby elements; this is done with the 'display' property.

Name:	display
New Values:	ruby | ruby-base | ruby-text | ruby-base-container | ruby-text-container

The following new 'display' values assign ruby layout roles to an arbitrary element:

''ruby''

Specifies that an element generates a ruby container box. (Corresponds to HTML/XHTML <ruby> elements.)

''ruby-base''

Specifies that an element generates a ruby base box. (Corresponds to HTML/XHTML <rb> elements.)

''ruby-text''

Specifies that an element generates a ruby annotation box. (Corresponds to HTML/XHTML <rt> elements.)

''ruby-base-container''

Specifies that an element generates a ruby base container box. (Corresponds to XHTML <rbc> elements; always implied in HTML.)

''ruby-text-container''

Specifies that an element generates a ruby annotation container box. (Corresponds to HTML/XHTML <ruby> elements.)

Anonymous Ruby Box Generation

The CSS model does not require that the document language include elements that correspond to each of these components. Missing parts of the structure are implied through the anonymous box generation rules similar to those used to normalize tables. [[!CSS21]]

1. Any in-flow block-level boxes directly contained by a ruby container, ruby base container, ruby annotation container, ruby base box, or ruby annotation box are forced to be inline-level boxes, and their 'display' value computed accordingly. For example, the 'display' property of an in-flow element with ''display: block'' parented by an element with ''display: ruby-text'' computes to ''inline-block''. This computation occurs after any intermediary anonymous-box fixup (such as that required by internal table elements).
2. Any consecutive sequence of ruby bases not parented by a ruby base container is wrapped in an anonymous ruby base container. Similarly, any consecutive sequence of ruby annotations not parented by a ruby annotation container is wrapped in an anonymous ruby annotation container.
3. Within each ruby base container, each sequence of inline-level boxes is wrapped in an anonymous ruby base box. Similarly, within each ruby annotation container, each sequence of inline-level boxes is wrapped in an anonymous ruby annotation box.
4. A sequence of ruby base containers and/or ruby annotation containers not parented by a ruby container is wrapped in an anonymous ruby container.

At this point, all ruby layout structures are properly parented, and the UA can start to associate bases with their annotations.

Note that the UA is not required to create any of these anonymous boxes in its internal structures, as long as pairing and layout behaves as if they existed.

Ruby Pairing and Annotation Levels

Within a ruby structure, each ruby base is associated with ruby annotations and vice versa. A ruby base can be associated with at most one ruby annotation per annotation level. If there are multiple annotation levels, it can therefore be associated with multiple ruby annotations. A ruby annotation is associated with one or more ruby bases; annotations can span multiple bases.

Annotation pairing is the process of associating ruby annotations with ruby bases.

1. First, the ruby structure is divided into ruby segments, each consisting of a single ruby base container followed by one or more ruby annotation containers. If the first child of a ruby container is a ruby annotation container, an anonymous, empty ruby base container is assumed to exist before it. Similarly, if the ruby container contains consecutive ruby base containers, anonymous, empty ruby annotation containers are assumed to exist between them. The ruby base container in each segment is thus associated with each of the ruby annotation containers in that segment.

   Each ruby annotation containers in a ruby segment represents one level of annotation: the first one represents the first level of annotation, the second one represents the second level of annotation, and so on.

2. Within each ruby segment, each ruby base box in the ruby base container is paired with one ruby annotation box from each ruby annotation container in its ruby segment. If there are not enough ruby annotations in a ruby annotation container, the last one is associated with any excess ruby bases. (If there are not any in the ruby annotation container, an anonymous empty one is assumed to exist.) If there are not enough ruby bases, any remaining ruby annotations are assumed to be associated with empty, anonymous bases inserted at the end of the ruby base container.

   If an implementation supports ruby markup with explicit spanning (e.g. XHTML Complex Ruby Annotations), it must adjust the pairing rules to pair spanning annotations to multiple bases appropriately.

A this point, ruby “columns” are defined, each represented by a single ruby base and associated with one ruby annotation (possibly an empty, anonymous one) from each annotation level.

Nested Ruby

When ruby containers are nested, pairing begins with the deepest ruby container, then expands out, treating each ruby container nested within another ruby container as a ruby base, and associating each ruby annotation associated with the nested ruby container as being associated with (spanning) all of its ruby bases.

Using nested ruby containers thus allows the representation of complex spanning relationships.

This shouldn't belong in Level 1. But HTML5 allows it, so we have to handle it. Yay HTML5.

Autohiding Annotations

If a ruby annotation has the exact same content as its base, it is hidden. Hiding a ruby annotation does not affect annotation pairing or the block-axis positioning of boxes in other levels. However the hidden annotation is not visible, and it has no impact on layout other than to separate adjacent sequences of ruby annotation boxes within its level, as if they belonged to separate segments and the hidden annotation’s base were not a ruby base but an intervening inline.

<ruby>
  <rb>振</rb><rb>り</rb><rb>仮</rb><rb>名</rb>
  <rp>(</rp><rt>ふ</rt><rt>り</rt><rt>が</rt><rt>な</rt><rp>)</rp>
<ruby>

Future levels of CSS Ruby may add controls for this, however in this level it is always forced.

The content comparison for this auto-hiding behavior takes place prior to white space collapsing. Is this easier? Or after collapsing is easier? We should do whatever is easier, as it really doesn't matter much which way to go.

White Space

I'm unsure exactly where space should be trimmed. :/ But pretty sure we need to keep spaces between things, otherwise ruby only works for CJK.

Collapsible white space within a ruby structure is discarded at the beginning and end of a ruby container, and at the beginning/end of a ruby annotation box or ruby base box if white space is not its only contents. Between ruby segments, between ruby bases, and between ruby annotations, however, white space is not discarded. If such white space is collapsible, it will collapse following the standard white space processing rules. [[!CSS3TEXT]] Between ruby segments, however, the contextual text for determining collapsing behavior is given by the ruby bases on either side, not the text on either side of the white space in the source document.

<ruby>
  <rb>東</rb><rb>京</rb>
  <rt>とう</rt><rt>きょう</rt>
</ruby>

<ruby>
  <rb>東</rb>	<rb>京</rb>
  <rt>とう</rt>	<rt>きょう</rt>
</ruby>

Any preserved white space is then wrapped in an anonymous box belonging to the ruby base container (if between ruby bases), ruby annotation container (if between ruby annotations), or ruby container (if between ruby segments). In the latter case, the text is considered part of the base level. This box does not take part in pairing. It merely ensures separation between adjacent bases/annotations.

<ruby>
  <rb>W</rb><rb>W</rb><rb>W</rb>
  <rt>World</rt> <rt>Wide</rt> <rt>Web</rt>
</ruby>

<ruby>
  <rb>Aerith</rb><rb> </rb><rb>Gainsboro</rb>
  <rt>エアリス</rt><rt>・</rt><rt>ゲインズブール</rt>
</ruby>

Specify how this impacts layout, or not.

Ruby layout

When a ruby structure is laid out, its base level is laid out on the line, aligned according to its 'vertical-align' property exactly as if its bases were a regular sequence of inline boxes. Each ruby base container is sized and positioned to contain exactly the full height of its ruby bases.

Ruby annotations associated with the base level are then positioned with respect to their ruby base boxes according to the applicable 'ruby-position' values. Ruby annotations within a level (within a single ruby container) are aligned to each other as if they were inline boxes participating in the same inline formatting context. Each ruby annotation container is sized and positioned to contain exactly the full height of its ruby annotations.

A ruby container (or fragment thereof) measures as wide as the content of its widest level. Similarly, ruby base boxes and ruby annotation boxes within a ruby “column” have the measure of the widest content in that “column”. In the case of spanning annotations (whether actually spanning or pretending to span per 'ruby-collapse'), the measures of the ruby annotation box and the sum of its associated ruby base boxes must match.

How the extra space is distributed when ruby content is narrower than the measure of its box is specified by the 'ruby-align' property.

Inter-character ruby layout

Inter-character annotations have special layout. When 'ruby-position' indicates ''inter-character'' annotations, the affected annotation boxes are spliced into and measured as part of the layout of the base level. The ruby base container must be sized to include both the base boxes as well as the ''inter-character'' annotation boxes The affected ruby annotation container is similarly sized so that its content box coincides with that of the ruby base container.

For the purpose of laying out other levels of annotations, an ''inter-character'' annotation effectively becomes part of its base. Or should it become a quasi-base between two bases? A spanning ''inter-character'' annotation is placed after all the bases that it spans.

Styling Ruby Boxes

In most respects, ruby boxes can be styled similar to inline boxes. However, the UA is not required to support any of the box properties (borders, margins, padding), any of the background properties or outline properties, or any other property that illustrates the bounds of the box on ruby base container boxes, ruby annotation container boxes, or ruby-internal ruby container boxes. The UA may implement these boxes simply as abstractions for inheritance and control over the layout of their contents.

Alternatively... use margins to control offsets? Or could line-height be adequate? Its centering behavior can be awkward.

Ruby box and line breaking

When there is not enough space for an entire ruby container to fit on the line, the ruby may be broken wherever the base level allows a break. Ruby most often breaks between base-annotation sets, but if the line-breaking rules allow it, can also break within a ruby base (and, in parallel, its associated annotation boxes).

Whenever ruby breaks across lines, ruby annotations must stay with their respective bases. The line must not break between a ruby base and its annotations, even in the case of ''inter-character'' annotations.

''inter-character'' ruby line breaking opportunity

Breaking between bases

In typical cases, ruby base boxes and ruby annotation boxes are styled to forbid internal line wrapping and do not contain forced breaks. (See Appendix A.) In such cases the ruby container can only break between adjacent ruby bases, and only if no ruby annotations span those ruby bases.

Whether ruby can break between two adjacent ruby bases is controlled by normal line-breaking rules for the affected text, exactly as if the ruby bases were adjacent inline boxes. (The annotations are ignored when determining soft wrap opportunities for the base level.)

<ruby>蝴<rt>hú</rt>蝶<rt>dié</rt>

Inter-base white space is significant for evaluating line break opportunities between ruby bases. As with white space between inlines, it collapses when the line breaks there. Similarly, annotation white space is also trimmed at a line break.

<ruby><rb>one</rb> <rb>two</rb> <rt>1</rt> <rt>2</rt></ruby>

Breaking within bases

For longer base texts, it is sometimes appropriate to allow breaking within a base-annotation pair. For example, if an English sentence is annotated with its Japanese translation, allowing the text to wrap allows for reasonable line breaking behavior in the paragraph.

Insert scanned example so people don't think this is just the ramblings of an insane spec-writer.

Line-breaking within a ruby base is only allowed if the 'white-space' property of the ruby base and all its parallel annotations allow it, and there exists a soft wrap opportunity within (i.e. not at the start or end) the content of each base/annotation box. Since there is no structural correspondance between fragments of content within ruby bases and annotations, the UA may break at any set of opportunities; but it is recommended that the UA attempt to proportionally balance the amount of content inside each fragment.

There are no line breaking opportunities within ''inter-character'' annotations.

Ruby alignment takes place within each fragment, after line-breaking.

Bidi Reordering

The easiest thing would be to treat each ruby base as an embedding of its 'direction'. But this means that implicit bidi reordering is scoped to within a single base.

Ruby box and line stacking

The 'line-height' property controls spacing between lines in CSS. When inline content on line is shorter than the 'line-height', half-leading is added on either side of the content, as specificed in CSS2.1§10.8. [[!CSS21]]

In order to ensure consistent spacing of lines, documents with ruby typically ensure that the 'line-height' is large enough to accommodate ruby between lines of text. Therefore, ordinarily, ruby annotation containers and ruby annotation boxes do not contribute to the measured height of a line's inline contents; any alignment (see 'vertical-align') and line-height calculations are performed using only the ruby base container, exactly as if it were a normal inline.

However, if the 'line-height' specified on the ruby container is less than the distance between the top of the top ruby annotation container and the bottom of the bottom ruby annotation container, then additional leading is added on the appropriate side of the ruby base container such that if a block consisted of three lines each containing ruby identical to this, none of the ruby containers would overlap.

Note that this does not ensure that the ruby annotations remain within the line box. It merely ensures that if all lines had equal spacing and equivalent amounts and positioning of ruby annotations, there would be enough room to avoid overlap.

Authors should ensure appropriate 'line-height' and 'padding' to accommodate ruby, and be particularly careful at the beginning or end of a block and when a line contains inline-level content (such as images, inline blocks, or elements shifted with 'vertical-align') taller than the paragraph's default font size.

More control over how ruby affects alignment and line layout will be part of the CSS Line Layout Module Level 3. Note, it is currently in the process of being rewritten; the current drafts should not be relied upon.

Ruby Properties

The following properties are introduced to control ruby positioning and alignment.

Ruby positioning: the 'ruby-position' property

This property controls position of the ruby text with respect to its base. Values have the following meanings:

Issue-107:  Roland Steiner has requested the addition of an auto value as default. See this thread and this one.

''over''

The ruby text appears over the base in horizontal text.

Ruby over Japanese base text in horizontal layout

''right''

The ruby text appears on the right side of the base in vertical text.

Ruby to the right of Japanese base text in vertical layout

''under''

The ruby text appears under the base in horizontal text. This is a relatively rare setting used in ideographic East Asian writing systems, most easily found in educational text.

Ruby under Japanese base text in horizontal layout

''left''

The ruby text appears on the left side of the base in vertical text.

Ruby to the left of Japanese base text in vertical layout

''inter-character''

The ruby text appears on the right of the base in horizontal text. This value forces the 'writing-mode' of the ruby annotation to be vertical.

This value is provided for the special case of traditional Chinese as used especially in Taiwan: ruby (made of bopomofo glyphs) in that context appears vertically along the right side of the base glyph, even when the layout of the base characters is horizontal:

“Bopomofo” ruby in traditional Chinese (ruby text shown in blue for clarity) in horizontal layout

Note that the user agent is responsible for ensuring the correct relative alignment and positioning of the glyphs, including those corresponding to the tone marks, when displaying. Tone marks are spacing characters that occur (in memory) at the end of the ruby text for each base character. They are usually displayed in a separate column to the right of the bopomofo characters, and the height of the tone mark depends on the number of characters in the syllable. One tone mark, however, is placed above the bopomofo, not to the right of it.

If multiple ruby annotation containers have the same 'ruby-position', they stack along the block axis, with lower levels of annotation closer to the base text.

Collapsed Ruby Annotations: the 'ruby-merge' property

This property controls how ruby annotation boxes should be rendered when there are more than one in a ruby container box.

Possible values:

''separate''

Each ruby annotation box is rendered in the same column(s) as its corresponding base box(es). This style is called “mono ruby” in [[JLREQ]].

For example, the following two markups render the same:

<ruby>無<rt>む</ruby><ruby>常<rt>じょう</ruby>

and:

<ruby style="ruby-merge:separate"><rb>無<rb>常<rt>む<rt>じょう</ruby>

''collapse''

All ruby annotation boxes within the same ruby segment on the same line are concatenated, and laid out as if their contents belonged to a single ruby annotation box spanning all their associated ruby base boxes. This style renders similar to “group ruby” in [[JLREQ]], except that ruby annotations are kept together with their respective ruby bases when breaking lines.

The following two markups render the same both characters fit on one line:

<ruby>無常<rt>むじょう</ruby>

and:

<ruby style="ruby-merge:collapse"><rb>無<rb>常<rt>む<rt>じょう</ruby>

However, the second one renders the same as ''ruby-position: separate'' when the two bases are split across lines.

''auto''

The user agent may use any algorithm to determine how each ruby annotation box is rendered to its corresponding base box.

One possible algorithm is described as Jukugo-ruby in [[JLREQ]].

Another, more simplified algorithm of Jukugo-ruby is to render as Mono-ruby if all ruby annotation boxes fit within advances of their corresponding base boxes, and render as Group-ruby otherwise.

ruby { display: ruby; }
rb   { display: ruby-base; white-space: nowrap; }
rt   { display: ruby-text; white-space: nowrap; font-size: 50%; }
rbc  { display: ruby-base-container; }
rtc  { display: ruby-text-container; }
ruby, rb, rt, rbc, rtc { unicode-bidi: isolate; }

rt { font-variant-east-asian: ruby; text-emphasis: none; }

ruby, rb, rt, rbc, rtc, rp {
  display: inline; white-space: inherit;
  font-variant-east-asian: inherit; text-emphasis: inherit; }

/* Parens around <rtc> */
rtc::before { content: "("; }
rtc::after  { content: ")"; }

/* Parens before first <rt> not inside <rtc> */
rb  + rt::before,
rtc + rt::before { content: "("; }

/* Parens after <rt> not inside <rtc> */
rb ~ rt:last-child::after,
rt + rb::before  { content: ")"; }
rt + rtc::before { content: ")("; }