From 05fd0191443677e16870e638251e52e7f08aa5fa Mon Sep 17 00:00:00 2001 From: "Kenneth G. Franqueiro" Date: Wed, 15 Jan 2025 13:44:54 -0500 Subject: [PATCH] Add errata to w3c/wcag repo and cross-reference from informative docs (#4170) This adds the following: - Imports the 2.1 and 2.2 errata pages into this repo - Reorganizes existing 2.1 errata in reverse-chronological order - Adds date stamps for all existing errata I could trace back to a commit - Makes use of variables and Liquid expressions to minimize potential for copy-paste errors between sections - Auto-generates table of contents within `CustomLiquid.ts` to avoid desync when adding versions - Documents patterns/formats for authoring errata in `errata/README.md` (with mention in top-level README) - Adds logic to parse information from errata pages and include relevant errata within Guideline/SC boxes and term definitions within informative docs pages - Errata are only included when building for a specific version (i.e. not the editor's draft, in which case corrections are expected to already be inlined) - Only errata against the latest published version are included in informative docs - Updates `publish-w3c` script to also copy relevant errata file for version being published - Adds links to errata pages in top-level index used for dev server and PR builds --- .eleventyignore | 1 + 11ty/CustomLiquid.ts | 43 +++++++- 11ty/cp-cvs.ts | 6 ++ 11ty/guidelines.ts | 122 +++++++++++++++------- README.md | 8 ++ _includes/understanding/about.html | 27 +++-- eleventy.config.ts | 16 +++ errata/21.html | 158 +++++++++++++++++++++++++++++ errata/22.html | 132 ++++++++++++++++++++++++ errata/README.md | 93 +++++++++++++++++ index.html | 2 + 11 files changed, 555 insertions(+), 53 deletions(-) create mode 100644 errata/21.html create mode 100644 errata/22.html create mode 100644 errata/README.md diff --git a/.eleventyignore b/.eleventyignore index 752acaedf1..a9be492c6d 100644 --- a/.eleventyignore +++ b/.eleventyignore @@ -1,4 +1,5 @@ *.md +**/README.md 11ty/ acknowledgements.html acknowledgements/ diff --git a/11ty/CustomLiquid.ts b/11ty/CustomLiquid.ts index 948a4847f3..5b19b8e2ab 100644 --- a/11ty/CustomLiquid.ts +++ b/11ty/CustomLiquid.ts @@ -92,9 +92,36 @@ export class CustomLiquid extends Liquid { super(options); this.termsMap = options.termsMap; } + + private renderErrata(html: string) { + const $ = load(html); + + const $tocList = $("#contents .toc"); + let $childList: CheerioAnyNode | null = null; + $("main section[id]:has(h2:first-child, h3:first-child)").each((_, el) => { + const $el = $(el); + // Only one of the following queries will match for each section + $el.find("> h2:first-child").each((_, h2El) => { + $childList = null; + $tocList.append(`
  • ${$(h2El).text()}
    • `); + }); + $el.find("> h3:first-child").each((_, h3El) => { + if (!$childList) $childList = $(`
      `).appendTo($tocList); + $childList.append(`
    1. ${$(h3El).text()}
      2. `); + }); + }); + + return $.html(); + } + public parse(html: string, filepath?: string) { // Filter out Liquid calls for computed data and includes themselves - if (filepath && !filepath.includes("_includes/") && isHtmlFileContent(html)) { + if ( + filepath && + !filepath.includes("_includes/") && + !filepath.includes("errata/") && + isHtmlFileContent(html) + ) { const isIndex = indexPattern.test(filepath); const isTechniques = techniquesPattern.test(filepath); const isUnderstanding = understandingPattern.test(filepath); @@ -309,6 +336,7 @@ export class CustomLiquid extends Liquid { // html contains markup after Liquid tags/includes have been processed const html = (await super.render(templates, scope, options)).toString(); if (!isHtmlFileContent(html) || !scope || scope.page.url === false) return html; + if (scope.page.inputPath.includes("errata/")) return this.renderErrata(html); const $ = load(html); @@ -468,10 +496,15 @@ export class CustomLiquid extends Liquid { }); for (const name of termNames) { const term = this.termsMap[name]; // Already verified existence in the earlier loop - $termsList.append( - `
      ${term.name}
      ` + - `
      ${term.definition}
      ` - ); + let termBody = term.definition; + if (scope.errata[term.id]) { + termBody += ` +

      Errata:

      + +

      View all errata

      + `; + } + $termsList.append(`
      ${term.name}
      ${termBody}
      `); } // Iterate over non-href links once more in now-expanded document to add hrefs diff --git a/11ty/cp-cvs.ts b/11ty/cp-cvs.ts index 3adf39bb7c..46938b2dd9 100644 --- a/11ty/cp-cvs.ts +++ b/11ty/cp-cvs.ts @@ -51,3 +51,9 @@ for (const [srcDir, destDir] of Object.entries(dirs)) { await copyFile(srcPath, destPath); } } + +await mkdirp(join(wcagBase, "errata")); +await copyFile( + join(outputBase, "errata", `${wcagVersion}.html`), + join(wcagBase, "errata", "Overview.html") +); diff --git a/11ty/guidelines.ts b/11ty/guidelines.ts index 27cc3fd8ff..4e198c37d6 100644 --- a/11ty/guidelines.ts +++ b/11ty/guidelines.ts @@ -3,9 +3,9 @@ import type { CheerioAPI } from "cheerio"; import { glob } from "glob"; import { readFile } from "fs/promises"; -import { basename } from "path"; +import { basename, join } from "path"; -import { flattenDomFromFile, load, type CheerioAnyNode } from "./cheerio"; +import { flattenDomFromFile, load, loadFromFile, type CheerioAnyNode } from "./cheerio"; import { generateId } from "./common"; export type WcagVersion = "20" | "21" | "22"; @@ -233,50 +233,52 @@ export async function getTermsMap(version?: WcagVersion) { // Version-specific APIs -const remoteGuidelines$: Partial> = {}; +const guidelinesCache: Partial> = {}; /** Loads guidelines from TR space for specific version, caching for future calls. */ -const loadRemoteGuidelines = async (version: WcagVersion) => { - if (!remoteGuidelines$[version]) { - const $ = load( - (await axios.get(`https://www.w3.org/TR/WCAG${version}/`, { responseType: "text" })).data - ); - - // Re-collapse definition links and notes, to be processed by this build system - $("a.internalDFN").removeAttr("class data-link-type id href title"); - $("[role='note'] .marker").remove(); - $("[role='note']").find("> div, > p").addClass("note").unwrap(); - - // Convert data-plurals (present in publications) to data-lt - $("dfn[data-plurals]").each((_, el) => { - el.attribs["data-lt"] = (el.attribs["data-lt"] || "") - .split("|") - .concat(el.attribs["data-plurals"].split("|")) - .join("|"); - delete el.attribs["data-plurals"]; - }); +const loadRemoteGuidelines = async (version: WcagVersion, stripRespec = true) => { + const html = + guidelinesCache[version] || + (guidelinesCache[version] = ( + await axios.get(`https://www.w3.org/TR/WCAG${version}/`, { responseType: "text" }) + ).data); + + const $ = load(html); + if (!stripRespec) return $; + + // Re-collapse definition links and notes, to be processed by this build system + $("a.internalDFN").removeAttr("class data-link-type id href title"); + $("[role='note'] .marker").remove(); + $("[role='note']").find("> div, > p").addClass("note").unwrap(); + + // Convert data-plurals (present in publications) to data-lt + $("dfn[data-plurals]").each((_, el) => { + el.attribs["data-lt"] = (el.attribs["data-lt"] || "") + .split("|") + .concat(el.attribs["data-plurals"].split("|")) + .join("|"); + delete el.attribs["data-plurals"]; + }); - // Un-process bibliography references, to be processed by CustomLiquid - $("cite:has(a.bibref:only-child)").each((_, el) => { - const $el = $(el); - $el.replaceWith(`[${$el.find("a.bibref").html()}]`); - }); + // Un-process bibliography references, to be processed by CustomLiquid + $("cite:has(a.bibref:only-child)").each((_, el) => { + const $el = $(el); + $el.replaceWith(`[${$el.find("a.bibref").html()}]`); + }); - // Remove generated IDs and markers from examples - $(".example[id]").removeAttr("id"); - $(".example > .marker").remove(); + // Remove generated IDs and markers from examples + $(".example[id]").removeAttr("id"); + $(".example > .marker").remove(); - // Remove extra markup from headings so they can be parsed for names - $("bdi").remove(); + // Remove extra markup from headings so they can be parsed for names + $("bdi").remove(); - // Remove abbr elements which exist only in TR, not in informative docs - $("#acknowledgements li abbr, #glossary abbr").each((_, abbrEl) => { - $(abbrEl).replaceWith($(abbrEl).text()); - }); + // Remove abbr elements which exist only in TR, not in informative docs + $("#acknowledgements li abbr, #glossary abbr").each((_, abbrEl) => { + $(abbrEl).replaceWith($(abbrEl).text()); + }); - remoteGuidelines$[version] = $; - } - return remoteGuidelines$[version]!; + return $; }; /** @@ -299,3 +301,45 @@ export const getAcknowledgementsForVersion = async (version: WcagVersion) => { */ export const getPrinciplesForVersion = async (version: WcagVersion) => processPrinciples(await loadRemoteGuidelines(version)); + +/** Parses errata items from the errata document for the specified WCAG version. */ +export const getErrataForVersion = async (version: WcagVersion) => { + const $ = await loadFromFile(join("errata", `${version}.html`)); + const $guidelines = await loadRemoteGuidelines(version, false); + const aSelector = `a[href*='}}#']:first-of-type`; + const errata: Record = {}; + + $("main > section[id]") + .first() + .find(`li:has(${aSelector})`) + .each((_, el) => { + const $el = $(el); + const erratumHtml = $el + .html()! + // Remove everything before and including the final TR link + .replace(/^[\s\S]*href="\{\{\s*\w+\s*\}\}#[\s\S]*?<\/a>,?\s*/, "") + // Remove parenthetical github references (still in Liquid syntax) + .replace(/\(\{%.*%\}\)\s*$/, "") + .replace(/^(\w)/, (_, p1) => p1.toUpperCase()); + + $el.find(aSelector).each((_, aEl) => { + const $aEl = $(aEl); + let hash: string | undefined = $aEl.attr("href")!.replace(/^.*#/, ""); + + // Check whether hash pertains to a guideline/SC section or term definition; + // if it doesn't, attempt to resolve it to one + const $hashEl = $guidelines(`#${hash}`); + if (!$hashEl.is("section.guideline, #terms dfn")) { + const $closest = $hashEl.closest("#terms dd, section.guideline"); + if ($closest.is("#terms dd")) hash = $closest.prev().find("dfn[id]").attr("id"); + else hash = $closest.attr("id"); + } + if (!hash) return; + + if (hash in errata) errata[hash].push(erratumHtml); + else errata[hash] = [erratumHtml]; + }); + }); + + return errata; +}; diff --git a/README.md b/README.md index 66c59c52de..7ecd29e4fa 100644 --- a/README.md +++ b/README.md @@ -240,6 +240,14 @@ To create a working example: * 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. +## Errata + +The errata documents for WCAG 2.1 and 2.2 are now maintained in this repository. +See the [Errata README](errata/README.md) for authoring details. + +**Note:** The errata for both versions are maintained on the `main` branch for use in builds. +Direct edits to the guidelines for WCAG 2.1 must be performed under `guidelines/` on the `WCAG-2.1` branch. + ## Translations WCAG 2.2 is ready for translation. To translate WCAG 2.2, follow instructions at [How to Translate WCAG 2](https://www.w3.org/WAI/about/translating/wcag/). diff --git a/_includes/understanding/about.html b/_includes/understanding/about.html index 098d0b9997..efcc2b298e 100644 --- a/_includes/understanding/about.html +++ b/_includes/understanding/about.html @@ -1,9 +1,18 @@ -{%- if guideline.type == "SC" -%} - {% sectionbox "success-criterion" "Success Criterion (SC)" -%} - {{ guideline.content }} - {%- endsectionbox %} -{%- elsif guideline.type == "Guideline" -%} - {% sectionbox "guideline" "Guideline" -%} - {{ guideline.content }} - {%- endsectionbox %} -{%- endif -%} +{%- capture section_id -%} + {%- if guideline.type == "SC" -%}success-criterion{%- else -%}guideline{%- endif -%} +{%- endcapture -%} +{%- capture section_title -%} + {%- if guideline.type == "SC" -%}Success Criterion (SC){%- else -%}Guideline{%- endif -%} +{%- endcapture -%} +{% sectionbox section_id section_title -%} + {{ guideline.content }} + {%- if errata[guideline.id] %} +

      Errata

      +
        + {%- for erratum in errata[guideline.id] %} +
      • {{ erratum }}
        • + {%- endfor -%} +
      +

      View all errata

      + {% endif -%} +{%- endsectionbox %} diff --git a/eleventy.config.ts b/eleventy.config.ts index d579a657ff..95d973b5c1 100644 --- a/eleventy.config.ts +++ b/eleventy.config.ts @@ -11,6 +11,7 @@ import { resolveDecimalVersion } from "11ty/common"; import { actRules, assertIsWcagVersion, + getErrataForVersion, getFlatGuidelines, getPrinciples, getPrinciplesForVersion, @@ -110,6 +111,7 @@ const termsMap = process.env.WCAG_VERSION ? await getTermsMap(version) : await g const globalData = { version, versionDecimal: resolveDecimalVersion(version), + errata: process.env.WCAG_VERSION ? await getErrataForVersion(version) : {}, techniques, // Used for techniques/index.html technologies, // Used for techniques/index.html technologyTitles, // Used for techniques/index.html @@ -277,6 +279,7 @@ export default function (eleventyConfig: any) { root: ["_includes", "."], jsTruthy: true, strictFilters: true, + timezoneOffset: 0, // Avoid off-by-one YYYY-MM-DD date stamp conversions termsMap, }) ); @@ -382,6 +385,19 @@ export default function (eleventyConfig: any) { } ); + // Renders a link to a GitHub commit or pull request + eleventyConfig.addShortcode("gh", (id: string) => { + if (/^#\d+$/.test(id)) { + const num = id.slice(1); + return `${id}` + } + else if (/^[0-9a-f]{7,}$/.test(id)) { + const sha = id.slice(0, 7); // Truncate in case full SHA was passed + return `${sha}` + } + else throw new Error(`Invalid SHA or PR ID passed to gh tag: ${id}`); + }); + // Renders a section box (used for About this Technique and Guideline / SC) eleventyConfig.addPairedShortcode( "sectionbox", diff --git a/errata/21.html b/errata/21.html new file mode 100644 index 0000000000..0335ead4d0 --- /dev/null +++ b/errata/21.html @@ -0,0 +1,158 @@ +{%- # PLEASE READ errata/README.md BEFORE EDITING -%} + + + + + Web Content Accessibility Guidelines (WCAG) 2.1 Errata + + + + +
      +

      W3C

      +

      Web Content Accessibility Guidelines (WCAG) 2.1 Errata

      +

      Last modified: $Date: 2024/02/01 14:32:47 $

      +

      Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive license rules apply.

      +
      +
      +
      +

      Abstract

      +

      This document records all known errors in the Web Content Accessibility Guidelines (WCAG) 2.1 specification.

      +

      The errata are classified as Substantive or Editorial, as classified by the W3C Classes of Changes, and listed in reverse chronological order based on the date of publication to which they are applicable.

      +

      Each entry has the following information:

      +
        +
      • The date it was added to the errata page.
        • +
      • The section referred to.
        • +
      • A description of the problem and correction if applicable.
        • +
      • A rationale for making the change (not required for editorial errata).
        • +
      +

      Substantive corrections are proposed by the Accessibility Guidelines Working Group, which has consensus that they are appropriate; they are not to be considered normative until a new Recommendation is published following the process to revise a Recommendation.

      +

      Please view the public comment instructions if you would like to comment to the Working Group. Comments submitted are publicly available in the archive for the Accessibility Guidelines Working Group public comments mailing list.

      +

      The full commit history can be viewed on GitHub.

      +
      +
      +

      Table of Contents

      +
        + {%- # Leave this empty - populated during the build process -%} +
      +
      +
      +
      + {%- assign trDate = "current" -%} + {%- assign trUrl = "https://www.w3.org/TR/WCAG21/" -%} +
      +

      Errata since Current Publication

      +
      +

      Substantive Errata

      +

      No substantive errata have been recorded at present.

      +
      +
      +

      Editorial Errata

      +

      No editorial errata have been recorded at present.

      +
      +
      + + {%- assign trDate = "2018-06-05" -%} + {%- capture trUrl -%} + https://www.w3.org/TR/{{ trDate | split: "-" | first }}/REC-WCAG{{ page.fileSlug }}-{{ trDate | replace: "-", "" }}/ + {%- endcapture -%} +
      +

      Errata since {{ trDate | date: "%d %B %Y" }} Publication

      +
      +

      Substantive Errata

      +

      No substantive errata have been recorded at present.

      +
      +
      +

      Editorial Errata

      +
        +
      • + 2023-04-18: + In 4.1.1 Parsing, + removing one note and adding two new notes, including: "This Success Criterion should be considered as always satisfied for any content using HTML or XML." + ({% gh "#3152" %}) +
        • +
      • + 2022-02-22: + In the definition of relative luminance, + updating the red threshold from 0.03928 to 0.04045. + ({% gh "#1780" %}) +
        • +
      • + 2022-02-02: + In a note in the definition of accessibility supported, + updating "Conformance Criterion" references to "Conformance Requirement". + ({% gh "#1777" %}) +
        • +
      • + 2019-05-09: + In 1.3.4 Orientation, + clarifying the note referencing "binary display orientation" to read "content is not necessarily restricted to landscape or portrait display orientation". + ({% gh "#724" %}) +
        • +
      • + 2018-08-06: + In 1.4.13 Content on Hover or Focus, + correcting the word "dismissable" to "dismissible". + ({% gh "b043430" %}) +
        • +
      • + 2018-08-06: + In 4. Robust, removing repetition of the word "by". + ({% gh "6f883b5" %}) +
        • +
      • + 2018-08-06: + In 5.2.2 Full pages, removing "New" from the beginning of the third note. + ({% gh "5d42e28" %}) +
        • +
      • + 2018-07-11: + In the Introduction, + correcting several (but not all) "WCAG 2.0" references to "WCAG 2.1". + ({% gh "#430" %}, {% gh "#426" %}, {% gh "170c48a" %}) +
        • +
      • + 2018-07-11: + In 1.4.10 Reflow, + removing a supernumary "Note" indicator from the first note. + ({% gh "#429" %}) +
        • +
      • + 2018-07-11: + In the definition for keyboard interface, + updating the second (of three) notes to be an example of the first note, leaving only two actual notes. + ({% gh "#428" %}) +
        • +
      • + 2018-07-11: + In the definition for technology, + updating the third note to instead be an example. + ({% gh "#428" %}) +
        • +
      • + 2018-07-11: + In 5.3.1 Required Components of a Conformance Claim, + removing the editorial note "In WCAG 2.0 this was a dated URI, which may need to be adjusted when this becomes a Rec." + ({% gh "#427" %}) +
        • +
      • + 2018-07-11: + In the 0.5.2 Numbering in WCAG 2.1, + correcting the words "critera" and "ccriteria" to "criteria". + ({% gh "#426" %}) +
        • +
      • + 2018-06-08: + In 7. Input Purposes for User Interface Components, + correcting the word "county" to "country". + ({% gh "426e131" %}) +
        • +
      • In the Status of This Document, + removing the first instance of the repeated paragraph beginning "This document has been reviewed by W3C Members...". +
        • +
      +
      +
      +
      + + diff --git a/errata/22.html b/errata/22.html new file mode 100644 index 0000000000..3cfbe2f4bd --- /dev/null +++ b/errata/22.html @@ -0,0 +1,132 @@ +{%- # PLEASE READ errata/README.md BEFORE EDITING -%} + + + + + Web Content Accessibility Guidelines (WCAG) 2.2 Errata + + + + +
      +

      W3C

      +

      Web Content Accessibility Guidelines (WCAG) 2.2 Errata

      +

      Last modified: $Date: 2023/07/21 18:31:26 $

      +

      Copyright © 2018 W3C® (MIT, ERCIM, Keio, Beihang). W3Cliability, trademark and document use rules apply.

      +
      +
      +
      +

      Abstract

      +

      This document records all known errors in the Web Content Accessibility Guidelines (WCAG) 2.2 specification.

      +

      The errata are classified as Substantive or Editorial, as classified by the W3C Classes of Changes, and listed in reverse chronological order based on the date of publication to which they are applicable.

      +

      Each entry has the following information:

      +
        +
      • The date it was added to the errata page.
        • +
      • The section referred to.
        • +
      • A description of the problem and correction if applicable.
        • +
      • A rationale for making the change (not required for editorial errata).
        • +
      +

      Substantive corrections are proposed by the Accessibility Guidelines Working Group, which has consensus that they are appropriate; they are not to be considered normative until a new Recommendation is published following the process to revise a Recommendation.

      +

      Please view the public comment instructions if you would like to comment to the Working Group. Comments submitted are publicly available in the archive for the Accessibility Guidelines Working Group public comments mailing list.

      +

      The full commit history can be viewed on GitHub.

      +
      +
      +

      Table of Contents

      +
        + {%- # Leave this empty - populated during the build process -%} +
      +
      +
      +
      + {%- assign trDate = "current" -%} + {%- assign trUrl = "https://www.w3.org/TR/WCAG22/" -%} +
      +

      Errata since Current Publication

      +
      +

      Substantive Errata

      +

      No substantive errata recorded at present.

      +
      +
      +

      Editorial Errata

      +

      No editorial errata recorded at present.

      +
      +
      + + {%- assign trDate = "2023-10-05" -%} + {%- capture trUrl -%} + https://www.w3.org/TR/{{ trDate | split: "-" | first }}/REC-WCAG{{ page.fileSlug }}-{{ trDate | replace: "-", "" }}/ + {%- endcapture -%} +
      +

      Errata since {{ trDate | date: "%d %B %Y" }} Publication

      +
      +

      Substantive Errata

      +

      No substantive errata have been recorded at present.

      +
      +
      +

      Editorial Errata

      +
        +
      • + 2024-11-22: + Modifying visual presentation for content identified as New + ({% gh "#1481" %}, {% gh "#4145" %}) +
        • +
      • + 2024-11-19: + Making editorial changes to improve consistent use of the terms + "success criteria/criterion", "web", "website", and "web page" + ({% gh "#4080" %}) +
        • +
      • + 2024-11-19: + In the definition for single pointer, + updating to further enumerate interaction types and distinguish input modalities. + ({% gh "#4070" %}, {% gh "#3536" %}) +
        • +
      • + 2024-11-19: + In 7. Input Purposes for User Interface Components, + correcting the word "dissement" to "arrondissement". + ({% gh "#4034" %}) +
        • +
      • + 2024-11-19: + In the definition for cognitive function test, + updating the term from uppercase to lowercase. + ({% gh "#3943" %}) +
        • +
      • + 2024-11-19: + In Abstract, modifying language regarding devices. + ({% gh "#3776" %}) +
        • +
      • + 2024-11-19: + In 3.3.8 Accessible Authentication (Minimum) + and the definitions for change of context, + general flash and red flash thresholds, and + structure, changing ordered lists to unordered lists when no order is intended. + ({% gh "#3756" %}) +
        • +
      • + 2024-11-19: + In the definition for used in an unusual or restricted way, + genericizing WCAG version reference from "2.1" to "2". + ({% gh "#3707" %}) +
        • +
      • + 2024-11-19: Removing the defunct "encloses" definition. ({% gh "#3636" %})
        • +
      • + 2024-11-19: + In 2.5.8 Target Size (Minimum), updating formatting, grammar, and punctuation of exceptions. + ({% gh "#3189" %}) +
        • +
      • + 2024-11-19: + Making editorial changes to improve consistent use of definitions in the success criteria ({% gh "#3038" %}) +
        • +
      +
      +
      +
      + + diff --git a/errata/README.md b/errata/README.md new file mode 100644 index 0000000000..59d05ecc12 --- /dev/null +++ b/errata/README.md @@ -0,0 +1,93 @@ +# Errata Editing Instructions + +Errata are listed in reverse-chronological order, first sectioned by publish date, +then within each section based on when each erratum was added. + +## Sections + +The first top-level section under `
      ` corresponds to the latest version / unpinned URL; +subsequent sections correspond to previous versions / date-stamped URLs. + +Each top-level section should be preceded by `trDate` and `trUrl` variable assignments. +These variables reduce the chance of copy-paste errors within individual errata. +For sections corresponding to previous versions, assignments should follow this pattern +(only `YYYY-MM-DD` should need to be replaced): + +``` +{%- assign trDate = "YYYY-MM-DD" -%} +{%- capture trUrl -%} + https://www.w3.org/TR/{{ trDate | split: "-" | first }}/REC-WCAG{{ page.fileSlug }}-{{ trDate | replace: "-", "" }}/ +{%- endcapture -%} +``` + +The level 2 heading in the top-level section for each previous version should use this code +(no replacements necessary, making use of the preceding variable reassignments): + +```html +

      Errata since {{ trDate | date: "%d %B %Y" }} Publication

      +``` + +## Erratum format + +Each erratum should be in the following format +(replacing `YYYY-MM-DD`, `Section Title`, `sectionid`, `details of changes`, and `#NNNN`): + +```html +
    2. + YYYY-MM-DD: + In Section Title, + details of changes. + ({% gh #NNNN %}) +
      3. +``` + +Adhering to this format is important, as any entries under the latest published version will also be +parsed for inclusion within Guideline/SC boxes and Key Terms definitions within Understanding pages. +(Newlines are insignificant and are suggested for source code readability.) + +Each piece of this format is further explained in the subsections below. + +### Section reference + +When applicable, errata should begin with an indication of the section they relate to, including a link. + +Example phrasing when linking to a section, e.g. a success criterion: + +```html +In 2.5.8 Target Size (Minimum) +``` + +Example phrasing when linking to a term definition: + +```html +In the definition for single pointer +``` + +(Remember that term definition fraagments always begin with `dfn-`.) + +It is possible to reference multiple sections/terms from one erratum, +so long as all of the links remain front-loaded prior to the erratum's details. + +### Details of changes + +`details of what happened` should be expressed in present progressive tense +(e.g. "updating", "removing", "adding"), with the desired outcome listed first. +For example: + +- updating the red threshold from ... to ... +- removing one note and adding two new notes, including ... +- removing a supernumary "Note" indicator from the first note. +- correcting the word ... to ... + +### GitHub PR or commit + +When possible, provide a reference to one or more GitHub pull requests or commit hashes +at the end of each erratum, in the format `({% gh "..." %})`. + +The format breaks down as follows: + +- `{% gh "..." %}` is a custom shortcode, which accepts one of the following: + - A PR number prefixed with `#`, e.g. `"#4080"` (this is the preferred option when available) + - A commit hash of 7 or more characters, with no prefix, e.g. `"b043430"` +- The quotes around the parameter passed to the `gh` shortcode are necessary for template parsing +- The outer parentheses exist only for punctuation, and are directly output diff --git a/index.html b/index.html index 56183d90c5..466655f759 100644 --- a/index.html +++ b/index.html @@ -19,6 +19,8 @@

      Web Content Accessibility Guidelines {{ versionDecimal }}

      {%- endif %}