Editorial: Normalize HTML spec references using xref #1906
Conversation
| <td class="role-base"> | ||
| <a href="https://www.w3.org/TR/html5/grouping-content.html#the-dl-element"><abbr title="Hypertext Markup Language">HTML</abbr> <code>dl</code></a> | ||
| </td> | ||
| <td class="role-base"><code><[^dl^]></code> in HTML</td> |
There was a problem hiding this comment.
I settled on a syntax convention of “<element-name> in HTML”, where just the element name is linked using its xref term. I kept (or added, where needed) the < and > brackets to aid in quick understandability/differentiation when referencing an HTML element versus a plain text role string or attribute name.
| @@ -12702,7 +12703,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2> | |||
| <tbody> | |||
| <tr> | |||
| <th class="property-related-head" scope="row">Related Concepts:</th> | |||
| <td class="property-related"><code>required</code> attribute in [[HTML]]</td> | |||
| <td class="property-related"><code>[^input/required^]</code> attribute in HTML</td> | |||
There was a problem hiding this comment.
We’ve got a few references to form-related attributes like required that could be misinterpreted as global attributes when they actually have multiple distinct HTML spec definitions, like [^input/required^] vs. [^textarea/required^] vs. [^select/required^]. For now, I just linked to the input-scoped definition and didn’t add any additional language to disambiguate. What do you think? Here are the applicable attributes I encountered:
placeholderreadonlyrequired
| @@ -13435,7 +13436,7 @@ <h3>State and Property Attributes</h3> | |||
| </section> | |||
| <section id="host_general_focus"> | |||
| <h2>Focus Navigation</h2> | |||
| <p>An implementing host language MUST provide support for the author to make all interactive elements focusable, that is, any renderable or event-receiving elements. An implementing host language MUST provide a facility to allow web authors to define whether these focusable, interactive elements appear in the default tab navigation order. The <code>tabindex</code> <a>attribute</a> in <abbr title="Hypertext Markup Language">HTML</abbr> is an example of one implementation.</p> | |||
| <p>An implementing host language MUST provide support for the author to make all interactive elements focusable, that is, any renderable or event-receiving elements. An implementing host language MUST provide a facility to allow web authors to define whether these focusable, interactive elements appear in the default tab navigation order. The <code>tabindex</code> <a>attribute</a> in HTML is an example of one implementation.</p> | |||
There was a problem hiding this comment.
TIL that when ReSpec encounters a unique <abbr> pattern in the document, it automatically generates identical <abbr> markup for all subsequent occurrences of the plain text abbreviation string. 🤩
Because I encountered a few explicit abbreviation markups for “HTML” during this PR, I found and left the first occurrence of “<abbr title="Hypertext Markup Language">HTML</abbr>” on line 475, then simplified all later occurrences to just plain “HTML” to reduce noise in the document.
FWIW, it looks like we’ve got a ton more abbreviations we could simplify if that were desirable? E.g., “WAI-ARIA”, “DOM”, “API”. If anyone think that’s a good idea, please say the word — I’d be happy to do a separate PR for that.
*[TIL]: Today I learned
*[FWIW]: For what it’s worth
adampage
added
the
editorial
adampage
changed the title
|
@spectranaut and @jnurthen, what do you think of this spot in the readme to add some |
|
Oh sorry -- I misread the comment. You already added what you wanted here, correct? |
|
Thanks, @pkra — yep, I’ve already added an update to the readme in this PR. |
SHA: 10112f8 Reason: push, by jnurthen Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: James Nurthen <jnurthen@users.noreply.github.com>
Closes #1903
A little editorial cleanup to normalize the way we reference HTML spec definitions for elements and attributes. I’ll leave a few notes in context below.
Preview | Diff