Rb

Use cases for ruby

This page looks at a number of use cases involving ruby, and proposes alternative approaches for meeting those use cases using the xhtml ruby annotation model, the current html5 model, and an augmented html5 model. The pros and cons of the different approaches are considered. The idea is to summarise technical arguments to inform discussions on the bugzilla and mailing lists.

The aim is to clarify which use cases are supported by the existing markup models (HTML5 or XHTML), and where they are not, provide suggestions about how the markup model can be adapted to support those use cases.

A key priority at the moment is: ISSUE-26: Please add support for rb http://www.w3.org/International/track/issues/26 This page addresses use cases related to complex ruby in order to establish whether this influences the need to add the rb tag to the current HTML5 model.

Note We will work on the assumption that the rb tag is only ever an optional tag, since there is agreement that the HTML5 model, which allows authors to use ruby without rb, can be useful to reduce markup overhead. There are also implementations that already support that approach. Suggestions that propose the use of rb should do so only if it serves a purpose that cannot be achieved with the current HTML5 model.

This material builds on comments by Fantasai at https://www.w3.org/Bugs/Public/show_bug.cgi?id=10830#c9 and http://fantasai.inkedblade.net/weblog/2011/ruby/ and Koji Ishii.

1 Compatibility

Use case

Of pages identified so far that use ruby in the wild, a majority tend to use rb in HTML, even though ruby is invalid in HTML4. Content authors moving to HTML5 want their existing pages to be conformant.

Approach

Allow rb as an optional element inside the ruby element any time you use base text.

Pros and cons

Allowing use of rb as an optional element would facilitate conversion of existing pages to valid html5.

It is not clear, however, that this is a strong requirement, given that other markup has to be adapted for conversion to valid html5 (such as pragma-based language declarations).

2 Ruby base styling

Use case

A content author wants to apply some styling to the base text. We'll use color in a number of examples here, which could be inherited from the ruby element, but there could be other types of styling that require direct access to the ruby base content itself. For example, here is a very common approach to educational materials which requires the ruby base to be styled independently of the ruby and rt elements.

Another use case would be where you want to hide the base text and show only the ruby text. This would be useful for adapting content to suit children, students and others who have trouble with kanji.

See also the related accessibility use case below.

There are three sub use cases:

(a) the style may be applied to all base text in a page or section, or

(b) styling may be selectively applied to individual ruby base items, or

(c) styling may be applied to parts of one ruby base separately. (For an example of this, imagine that the figure above of educational material contained the word 今日. These two kanji characters are phonetically annotated with a single run of ruby text, きょう, but you would need to style the boxes around each kanji character separately.)

Approach 1: Current HTML5 model

Use the current html5 model for simple ruby, but apply styling by styling the ruby element and rt elements. The markup would look like this:

<ruby>base1<rt>rt1</rt>base2<rt>rt2</rt><ruby>

To style the base element, apply a style to the ruby element, then apply a style to the rt element that overrides that style. Eg.

ruby { color: red; }
rt   { color: black; }

Pros and cons

For styling that is achievable by this method, this is somewhat clumsy. For example, to keep the colour of the rt text the same as that of the surrounding text you would have to change the rt text properties as well that of the text surrounding the ruby element.

Some properties can not be applied to base text with this method, such as background or border, so you would not be able to produce the educational example above by this method. Nor would you be able to replace the ruby base with the ruby text.

Does it support the use case?

Only in simple scenarios. It doesn't enable direct access to the base text, therefore excluding that kind of styling and causing problems for accessible rendering.

Approach 2: Current HTML5 model

Use the span element for styling, eg.

<ruby><span>base1</span><rt>note1</rt><span>base2</span><rt>note2</rt></ruby>

Then style the span elements, eg.

ruby span { color: red; }

Pros and cons

Use of this element is similar to using the rb tag, though it's use for presentational hooks is slightly less controversial. On the other hand, it's not as short as rb.

Unlike rb, several span elements could be used on one item of ruby text (eg. to colour three successive characters with different colours) or to style just one of the characters in a multi-character base text. This is use case (c) above.

If the rb tag is used, rather than the span tag, the semantic nature of the tag urges that there should only be one rb tag per ruby base item, so styling the characters in a single base text separately would not be possible.

It is possible to style span tags inside ruby elements in IE8 and current desktop versions of Firefox, Chrome, Safari and Opera. See the tests at http://www.w3.org/International/tests/html-css/ruby/results-ruby-markup#styling

Examples

• Applying background colour to span elements
• Styling the ruby base independently of the ruby and rt
• Styling parts of a single ruby base independently
• Replacing the ruby base with the ruby text

Best viewed in Chrome and Safari (but sort of works in IE too).

Does it support the use case?

Yes, for most simple styling cases. But for direct styling of the base text you need to always use a span, and that begins to beg the question why there isn't a semantic rb element instead. General conversion of ruby to ruby text only for accessibility is still problematic.

Approach 3: XHTML model

Use rb elements in the ruby elements you want to style, eg.

 <ruby><rb>BASE1</rb><rt>note1</rt></ruby><ruby><rb>base2</rb><rt>note2</rt></ruby>

Then style the rb elements:

rb  { background-color: green; }

Pros and cons

You no longer have the need to identify the colour of the surrounding text for the rt, nor do you have the clumsiness of styling then overwriting that style.

The XHTML model requires rb always, and allows only one rb per ruby element. This leads to a huge markup overhead, compared to the current HTML5 model, and can therefore make it harder to author and maintain source code.

The XHTML model is also problematic in that the HTML5 model has now been implemented by more than just IE.

Use of the rb tag for styling doesn't lend itself to situations where you want to style parts of the ruby base separately, per sub use case (c) above. The XHTML model doesn't allow for spans.

It is not possible to style rb tags natively in IE8, but it is possible if you use the HTML5 shiv after that has rb added to it. It is possible in IE9 and current desktop versions of Firefox, Chrome, Safari and Opera. See the tests at http://www.w3.org/International/tests/html-css/ruby/results-ruby-markup#styling

Examples

• Applying background colour to rb elements
• Styling the ruby base independently of the ruby and rt

Does it support the use case?

For most cases, yes, but not for styling base characters independently. But mandatory use of rb and the markup overhead make it untenable as a solution.

Approach 4: Optional rb tag

Use rb elements in the ruby elements you want to style, eg.

 <ruby><rb>base1</rb><rt>note1</rt><rb>base2</rb><rt>note2</rt></ruby>

Then style the rb elements:

rb  { background-color: green; }

Pros and cons

You no longer have the need to identify the colour of the surrounding text for the rt, nor do you have the clumsiness of styling then overwriting that style.

On the other hand, if you wanted to style most or all of the ruby bases in your page, you would have to use rb markup for all that markup. Content authors are unlikely to want to use the rb tag religiously just in case they may want to style it later, and if they don't and they want to style all ruby in the page, they will need to retrofit rb tags throughout before the styling will work.

Then again, if you only want to style selective ruby elements, having an element around the base text provides a simple way to do so that avoids the problem of interference with the rt styling.

Also, if you know you will want to style the base text independently of the ruby and rt text, as for the example of educational material above, it will be worthwhile to add rb tags for those cases, since you will need the rb tag to achieve the styling.

Use of the rb tag for styling doesn't lend itself to situations where you want to style parts of the ruby base separately, per sub use case (c) above. You would not want more than one rb tag per rt, so you would have to resort to spans.

It is not possible to style rb tags natively in IE8, but it is possible if you use the HTML5 shiv after that has rb added to it. It is possible in IE9 and current desktop versions of Firefox, Chrome, Safari and Opera. See the tests at http://www.w3.org/International/tests/html-css/ruby/results-ruby-markup#styling

Examples

• Applying background colour to rb elements
• Styling the ruby base independently of the ruby and rt

Does it support the use case?

Basically, yes, but we can no longer expect authors to religiously use rb for all ruby bases, so there are still issues for retrofitting styles and for accessibility support.

Approach 5: Invisible rb tag

Allow CSS to style ruby base directly without the need for markup. eg. use

rb { color: red; }   

for the following markup

 <ruby>base1<rt>note1</rt>base2<rt>note2</rt></ruby>

Pros and cons

You would have to resort to span to style a particular, single ruby base. This would only provide a way of styling all rb element in a page or other parent element, or all the rbs in a ruby element with a certain class or id.

The following is from Koji Ishii:

This helps following use cases without making markups verbose:

• Styling ruby base differently from regular text and annotation.
• For accessibility and for children, it is often desirable to hide base text, replacing it with the annotation. With the proposed design, rb { display:none; } rt { display:inline; } can do this. But you can't do ruby { display:none; }.
• Examinations print an empty box with borders for base text with annotations on top of the box, so that students can fill the base text. The border has to be applied to base box, not to ruby box.
• While applying styles to ruby and applying different styles to rt can solve some cases of styling base text, there are two issues unresolved with the method: 1) rt cannot inherit values from parents of ruby, and 2) properties such as background, border, or display works differently for ruby and base text.
• Traversing DOM becomes easier. Without rb, traversing needs to scan all children of ruby except rt and rp and combine them. If, for instance, base text is H₂O, it consists of 3 nodes. CSS Ruby creates an anonymous box around the 3 boxes but there's no direct counterpart in DOM without implicit rb tag.
• TBD, see fantasai's blog article and {https://www.w3.org/Bugs/Public/show_bug.cgi?id=10830#c9 her comment 9] of the bug.

There are two ways to implement this.

1. Imply rb into DOM, just like tbody is implied
2. Assign rb style to ruby base anonymous box

The later only works if they are styled as ruby, because the anonymous box exists for ruby but not for inline display, so it'll not work for ruby-position: inter-character or inline, and also when fallback occurred.

Also, the former makes accessing base text slightly easier, as grabbing the rb element is easier than grabbing all elements other than rt and rp (and any future additions) elements.

On the other hand, the former requires changes in parser. Also there are several cases we need to define behavior; e.g., what if rb and non-rb base are mixed, what happens if non-rb are inserted by JavaScript, etc.

Does it support the use case?

Yes.

2a Accessible rendering

Use case

A research for elementary and junior-high students done by the Japanese government in 2010 indicates that 0.2% of them have difficulty to read Hiragana, and 6.9% for Kanji. Kanji dyslexia is considered that they have difficulty in visual recognition of complex drawings, and therefore adding ruby makes them even harder to read (ruby text adds more complexity.) The researcher tried several methods to improve their readability and found that the best method was to replace Kanji with Hiragana. For this use case, it'd be ideal if user stylesheet can replace Kanji with its reading without changing markup.

This implies that it is necessary to have direct access to the ruby base, whether or not it is marked up with an rb tag.

Approaches

See approaches in section 2 above.

The only approach that would work consistently is approach 5, given that approach 4 is only optional use of rb but an accessibility tool would need to be able to style any base text, whether the author had used rb or not.

3 Fallback for multiple bases in one paren

Use case

Tokyo is written with two kanji characters, 東, which is pronounced とう, and 京, which is pronounced きょう. Each base character should be annotated individually, but the fallback should be 東京(とうきょう) not 東(とう)京(きょう).

The latter (ie. two parens) is what you would get with the current html5 ruby markup model.

Note that inline styling is not only used when ruby is not supported, but also when the font size is too small for ruby to be readable KIshii.

Approach 6: HTML5 model

This cannot be done with the current HTML5 model, ie. you can only have 東(とう)京(きょう).

  <ruby>東<rp>（</rp><rt>とう</rt><rp>）</rp>京<rp>（</rp><rt>きょう</rt><rp>）</rp></ruby>

Does it support the use case?

No.

Approach 7: XHTML model

The Ruby Annotation model allows for association of rb and rt elements, however the ruby annotation model doesn't allow for fallbacks in complex ruby.

This approach would require some divergence from the current situation (which may not be a big issue, since there is very little support for or use of complex ruby at the moment). It would be necessary to allow an rp element at the start and end of the rtc element.

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

Does it support the use case?

No.

Approach 8: rb rb rp rt rt rp

This could be achieved if the ruby could be written as

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

Pros and cons

This is a significant change to the current html5 model, and it also doesn't match the Ruby Annotation model. It is a simplified form of complex ruby.

Note this method precludes using Approach 3 for double-sided ruby. (But see 5 Double-sided ruby, Approach 5).

Does it support the use case?

Yes.

4 Jukugo ruby

Use case

Compound words in Japanese (aka. jukugo) allow for significant overlaps of the ruby text with adjacent base characters, however the relationships between rt and base text has to remain clear because line breaks can occur in the middle of the compound word and the base characters that move to the next line have to take with them all rts, and no more, that they are associate with (unlike group ruby, which cannot admit line breaks).

For a description of jukugo ruby and how it differs from mono ruby and group ruby, see http://rishida.net/blog/?p=469 (See in particular the images at the bottom of the page that show the complex distribution of ruby text, sometimes forcing gaps to appear. Jukugo ruby may often look like group ruby, but it is not.)

In all cases the CSS Ruby spec would need to be changed to allow proper distribution of ruby text across the ruby.

Approach 8: HTML5 model

Just use the current html5 ruby model, but style the ruby element so that the rt distributes itself across the base text in a way appropriate to jukugo ruby, including allowing breaks between any ruby-base+ pair. For the styling to work, the rt would have to be able to associate itself with a particular base text item.

<ruby>思<rt>し</rt>春<rt>しゅん</rt>期<rt>き</rt></ruby>

Pros and cons

It's simple and intuitive.

Users would need to put ruby tags around the jukugo words, to indicate the boundaries of the jukugo, which may mean slightly more ruby tags than otherwise, but that is probably unavoidable.

Does it support the use case?

Yes.

Approach 9: XHTML model

To define the boundaries of the base characters that make up the jukugo word you would need to use complex ruby from the Ruby Annotation spec. This would require use of rb but also rbc and rtc. Again, CSS would be needed to apply the correct overlap of ruby text and base elements.

  <ruby>
  <rbc><rb>思</rb><rb>春</rb><rb>期</rb></rbc>
  <rtc><rt>し</rt><rt>しゅん</rt><rt>き</rt></rtc>
  </ruby>

Pros and cons

Complex ruby in the XHTML model doesn't allow text to break in the middle of a ruby element. This is showstopper.

It's very heavy on markup, and even though it associates rbs with rts, it's not clear not sure what the advantage is, if css ruby could be used to apply the necessary overlaps. It would also be more complicated to implement.

Does it support the use case?

No.

Approach 10: rb rb... rt rt...

Use markup like this.

  <ruby>
  <rb>思</rb><rb>春</rb><rb>期</rb>
  <rt>し</rt><rt>しゅん</rt><rt>き</rt>
  </ruby>

Pros and cons

Less heavy on markup than Approach 9.

It enables the 東京(とうきょう) fallback use case, too.

Does not require closing tags around words, if jukugo ruby is defined as taking only consecutive sequences of bases. ??

IE's rendering of this markup is close to jukugo ruby already; it just doesn't allow line-breaking within the word.

Examples

Line breaks in ruby elements

Does it support the use case?

Yes.

5 Double-sided ruby

Use case

Sometimes ruby is found on both sides of the base text.

There are a couple of sub use cases:

• Double-sided ruby is often a combination of phonetic information (which is done on a mono ruby basis) plus semantic or other ruby text (which is realised as group ruby).
• For phonetic and semantic case, oftentimes the two ruby text are applied to different part of base text, like this
• Sometimes the author may want to put mono ruby on both sides of the base text, so that each ruby base is associated with two ruby texts that are positioned relative to that ruby base.

Real Examples

• Sometimes used in novels.
  • Aozora Bunko (wikipedia) has 10,870 novels and 17 of them have double-sided ruby, which is roughly 0.16%. Atomi University's research shows 65,065 books were published in Japan in year 2000, so simple math gives us about 102 books with double-sided ruby are published every year.
    • A review article of Aozora Bunko reader software
  • Harry Potter uses double-sided ruby for subtitles of incantations. In this picture, the upper shows the sound while the lower shows the reading of the meaning.
• Widely used in school textbooks for Japanese, social studies, and histories.
  • Examples: 1 2 3 4
  • Exam question examples: 1 (p. 10) 2 (p. 10) 3 (p. 2) 4 (p. 3, signle-side double ruby) 5 (p. 6)
• Widely used in Japanese history research papers.
  • One ruby for the pseudo-Chinese reading (On-yomi in Japanese,) and another for Japanese reading (Kun-yomi in Japanese.)
  • Example: A research paper used in title (page 2) and also in page 13 to 14 (printed page number 164 to 165)
  • Example: An article of a school law established in 1872
  • Often used in ancient documents research papers because the reading of ancient words only found in written materials were not determined and there are more than one possible way to read them.
• Kanbun (classical Chinese text with annotation to help Japanese to read, wikipedia) usually require double-sided ruby.
  • Example
  • In a Q&A site, the question is about how to layout Kanbun in word processors, and the best answer teaches how to enter double-sided ruby using Ichitaro, one of the most popular word processors in Japan.

Approach 11: HTML5 model

Nest ruby using the current html5 model.

<ruby><ruby>BASE<rt>rt1</rt></ruby><rt>rt2</rt></ruby>

Pros and cons

It would be necessary to specify in the html5 spec that by default the latter rt should go below the base text.

This is actually fairly simple markup, compared to the ruby annotation complex ruby markup.

Nesting ruby in this way works when one of the ruby texts is treated as group ruby. It doesn't work if you want to align rt in mono (or jukugo) ruby fashion on both sides.

When two rt are paired with different parts of base, nesting only works when one contains the other; e.g., for base "ABC", the first rt is for "AB" and the second rt is for "BC". From the data we have today, it looks like that covers the most use cases, but it might not be good enough for Kanbun use cases. In this regard, I think we need more research.

Does it support the use case?

Only partially. Mono ruby on both sides is not possible.

Approach 12: XHTML model

Use complex ruby from the ruby annotation spec.

<ruby>
   <rbc><rb>BASE1</rb><rb>BASE2</rb><rb>BASE3</rb></rbc>
   <rtc><rt>rt1a</rt><rt>rt2a</rt><rt>rt3a</rt></rtc>
   <rtc><rt>rt1b</rt>rt2b<rt></rt><rt>rt3b</rt></rtc>
   </ruby>

The above markup allows for two rts to be associated with each rb like mono ruby.

<ruby>
   <rbc><rb>BASE1</rb><rb>BASE2</rb><rb>BASE3</rb></rbc>
   <rtc><rt>rt1</rt><rt>rt2</rt><rt>rt3</rt></rtc>
   <rtc><rt rbspan="2">rt4</rt></rtc>
   </ruby>

This markup, incorporating the rbspan, could be used for associating mono ruby on the top and group ruby below.

Pros and cons

There's a lot of markup.

You can achieve quite complicated tabular effects with rbspans, but it's a little complicated to keep track of things, and it's not clear that that is really required.

Examples

Nested ruby works on Chrome and Safari, but not IE, but puts both rts above the base, instead of one on each side

Doubled rt tags after base text Doesn't work on Chrome/Safari, but both rts are treated as a single annotation of the base text (ie. side by side but over the base text) by IE.

(See a summary of results and links to the test framework at http://www.w3.org/International/tests/html-css/ruby/results-ruby-markup#multiply (Multiplying markup) )

Does it support the use case?

Yes, but rather complicated markup.

Approach 13: BASE rt rt BASE rt rt

Augmented html5 model.

 <ruby>base1<rt>note1a</rt><rt>note1b</rt>base2<rt>note2</rt></ruby>

Pros and cons

This is not part of the html5 model, and would have to be an addition.

This would enable two mono ruby annotations to be associated with one ruby base at a time. You could achieve gaps on one side or the other by having no rt element or an empty element.

You cannot have group ruby on one side and mono/jukugo ruby on the other with this markup.

You cannot have the upper and the lower to have different base text, as in this example, 1st and 3rd examples in printed page number 165.

This is much simpler markup than that for complex ruby in the ruby annotation spec.

Does it support the use case?

Only partially. Mono ruby on one side and group on the other is not possible.

Approach 14: nesting + BASE rt rt

Combine approaches 2 and 3, ie. to put mono ruby on both sides of base text use the rb approach, and to put group ruby on one (or both) side use the nested approach.

Pros and cons

Each part is probably intuitive enough to work, and is simple enough to code. However, the two together requires the user to remember two different ways of doing something.

It still requires that html5 augments its model to allow either approach.

Does it support the use case?

Yes, but somewhat clumsy for authors.

Approach 15: rb rb... rt rt... rtc

Add an rtc element that can contain ruby text or a series of rt elements.

For example, to have mono ruby on both sides of a word, use

<ruby><rb>base1</rb><rb>base2</rb>
     <rt>note1</rt><rt>note2</rt>
     <rtc><rt>NOTE1</rt><rt>NOTE2</rt></rtc>
     </ruby>

To have group ruby on one side, use

<ruby><rb>base1</rb><rb>base2</rb>
     <rt>note1</rt><rt>note2</rt>
     <rtc>spanning note</rtc>
     </ruby>

Pros and cons

This offers a more uniform approach to double sided ruby markup, however it requires the addition of rb and rtc tags to HTML5 (plus, of course, some rules for interpreting the markup and the mapping between elements).

It also makes it easier to do fallback with a single set of parens around the annotations of the word as a whole, see 3 Fallback for multiple bases in one paren, Approach 1.

It can be extended to handle everything else in Ruby Annotation's complex ruby model, if that becomes necessary in the future.

Does it support the use case?

Yes.

Summary

Use case	HTML5 model	XHTML model	Alternative proposal
Ruby base styling	Yes, but issues about appropriateness	-	Make rb in DOM and optional as markup
Accessible rendering	No	Yes	Make rb in DOM and optional as markup
Fallback in one paren	No	No.	Use rb,rb,...rp,rt,rt...rp
Jukugo ruby	Yes	No	Use rb,rb...rt,rt...
Double-sided ruby	No	Yes, but complex	Use rb,rb...rt,rt,...rtc