Remove superseded XSLT build targets and update README (w3c#3985)

WAI site pushes and gh-pages deploys no longer depend on the XSLT build process, and w3c#3975 includes code that works _only_ with the Eleventy-based build system. To avoid any accidents, this PR removes the parts of the XSLT process that are no longer needed, i.e. anything exclusively related to generating techniques and understanding pages. (Anything related to JSON generation has been left intact, until such time as that is tackled under the new process as well.) This PR also updates the main README to include a reference to the new build system README, remove references to XML and XSLT, update documentation around term definitions, and add documentation about marking obsolete techniques (added by w3c#3975). Additional README fixes: - Typos - Notation that was being swallowed during markdown parsing (e.g. `<version>`) - Default branch references (updated from master to main)
AKJUS · Aug 7, 2024 · 86d3081 · 86d3081
1 parent 42597e3
commit 86d3081
Show file tree

Hide file tree

Showing 10 changed files with 48 additions and 2,384 deletions.
diff --git a/11ty/CustomLiquid.ts b/11ty/CustomLiquid.ts
@@ -16,6 +16,7 @@ import { techniqueToUnderstandingLinkSelector } from "./understanding";
 
 const titleSuffix = " | WAI | W3C";
 
+/** Matches index and about pages, traditionally processed differently than individual pages */
 const indexPattern = /(techniques|understanding)\/(index|about)\.html$/;
 const techniquesPattern = /\btechniques\//;
 const understandingPattern = /\bunderstanding\//;
@@ -85,7 +86,6 @@ export class CustomLiquid extends Liquid {
   public parse(html: string, filepath?: string) {
     // Filter out Liquid calls for computed data and includes themselves
     if (filepath && !filepath.includes("_includes/") && isHtmlFileContent(html)) {
-      /** Matches paths that would go through process-index.xslt in previous process */
       const isIndex = indexPattern.test(filepath);
       const isTechniques = techniquesPattern.test(filepath);
       const isUnderstanding = understandingPattern.test(filepath);

diff --git a/11ty/README.md b/11ty/README.md
@@ -86,6 +86,6 @@ when `WCAG_MODE=editors` is also set.
 - The main configuration can be found in top-level `eleventy.config.ts`
 - Build commands are defined in top-level `package.json` under `scripts`,
   and can be run via `npm run <name>`
-- If you see files named `*.11tydata.js`, these contribute data to the Eleventy build
+- If you see files named `*.11tydata.*`, these contribute data to the Eleventy build
   (see Template and Directory Data files under
   [Sources of Data](https://www.11ty.dev/docs/data/#sources-of-data))
diff --git a/README.md b/README.md
@@ -11,18 +11,20 @@ This repository is used to develop content for WCAG 2, as well as associated und
 
 * Avoid use of RFC2119 terms such as "must", "shall", or "may" in non-normative content, to avoid confusion with normative role.
 
+See also: [WCAG 2 Style Guide](https://github.com/w3c/wcag/wiki/WCAG-2-style-guide)
+
 ## File Structure
 
 WCAG 2.0 was maintained in a different file structure than subsequent versions of WCAG. Source files for WCAG 2.0 are in the wcag20 folder and exists primarily for archival purposes. Do not edit content in that folder.
 
-Content for WCAG 2.1 and later is organized accordign to the file structure below. The WCAG repository contains source and auxiliary files for WCAG 2, Understanding WCAG 2, and eventually techniques. It also contains auxiliary files that support automated formatting of the document. To facilitate multi-party editing, each success criterion is in a separate file, consisting of a HTML fragment that can be included into the main guidelines. Key files include:
+Content for WCAG 2.1 and later is organized according to the file structure below. The WCAG repository contains source and auxiliary files for WCAG 2, Understanding WCAG 2, and eventually techniques. It also contains auxiliary files that support automated formatting of the document. To facilitate multi-party editing, each success criterion is in a separate file, consisting of a HTML fragment that can be included into the main guidelines. Key files include:
 
-* guidelines/index.html - the main guidelines file
-* guidelines/sc/<version>/*.html - files for each success criterion
-* guidelines/terms/<version>/*.html - files for each definition
-* understanding/<version>/*.html - understanding files for each success criterion
+* `guidelines/index.html` - the main guidelines file
+* `guidelines/sc/{version}/*.html` - files for each success criterion
+* `guidelines/terms/{version}/*.html` - files for each definition
+* `understanding/{version}/*.html` - understanding files for each success criterion
 
-Where <version> is "20", content came from WCAG 2.0. "21" is used for content introduced in WCAG 2.1, "22" for WCAG 2.2, etc.
+Where `{version}` is "20", content came from WCAG 2.0. "21" is used for content introduced in WCAG 2.1, "22" for WCAG 2.2, etc.
 
 ## Editing Draft Success Criteria
 
@@ -34,7 +36,7 @@ Where <version> is "20", content came from WCAG 2.0. "21" is used for content in
 1. Open the guidelines/index.html file and remove comment marks around the lines that reference the success criterion and terms you have edited..
 1. Follow the [success criteria format](#user-content-success-criteria-format) below to create the SC content.
 1. Save the file and commit the change. NOTE: It is important to also add a suitable 'commit message'. In the comments, reference the issue number from which the proposal was developed starting with a hash, e.g., `#1`. 
-1. When the success criterion is ready for Working Group review, inform the chairs. Once the proposal has been accepted by the Working Group, the editors will merge the working branch into the master branch, which puts it in the editors' draft and eventual Technical Report publication.
+1. When the success criterion is ready for Working Group review, inform the chairs. Once the proposal has been accepted by the Working Group, the editors will merge the working branch into the main branch, which puts it in the editors' draft and eventual Technical Report publication.
 
 ### Success Criteria Format
 
@@ -79,21 +81,23 @@ Values you provide are described below. Refer to [Success Criterion 2.2.1](https
 
 ### Definitions
 
-If you providing term definitions along with your SC, include them in the glossary. Position them in the appropriate alphabetical order with the rest of the terms and use the following format:
+If you are providing term definitions along with your SC, include them in the respective `guidelines/terms/{version}` directory, one-per-file, using the following format:
 
 ```html
-<dt><dfn>{Term}</dfn></dt>
+<dt><dfn id="dfn-{shortname}">{Term}</dfn></dt>
 <dd>{Definition}</dd>
 ```
 
-The ```dfn``` element tells the script that this is a term and causes special styling and linking features. To link to a term, use an `<a>` element without an `href` attribute; if the link text is the same as the term, the link will be correctly generated. For example, if there is a term `<dfn>web page</dfn>` on the page, a link in the form of `<a>web page</a>` will result in a proper link. If the link text has a different form from the canonical term, e.g., "web pages" (note the plural), you can provide a hint on the term definition with the `data-lt` attribute. In this example, modify the term to be `<dfn data-lt="web pages">web page</dfn>`. Multiple alternate names for the term can be separated with pipe characters, with no leading or trailing space, e.g., `<dfn data-lt="web pages|page|pages">web page</dfn>`.
+The ```dfn``` element tells the script that this is a term and causes special styling and linking features. To link to a term, use an `<a>` element without an `href` attribute; if the link text is the same as the term, the link will be correctly generated. For example, if there is a term `<dfn>web page</dfn>` on the page, a link in the form of `<a>web page</a>` will result in a proper link.
+
+If the link text has a different form from the canonical term, e.g., "web pages" (note the plural), you can provide a hint on the term definition with the `data-lt` attribute. In this example, modify the term to be `<dfn data-lt="web pages">web page</dfn>`. Multiple alternate names for the term can be separated with pipe characters, with no leading or trailing space, e.g., `<dfn data-lt="web pages|page|pages">web page</dfn>`.
 
 ## Editing Draft Understanding Content
 
 There is one Understanding file per success criterion, plus an index:
 
-* understanding/index.html - index page, need to uncomment or add a reference to individual Understanding pages as they are made available
-* understanding/<version>/*.html - files for each understanding page, named the same as the success criterion file in the guidelines
+* `understanding/index.html` - index page, need to uncomment or add a reference to individual Understanding pages as they are made available
+* `understanding/{version}/*.html` - files for each understanding page, named the same as the success criterion file in the guidelines
 
 Files are populated with a template that provides the expected structure. Leave the template structure in place, and add content as appropriate within the sections. Elements with class="instructions" provide guidance about what content to include in that section; you can remove those elements if you want but don't have to. The template for examples proposes either a bullet list or a series of sub-sections, choose one of those approaches and remove the other from the template. The template for techniques includes sub-sections for "situations", remove that wrapper section if not needed.
 
@@ -111,8 +115,6 @@ The [technique template](techniques/technique-template.html) shows the structure
 
 Techniques can use a temporary style sheet to facilitate review of drafts. This style sheet is replaced by other style sheets and structure for formal publication. To use this style sheet, add `<link rel="stylesheet" type="text/css" href="../../css/editors.css"/>` to the head of the technique.
 
-The generator used to publish techniques uses XML processing, so techniques must be well-formed XML. Techniques use HTML 5 structure so are actually [HTML Polyglot](https://www.w3.org/TR/html-polyglot/).  
-
 ### Images, Examples, Cross References for Techniques
 
 Techniques can include images. Place the image file in the `img` folder of the relevant technology - meaning all techniques for a technology share a common set of images. Use a relative link to load the image. Most images should be loaded with a `<figure>` element and labeled with a `<figcaption>` positioned at the bottom of the figure. `<figure>` elements must have an `id` attribute. Small inline images may be loaded with a `<img>` element with suitable `alt` text.
@@ -134,10 +136,11 @@ Each new technique should be created in a new branch. Set-up of the branch and f
 ```Shell
 bash create-techniques.sh <technology> <filename> <type> "<title>"
 ```
-\<technology> is the technology directory for the technique
-\<filename> is the temporary filename (without extension) for the technique
-\<type> is "technique" or "failure"
-\<title> is the title of the technique, enclosed in quotes and escaping special characters with \\
+
+* `<technology>` is the technology directory for the technique
+* `<filename>` is the temporary filename (without extension) for the technique
+* `<type>` is "technique" or "failure"
+* `<title>` is the title of the technique, enclosed in quotes and escaping special characters with \\
 
 This automates the following steps:
 
@@ -149,16 +152,36 @@ This automates the following steps:
 Once a technique branch and file is set up, populate the content and request review:
 
 * Populate the template with appropriate content, using other techniques as examples for code formatting choices. Keep the existing structural sections from the template in place.
-* When the technique is ready for review, make a pull request into master.
+* When the technique is ready for review, make a pull request into the main branch.
 * If you wish to reference the draft technique from an Understanding document, use the technique's rawgit URI.
 * After a technique is approved, the chairs will assign it an ID and update links to it in the Undestanding documents. 
 
 ### Formatting Techniques
 
-Techniques in the repository are plain HTML files with minimal formatting. For publication to the editors' draft and W3C location, techniques are formatted by an XSLT-based generator managed by Apache Ant running in Java. Most people do not need to worry about this, but relevant files are the [Ant build file](build.xml) and [XSLT files](xslt).
+Techniques in the repository are plain HTML files with minimal formatting. For publication to the editors' draft and W3C location, techniques are formatted by a build process based on Eleventy for templating and Cheerio for transformations. More details, including instructions for previewing locally, can be found in the [build process README](11ty/README.md).
 
 The generator compiles the techniques together as a suite with formatting and navigation. It enforces certain structures, such as ordering top-level sections described above and standardizing headings. It attempts to process cross reference links to make sure the URIs work upon publication. One of the most substantial roles is to populate the Applicability section with references to the guidelines or success criteria to which the technique relates. The information for this comes from the Understanding documents. Proper use of the technique template is important to enable this functionality, and mal-formed techniques may cause the generator to fail.
 
+### Obsolete Techniques
+
+Obsolete techniques should not be removed from the repository. Instead, they can be marked using YAML front-matter. For example:
+
+```yaml
+---
+obsoleteSince: 22
+obsoleteMessage: |
+  This failure relates to 4.1.1: Parsing, which was removed as of WCAG 2.2.
+---
+```
+
+* `obsoleteSince` indicates the earliest version of WCAG 2 when the technique became obsolete
+  (this may be set to `20` if it should effectively be obsolete for all versions, e.g. for
+  techniques involving deprecated HTML elements)
+* `obsoleteMessage` indicates a message to be displayed within the About this Technique section
+
+In cases where entire technologies are obsolete (e.g. Flash and Silverlight), these properties may also be specified at the technique subdirectory level, e.g. via `techniques/flash/flash.11tydata.json`.
+Note that this case specifically requires JSON format, as this is consumed by both Eleventy and additional code in the build process used to assemble techniques data.
+
 ## Working Examples
 
 Examples in techniques should be brief easy-to-consume code samples of how the technique is used in content. Therefore examples should focus on the specific features the technique describes, and not include related content such as style, script, surrounding web content, etc.
@@ -174,8 +197,8 @@ To create a working example:
 * Create a directory for the example inside the working examples directory, using the semantic name for the example minus the prefix used in the branch name, e.g., `working-examples/alt-attribute/`.
 * If the primary example is HTML, name the file `index.html`. Otherwise, create a suitable file name.
 * Refer to resources shared among multiple examples using relative links, e.g., `../css/example.css`. Place other resources in the same directory as the main example, e.g., `working-examples/alt-attribute/css/alt.css`.
-* Reference working examples from techniques using the rawgit URI to the example in its development branch, e.g., `https://rawgit.com/w3c/wcag/master/working-examples/alt-attribute/`. Editors will update links when examples are approved.
-* When the example is complete and functional, submit a pull request into the master branch.
+* Reference working examples from techniques using the rawgit URI to the example in its development branch, e.g., `https://rawgit.com/w3c/wcag/main/working-examples/alt-attribute/`. Editors will update links when examples are approved.
+* When the example is complete and functional, submit a pull request into the main branch.
 
 ## Translations