mbox series

[v5,0/2] documentation: remove non-ASCII confusables, add a check

Message ID 20260803034827.26904-1-niko.mauno@vaisala.com
Headers show
Series documentation: remove non-ASCII confusables, add a check | expand

Message

Niko Mauno Aug. 3, 2026, 3:48 a.m. UTC 
From: Niko Mauno <niko.mauno@vaisala.com>

The three whitespace/operator fixes from the earlier revisions of this
series have been merged. The two remaining patches are rebased
on the current master tip: they remove the non-ASCII "confusable"
characters from the documentation sources and add a check to keep them
out.

  * documentation: replace non-ASCII confusables (curly quotes, en/em
    dashes, zero-width spaces, and no-break spaces outside tree output)
    with ASCII; e.g. a curly quote copied into a recipe causes a
    bitbake ParseError. Legitimate non-ASCII (box-drawing in directory
    trees, the no-break spaces the tree command emits there, accented
    contributor names, CJK) is left untouched.
  * tools: add the check-confusables script and wire it up as a
    pre-commit hook and in the Makefile "checks" target, in the same
    fashion as check-glossaries, to guard against regressions.

Changes since v4:
  * Rebased on current master; the three whitespace/operator fixes are
    dropped from the series, as they have been merged.
  * Five files that the confusables patch used to touch are no longer
    part of it, as master has since gained equivalent fixes for them
    (contributor-guide/identify-component.rst, dev-manual/layers.rst,
    ref-manual/faq.rst, ref-manual/qa-checks.rst and
    ref-manual/variables.rst).
  * Re-ran the check across the whole tree on the new base; the
    documentation added to master in the meantime is clean.
  * Rewrapped a ragged paragraph in the first commit message; no
    content changes to either patch otherwise.

Changes since v3:
  * Add a copyright and license (MIT) header to the check-confusables
    script (per review feedback).
  * Spell the confusable characters in the map, and the related
    constants, as \u escape sequences rather than literal glyphs, so
    the source itself is unambiguous ASCII (per review feedback).
  * Explain in the commit message why the script carries a short
    curated table of its own instead of depending on a general-purpose
    confusables package: such a package targets the full Unicode
    homoglyph table and would flag the accented names, CJK and
    box-drawing characters we deliberately keep, so an allow-list and
    replacement policy of our own would be needed regardless.

Changes since v2:
  * Keep the no-break spaces that the tree command emits in directory
    listings, and make the check tolerate them on lines containing
    box-drawing characters (per review feedback). No-break spaces in
    prose and command examples are still converted.
  * Make the pre-commit hook pass filenames and check only the changed
    files (per review feedback); the Makefile "checks" target still
    scans the whole tree.
  * Stop treating the horizontal ellipsis as a confusable; the
    truncated git hashes in the release notes are left as-is, as it is
    a cosmetic character rather than a tooling hazard.

Changes since v1:
  * Squashed the two confusable cleanups (recipe-style-guide and
    identify-component) into a single documentation-wide patch and
    extended it to all remaining occurrences.
  * Added the check-confusables tool, pre-commit hook and Makefile
    integration.

Niko Mauno (2):
  documentation: Replace non-ASCII confusable characters with ASCII
  tools: Add check-confusables pre-commit hook

 .pre-commit-config.yaml                       |   5 +
 documentation/Makefile                        |   1 +
 documentation/contributor-guide/index.rst     |   4 +-
 .../contributor-guide/recipe-style-guide.rst  |   8 +-
 .../contributor-guide/submit-changes.rst      |   4 +-
 documentation/dev-manual/build-quality.rst    |   2 +-
 documentation/dev-manual/debugging.rst        |  14 +-
 documentation/dev-manual/new-recipe.rst       |   4 +-
 documentation/kernel-dev/common.rst           |  10 +-
 .../migration-guides/release-notes-4.1.rst    |   2 +-
 documentation/ref-manual/classes.rst          |   4 +-
 .../ref-manual/devtool-reference.rst          |   4 +-
 .../yocto-project-supported-features.rst      |  10 +-
 .../test-manual/yocto-project-compatible.rst  |   2 +-
 documentation/tools/check-confusables         | 123 ++++++++++++++++++
 .../transitioning-to-a-custom-environment.rst |   2 +-
 documentation/what-i-wish-id-known.rst        |  14 +-
 17 files changed, 171 insertions(+), 42 deletions(-)
 create mode 100755 documentation/tools/check-confusables


base-commit: 41dae3c3da3ada1745fc60228ff6269c64ee2361