mbox series

[v3,0/5] documentation: minor fixes, plus a confusables check

Message ID 20260728090746.27793-1-niko.mauno@vaisala.com
Headers show
Series documentation: minor fixes, plus a confusables check | expand

Message

Niko Mauno July 28, 2026, 9:07 a.m. UTC 
From: Niko Mauno <niko.mauno@vaisala.com>

A small collection of documentation fixes. Several correct example
snippets that misbehave when copied verbatim; the last two remove
non-ASCII "confusable" characters and add a check to keep them out.

  * ref-manual: add the trailing space missing from :prepend examples,
    so readers don't risk inadvertent string concatenation.
  * ref-manual: drop superfluous spaces from :append examples.
  * dev-manual: add the whitespace around '=' that the Whinlatter
    (5.3) recipe parser now warns about.
  * 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 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.
  * Add Quentin's Reviewed-by to the three whitespace/operator fixes
    that are unchanged since v1.

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.
  * The three whitespace/operator fixes are unchanged.

Niko Mauno (5):
  ref-manual: Fix occurrences of omitted space with :prepend
  ref-manual: Prune superfluous space with :append
  dev-manual: Fix missing whitespace around '=' operator
  documentation: Replace non-ASCII confusable characters with ASCII
  tools: Add check-confusables pre-commit hook

 .pre-commit-config.yaml                       |   5 +
 documentation/Makefile                        |   1 +
 .../contributor-guide/identify-component.rst  |   4 +-
 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/layers.rst           |   2 +-
 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 +-
 documentation/ref-manual/faq.rst              |   6 +-
 documentation/ref-manual/qa-checks.rst        |   2 +-
 documentation/ref-manual/variables.rst        |   5 +-
 .../yocto-project-supported-features.rst      |  10 +-
 .../test-manual/yocto-project-compatible.rst  |   2 +-
 documentation/tools/check-confusables         | 115 ++++++++++++++++++
 .../transitioning-to-a-custom-environment.rst |   2 +-
 documentation/what-i-wish-id-known.rst        |  14 +--
 22 files changed, 174 insertions(+), 50 deletions(-)
 create mode 100755 documentation/tools/check-confusables


base-commit: 358519ca6406a89fee42c45dcaf63a37a374f33c