Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove superseded XSLT build targets and update README #3985

Merged
merged 3 commits into from
Aug 7, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion 11ty/CustomLiquid.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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\//;
Expand Down Expand Up @@ -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);
Expand Down
2 changes: 1 addition & 1 deletion 11ty/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,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))
67 changes: 45 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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.

Expand All @@ -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.
Expand All @@ -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:

Expand All @@ -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.
Expand All @@ -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

Expand Down
Loading