Skip to content

Commit 5e44195

Browse files
kfranqueirokfranqueiro
authored
Add cspell and fix typos (#4605)
This PR: - Configures cspell for this repository - Fixes all reported typos - Adds a custom dictionary for words that should always be valid, and defines appropriate one-offs for individual files - Adds an npm script and a github workflow to run on PRs ([example run](https://github.com/kfranqueiro/wcag/actions/runs/17648224537/job/50151828441?pr=3)) - Documents how to add words in the README Credit to @fstrr for getting the idea from the aria-practices repo and initially experimenting with it on wcag3 and some other repos
1 parent 304d125 commit 5e44195

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

58 files changed

+1391
-76
lines changed

‎.github/workflows/cspell.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
name: Check Spelling
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
7+
jobs:
8+
spellcheck:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
- uses: streetsidesoftware/cspell-action@v7

‎11ty/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ XSLT-based build process using Eleventy.
88
Make sure you have Node.js installed. This has primarily been tested with v20,
99
the current LTS at time of writing.
1010

11-
If you use [fnm](https://github.com/Schniz/fnm) or [nvm](https://github.com/nvm-sh/nvm) to manage multiple Node.js versions,
11+
If you use [`fnm`](https://github.com/Schniz/fnm) or [`nvm`](https://github.com/nvm-sh/nvm) to manage multiple Node.js versions,
1212
you can switch to the recommended version by typing `fnm use` or `nvm use`
1313
(with no additional arguments) while in the repository directory.
1414

‎README.md‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ If you are providing term definitions along with your SC, include them in the re
9494
<dd>{Definition}</dd>
9595
```
9696

97-
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.
97+
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.
9898

9999
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>`.
100100

@@ -141,7 +141,7 @@ New techniques should use a filename that is derived from a shortened version of
141141

142142
Each new technique should be created in a new branch. Set-up of the branch and file is automated via the create-techniques.sh script, which can be run with bash. The command line is:
143143

144-
```Shell
144+
```
145145
bash create-techniques.sh <technology> <filename> <type> "<title>"
146146
```
147147

@@ -162,7 +162,7 @@ Once a technique branch and file is set up, populate the content and request rev
162162
* 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.
163163
* When the technique is ready for review, make a pull request into the main branch.
164164
* If you wish to reference the draft technique from an Understanding document, use the technique's rawgit URI.
165-
* After a technique is approved, the chairs will assign it an ID and update links to it in the Undestanding documents.
165+
* After a technique is approved, the chairs will assign it an ID and update links to it in the Understanding documents.
166166

167167
### Formatting Techniques
168168

@@ -190,6 +190,18 @@ obsoleteMessage: |
190190
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`.
191191
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.
192192

193+
## Spell-checking
194+
195+
Both the normative and informative content is checked for spelling errors using [cspell](https://cspell.org/). This check runs on pull requests, and can be run locally via `npm run cspell` (requires [Node.js](https://nodejs.org/); remember to run `npm i` first if you haven't recently).
196+
197+
### Adding valid words
198+
199+
If a word is flagged that should be allowed anywhere it appears, add a line to the top-level `custom-words.txt` file, ideally under the appropriate section in alphabetical order.
200+
201+
If a word is flagged that should be allowed in a specific file, but should be considered incorrect elsewhere, add an entry to the `overrides` list in the top-level `cspell.yml` file. (Several examples already exist for reference.)
202+
203+
Note that both inline code and code blocks are ignored, so if you are using a term that pertains to a specific language/syntax, consider enclosing it in `<code>` or `<pre>` as appropriate.
204+
193205
## Version-specific Documentation
194206

195207
Informative documents are generated from the same source files for both WCAG 2.2 and 2.1,

‎cspell.yml‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
version: "0.2"
2+
allowCompoundWords: true
3+
minWordLength: 3
4+
dictionaries:
5+
- en_US
6+
- companies
7+
- softwareTerms
8+
- css
9+
- html
10+
- custom
11+
dictionaryDefinitions:
12+
- name: custom
13+
path: custom-words.txt
14+
addWords: true
15+
ignorePaths:
16+
- "_includes/**"
17+
- "acknowledgements/**"
18+
- "conformance-challenges/**"
19+
- "lib/**"
20+
- "requirements/**"
21+
- "wcag20/**"
22+
- "working-examples/**"
23+
- "xslt/**"
24+
- "*.css"
25+
- "*.js"
26+
- "*.json"
27+
- "*.sh"
28+
- "*.ts"
29+
- "*.xml"
30+
- "*.yml"
31+
- "custom-words.txt"
32+
useGitignore: true
33+
overrides:
34+
# File-specific words are defined here, which should be considered typos elsewhere
35+
- filename: errata/*.html
36+
words: [ccriteria] # Records of corrected typos
37+
- filename: guidelines/input-purposes.html
38+
words: [lle] # Superscript fragment of Mlle
39+
- filename: techniques/*/F32.html
40+
words: [Higashi, Kyo, Miyako] # Japanese examples
41+
- filename: techniques/*/F71.html
42+
words: [ϲоοk] # Intentional Unicode character example
43+
- filename: techniques/*/FLASH17.html
44+
words: [SWFFocus] # Class mentioned only in this page
45+
- filename: techniques/*/FLASH28.html
46+
words: [rulez] # Example in leetspeak
47+
- filename: techniques/*/H34.html
48+
words: [HCTIWS, SDRADNATS, BEW] # Intentionally-reversed words
49+
- filename: techniques/*/H56.html
50+
words: [YTIVITCA, NOITAZILANOITANRETNI] # Intentionally-reversed words
51+
- filename: techniques/*/SVR2.html
52+
words: [jna] # Example file extension
53+
- filename: understanding/*/language-of-parts.html
54+
words: [voyture] # Pronunciation example
55+
- filename: understanding/*/text-spacing.html
56+
words: [drawi, whe] # Examples of text clipping
57+
languageSettings:
58+
- languageId: html
59+
ignoreRegExpList:
60+
# Non-English elements
61+
- /<(\w+)[^>]+lang="(?!en)\w+"[^>]*>.*?<\/\1>/gi
62+
# Encoded citations
63+
- /\[\[[^\]]+\]\]/g
64+
# Other citations
65+
- /\w+ et al\b/g
66+
# pre/code tags
67+
- /<(pre|code)\b[^>]*>[\s\S]*?</\1>/g
68+
# (...) References sections
69+
- /<section>\s*<h\d>[^<]*references</h\d>[\s\S]*?</section>/gi
70+
# Resources (...) sections
71+
- /<section[^>]*>\s*<h\d>\s*resources[^<]*</h\d>[\s\S]*?</section>/gi
72+
# HTML tags
73+
- /<[^>]*>/g
74+
# Namespaces
75+
- /x(mlns|si):\w+/g
76+
# Liquid directives
77+
- /\{[\{%].*?[\}%]\}/g
78+
- languageId: markdown
79+
ignoreRegExpList:
80+
# Fenced code block
81+
- |
82+
/
83+
^(\s*```).* # Opening ```
84+
[\s\S]*? # Code block
85+
^``` # Closing ```
86+
/gmx
87+
# Inline code
88+
- /`[^`\n]+`/g

‎custom-words.txt‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Placeholders
2+
GXXX
3+
FXXX
4+
5+
# Expected acronyms and abbreviations
6+
3GPP
7+
ACTF
8+
AGWG
9+
ALS
10+
APG
11+
APNG
12+
ATAG
13+
BCP
14+
BWV
15+
CCID
16+
CEDEX
17+
CIE
18+
CLR
19+
COGA
20+
CVV
21+
DCMI
22+
DFXP
23+
DPUB
24+
DSS
25+
ERCIM
26+
HDR
27+
HFS
28+
ICT
29+
IEC
30+
IDREF
31+
IMS
32+
ISA
33+
LINQ
34+
LVTF
35+
MBASW
36+
MCID
37+
METS
38+
MSAA
39+
MSIL
40+
NOAA
41+
NCX
42+
PCI
43+
PDA
44+
PII
45+
Prt
46+
RDDL
47+
resx
48+
SAMI
49+
Scn
50+
SCR
51+
SDR
52+
SIL
53+
SMIL
54+
SPC
55+
SRT
56+
SVR
57+
TTML
58+
UAAG
59+
UCS
60+
UIA
61+
UWP
62+
VTT
63+
WAI
64+
WCAG
65+
WGBH
66+
WPF
67+
XAP
68+
XYZ
69+
70+
# Proper names
71+
Flesch
72+
Kincaid
73+
Knowbility
74+
McLeish # Study cited in understanding/21/text-spacing.html
75+
Roselli
76+
Smallville
77+
Soueidan
78+
Vanna # Example in G193
79+
YubiKey
80+
Zehe
81+
82+
# Words
83+
auditorily
84+
conferatur # Latin, expansion of "cf."
85+
dyscalculia
86+
genericizing
87+
linearization
88+
look-alikes
89+
mistagged
90+
ʻokina # Hawaiian
91+
parameterizes
92+
reauthentication
93+
resequencing
94+
reskinning
95+
tic-tac-toe
96+
tristimulus
97+
unsynchronized
98+
untimed
99+
untrap

‎errata/21.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,7 @@ <h3>Editorial Errata</h3>
189189
<li>
190190
2018-07-11:
191191
In <a href="{{ trUrl }}#reflow">1.4.10 Reflow</a>,
192-
removing a supernumary "Note" indicator from the first note.
192+
removing a supernumerary "Note" indicator from the first note.
193193
({% gh "#429" %})
194194
</li>
195195
<li>

‎errata/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ Example phrasing when linking to a term definition:
6363
In the definition for <a href="{{ trUrl }}#dfn-single-pointer">single pointer</a>
6464
```
6565

66-
(Remember that term definition fraagments always begin with `dfn-`.)
66+
(Remember that term definition fragments always begin with `dfn-`.)
6767

6868
It is possible to reference multiple sections/terms from one erratum,
6969
so long as all of the links remain front-loaded prior to the erratum's details.
@@ -76,7 +76,7 @@ For example:
7676

7777
- updating the red threshold from ... to ...
7878
- removing one note and adding two new notes, including ...
79-
- removing a supernumary "Note" indicator from the first note.
79+
- removing a supernumerary "Note" indicator from the first note.
8080
- correcting the word ... to ...
8181

8282
### GitHub PR or commit

0 commit comments

Comments
 (0)