CSS3 module: Ruby

W3C Working Draft 16 February 2001

This version:

http://www.w3.org/TR/2001/WD-css3-ruby-20010216/
(ZIP archive)

Latest version:

http://www.w3.org/TR/css3-ruby

Previous version:

See Status of This Document

Editors:

Michel Suignard (Microsoft)

Authors:

Marcin Sawicki (former editor)

Michel Suignard (Microsoft)

Copyright © 2001 W3C^® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use, and software licensing rules apply.

Abstract

This document proposes a set of CSS properties associated with the 'Ruby' elements.

Status of This Document

This document is a working draft of the CSS Working Group which is part of the Style activity. It contains a proposal for features to be included in CSS level 3.

Feedback is very much welcomed. Comments can be sent directly to the editor, but the mailing list www-style@w3.org (see instructions) is also open and is preferred for discussion of this and other drafts in the Style area.

This working draft may be updated, replaced or rendered obsolete by other W3C documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". Its publication does not imply endorsement by the W3C membership or the CSS Working Group (members only).

A previous version of the material in this working draft was published as Chapter 7 of International Layout (W3C Working Draft 10 Sept. 1999, http://www.w3.org/TR/1999/WD-i18n-format-19990910/). To find the latest version of this working draft, please follow the "Latest version" link above, or visit the list of W3C Technical Reports.

1. Dependencies on other modules

This CSS3 module depends on the following other CSS3 modules:

• TBD (but will include the module describing 'writing-mode')

It has non-normative (informative) references to the following other CSS3 modules:

• TBD

2. Introduction

There is a number of illustrations in this document for which the following legend is used:

- wide-cell glyph (e.g. Han) which is the n-th character in the text run, they may also appear as half size boxes when used as annotations.
- narrow-cell glyph (e.g. Roman) which is the n-th glyph in the text run.

Many typographical properties in East Asian typography depend on the fact that a character is typically rendered as either a wide or narrow character. All characters described by the Unicode Standard can be categorized by a width property. This is covered by a Unicode Technical report (TR#11) available from the Unicode Web site.

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 in the UA. Spacing between these characters in the diagrams is usually symbolic, unless intentionally changed to make a point.

2.1 What is ruby?

"Ruby" is the commonly used name for a run of text that appears in the immediate vicinity of another run of text, referred to as the "base", and serves as an annotation or a pronunciation guide associated with that run of text. Ruby, as used in Japanese, is described in JIS X-4051 [JIS]. The ruby structure and the HTML markup to represent it is described in the Ruby specification [RUBY]. This section describes the CSS properties relevant to ruby. The following figures show two examples of Ruby.

In the second example, multiple annotations are attached to a base sequence, the hiragana characters on top refer to the pronunciation of the base Kanji characters, while the word 'University' on the bottom is an annotation describing the English translation of the two last Kanji characters of the base. The two examples correspond respectively to two types of ruby: a simple ruby using a simple ruby markup and a complex ruby using a complex ruby markup.

2.2 Ruby box model

In a UA that supports ruby, the ruby structure consists of three or more boxes. The outermost container is the ruby element itself. In the simple case, it is a container for two non-overlapping boxes: the ruby text box (rt element) and the ruby base box (rb element). The positioning of these two boxes relative to each other is controlled by the 'ruby-position' property.

Figure 2.2.1: Ruby box model (simple case)

In the case of complex ruby, the ruby element is a container for two or three non-overlapping boxes: one ruby base collection (rbc element), and one or two ruby text collections (rtc element). The rbc element is itself a container for one or several ruby base box (rb element), while each rtc element is a container for one or several ruby text box (rt element). The position of the rtc element in relation to the related rbc element is controlled by the 'ruby-position' property. The two following figures show examples of these complex ruby.

Figure 2.2.2: Ruby box model (complex ruby with an empty rb element after)

In the example above, the rtc element following the rbc element contains two rt elements with the first one being empty, the empty rt element corresponds to the first part of the ruby base collection (identified by the first rb element within the rbc element)

Figure 2.2.3: Ruby box model (complex ruby with a spanning ruby text element)

In the example above, the rtc element preceding the rbc element spans the whole ruby base collection. The following rtc element still contain two rt elements, one of which is empty. The spanning behavior of rt text elements is controlled by the  rbspan attribute in a way similar to the colspan attribute used for table column.

The width of the ruby box is by default determined by its widest child element, whose width in turn is determined by its content. All ruby's direct children assume the width of the widest one of them. In this respect, the ruby box is much like a two or three row table element, with the following exceptions:

• the ruby box is an inline element, like an image, even though it itself, like a table, is a container of other boxes
• the equivalent of the cells: the rb element and the rt text element can only contain inline-level elements. This also means that a ruby element cannot be embedded into another ruby element.
• the content of each 'cell' is always measured at its maximum width 
• unlike a table, a ruby element doesn't have to fit in a line, the ruby box may be split into several boxes at line boundary, depending of the spanning of the ruby texts. This is however only possible for the complex ruby and can only happen at the boundary of non spanning elements.
• both the ruby text and the ruby base boxes may overlap with adjacent text (outside of the ruby element) if an appropriate 'ruby-overhang' parameter is set via CSS. Note however that the actual content of the ruby base cannot overlap with that adjacent text. The distribution of the content of the ruby base within the ruby base box is controlled by the 'ruby-align' property.

If the ruby text is not allowed to overhang, then the ruby behaves like a traditional box, i.e. only its contents are rendered within its boundaries and adjacent elements do not cross the box boundary:

However, if ruby text is allowed to overhang adjacent elements and it happens to be wider than its base, then the adjacent content is partially rendered within the area of the ruby base box, while the ruby text may be partially overlapping with the upper blank parts of the adjacent content:

The ruby text related to a ruby base can never overhang another ruby base.

The alignment of the contents of the base or the ruby text is not affected by the overhanging behavior. The alignment is achieved the same way regardless of the overhang behavior setting and it is computed before the space available for overlap is determined. It is controlled by the 'ruby-align' property.

The exact circumstances in which the ruby text will overhang other elements, and to what degree it will do so, will be controlled by the 'ruby-overhang' property.

This entire logic applies the same way in vertical ideographic layout, only the dimension in which it works in such a layout is vertical, instead of horizontal.

2.3 Ruby box and line-height

For a line box containing one or several ruby elements the line height is first determined without considering the ruby text elements, i.e. only the ruby base element line height is considered.

If the resulting half-leading values are zero or not large enough to fit the ruby text elements, the half-leading values are increased until these ruby text elements can be fitted into their respective half-leading. Only the half-leading corresponding to the ruby text element to be inserted is increased, the other half-leading is left unchanged from the original computed line height. If both half-leading have ruby text elements, both may be adjusted.

This mechanism allows rendering of evenly spaced lines of text within a block-level element, whether a line contains ruby or not. The authors need only to set for the block-level element a line height value larger than the computed line-height of the larger ruby element within the block.

The same principle applies to the grid layout. Basically, the whole ruby element needs to be considered for sizing purpose, but for alignment purpose, only the ruby base is taken into account.

3. Ruby Properties

3.1 Ruby positioning: the 'ruby-position' property

This property is used by the parent of elements with display: ruby-text to control the position of the ruby text with respect to its base. Such parents are typically either the ruby element itself (simple ruby) or the rtc element (complex ruby). Possible values:

before

The ruby text appears before the base. This is the most common setting used in ideographic East Asian writing systems. This is the initial value.

Figure 3.1.1: Top ruby in horizontal layout applied to Japanese text

If the base appears in a vertical-ideographic layout mode, the ruby appears on the right side of the base and is rendered in the same layout mode as the base (i.e. vertical-ideographic).

Figure 3.1.2: Top ruby in vertical ideographic layout applied to Japanese text

Note the special case of traditional Chinese as used especially in Taiwan: ruby (made of Bopomofo glyphs) in that context can appear along the right side of the base glyph, as if the text were in vertical layout, but the bases themselves are rendered on a horizontal line, since the actual layout is horizontal:

Figure 3.1.3: "Bopomofo" ruby in traditional Chinese (ruby text shown in blue for clarity) in horizontal layout

In order to achieve that effect, vertical-ideographic layout should be set on each individual ruby. That can be accomplished with the following simple CSS rule:

ruby.bopomofo { writing-mode: tb-rl }

after

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

Figure 3.1.4: Bottom ruby in horizontal layout applied to Japanese text

If the base appears in a vertical ideographic mode, the bottom ruby appears on the left side of the base and is rendered in the same layout mode as the base (i.e. vertical).

Figure 3.1.5: Top ruby in vertical ideographic layout applied to Japanese text

right

The ruby text appears on the right of the base. Unlike 'before' and 'after', this value is not relative to the text flow direction.

inline

The ruby text appears inline following the base. The contents of the rp element [RUBY] are displayed. This is the setting that causes ruby to appear the way it would in UAs not supporting the ruby markup.

ruby { ruby-position: inline }

when applied to the following content:

<ruby>AAA<rp>(<rt>aaa<rp>)</ruby>

will be displayed as:

AAA(aaa)

Figure 3.1.6: Inline ruby markup and its result

Except when the 'ruby-position' property is set to the value 'inline', the UA must not display the contents of the rp element [RUBY].

If two rtc elements are set with the same ruby-position value, (for example both 'before'), the two elements will be stacked together with the first declared element closer to the rbc element.

3.2 Ruby alignment: the 'ruby-align' property

This property can be used on any element to control the text alignment of the ruby text and ruby base contents relative to each other. It applies to all the ruby's in the element. For simple ruby, the alignment is applied to the ruby child element whose content is shorter: either the rb element or the rt element [RUBY]. For complex ruby, the alignment is also applied to the ruby child elements whose content is shorter: either the rb element and/or one or two rt elements for each related ruby text and ruby base element within the rtc and rbc element.

Possible values:

auto

The user agent determines how the ruby contents are aligned. This is the initial value. The behavior recommended by [JIS] is for a wide-cell ruby is to be aligned in the 'distribute-space' mode:

Figure 3.2.1: Wide-cell text in 'auto' ruby alignment is 'distribute-space' justified

The recommended behavior for a narrow-cell glyph ruby is to be aligned in the 'center' mode.

Figure 3.2.2: Narrow-width ruby text in 'auto' ruby alignment is centered

start

left

The ruby text content is aligned with the start edge of the base.

Figure 3.2.3: Start ruby alignment

center

The ruby text content is centered within the width of the base. If the length of the base is smaller than the length of the ruby text, then the base is centered within the width of the ruby text.

Figure 3.2.4: Center ruby alignment

end

right

The ruby text content is aligned with the end edge of the base.

Figure 3.2.5: End ruby alignment

distribute-letter

If the width of the ruby text is smaller than that of the base, then the ruby text contents are evenly distributed across the width of the base, with the first and last ruby text glyphs lining up with the corresponding first and last base glyphs. If the width of the ruby text is at least the width of the base, then the letters of the base are evenly distributed across the width of the ruby text.

Figure 3.2.6: Distribute-letter ruby alignment

distribute-space

If the width of the ruby text is smaller than that of the base, then the ruby text contents are evenly distributed across the width of the base, with a certain amount of white space preceding the first and following the last character in the ruby text. That amount of white space is normally equal to half the amount of inter-character space of the ruby text. If the width of the ruby text is at least the width of the base, then the same type of space distribution applies to the base. In other words, if the base is shorter than the ruby text, the base is distribute-space aligned. This type of alignment is sometimes referred to as the "1:2:1" alignment [JIS].

Figure 3.2.7: Distribute-space ruby alignment

line-edge

If the ruby text is not adjacent to a line edge, it is aligned as in 'auto'. If it is adjacent to a line edge, then it is still aligned as in auto, but the side of the ruby text that touches the end of the line is lined up with the corresponding edge of the base. This type of alignment is specified by [JIS]. This type of alignment is relevant only to the scenario where the ruby text is longer than the ruby base. In the other scenarios, this is just 'auto'.

Figure 3.2.8: Line edge ruby alignment

For a complex ruby with spanning elements, one additional consideration is required. If the spanning element spans multiple 'rows' (other rbc or rtc elements), and the ruby alignment requires space distribution among the 'spanned' elements, a ratio must be determined among the 'columns' of spanned elements. This ratio is computed by taking into consideration the widest element within each column.

In the context of this property, the 'left' and 'right' values are synonymous with the 'start' and 'end' values respectively. I.e. their meaning is relative according to the text layout flow. Most of the other CSS properties interpret 'left' and 'right' on an 'absolute' term. See Appendix A of the CSS3 Text Module for further details.

3.3 Ruby overhanging: the 'ruby-overhang' property

This property determines whether, and on which side, ruby text is allowed to partially overhang any adjacent text in addition to its own base, when the ruby text is wider than the ruby base. Note that ruby text is never allowed to overhang glyphs belonging to another ruby base. Also the UA is free to assume a maximum amount by which ruby text may overhang adjacent text. The UA may use the [JIS] recommendation of using one ruby text character length as the maximum overhang length.

Possible values:

auto

The ruby text can overhang text adjacent to the base on either side. [JIS] specifies the categories of characters that ruby text can overhang. The UA is free to follow the [JIS] recommendation or specify its own classes of characters to overhang. This is the initial value.

Figure 3.3.1: Ruby overhanging adjacent text

start

The ruby text can overhang the text that precedes it. That means, for example, that ruby can overhang text that is to the left of it in horizontal LTR layout, or it can overhang text that is above it in vertical-ideographic layout.

Figure 3.3.2: Ruby overhanging preceding text only

end

The ruby text can overhang the text that follows it. That means, for example, that ruby can overhang text that is to the right of it in horizontal LTR layout, or it can overhang text that is below it in vertical-ideographic layout.

Figure 3.3.3: Ruby overhanging following text only

none

The ruby text cannot overhang any text adjacent to its base, only its own base.

Figure 3.3.4: Ruby not allowed to overhang adjacent text

4. The CSS ruby model

The CSS ruby model is based on the XHTML Ruby Annotation module proposal [RUBY], in which the structure of a ruby closely parallels the visual layout  of the ruby element. In this model, a ruby consists of one or more base elements associated with one or more annotation elements.

The CSS model does not require that the document language include elements that correspond to each of these components. 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. The following 'display' values assign ruby semantics to an arbitrary element:

ruby (in XHTML: ruby)

Specifies that an element defines a ruby structure.

ruby-base (in XHTML: rb)

Specifies that an element defines a ruby base.

ruby-text (in XHTML: rt)

Specifies that an element defines a ruby text.

ruby-base-container (in XHTML: rbc)

Specifies that an element contains one or more ruby base.

ruby-text-container (in XHTML: rtc)

Specifies that an element contains one or more ruby text.

Issue: We are not dealing with the RBSPAN attribute at this point. It is felt that it should use the same solution as COLSPAN which is currently left unsolved by the CSS table model.

5. Properties index

6. Profiles

There are two modules defined by this chapter:

CSS3 Simple Ruby model

CSS3 Complex Ruby model.

They both contain all the properties specified by this CSS chapter, i.e. 'ruby-align', 'ruby-overhang' and 'ruby-position'. They differ by the required 'display' property values. The Simple Ruby model requires the values: 'ruby', 'ruby-base' and 'ruby-text'. The Complex Ruby model requires in addition the values: 'ruby-base-container' and 'ruby-text-container'.

Glossary

"Bopomofo"

37 characters and 4 tone markings used as phonetics in Chinese, especially standard Mandarin.

"Hangul"

Subset of the Korean writing system.

"Hanja"

Subset of the Korean writing system that utilizes ideographic characters borrowed or adapted from the Chinese writing system. Also see Kanji.

"Hiragana"

Subset of the Japanese writing system consisting of phonetic characters to represent Japanese words. Also see Katakana.

Ideogram, Ideograph

Character in the Chinese (or East Asian in general) writing system that represents a thing or an idea but not a particular word or phrase for it.

"Kana"

Syllabic subset of the Japanese system of writing that can be used exclusively for writing foreign words or in combination with kanji.

"Kanji"

Subset of the Japanese writing system that utilizes ideographic characters borrowed or adapted from Chinese writing. Also see Hanja.

"Katakana"

Subset of the Japanese writing system consisting of phonetic characters used to represent Roman words. Also see Hiragana.

Logograph, Logogram

Character in the Chinese (or East Asian in general) writing system that represents an entire word.

Ruby

A run of text that appears in the vicinity of another run of text and serves as an annotation or a pronunciation guide for that text.

Acknowledgements

This specification would not have been possible without the help from:

Stephen Deach, Martin Dürst,  Hideki Hiura, Masayasu Ishikawa, Chris Pratley, Takao Suzuki, Frank Tang, Chris Thrasher, Masafumi Yabe, Steve Zilles.

References

[CSS2]

Cascading Stylesheets, level 2 (CSS2) Specification, W3C Recommendation

Bert Bos, Håkon Wium Lie, Chris Lilley and Ian Jacobs, 12 May 1998
Available at: http://www.w3.org/TR/REC-CSS2/

[HTML4]

HTML 4.01 Specification, W3C Recommendation

Dave Raggett, Arnaud Le Hors and Ian Jacobs, 24 December 1999
Available at: http://www.w3.org/TR/REC-html401/

[JIS]

Line composition rules for Japanese documents

JIS X 4051-1995, Japanese Standards Association, 1995 (in Japanese)

[RUBY]

Ruby Annotation, W3C Working Draft

Marcin Sawicki, Michel Suignard, Masayasu Ishikawa, Martin Dürst and Tex Texin, 16 February 2001,
Available at: http://www.w3.org/TR/ruby/

[XSL]

Extensible Stylesheet Language (XSL) Version 1.0, W3C Candidate Recommendation

Sharon Adler (and others), 21 November 2000
Available at: http://www.w3.org/TR/xsl/

Change Log

Changes from the previous publication of the material in this Working Draft, in Chapter 7 of International Layout (W3C Working Draft 10 Sept. 1999, http://www.w3.org/TR/1999/WD-i18n-format-19990910/).