Review pass of term definitions

[nigelmegitt]

Using Respec, terms that are defined locally can be used to navigate to the places they are used, using a UI like:

However, terms that are defined by direct reference to another specification using data-cite cannot be navigated in this way. Instead, clicking on the term definition just goes straight to the definition, on another page.

Also, Respec's documentation suggests data-cite should not be used, in favour of xref

Suggest doing an editorial pass to ensure that all defined terms are consistent, and clearly navigable, without necessarily taking the user away from the page immediately. This may mean having slightly clunky term definitions that just say "As defined in XYZ", where the XYZ link does take the user to the page that defines the term.

Discussed on TTWG call at https://www.w3.org/2022/03/03-tt-minutes.html#t02

[nigelmegitt]

Since #75 we now have a term definitions appendix that helps show where the definitions of terms externally defined are sourced. There are still occasional links through to external specifications.

Categorising them:

• Ones that are used within term definitions: seems like a good pattern to me; I suggest not changing them.
• Ones that just jump directly out of the spec:
  • W3C Process: At risk (scheduled for removal)
  • TTML2: Root Container Region
  • IMSC: Related Video Object
  • IMSC: Presented Image (scheduled for removal)
  • TTML2: Presentation Processor
  • i18n Glossary: grapheme

The styling of external term definitions with data-cite is slightly different to the styling of internal term definitions:

Internal term definition example:

External term definition example:

(coloured because I've visited the link I think)

The underlined link suggests that clicking will go somewhere else, whereas the non-underlined internal term definition produces a pop-up with a permalink and links to the in-document usage locations for the term.

The fix discussed before is to define a local term, and then in the definition of that term include the data-cite external reference, to avoid the surprise of leaving the spec.

It looks like the advice not to use data-cite is no longer in the Respec documentation, so I suggest not trying to use xref instead.

I will prepare a local branch with this proposed fix and see how it looks before deciding whether to open a pull request or recommend that we make no change. Happy to push that branch and open a draft pull request if anyone else wants to take a look and come to their own conclusion.

[nigelmegitt]

Proposed "fix" open for review at #76 - I'm genuinely not sure how much of an improvement it is, though it does address the consistency issue raised here, and completes that editorial pass, on the assumption that the "at risk" and image profile based terms will be removed anyway as per #73.