Support marking obsolete techniques and restore removed ones

[kfranqueiro]

This PR supersedes #3961; it accomplishes the same output, plus resolves a leftover empty section remaining in that PR.

Related issues: #3651, #3758

Note to WG

I would appreciate eyes on obsoleteMessage wording, seen at the end of each technique's About box (or at the top of HTML files in this PR) for restored obsolete techniques:

• Parsing techniques (obsolete in 2.2): F70, F77, G134, G192, H74, H75, H93, H94 (all should have the same message)
• Other previously-removed techniques: H4, H35, H46, H60, H73, H45, H59, H70, SCR37, G187, F87
• Flash and Silverlight (Message is implemented centrally for each of these types, inherited from the XSLT build system)

You don't need to worry about the implementation parts of the PR (unless you want to); I expect to ask @iadawn to review that part.

Background

Historically, techniques have been removed from this repository when they become obsolete. However, they are not removed from the WAI site in order to avoid link rot. This is not ideal, as it leaves those pages in isolation with no indication of being obsolete (with the exception of Flash and Silverlight pages, which had a message added by the build process).

Summary

This PR adds support for marking techniques as obsolete via front-matter. When a technique is marked as obsolete, it has the following effects:

• Obsolete techniques contain an extra message at the bottom of their "About this technique" paragraph (roughly following the existing example from Flash and Silverlight techniques)
• Links to the technique are omitted (e.g. from the techniques index and related techniques sections)
  • The one exception to this is links from one obsolete technique to another, in which case the links remain intact, to preserve the current WAI site behavior of obsolete technique pages remaining effectively untouched

This PR also adds considerations for WCAG 2.2's obsolete SC, 4.1.1 Parsing:

• Obsolete SC will no longer be referenced within the About this Technique box regarding applicable SC
• The Related Techniques section in Understanding pages for obsolete SC is excluded, since those techniques will also no longer reference the SC
• As with the exception to links above, these considerations only apply to pages that are not also obsolete themselves

Changes

• Implements 2 data fields for techniques pages:
  • obsoleteSince - indicates version upon which the technique became obsolete (in XY notation e.g. 22)
  • obsoleteMessage - Message to display in About this Technique box
  • These can be set in front-matter or in directory-level Eleventy data files (e.g. for Flash and Silverlight)
• Updates some transformation logic to account for new cases where list items or sections may become empty due to removed links to obsolete techniques
• Adds back almost all obsolete techniques I could find in git history, with obsoleteSince and obsoleteMessage set
  • To avoid cruft and confusion, I have intentionally not added back cross-links between previously-removed techniques, with the exception of H75 (which will still be relevant in WCAG 2.1, which I am also working on supporting in the new build system)

Exclusions

There are 2 techniques I have not restored; if folks have suggestions on wording for obsoleteMessage for them, I can add them:

• SCR21: this was removed for seemingly having more to do with subjective coding preference than accessibility
• G222: this only exists in 2.1 docs and probably shouldn't have ever been backported there, as it pertains to a SC that was initially added in 2.2 (not 2.1!) then removed before 2.2 was published

Note: XSLT build system deprecation

This PR introduces front-matter in some HTML files, which the previous XSLT build system won't know how to handle. Now that we have the Eleventy build system in use for WAI site updates as well as gh-pages deploys, there should be no further dependencies on it, and I plan to remove it and think about updating the main README (update: in #3985).

[netlify[bot]]

✅ Deploy Preview for wcag2 ready!

Name	Link
🔨 Latest commit	407efdff937eb4058817cb47a97880976061c29e
🔍 Latest deploy log	https://app.netlify.com/sites/wcag2/deploys/66b29235bf362d000822dd9a
😎 Deploy Preview	https://deploy-preview-3975--wcag2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[fstrr]

Could we make it stand out a bit more? Something along the lines of (but better looking) the note on the W3C's HTML 5 spec, for example. I'm not suggesting it be another fixed position box, it's more the fact that it stands out visually.

[iadawn]

I would like to make it stand out a bit more. Will have a play.

[w3cbot]

kfranqueiro marked as non substantive for IPR from ash-nazg.

[iadawn]

This is my suggested alternative. I do have the code but GitHub PRs of PRs is breaking me for the momet.

Includes:

• 'Obsolete' in page title
• Whole page class with subtle styling
• Move obsolete message box to just below title
• Slightly different styling for message box

[kfranqueiro]

Kevin sent me his changes (which are great, I was unaware of the CSS variables available in the W3C site's CSS) and I've integrated them with a couple of changes:

• Obsolete box uses h2 rather than h3 (the latter would be skipping a heading level; I've intentionally avoided adding it to the table of contents though)
• I was able to move Kevin's new Obsolete box design entirely into one of the _includes files (which is great that it enables doing that - less work for Cheerio)

[shawna-slh]

Is there a reason not to use the WAI site component for Document Notes, e.g., Deprecated? (Here's an implementation of Archived.)

We can create one for Obsolete.

We can also update the component visual design and other if we deem that best.

The component currently adds the note type to the <title>, which I think is important. Perhaps it should also be in the h1? — it's there visually but I think not programmatically.

[iadawn]

(Oops, missed the link to 'deprecated' - some of the below still applies)

Was thinking about the approach that I took before seeing the Archive component. This what was I had in mind when creating the Obsolete approach:

1. Extremely visually salient
2. Apparent that there was something different on the whole page
3. Clear to screen reader users

The Archived component does some of one, none of two and some of three.

The obsolete box is that bit more salient: whole block colour, stronger block heading style. Arguable whether red or yellow is more visually salient, that may be much more of a preference. One thing I did play about with was including an icon to make it even stronger as a warning.

I included a left hand border as something to try to hint at there being something different about this page. Bars like this are are a relatively common way to link together content (for example GDS error message component) although I would struggle to find a pattern where it is used full page.

Finally, Obsolete pages includes content in the <title>. I am not sure it also needs it in the <h1>. I played with it a bit but it started to become a bit cluttered visually and I am assuming this would be similarly cluttered for screen reader users.

Broadly speaking I think there is a need for a component that is stronger than archived. Archived content may still have some interest within it, Obsolete content should not be used. These are slightly different points.

[mbgower]

I am fine with going with the EO deprecated style for the obsolete, but also think Kevin's comments about a visual distinction have merit. Either is an improvement on current, and either would be satisfactory IMO.

[bruce-usab]

Just my first impression opinion, this is all moving in the right direction and an improvement. Thank you Shawn and Keven and EO.

Is there a reason not to use the WAI site component for Document Notes, e.g., Deprecated? (Here's an implementation of Archived.)

+1 to deprecated component, -1 to archived component.

[bruce-usab]

@kfranqueiro what is the plan for 2.1 and 4.1.1 Techniques?. I am of the opinion they should also be flagged as Obsolete.

This failure relates to 4.1.1: Parsing, and should be considered as always satisfied for any content using HTML or XML. This Success Criterion was removed in WCAG 2.2.

[kfranqueiro]

@kfranqueiro what is the plan for 2.1 and 4.1.1 Techniques?. I am of the opinion they should also be flagged as Obsolete.

@bruce-usab I marked them as obsoleteSince: 22, which would not flag them as obsolete in 2.1, since the SC wasn't removed until 2.2. If we really feel strongly, that can be tweaked by changing obsoleteSince in the 4.1.1-related techniques in this PR.

This property has no effect on message content, only on whether the message is rendered or not, depending on the version being built.

(Note that the majority of 2.1-specific support for the Eleventy build system will be in a separate PR after this gets merged.)

[kfranqueiro]

Replying to @bruce-usab:

Can we find a disclaimer on Adobe.com wrt Flash being unsupported to link to? (And to something similar for Silverlight?)

I've now added links to end-of-life articles regarding both.

For the technique using summary attribute on tables, please mention the version or year the attribute was dropped from HTML.

I added a change to reflect that summary has been obsolete since HTML5 (as per the differences document published in 2014; the decision to remove it seems to date back as early as 2011).

I'm curious as to why this was requested for this specific attribute?

[bruce-usab]

From backlog call today, I aspire to offer some additional text for the explanations of why obsoleted for the few that (like summary) just have the statement that XYZ is obsolete.

[iadawn]

@bruce-usab If you open that up as a separate PR