documentation for doc-example suggests invalid ARIA

[Seirdy]

doc-example can be used on a <figure> that has no <figcaption>; however, a figure with a figcaption may not have any roles (to maintain the parent/child relation).
See w3c/html-aria#209

The doc-example documentation suggests using role="doc-example" on a <figure> element with a <figcaption>, which is invalid.

[mattgarrish]

I'll check into this, but we updated the superclass of doc-example to figure so that it would be valid to use with a figcaption.

I suspect the ARIA in HTML document just needs updating, but we can't do that until the 1.1 revision is a recommendation.

[jnurthen]

@scottaohara can you look at this

[scottaohara]

The updates HTML AAM has proposed / are being made to the figure element should hopefully help ease the restrictions in aria in html.

but it sounds like doc-example is a synonym for figure? What's the benefit of this dpub role if it performs the same function as a figure?

[pkra]

but it sounds like doc-example is a synonym for figure? What's the benefit of this dpub role if it performs the same function as a figure?

I think w3c/aria#1643 is strongly related :)

[scottaohara]

i assumed as much @pkra :)

[Seirdy]

On Thu, Apr 07, 2022 at 10:37:16AM -0700, scottaohara wrote: but it sounds like `doc-example` is a synonym for `figure`? What's the benefit of this dpub role if it performs the same function as a `figure`?

I'm not sure all figures should necessarily have "doc-example" roles. For instance, a figure could be the focus of a page rather than an illustration of a concept described in the main body. Figures in articles are often semantically similar to floating blocks in printed works, only some of which are "examples". At least, that's my current understanding.

…

-- Seirdy

[pkra]

Along the lines of what I wrote on w3c/aria#1643 I think there is a significant (potential) benefit for these kinds of subclass roles. As with the link-related roles (footnotes, citations etc) I would agree that - by default - they should be exposed by their superclass.

But, e.g., a (text)book can easily have a dozen different types of fragments that tend to end up as <figure> (with dozens of occurrences each - even in a single chapter). These different types of fragments tend to be very distinct -- different visual styles, different numbering schemes, and wildly different content structures.

I realize that (last I checked) AT affordances for figures aren't exactly great out of the box but I think users could greatly benefit from having the means to filter out different types. Searching 50 figures to find Example 2 is just not great.

In the end, the overhead for implementors seems very small compared to the (potential) benefit.

[scottaohara]

Thanks @pkra for the providing the context. Some follow up questions i have though which are meant to help me understand this better, and do not necessarily represent me being against making any changes:

• would there / is there a way for users to navigate by doc-examples separately from figures?
• with the change in html aam for a figure to have an aria-details association with its figcaption rather than an aria-labelledby association, if the answer to my previous question is that there is no alternative mechanism to navigate specifically by examples, then I'd expect authors to provide the element a name of 'example 2' to be able to more quickly identify the second example. but if they had to use the name of 'example 2' that seems like it'd be duplicative of the exposed 'doc-example' role "example 2, example".

I do think it's important to be in alignment with the changes to figure and its association with figcaption, as the change to their association is being made due to the often overly redundant/verbose and even unuseful (problematic) names the figcaption provides the parent figure - particularly when it contains structured semantic elements.

If dpub is relying on this association to provide doc-example accessible names based on the figcaption content, then that'll soon be out of sync with how the elements (figure/figcaption) are meant to be associated/exposed.

But, circling back to my first question, if there are mechanisms to specifically navigate by figures or doc-examples, then the 'example' of finding the second doc-example based on instance rather than name makes much more sense.

[pkra]

I'm sorry if I sidetracked the issue.

would there / is there a way for users to navigate by doc-examples separately from figures?

I don't think there is with AT -- there aren't many affordances for figures in general.

I do think it would be a benefit, at least in an educational setting. I think there's evidence indicating that people benefit from such filtering, e.g., print textbooks can have multiple "table/list of" (figures, tables, definitions, exercises).

if they had to use the name of 'example 2' that seems like it'd be duplicative of the exposed 'doc-example' role "example 2, example".

Yes but that's also the case with "regular" figures -- at least in my line of work, "regular" figure captions generally start with "Figure 1." etc.

I do think it's important to be in alignment with the changes to figure and its association with figcaption

Agreed.

To me doc-example is very similar to doc-noteref, doc-glossref. To go back to affordances, just like I would expect doc-noteref to be included in the list of links, I'd still want doc-example in a list of figures. It's so close to its superclass that it's more of a role description (but in a good way).

If a role is a subclass of the element's native role in such a close way, should html-aria really say it's prohibited?

If dpub is relying on this association to provide doc-example accessible names based on the figcaption content, then that'll soon be out of sync with how the elements (figure/figcaption) are meant to be associated/exposed.

FWIW, I think the changes to figure are appropriate for doc-example, too.

[Seirdy]

On Sat, Apr 09, 2022 at 09:28:07AM -0700, Peter Krautzberger wrote: > would there / is there a way for users to navigate by doc-examples separately from figures? I don't think there is with AT -- there aren't many affordances for figures in general. I do think it would be a benefit, at least in an educational setting. I think there's evidence indicating that people benefit from such filtering, e.g., print textbooks can have multiple "table/list of" (figures, tables, definitions, exercises).

I often use figures for code snippets, images, and quotations that illustrate my point (with citations in the figcaption, recommended in the WHATWG HTML Living Standard). The quotations don't normally serve as examples, so being able to skip them would be really useful. I currently resort to microdata, with schema.org metadata for code snippets and quotations.

[scottaohara]

Thank you for the detailed response @pkra

This definitely sounds like an update that can be made to aria in html.

re:
“ If a role is a subclass the element's native role in such a close way, should html-aria really say it's prohibited?”

Dpub 1.0 didn’t have figure as the superclass role, so it wasn’t really a consideration at the time the rule was made. Now that dpub 1.1 has this changed, it makes sense to allow this role

I’m away from my computer for the weekend, so if you see this before Monday and want to transfer this issue or log a new issue against aria in html, I’ll make this change. Otherwise, if I’ll keep this issue in my notifications feed on GitHub to remind me to create an issue/or for this.

[mattgarrish]

@scottaohara I see you opened an issue for the ARIA in HTML spec. Do you need this issue open anymore or is it okay to close it off?

(And many thanks for picking it up!)

[scottaohara]

@mattgarrish, you can close this. I would have merged this but for the fact I do not merge changes without two implementations. We have one that has already made the change to their rules, but the other three have not moved ahead to make the change in their rules. Feel free to give them friendly nudges to update, so that this valid allowance doesn't get exposed as an error :)

[mattgarrish]

Okay, thanks, will see what I can do!