Closed nigelmegitt closed 7 months ago
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:
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.
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.
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 ofxref
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