w3c / html-ruby

HTML Ruby Markup Extensions
https://www.w3.org/TR/html-ruby-extensions/
Other
3 stars 3 forks source link

Add rb>rt>rb>rt example code to Example 1 #17

Open r12a opened 1 week ago

r12a commented 1 week ago

2.1. The ruby element > Example 1 https://www.w3.org/TR/html-ruby-extensions/#basic-ruby-ex

This example shows Japanese text, with ruby markup used to annotate the ideographs with their pronunciation.

The example code uses

<ruby>霧<rt>きり</rt></ruby>とも<ruby>霞<rt>かすみ</rt></ruby>とも

I suggest that we show 3 markup models, beginning with the maximal markup model, which is

<ruby><rb>霧</rb><rt>きり</rt></ruby>とも<ruby><rb>霞</rb><rt>かすみ</rt></ruby>とも

And then going on to show 2 shorthand approaches, but first showing

<ruby><rb>霧<rt>きり</ruby>とも<ruby><rb>霞<rt>かすみ</ruby>とも

That model is both efficient and particularly useful because it puts the rb element in play without any more markup than the current HTML shorthand. I see it as the optimal approach, and so i think we should make it more visible.

I would only then add the markup in the current example text.

I think this will help nudge readers towards including the rb element in the spec, which is what they always used to do and which is more useful for styling.

Example 9 https://www.w3.org/TR/html-ruby-extensions/#rb-ex

Shows 2 alternative markup patterns for the rb element, including the one i'm suggesting above, but doesn't include the 3rd, which is fully marked up. I think it should, for completeness.

frivoal commented 5 days ago

This is an introductory example. There's more coming later discussing all the possible markup variants (and why you might chose one over another). I don't want to get too deep into optional elements and optional end tags before the normative prose has a chance to introduce all of them, so I think we should stay away from showing the full thing as well as variants, and should stick with a single simple variant, whose meaning is obvious enough based on context, before we explain the rest.

I think the example as it currently is does that job reasonably, so I'm inclined not to change it, even if I think there are other variants that might work as well for that job too, such as:

<ruby>霧<rt>きり</ruby>とも<ruby>霞<rt>かすみ</ruby>とも

or

<ruby><rb>霧<rt>きり</ruby>とも<ruby><rb>霞<rt>かすみ</ruby>とも

In any case, I don't think we should use more than one in this particular example


As an aside, the maximal markup model isn't:

<ruby><rb>霧</rb><rt>きり</rt></ruby>とも<ruby><rb>霞</rb><rt>かすみ</rt></ruby>とも

but rather:

<ruby><rb>霧</rb><rtc><rt>きり</rt></rtc></ruby>とも<ruby><rb>霞</rb><rtc><rt>かすみ</rt></rtc></ruby>とも
r12a commented 5 days ago

@frivoal It's because it's the introductory example that i think we need to take a little care with it. Content authors reading the spec are likely to see this as a prime example for creating ruby or copy-paste the example and tweak it. My main desire is to encourage the use of the rb tag (which content authors used to use regularly, but i suspect have since been drifting into the HTML5 syntax.

So if we only have one, that's fine, but i'd recommend using

<ruby><rb>霧<rt>きり</ruby>とも<ruby><rb>霞<rt>かすみ</ruby>とも