Have a shared list of references?

[Jym77]

While writing/editing rules, I feel I spend a lot of time curating the list of references, and notably copying some from other rules (I can't count how often I've copied the ref for "flat tree"…) And we seem to end up with fairly long list of refs in modern rules… (I'm having ~20-25 refs in some of the rules for Bypass blocks…) And these lists are often poorly curated (typically, not ordered which result in adding the same ref twice because the first occurrence wasn't found).

We might benefit from having a shared list of references that would be automatically added to each markdown file (rule and def) before converting to HTML (the HTML conversion takes care of killing the unused ones). This list would contain both our own definitions (and this can also be automatically generated from the individual files metadata), and some of the most commonly used external definition ("flat tree" comes to mind, but there are many others). Rarely used refs could be kept in the individual files if wanted.

Benefits:

• Less time spend in curating reference list in each file.
• Easier to maintain consistency in references (notably, HTML specs are sometimes linked to the /multipage doc and sometimes to the single page one).
• Easier to maintain consistency in links' titles (the quoted string at the end of references). See Unifying titles of links in reference list #1297.
• Possibility to gather a "used in rules" list for external references, like we have for our own defs. (already possible now but without a single name for these, this is mostly pointless)

Challenges:

• Need a bit of coding for automating this. Especially if we want to automate the inclusion of our definition.
• Harder to check that all refs used in a rule exist, but should be OK-ish by injecting the list beforehand.
• Maintaining a single long list of refs. Need a bit of guidance and a lot of discipline (similar to our spelling exception list), plus maybe some tests to prevent adding duplicate refs, … Also, will create a bit more merge conflicts on secondary files.
• Loosing a bit of locality. Now we need to check the refs list to review a rule.

---

Concretly:

• Based on definitions meta-data, we auto-generate a file containing:

[accessible name]: #accessible-name 'Definition of Accessible Name'
[included in the accessibility tree]: #included-in-the-accessibility-tree 'Definition of Included in the Accessibility Tree'
…

• We maintain by hand a file containing:

[document]: https://dom.spec.whatwg.org/#concept-document 'DOM definition of Document'
[sc241]: https://www.w3.org/TR/WCAG21/#bypass-blocks 'Success Criterion 2.4.1 Bypass Blocks'
[sequential focus navigation]: https://html.spec.whatwg.org/multipage/interaction.html#sequential-focus-navigation 'HTML definition of Sequential Focus Navigation'
…

this file needs curating, so probably sectioning and keeping alphabetical order, and testing if the same key is used twice.

• Both files are automatically added at the end of each rule and definition file at build time.
• Now, rules can use A [document][] with content [included in the accessibility tree][] without needing to copy these references all over the place.

[Jym77]

Here are all of our duplicated references keys, with usage. This doesn't consider keys that are similar but somehow different (e.g. "web page" and "web page (html)" seem to be the same, plural in "text node"/"text nodes", …)

$ grep "^[[]" _rules/*.md pages/glossary/*.md | cut -d: -f2 | grep "^[[].*[]]$" | sort | uniq -cd | sort -nr
     36 [visible]
     35 [included in the accessibility tree]
     24 [semantic role]
     21 [accessible name]
     17 [presentational roles conflict resolution]
     15 [flat tree]
     13 [attribute value]
     12 [explicit role]
     10 [web page]
     10 [focusable]
      9 [ancestor]
      8 [instrument]
      6 [non-text content]
      5 [wai-aria specifications]
      5 [top-level browsing context]
      5 [implicit role]
      5 [grandfathered tags]
      5 [computed]
      5 [clearly labeled location]
      4 [valid language tag]
      4 [html document]
      4 [explicit semantic role]
      4 [event]
      4 [document]
      4 [changes in content]
      4 [bcp 47]
      3 [whitespace]
      3 [web page (html)]
      3 [text nodes]
      3 [text node]
      3 [shadow tree]
      3 [sequential focus navigation]
      3 [sc249]
      3 [same resource]
      3 [purely decorative]
      3 [overflow]
      3 [media resource]
      3 [matching]
      3 [marked as decorative]
      3 [implicit semantic role]
      3 [hidden state]
      3 [firing]
      3 [essential]
      3 [descendant]
      3 [child]
      2 [window object]
      2 [visible text content]
      2 [usc412]
      2 [usc246]
      2 [text]
      2 [space separated]
      2 [sc412]
      2 [sc2.5.4]
      2 [sc246]
      2 [sc244]
      2 [role attribute]
      2 [property]
      2 [programmatic label]
      2 [programmatically determined link context]
      2 [primary language subtag]
      2 [presentation]
      2 [owned by]
      2 [nested browsing context]
      2 [named from author]
      2 [light tree]
      2 [language subtag registry]
      2 [label]
      2 [image request state]
      2 [html element]
      2 [global]
      2 [event listener list]
      2 [event listener]
      2 [element]
      2 [document title]
      2 [disabled]
      2 [device orientation]
      2 [device motion]
      2 [decorative]
      2 [current request]
      2 [content type]
      2 [content]
      2 [completely available]
      2 [browsing context]
      2 [assigned]
      2 [ascii whitespace]
      2 [aria 1.1]
      2 [accessible name and description computation]
      2 [accessible description]
      2 [accessibility tree]
      2 [accessibility supported]
      2 [abstract]

[WilcoFiers]

Great idea, need a volunteer for this though.

[Jym77]

CG call (22/10/2020): good idea but not much time to do it. Keeping it open for now, in case anybody is willing to spend time implementing this.
Auto-inclusion of our own defs is good. External defs are a bit more problematic as rules might refer to different versions (because they are written at different time), so it would be hard to maintain.

[WilcoFiers]

I'm going to take on this task as part of migrating content to the WAI website.