Title: CSS Ruby Layout Module Level 1
Shortname: css-ruby
Level: 1
Status: ED
Work Status: Exploring
Group: csswg
ED: https://drafts.csswg.org/css-ruby-1/
TR: https://www.w3.org/TR/css-ruby-1/
Previous Version: https://www.w3.org/TR/2014/WD-css-ruby-1-20140805/
Previous Version: https://www.w3.org/TR/2013/WD-css3-ruby-20130919/
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Koji Ishii, Google, kojiishi@gmail.com, w3cid 45369
Editor: Xidorn Quan, Mozilla https://www.mozilla.org/, https://www.upsuper.org/, w3cid 73936
Editor: Florian Rivoal, Invited Expert, https://florian.rivoal.net/, w3cid 43241
Abstract: “Ruby”, a form of interlinear annotation, are short runs of text alongside the base text.
Abstract: They are typically used in East Asian documents to indicate pronunciation or to provide a short annotation.
Abstract: This module describes the rendering model and formatting controls related to displaying ruby annotations in CSS.

spec:css-text-3; type:dfn; text:character

Introduction

Module interactions

Value Definitions

Diagram conventions

Wide-cell glyph (e.g. Han) that is the nth character in the text run. They are typically sized to 50% when used as annotations.

Narrow-cell glyph (e.g. Roman) which is the nth glyph in the text run.

What is ruby?

In this first example, a single annotation is used to annotate the base text.

Example of ruby used in Japanese (simple case)

In Japanese typography, this case is sometimes called taigo ruby (Japanese: 対語ルビ) or group-ruby (per-word ruby), ( because the annotation as a whole is associated with multi-character word (as a whole).

In this second example, two levels of annotations are attached to a base sequence: the hiragana characters on top refer to the pronunciation of each of the base kanji characters, while the words “Keio” and “University” on the bottom are annotations describing the English translation.

Complex ruby with annotation text over and under the base characters

Notice that to allow correct association between the hiragana characters and their corresponding Kanji base characters, the spacing between these Kanji characters is adjusted. (This happens around the fourth Kanji character in the figure above.) To avoid variable spacing between the Kanji characters 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.

Ruby Box Model

Ruby-specific 'display' Values

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

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; generated as an anonymous box in HTML.)

ruby-text-container

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

Authors using a language (such as HTML) that supports dedicated ruby markup should use that markup rather than styling arbitrary elements (like <span>) with ruby 'display' values. Using the correct markup ensures that screen readers and non-CSS renderers can interpret the ruby structures.

The Ruby Formatting Context

Non-Inline Ruby

Anonymous Ruby Box Generation

1. [=Inlinify=] block-level boxes: Any in-flow boxes directly contained by a [=ruby container=], [=ruby base container=], [=ruby annotation container=], [=ruby base box=], or [=ruby annotation box=] are “[=inlinified=]” per [[!CSS-DISPLAY-3]]), and their 'display' value computed accordingly, so that they contain only inline-level content. 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''.
2. Generate anonymous ruby containers: Any consecutive sequence of improperly-contained [=ruby base containers=], [=ruby annotation containers=], [=ruby bases=], and/or [=ruby annotations=] (and any intervening [=white space=]) is wrapped in an anonymous [=ruby container=]. For the purpose of this step:
   • an improperly-contained [=ruby base=] is one not parented by a [=ruby base container=] or [=ruby container=]
   • an improperly-contained [=ruby annotation=] is one not parented by a [=ruby annotation container=] or [=ruby container=]
   • an improperly-contained [=ruby base container=] or [=ruby annotation container=] is one not parented by a [=ruby container=]
3. Wrap misparented inline-level content: Any consecutive sequence of text and inline-level boxes directly parented by a [=ruby container=] or [=ruby base container=] is wrapped in an anonymous [=ruby base=]. Similarly, any consecutive sequence of text and inline-level boxes directly parented by a [=ruby annotation container=] is wrapped in an anonymous [=ruby annotation=]. (For this purpose, misparented [=internal table elements=] are treated as [=inline-level content=] since, being parented by ruby boxes, they will be ultimately wrapped by an [=inline-level=] [=table wrapper box=].) However, if an anonymous box so constructed contains only [=white space=], it is considered intra-ruby white space and is either discarded or preserved as described below.
4. Trim leading/trailing white space: Any [=intra-ruby white space=] that is not the sole child of its parent and occurs at the beginning or end of a [=ruby container=], [=ruby annotation container=], or [=ruby base container=] is removed, as if it had ''display: none''
5. Remove inter-level white space: Any [=intra-ruby white space=] whose immediately adjacent siblings match one of the patterns below is inter-level white space and is removed, as if it had ''display: none''.

   Previous box	Next box
   any	[=ruby annotation container=]
   not [=ruby annotation=]	[=ruby annotation=]

6. Interpret intra-level white space: Any [=intra-ruby white space=] box whose immediately adjacent siblings match one of the patterns below is assigned the box type and subtype defined in the table below:

   Previous box	Next box	Box type	Subtype
   [=ruby base=]	[=ruby base=]	[=ruby base=]	inter-base white space
   [=ruby annotation=]	[=ruby annotation=]	[=ruby annotation=]	inter-annotation white space
   [=ruby annotation=] or [=ruby annotation container=]	[=ruby base=] or [=ruby base container=]	[=ruby base=]	inter-segment white space
   [=ruby base=] or [=ruby base container=]	[=ruby base container=]
   [=ruby base container=]	[=ruby base=] or [=ruby base container=]

   The intra-level white space boxes defined above are treated specially for [=pairing=] and layout. See below.
7. Suppress line breaks: Convert all forced line breaks inside [=ruby annotations=] (regardless of 'white-space' value) as defined for [=collapsible=] segment breaks in CSS Text Level 3 § 4.1.2. Issue: The goal of this is to simplify the layout model by suppressing any line breaks within ruby annotations. Alternatively we could try to define some kind of acceptable behavior for them.
8. Generate anonymous level containers: Any consecutive sequence of [=ruby bases=] and [=inter-base white space=] (and not [=inter-segment white space=]) not parented by a [=ruby base container=] is wrapped in an anonymous [=ruby base container=]. Similarly, any consecutive sequence of [=ruby annotations=] and [=inter-annotation white space=] not parented by a [=ruby annotation container=] is wrapped in an anonymous [=ruby annotation container=].

Annotation Pairing

Segment Pairing and Annotation Levels

• 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.

Unit Pairing and Spanning Annotations

• with two [=ruby bases=] or [=ruby annotations|annotations=] that surround corresponding [=intra-level white space=] in another level, then the so-corresponding [=intra-level white space=] boxes are also paired.
• with a single spanning [=ruby annotation=], then the [=intra-level white space=] is also paired to that [=ruby annotation=]
• with two [=ruby bases=] or [=ruby annotations|annotations=] with no intervening [=intra-level white space=], then the [=intra-level white space=] box pairs with an anonymous empty [=intra-level white space=] box assumed to exist between them.

Complex Spanning with Nested Ruby

Autohiding Base-identical Annotations

This is to allow correct inlined display of annotations for Japanese words that are a mix of kanji and hiragana. For example, the word 振り仮名 should be inlined as

振り仮名(ふりがな) and therefore marked up as

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

However, when displayed as ruby, the “り” should be hidden

Hiragana ruby for 振り仮名. Notice there is no hiragana annotation above り, since it is already in hiragana.

White Space Collapsing

• at the beginning and end of a [=ruby container=], [=ruby annotation=] container, or [=ruby base container=],
• between a [=ruby base container=] and its following [=ruby annotation container=],
• between [=ruby annotation containers=].

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

			<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>

			<ruby>
				屋<rt>おく</rt>内<rt>ない</rt>
				禁<rt>きん</rt>煙<rt>えん</rt>
			</ruby>

			<ruby>
				屋<rt>おく</rt>	内<rt>ない</rt>
				禁<rt>きん</rt>	煙<rt>えん</rt>
			</ruby>

Ruby Layout

Inter-character Ruby Layout

Styling Ruby Boxes

Breaking Across Lines

''inter-character'' ruby line breaking opportunity

Breaking Between Bases

Ruby line breaking opportunity

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

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

Breaking Within Bases

Bidi Reordering

• The contents of a [=ruby base=] or [=ruby annotation=] must remain contiguous.
• [=Ruby annotations=] must be reordered together with their [=ruby bases=].
• All [=ruby bases=] spanned by a single [=ruby annotation=] must remain contiguous.

• Bidi isolation is forced on all [=internal ruby boxes=] and the [=ruby container=]: the ''unicode-bidi/normal'' and ''embed'' values of 'unicode-bidi' compute to ''isolate'', and ''bidi-override'' computes to ''isolate-override''. Note: This means that implicit bidi reordering does not work across ruby bases, so authors will need to ensure that the [=ruby container=]’s declared directionality does indeed match its contents.
• During layout, [=ruby segments=] are ordered within the [=ruby container=] by the 'direction' property of their [=ruby container=].
• Within a segment, [=ruby bases=] and [=ruby annotations=] are ordered within their respective containers by the 'direction' property of the segment’s [=ruby base container=]. Note: This means the 'direction' property on [=ruby annotation containers=] is ignored for the purpose of layout. However, it can still inherit into the container's children and thereby affect the [=inline base direction=] of any [=ruby annotations=] it contains.

Line Spacing

Ruby annotations will often overflow the line; authors should ensure content over/under a ruby-annotated line is adequately spaced to leave room for the ruby.

Ruby Formatting Properties

Ruby Positioning: the 'ruby-position' property

	Name: ruby-position
	Value: over | under | inter-character
	Initial: over
	Applies to: ruby annotation containers
	Inherited: yes
	Computed value: specified keyword
	Animation type: discrete
	

over

The ruby text appears [=line-over=] the base.

Ruby over Japanese base text in horizontal layout

Ruby to the right of Japanese base text in vertical layout

under

The ruby text appears [=line-under=] the base. 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

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 computed value of 'writing-mode' of the [=ruby annotation container=] to be ''vertical-rl''. 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

Sharing Annotation Space: the 'ruby-merge' property

	Name: ruby-merge
	Value: separate | merge | auto
	Initial: separate
	Applies to: ruby annotation containers
	Inherited: yes
	Computed value: specified keyword
	Animation type: by computed value type
	

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>

merge

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:merge"><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, with the intention that if all annotations fit over their respective bases, the result is identical to “mono ruby”, but if some annotations are wider than their bases the space is shared in some way to avoid imposing space between bases.

One possible algorithm is described as “jukugo ruby” in [[JLREQ]]. Another, more simplified algorithm of “jukugo ruby” is to render as ''separate'' if all ruby annotation boxes fit within the advances of their corresponding base boxes, and render as ''merge'' otherwise.

Ruby Text Distribution: the 'ruby-align' property

	Name: ruby-align
	Value: start | center | space-between | space-around
	Initial: space-around
	Applies to: ruby bases, ruby annotations, ruby base containers, ruby annotation containers
	Inherited: yes
	Computed value: specified keyword
	Animation type: by computed value type
	

start

The ruby content is aligned with the start edge of its box.

''ruby-align/start'' ruby distribution

center

The ruby content is centered within its box.

''ruby-align/center'' ruby distribution

space-between

The ruby content expands as defined for normal text justification (as defined by 'text-justify'), except that if there are no [=justification opportunities=] the content is centered.

''ruby-align/space-between'' ruby distribution

space-around

As for ''ruby-align/space-between'' except that there exists an extra [=justification opportunities=] whose space is distributed half before and half after the ruby content.

Since a typical implementation will by default define [=justification opportunities=] between every adjacent pair of CJK [=characters=] and not between adjacent pairs of Latin [=characters=], this should result in the behavior recommended by [[JLREQ]]: for wide-cell ruby content to be distributed...

Wide-cell text in ''ruby-align/space-around'' ruby distribution is spaced apart

... and narrow-cell glyph ruby to be centered.

Narrow-width ruby text in ''ruby-align/space-around'' ruby distribution is centered

Ruby Text Decoration

Edge Effects

Overhanging Ruby: the 'ruby-overhang' property

	Name: ruby-overhang
	Value: auto | none
	Initial: auto
	Applies to: ruby annotation containers
	Inherited: yes
	Computed value: specified keyword
	Animation type: by computed value type
	

auto

When a [=ruby annotation container=] is longer than its corresponding [=ruby base container=], the [=ruby annotation container=] may partially overlap adjacent boxes. Whether, how much, and under which conditions to overhang are determined by the UA.

none

A [=ruby annotation container=] is never allowed to extend past the [=ruby annotation container=].

Simple ruby whose text is not allowed to overhang adjacent text

Simple ruby whose text is allowed to overhang adjacent text

Line-edge Alignment

Line-edge alignment

Appendix A: Default Style Sheet

A.1 Supporting Ruby Layout

		ruby { display: ruby; }
		rp   { display: none; }
		rbc  { display: ruby-base-container; }
		rtc  { display: ruby-text-container; }
		rb   { display: ruby-base; white-space: nowrap; }
		rt   { display: ruby-text; }
		ruby, rb, rt, rbc, rtc { unicode-bidi: isolate; }

		rtc, rt {
			font-variant-east-asian: ruby;  /* See [[CSS3-FONTS]] */
			text-emphasis: none;            /* See [[CSS3-TEXT-DECOR]] */
			white-space: nowrap;
			line-height: 1; }
		rtc:lang(zh), rt:lang(zh) {
			ruby-align: center; }

		rtc, :not(rtc) > rt {
			font-size: 50%; }
		rtc:lang(zh-TW), :not(rtc) > rt:lang(zh-TW) {
			font-size: 30%; }               /* bopomofo */
	

A.2 Inlining Ruby Annotations

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

A.3 Generating Parentheses

		/* 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: ")("; }

Glossary

Bopomofo or Zhuyin Fuhao (Chinese: ㄅㄆㄇㄈ, 注音符號, or 注音符号)

37 characters and 4 tone markings used as phonetics in Chinese, especially standard Mandarin. These are often, but not exclusively, used for ruby annotations.

Example of Bopomofo used as phonetic inter-character annotations in Chinese

Bopomofo tone marks are spacing characters that occur (in memory) at the end of each bopomofo syllable. They are typically displayed in a separate track to the right of or above the other bopomofo characters, and the position of the tone mark depends on the number of characters in the syllable. The neutral tone mark, however, is placed before (and in line with) the bopomofo, not alongside it. Note: The user agent and font subsystem are responsible for ensuring the correct relative alignment and positioning of glyphs, including [=bopomofo tone marks=], when displaying text-- whether the text occurs in ruby annotations or as normal inline content. Such glyph placement is not a function of CSS ruby layout.

Hanja (Korean: 漢字)

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

Hiragana (Japanese: 平仮名)

Japanese syllabic script, or character of that script. Rounded and cursive in appearance. Subset of the Japanese writing system, used together with kanji and katakana. In recent times, mostly used to write Japanese words when kanji are not available or appropriate, and word endings and particles. Also see Katakana.

Ideograph

A character that is used to represent an idea, word, or word component, in contrast to a character from an alphabetic or syllabic script. The most well-known ideographic script is used (with some variation) in East Asia (China, Japan, Korea,...).

Kana (Japanese: 仮名)

Collective term for hiragana and katakana.

Kanji (Japanese: 漢字)

Japanese term for ideographs; ideographs used in Japanese. Subset of the Japanese writing system, used together with hiragana and katakana. Also see Hanja.

Katakana (Japanese: 片仮名)

Japanese syllabic script, or character of that script. Angular in appearance. Subset of the Japanese writing system, used together with kanji and hiragana. In recent times, mainly used to write foreign words. Also see Hiragana.

Acknowledgments

Changes

Changes since the 5 August 2014 WD

• Add back ''ruby-overhang: auto | none'' for basic control over ruby overhang behavior.
• Harmonize inlinification with the CSS Display Module.
• Allow UA to shift ruby/emphasis marks if they conflict with underlines/overlines.
• Disable auto-hiding when the computed value of 'ruby-merge' is collapse.
• Tweak the default style sheet.
• Add section defining interaction with text decoration.
• Defer the right and left values of 'ruby-position' to the next level.
• Change ruby [=pairing=] rules to only apply spanning on anonymous annotations (i.e. content directly contained by an <{rtc}>).
• Pair excess bases / annotations with auto-generated empty anonymous bases / annotations.
• Apply 'ruby-position' to ''::first-line''. (Issue 2998)
• Clarify containing block of ruby boxes and contents is, as in the case of other inline boxes, the nearest block container.
• Clarify handling of misparented internal table elements.
• Trim leading/trailing white space in ruby containers, base base containers, and annotation containers to prevent it from interfering with pairing.
• Define layout effect of empty base and annotation containers.
• Disable margins, padding, and borders on ruby base containers and ruby annotation containers (but not on ruby bases and ruby annotations).

Changes since the 19 September 2013 WD

• Rewrite anonymous box generation rules and white space handling rules, defined specialized [=pairing=] of anonymous white space boxes.
• Take [=nested ruby=] handling out of [=pairing=]. (Will be handling it via sizing/layout.)
• Define bidi layout of ruby structures.

Changes since the 30 June 2011 WD

Remove ruby-span and mentions of rbspan.

Explicit spanning is not used in HTML ruby in favor of implicit spanning. This can't handle some pathological double-sided spanning cases, but there seems to be no requirement for these at the moment. (For implementations that support full complex XHTML Ruby, they can imply spanning from the markup the same magic way that we handle cell spanning from tables. It doesn't seem necessary to include controls this in Level 1.)

Defer ruby-overhang and ruby-align: line-end to Level 2.

It's somewhat complicated, advanced feature. Proposal is to make this behavior UA-defined and provide some examples of acceptable options.

Close issue requesting display: rp: use display: none.

The Internationalization WG added an issue requesting a display value for <{rp}> elements. They're supposed to be hidden when <{ruby}> is displayed as ruby. But this is easily accomplished already with display: none.

Change 'ruby-position' values to match 'text-emphasis-position'.

Other than ''inter-character'', which we need to keep, it makes more sense to align ruby positions with 'text-emphasis-position', which can correctly handle various combinations of horizontal/vertical preferences.

Remove unused values of 'ruby-align'.

left, right, and end are not needed.

Replace auto, distribute-letter, and distribute-space from 'ruby-align' with ''space-between'' and ''space-around''.

The auto value relied on inspecting content to determine behavior; this can be avoided by just using ''space-around'' with standard justification rules (which allow spacing between CJK but not between Latin). Replaced distribute-letter and distribute-space with ''space-between'' and ''space-around'' for consistency with distribution keywords in [[CSS-FLEXBOX-1]] and [[CSS-ALIGN-3]] and to avoid any links to the definition of text-justify: distribute.

Added 'ruby-merge' property to control jukugo rendering.

This is a stylistic effect, not a structural one; the previous model assumed that it was structural and suggested handling it by changing markup. :(

Remove inline from 'ruby-position'.

This is do-able via display: inline on all the ruby-related elements, see Appendix A.

Added Default Style rules

As requested by Internationalization WG.

Wrote anonymous box generation rules

And defined [=pairing=] of bases and annotations. Should now handle all the crazy proposed permutations of HTML ruby markup.

Defined layout of ruby

Defined in detail space distribution, white space handling, line breaking, line stacking, etc. Open issue left for bidi.