The html-ruby from w3c

Accessibility self review

This review is based on the 23 May 2024 WD, answering question from APA's FAST Checkliks

Prelude:

This specification extends an existing feature rather than introduce a new one. Maybe of the accessibility characteristics of this technology pre-exist in the underlying feature. This extension improves upon them.

Ruby, at its core, associates text with one (or more) annotations about the text, with the intent of displaying the annotation along side the annotated text, in a visually distinct way. Although this can be used for a number of reasons, the primary motivation is primarily an accessibility feature targeting people, who for a variety of reasons, have difficulty reading the base text. By far, the dominant use case is for ideograph based east-asian languges, where learning the writing system requires memorization of thousands of different letters. Children, non-native speakers, people with learning disabilities, or people from under-privileged backgrounds and with a limited education, frequently struggle to read unassisted. Ruby enables phonetic annotations to be attached to the potentially challenging text, thereby making otherwise unreadable content accessible to more readers.

These annotations are typically displayed between lines of text immediately above or below the words they annotate, though alternative presentations can be desired and are enabled by CSS in general, and https://www.w3.org/TR/css-ruby-1/ in particular.

All this is true prior to this extension specification. However, the markup patterns enabled by the HTML standard, while concise and effective in simple cases, are insufficient to handle all use cases well. In particular, while it does enable authors to indicate annotation is associated with which word, it does not give them sufficient tools for authors to also indicate which part of the annotation is associated with which character in the base word, unless they are willing to sacrifice the natural document order, and interleave parts of annotations between parts of words.

The negative consequence of not having a complete mapping of annotation parts with base text parts while respecting the natural document order is that authors need to change their markup depending on the specifics of the visual rendering they intend, as not all presentations can be supported from the same semantic markup. Further, some markup patterns, necessary for some desirable presentational characteristics, break other features, such as search ability or copy and paste, due to unnatural interleaved markup patterns they require.

A key goal of this specification is to remedy these downsides, by offering markup patterns that convey the complete relations between the base text and its parts with the annotation and its parts, while respecting the natural order of the text. From there, authors and user or user agents can offer alternative presentations without modifying the markup, and no longer have to make compromises such as choosing between proper alignment and proper line breaking, while the natural order of the text in the markup avoids the search / copy-paste / or speech synthesis ordering problems that could occur with otherwise.

Occasionally, having multiple levels of annotation over the same base text can be desirable. The current HTML spec purports to address this, but the way it specifies this is not implemented in user agents, and suffers from similar inflexibilities. The markup model defined by extension specification addresses this issue as well.

A known pre-existing challenge with ruby, which this revision of the specification does not attempt to address, relates to speech
synthesis: when faced with annotated text, should screen-readers or other text-to-speech systems read the base text, the annotation, or both? Depending on the use case, the appropriate answer may vary, and picking the wrong answer can be confusing to the reader. There currently is no good way for authors to indicate their intent, or for user-agents to infer it reliably. This extension specification does not address the problem, but does not make it worse either. The i18n Working Group is pursuing an exploration of this problem space, documented in https://w3c.github.io/ruby-t2s-req/. We hope that to tackle this in a later project. For the moment, with this extension specification, the focus is on getting the basic markup structure right.

Answers to the questions:

If technology allows visual rendering of content
This technology is HTML markup for text, it does enable visual rendering. The same CSS/HTML/… techniques that apply to any and all HTML textual markup apply here to.
- There is a defined way for a non-visual rendering to be created. Since this spec un-obsoletes <rb> and <rtc>, we should revert the w3c/html-aam#253 Pull request, which removed them from HTML accessibility mappings when they were obsoleted.
- Content can be resized. (usual HTML/CSS/… answer)
- Luminosity and hue contrast can adapt to user requirements. (usual HTML/CSS/… answer)
- Text presentation attributes can be changed. (usual HTML/CSS/… answer)
- Visual presentation of pointers and cursors can be adjusted. (usual HTML/CSS/… answer)
- Changing content presentation does not render it unreadable. As discussed above, without this extension specification, not all presentations can be achieved from a single markup pattern, and trying to change can result in undesirable results. This specification remedies this problem
- Technology does not allow blinking or flashing of content, or provides a feature for users to quickly turn it off or permanently disable it. (usual HTML/CSS/… answer)
- It is possible to make navigation order correspond to the visual presentation. As discussed above, without this extension specification, it is sometimes necessary to put things out of order in the markup in order to get the correct visual rendering. This specification remedies this problem
If technology provides author control over color
This technology is HTML markup for text. It does not introduce new abilities to control color, but usual CSS techniques apply.
- There is a mechanism for users to override colors of text and user interface components. (usual CSS/… answer)
- There is a feature for authors to define semantically available "color classes" that users can easily map to custom colors, and give preference to this vs. coloring objects individually. (usual CSS/… answer)
- There is a feature for users to choose color schemata that work for them. (usual CSS/… answer)
- The foreground and background color of an object can be reported to the user via AT. (usual CSS/… answer)
- There are ways to set foreground and background colors separately for all objects. (usual CSS/… answer)
- Compositing rules for foreground and background colors are well defined. (usual CSS/… answer)
If technology provides features to accept user input
It does not.
If technology provides user interaction features
It does not directly offer any new interaction capabilities.
If technology defines document semantics
It is used in an HTML document. Many answers to the questions asked are provided by HTML itself, not by this extention
- Authors can title Web pages. (usual HTML answer)
- Authors can title sections of content. (usual HTML answer)
- Authors can clearly indicate the target of a hyperlink and function of a control. (usual HTML answer)
- Authors can indicate content language, for the page as a whole and for blocks of content. (usual HTML answer)
- Authors can support understanding of abbreviations / acronyms / initialisms, idioms, jargon, etc. @@@@
- Authors can support correct machine pronunciation of ambiguously spelled terms (e.g., in the phrase "I am content with this content" there are different correct pronunciations of the lexeme "content"). This is a pre-existing problem, which this specification neither introduces nor resolves. We intend to look into ways to address it in follow up projects. See discussion above
- Authors can identify regions of content, particularly the "main" region. (usual HTML answer)
- Declarative mechanisms (that have accessibility semantics pre-defined in the spec) are used to implement technology features whenever possible. (usual HTML answer)
- There are unambiguous ways to express relationships between units of content, such as object nesting, ID referencing, etc. As discussed above, this was not entirely true of ruby markup prior to this extension specification, but this specification does remedy this problem
- Prefer structural semantics to presentational semantics. As discussed above, this was not true of ruby markup prior to this extension specification, but this specification does remedy this problem
- When providing presentational semantics, they can be easily mapped to structural semantics, e.g., to support restyling or meaningful exposure to accessibility APIs. (usual HTML answer)
- Support a comprehensive set of authoring use cases to minimize the need for alternative content. (e.g., don't make authors resort to text in images to get the style they want). (usual HTML answer)
- Semantics allow precise and replicable location information in the document to be determined. (usual HTML answer)
- Semantics exist to convey meaning that is commonly conveyed via presentation. As discussed above, this was not entirely true of ruby markup prior to this extension specification, but this specification does remedy this problem
If technology provides time-based visual media
It does not.
If technology provides audio
This technology does not provide audio in and of its own. See the discussion above for remarks about interaction with screen-readers.
If technology allows time limits
It does not.
If technology allows text content
- Authors can define non-text alternatives for text content. _Ruby enables annotation of content. typically text annotates text, but text can annotate images, images can annotate text, images can annotate images… there's no restriction.
- Authors can define non-text alternatives for non-text content. Same as above
If technology creates objects that don't have an inherent text representation
Not really applicable. It creates relatationships between other bits of HTML markup, not really new objects.
If technology provides content fallback mechanisms, whether text or other formats
The questions are not really applicable, because Ruby provides alternate content / annotations over content, which are not inherently "fallback" content, as they are not meant to be displayed instead of the main content when it fails, but along side it. Nevertheless, CSS can be used to show or hide some of the alternatives, and the markup patterns enable knowing which content is primary and which is annotations for it. This is true of pre-existing ruby markup, and remains true with this extension.
If technology provides visual graphics
it does not
If technology provides internationalization support
- Accessibility features can be internationalized to the same degree as other features
If technology defines accessible alternative features
- Accessible alternatives themselves meet the same bar of accessibility.
If technology provides content directly for end-users
- Content can be encoded in a manner that allows machine transformation into accessible output
If technology defines an API
It does not. (HTML does, but and this fits within that, but it does not define a new API)
If technology defines a transmission protocol
It does not.

Typo: Missing slash in closing tag

Slash of closing tag of ruby element in some examples is missing.

EXAMPLE5
<ruby><rb>京<rb>都<rb>市<rt>きょう<rt>と<rt>し<ruby>
<ruby><rb>京<rb>都<rb>市<rp>（<rt>きょう<rt>と<rt>し<rp>）<ruby>

EXAMPLE8
<ruby><rb>京<rb>都<rb>市<rt>きょう<rt>と<rt>し<ruby>

Level 2 features should be strongly recommended and levels 3 and 4 features should be marked as "at risk"

Fantasai's blog article about ruby markup design is still very useful. In particular, it shows four possible levels: Level 1 (Simple Ruby), Level 2 (Multi-pair Word Ruby, Level 3 (Double Ruby) and Level 4 (Full Complex Ruby).

I think that level 2 features should be strongly recommended and levels 3 and 4 features should be marked as "at risk". Such a change make this extension work more relevant. In its current form, I am not sure if developers think this draft really relevant.

Bopomofo ruby on the right in horizontal text is the norm, not just frequent

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

In horizontal writing, they are frequently also typeset to the right, in this case sandwiched between individual base characters

change to

In horizontal writing, they are usually also typeset to the right, in this case sandwiched between individual base characters:

Placing bopomofo over the base in horizontal writing is not typical. The norm is to appear to the right of the base.

Internationalization self review

This short review is for the following spec: HTML Ruby Markup Extensions.

Short i18n review checklist is here

Need to explicitly mention the default placement of ruby with 2 sets of annotations

The browser parsers already support most of what is needed for ruby, but a key challenge at the moment is that when there are two sets of ruby annotations they are not placed correctly by some browser engines.

There are examples of what to do in the spec, but i couldn't find any normative text or anything in the Rendering section to indicate the expected default positioning of the items around the base. This can be styled by the author using the CSS Ruby spec, but that is putting the cart before the horse. I think this spec needs to specify a default (ie. without CSS declarations) placement, ie. that the two items should go on different sides of the base. Which goes where can probably be left to the browser implementer (leaving latitude for them to factor in language-related positioning), but we shouldn't see both annotations on the same side of the base, or one set of annotations trailing along the baseline after the rest of the ruby element.

Remove example 8 figure 3 to avoid canonicalising a not-yet-established approach

2.1. The ruby element > Example 8 > Figure 3
https://www.w3.org/TR/html-ruby-extensions/#jukugo-ruby

Understood: All 3 examples are jukugo ruby, meaning that the bases and annotations are individually linked, and the ruby element can be split across a line, taking all necessary annotations with the wrapped base(s). This comment is about the arrangement of the hiragana characters above the kanji when all sit on the same line.

Example 2 shows an arrangement that is described in JLReq, where at least one of the hiragana in an annotation must appear above its related base. (If 都 was annotated by 3 hiragana a gap would open between the base characters.

Example 3 shows an arrangement that looks the same as group ruby would look, and where the と annotation doesn't appear (or barely appears) over the 都 base, because all characters are justified across all the bases (which is what you'd expect for group ruby). I think there was some throwing up of hands at some point by people who feared that jukugo might be a little complicated to implement, "so let's just say that it should look like group ruby", but i don't think that that is yet formalised. Having example 3 in the spec makes it appear to be a valid option.

I suggest that we remove example 3 until such time as a decision is taken by the jlreq group about whether jukugo ruby could actually appear like this. And if that does turn out to be a valid option, i think we should make it very clear that the arrangement of hiragana over kanji in jukugo ruby can follow different rules, rather than giving the impression that the arrangement in fig 3 is the one canonical way to approach the arrangement when the ruby text is set to 60%.

typo: Correct “jukugo ruby” is not be possible

Mention that ruby is not just for schoolkids and other esoteric users

Introduction
https://www.w3.org/TR/html-ruby-extensions/#intro

Typically ruby is used in East Asian scripts to provide phonetic transcriptions of obscure and little known characters, characters that the reader is not expected to be familiar with (such as children or foreigners learning to write), or characters that have multiple readings which can’t be determined by the context (eg. some Japanese names). For example it is widely used in educational materials and children’s texts. It is also occasionally used to convey information about the meaning of ideographic characters.

This somewhat intimates that 'ordinary' people don't usually need ruby and its use is rather restricted to special cases, but actually it is normal to find ruby in any novel, comic, or in-flight magazine that a person picks up. Perhaps change the penultimate sentence to

For example it is widely used in educational materials and children’s texts, but it can also be readily found in many types of literature and signage.

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

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.

Findability, copyability

Excited to see progress in web Ruby! If Ruby didn't have challenges enough (modeling, layout, and fine-tuning), it might be good to consider findability and copyability sooner than later, at least as the needs for representation are concerned. It's not obvious to me which technology is responsible, so centralizing a discussion here seemed to make sense, but feel free to close if out of scope in this repository.

In this more general issue (CSSWG #3460), I bring up the need for more control over findability and copyability, two primitive manipulations that become more complex in annotated documents. Briefly, with respect to Ruby, findability requirements could be improved by an optionally branching search algorithm, and two context-menu options "Copy with annotations" and "Copy without annotations" could possibly fulfill the majority of user needs for copyability (or analogously for selectability maybe).

Appendix B of the draft touches on the existence of possible issues involving findability (searchability) and copyability, but just in the context of supporting both interleaved versus tabular ruby markup.

Are line breaks in examples ok?

Various examples in the spec use line breaks to make it easier to read the markup. I remember that we had to remove those line breaks in the early days, since they would distort the rendered output when converted to spaces. I think there was some discussion about use of line breaks subsequently, but i can't remember where we stand at the moment. Perhaps this is described in the HTML spec, but does it apply equally to all styles of markup that are possible with ruby (eg. ones that don't have an rb element)?

I don't think the spec mentions this, either, should it?

Responses to the Security and Privacy Self-Review questionaire

Responses to the Self-Review Questionnaire: Security and Privacy, filed against the 23 May 2024 Working Draft.

What information does this feature expose,
and for what purposes?

This is a passive feature (markup) which only allows an origin to convey text to a user, as would other HTML Text-level elements.

No information about or from the user nor their environment is exposed to any party.

Do features in your specification expose the minimum amount of information
necessary to implement the intended functionality?

They do not expose any information to anyone, other than conveying text from an origin to a user, as would other HTML Text-level elements.

Do the features in your specification expose personal information,
personally-identifiable information (PII), or information derived from
either?

No.

How do the features in your specification deal with sensitive information?

This is a passive feature (markup) which only allows an origin to convey text to a user, as would other HTML Text-level elements. It is not exposed to sensitive information, and therefore do not need to do anything about it.

Do the features in your specification introduce state
that persists across browsing sessions?

No.

Do the features in your specification expose information about the
underlying platform to origins?

No.

Does this specification allow an origin to send data to the underlying
platform?

No.

Do features in this specification enable access to device sensors?

No.

Do features in this specification enable new script execution/loading
mechanisms?

No.

Do features in this specification allow an origin to access other devices?

No.

Do features in this specification allow an origin some measure of control over
a user agent's native UI?

No.

What temporary identifiers do the features in this specification create or
expose to the web?

None.

How does this specification distinguish between behavior in first-party and
third-party contexts?

No difference is made, and none seems appropriate or necessary.

How do the features in this specification work in the context of a browser’s
Private Browsing or Incognito mode?

No difference is made, and none seems appropriate or necessary.

Does this specification have both "Security Considerations" and "Privacy
Considerations" sections?

yes.

Do features in your specification enable origins to downgrade default
security protections?

No.

What happens when a document that uses your feature is kept alive in BFCache
(instead of getting destroyed) after navigation, and potentially gets reused
on future navigations back to the document?

Nothing special. This is just marked up text.

What happens when a document that uses your feature gets disconnected?

Nothing special. This is just marked up text.

What should this questionnaire have asked?

Nothing additional seems needed. This is not a security of privacy sensitive feature.

Wide review tracker

This issue tracks horizontal and other reviews requested on this document, since its restoration as a WD.

Reviews requested should be listed here, and checked once the review has been completed. Requests for reviews that do not have a "completed" state (but are merely a heads up to some group) should be listed without a checkbox.

w3c / html-ruby Goto Github PK

html-ruby's Introduction

HTML Ruby Markup Extensions

html-ruby's People

Contributors

Stargazers

Watchers

Forkers

html-ruby's Issues

Prelude:

Answers to the questions:

Recommend Projects

Recommend Topics

Recommend Org