doc-glossary requires update

[TzviyaSiegman]

Code sample for doc-glossary requires review and/or revision. Required owned elements may need to be revised based on changes made in ARIA 1.1

The implied role of dt is unclear:

• the normative definition is in ARIA in HTML, which says it has an implicit role of 'listitem':
  https://w3c.github.io/html-aria/#dd-dt2
  *, however, the informative allowed ARIA role attribute value described in W3C’s HTML is 'none'
  https://www.w3.org/TR/html/grouping-content.html#elementdef-dt
• and HTML AAM says it should be mapped using the WAI-ARIA mapping for the 'term' role
  https://w3c.github.io/html-aam/#el-dt

This is discussed in

• DT element change to default role=term (ARIA Working Group Comment) html-aria#57
• DT element change to default role=term (ARIA Working Group Comment) html-aam#78
• Create description (was:definition) list role aria#504
  cc/@mattgarrish, @rdeltour

[mattgarrish]

We can't solve this yet, obviously, but as interim measure I'm going to change the example so that doc-glossary is on a section element plus remove the roles from dt/dd.

[mattgarrish]

Looking at this again, moving doc-glossary to section matches the ARIA in HTML definition so that change seems fine.

The one question that remains is whether we need to list term/definition as required owned elements?

dt now maps to term and dd to definition by default. So a glossary section with a dl list would satisfy the requirement (without each dt/dd needing to have an explicit role), at least as I read the owned elements definition which only requires they be descendants. If a dl isn't used, then we would require at least one term/definition pair to be explicitly marked.

Does that sound right?

/cc @TzviyaSiegman @rdeltour

[rdeltour]

The one question that remains is whether we need to list term/definition as required owned elements?

Keeping in mind that the current definition of "required owned elements" is subject to change in w3c/aria#748, I think this would still be OK with the new proposal(s).

I'm lacking expertise with real-world published glossaries, but it does seem natural for a glossary to have terms and definitions 😊, so I don't foresee any issue with it.

[mattgarrish]

I think this would still be OK with the new proposal(s)

Right, by that definition having generic elements in-between is fine, and as far as I'm aware dl falls in the none category (it currently isn't assigned a default role in ARIA in HTML).

dl is the most common pattern I've seen for glossaries, but I'm sure like everything in publishing there's no single design pattern. Someone could use a ul element with dfn followed by role="definition" on the definition. In that case, you'd have to add aria-owns and link everything up.

That's why I'm still a little worried that we're over-prescribing usage.

[mattgarrish]

Doing some general digging, I've seen everything from tables, lists and paragraphs used to format glossaries.

What if we instead add a paragraph like:

The structure of a glossary SHOULD make it possible for end users to identify each term and associated definition (e.g., using the [HTML] dl or dfn elements).

That might better cover the implied nature (nearest containing element) when dfn is used?

We could then add an extra example with a list:

<ul>
   <li>[<dfn>xyz</dfn>] blah blah blah</li>
</ul>