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

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

[niko.mauno]

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, ellipsis, non-breaking and zero-width spaces) with ASCII;
    e.g. a curly quote copied into a recipe causes a bitbake
    ParseError. Legitimate non-ASCII (box-drawing in directory trees,
    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 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 (24 files, not 2).
  * Added the check-confusables tool, pre-commit hook and Makefile
    integration.
  * The three whitespace/operator fixes are unchanged from v1.

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 +-
 .../dev-manual/creating-fragments.rst         | 18 ++---
 documentation/dev-manual/debugging.rst        | 14 ++--
 documentation/dev-manual/layers.rst           |  2 +-
 documentation/dev-manual/new-recipe.rst       |  4 +-
 .../dev-manual/prebuilt-libraries.rst         | 28 +++----
 documentation/kernel-dev/common.rst           | 10 +--
 .../migration-guides/release-notes-4.1.rst    | 22 +++---
 .../migration-guides/release-notes-5.0.rst    | 12 +--
 .../migration-guides/release-notes-5.1.rst    | 16 ++--
 .../migration-guides/release-notes-5.2.rst    | 40 +++++-----
 .../migration-guides/release-notes-5.3.rst    | 42 +++++-----
 .../migration-guides/release-notes-6.0.rst    | 44 +++++------
 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/structure.rst        | 14 ++--
 documentation/ref-manual/variables.rst        |  7 +-
 .../yocto-project-supported-features.rst      | 10 +--
 .../test-manual/yocto-project-compatible.rst  |  2 +-
 documentation/tools/check-confusables         | 77 +++++++++++++++++++
 .../transitioning-to-a-custom-environment.rst |  2 +-
 documentation/what-i-wish-id-known.rst        | 14 ++--
 30 files changed, 254 insertions(+), 168 deletions(-)
 create mode 100755 documentation/tools/check-confusables


base-commit: 358519ca6406a89fee42c45dcaf63a37a374f33c
-- 
2.47.3

[PATCH v2 1/5] ref-manual: Fix occurrences of omitted space with :prepend

[niko.mauno]

From: Niko Mauno <niko.mauno@vaisala.com>

Add trailing space to value field in :prepend assignments, in
order to avoid providing examples which could lead the users to risk
inadvertent string concatenation.

Signed-off-by: Niko Mauno <niko.mauno@vaisala.com>
---
 documentation/ref-manual/faq.rst       | 6 ++++--
 documentation/ref-manual/variables.rst | 3 ++-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
index 65d5db5d2..2ffacaf94 100644
--- a/documentation/ref-manual/faq.rst
+++ b/documentation/ref-manual/faq.rst
@@ -126,7 +126,8 @@ attempt before any others by adding something like the following to the
        git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
        ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
        http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
-       https://.*/.* &YOCTO_DL_URL;/mirror/sources/"
+       https://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
+   "
 
 These changes cause the build system to intercept Git, FTP, HTTP, and
 HTTPS requests and direct them to the ``http://`` sources mirror. You
@@ -165,7 +166,8 @@ file as long as the :term:`PREMIRRORS` server is current::
        git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
        ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
        http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
-       https://.*/.* &YOCTO_DL_URL;/mirror/sources/"
+       https://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
+   "
    BB_FETCH_PREMIRRORONLY = "1"
 
 These changes would cause the build system to successfully fetch source
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 394797ca3..0066ede0f 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7843,7 +7843,8 @@ system and gives an overview of their function and contents.
              git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
              ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
              http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
-             https://.*/.* &YOCTO_DL_URL;/mirror/sources/"
+             https://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
+         "
 
       These changes cause the
       build system to intercept Git, FTP, HTTP, and HTTPS requests and
-- 
2.47.3

[PATCH v2 2/5] ref-manual: Prune superfluous space with :append

[niko.mauno]

From: Niko Mauno <niko.mauno@vaisala.com>

Remove occurrences of superfluous space characters in value field of
:append assignments.

Signed-off-by: Niko Mauno <niko.mauno@vaisala.com>
---
 documentation/ref-manual/qa-checks.rst | 2 +-
 documentation/ref-manual/variables.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/ref-manual/qa-checks.rst b/documentation/ref-manual/qa-checks.rst
index 9654cf08e..09b0f628a 100644
--- a/documentation/ref-manual/qa-checks.rst
+++ b/documentation/ref-manual/qa-checks.rst
@@ -889,7 +889,7 @@ or "-fpic" to the compiler command-line options. For example, given
 software that reads :term:`CFLAGS` when you build it,
 you could add the following to your recipe::
 
-   CFLAGS:append = " -fPIC "
+   CFLAGS:append = " -fPIC"
 
 For more information on text relocations at runtime, see
 https://www.akkadia.org/drepper/textrelocs.html.
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 0066ede0f..b124e9c30 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -5559,7 +5559,7 @@ system and gives an overview of their function and contents.
          KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
          KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}"
          KERNEL_FEATURES:append:qemuall = " cfg/virtio.scc"
-         KERNEL_FEATURES:append:qemux86 = "  cfg/sound.scc cfg/paravirt_kvm.scc"
+         KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
          KERNEL_FEATURES:append:qemux86-64 = " cfg/sound.scc"
 
    :term:`KERNEL_FIT_LINK_NAME`
-- 
2.47.3

[PATCH v2 3/5] dev-manual: Fix missing whitespace around '=' operator

[niko.mauno]

From: Niko Mauno <niko.mauno@vaisala.com>

According to the Whinlatter (5.3) migration guide;

  A new warning is now printed when there are no whitespaces around an '=' assignment in recipes

Fix occurrence of example verbatim applying of which would generate
such warning.

Signed-off-by: Niko Mauno <niko.mauno@vaisala.com>
---
 documentation/dev-manual/layers.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
index dc63478a3..d33eb136d 100644
--- a/documentation/dev-manual/layers.rst
+++ b/documentation/dev-manual/layers.rst
@@ -252,7 +252,7 @@ following list:
          KERNEL_CC:append:arc = " ${TOOLCHAIN_OPTIONS}"
          KERNEL_LD:append:arc = " ${TOOLCHAIN_OPTIONS}"
 
-         KERNEL_FEATURES:append:qemuall=" features/debug/printk.scc"
+         KERNEL_FEATURES:append:qemuall = " features/debug/printk.scc"
 
    -  *Place Machine-Specific Files in Machine-Specific Locations:* When
       you have a base recipe, such as ``base-files.bb``, that contains a
-- 
2.47.3

[PATCH v2 4/5] documentation: Replace non-ASCII confusable characters with ASCII

[niko.mauno]

From: Niko Mauno <niko.mauno@vaisala.com>

Several documentation sources contain non-ASCII "confusable" characters
such as curly quotes, en and em dashes, a horizontal ellipsis and
non-breaking or zero-width spaces. These look almost identical to their
plain ASCII counterparts but break tooling and mislead readers who copy
text out of the manuals.

For example, the curly double quotes present in the recipe style guide
example caused parse errors when copied into an actual recipe:

  ERROR: ParseError at .../foobar.bb:158: unparsed line: 'RDEPENDS:${PN} = "foo"'

and dash substitutions silently corrupt command-line options, turning
"--help" and "--dump-signatures" into unusable non-ASCII look-alikes.

Replace all such occurrences across the documentation with their
regular ASCII equivalents. Legitimate non-ASCII content, such as the
box-drawing characters used in directory trees, accented letters in
contributor names and CJK characters, is intentionally left untouched.

These occurrences were detected with the
documentation/tools/check-confusables script introduced in the
following commit.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Niko Mauno <niko.mauno@vaisala.com>
---
 .../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 +-
 .../dev-manual/creating-fragments.rst         | 18 ++++----
 documentation/dev-manual/debugging.rst        | 14 +++---
 documentation/dev-manual/new-recipe.rst       |  4 +-
 .../dev-manual/prebuilt-libraries.rst         | 28 ++++++------
 documentation/kernel-dev/common.rst           | 10 ++---
 .../migration-guides/release-notes-4.1.rst    | 22 +++++-----
 .../migration-guides/release-notes-5.0.rst    | 12 ++---
 .../migration-guides/release-notes-5.1.rst    | 16 +++----
 .../migration-guides/release-notes-5.2.rst    | 40 ++++++++---------
 .../migration-guides/release-notes-5.3.rst    | 42 +++++++++---------
 .../migration-guides/release-notes-6.0.rst    | 44 +++++++++----------
 documentation/ref-manual/classes.rst          |  4 +-
 .../ref-manual/devtool-reference.rst          |  4 +-
 documentation/ref-manual/structure.rst        | 14 +++---
 documentation/ref-manual/variables.rst        |  2 +-
 .../yocto-project-supported-features.rst      | 10 ++---
 .../test-manual/yocto-project-compatible.rst  |  2 +-
 .../transitioning-to-a-custom-environment.rst |  2 +-
 documentation/what-i-wish-id-known.rst        | 14 +++---
 24 files changed, 162 insertions(+), 162 deletions(-)

diff --git a/documentation/contributor-guide/identify-component.rst b/documentation/contributor-guide/identify-component.rst
index 6cf8ed985..26308a0e9 100644
--- a/documentation/contributor-guide/identify-component.rst
+++ b/documentation/contributor-guide/identify-component.rst
@@ -18,5 +18,5 @@ maintainers.
 
 If the issue is in the core metadata layer (OpenEmbedded-Core) or in BitBake,
 issues can be reported in the :yocto_bugs:`Yocto Project Bugzilla <>`. The
-:yocto_lists:`yocto </g/yocto>` mailing list is a general “catch-all” location
-where questions can be sent if you can’t work out where something should go.
+:yocto_lists:`yocto </g/yocto>` mailing list is a general "catch-all" location
+where questions can be sent if you can't work out where something should go.
diff --git a/documentation/contributor-guide/index.rst b/documentation/contributor-guide/index.rst
index a83216945..b374cc1c4 100644
--- a/documentation/contributor-guide/index.rst
+++ b/documentation/contributor-guide/index.rst
@@ -7,8 +7,8 @@ Yocto Project and OpenEmbedded Contributor Guide
 The Yocto Project and OpenEmbedded are open-source, community-based projects so
 contributions are very welcome, it is how the code evolves and everyone can
 effect change. Contributions take different forms, if you have a fix for an
-issue you’ve run into, a patch is the most appropriate way to contribute it.
-If you run into an issue but don’t have a solution, opening a defect in
+issue you've run into, a patch is the most appropriate way to contribute it.
+If you run into an issue but don't have a solution, opening a defect in
 :yocto_bugs:`Bugzilla <>` or asking questions on the mailing lists might be
 more appropriate. This guide intends to point you in the right direction to
 this.
diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst
index f81ffb2ab..84c6bb14e 100644
--- a/documentation/contributor-guide/recipe-style-guide.rst
+++ b/documentation/contributor-guide/recipe-style-guide.rst
@@ -192,11 +192,11 @@ Custom tasks should be sorted similarly.
 
 Package specific variables are typically grouped together, e.g.::
 
-    RDEPENDS:${PN} = “foo”
-    RDEPENDS:${PN}-libs = “bar”
+    RDEPENDS:${PN} = "foo"
+    RDEPENDS:${PN}-libs = "bar"
 
-    RRECOMMENDS:${PN} = “one”
-    RRECOMMENDS:${PN}-libs = “two”
+    RRECOMMENDS:${PN} = "one"
+    RRECOMMENDS:${PN}-libs = "two"
 
 Recipe License Fields
 ---------------------
diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst
index ae7a097ad..48c8af2fe 100644
--- a/documentation/contributor-guide/submit-changes.rst
+++ b/documentation/contributor-guide/submit-changes.rst
@@ -17,7 +17,7 @@ Both Yocto Project and OpenEmbedded have many key components that are
 maintained by patches being submitted on mailing lists. We appreciate this
 approach does look a little old fashioned when other workflows are available
 through web technology such as GitHub, GitLab and others. Since we are often
-asked this question, we’ve decided to document the reasons for using mailing
+asked this question, we've decided to document the reasons for using mailing
 lists.
 
 One significant factor is that we value peer review. When a change is proposed
@@ -40,7 +40,7 @@ of key people from the project, which would again be to its detriment.
 
 The projects are acutely aware that potential new contributors find the
 mailing list approach off-putting and would prefer a web-based GUI.
-Since we don’t believe that can work for us, the project is aiming to ensure
+Since we don't believe that can work for us, the project is aiming to ensure
 `patchwork <https://patchwork.yoctoproject.org/>`__ is available to help track
 patch status and also looking at how tooling can provide more feedback to users
 about patch status. We are looking at improving tools such as ``patchtest`` to
diff --git a/documentation/dev-manual/build-quality.rst b/documentation/dev-manual/build-quality.rst
index c2e46b69c..e9b066c44 100644
--- a/documentation/dev-manual/build-quality.rst
+++ b/documentation/dev-manual/build-quality.rst
@@ -358,7 +358,7 @@ You can examine build history output from the command line or from a web
 interface.
 
 To see any changes that have occurred (assuming you have
-:term:`BUILDHISTORY_COMMIT` = "1"),
+:term:`BUILDHISTORY_COMMIT` = "1"),
 you can simply use any Git command that allows you to view the history
 of a repository. Here is one method::
 
diff --git a/documentation/dev-manual/creating-fragments.rst b/documentation/dev-manual/creating-fragments.rst
index 7f437d7c9..8c3e24452 100644
--- a/documentation/dev-manual/creating-fragments.rst
+++ b/documentation/dev-manual/creating-fragments.rst
@@ -37,9 +37,9 @@ You can create one or more :term:`configuration fragment` files in your
 
    meta-custom
    ├── conf
-   │   ├── fragments
-   │   │   └── custom-fragment.conf
-   │   └── layer.conf
+   │   ├── fragments
+   │   │   └── custom-fragment.conf
+   │   └── layer.conf
    ...
 
 For our ``custom-fragment.conf`` file, the following variables **must** be set
@@ -99,12 +99,12 @@ example, it's possible to create sub-directories to organize your fragments::
 
    meta-custom
    ├── conf
-   │   ├── fragments
-   │   │   ├── networking
-   │   │   │   └── mirrors.conf
-   │   │   └── resources
-   │   │       └── numberthreads.conf
-   │   └── layer.conf
+   │   ├── fragments
+   │   │   ├── networking
+   │   │   │   └── mirrors.conf
+   │   │   └── resources
+   │   │       └── numberthreads.conf
+   │   └── layer.conf
    ...
 
 In the above example, the ``meta-custom/networking/mirrors`` and
diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
index 21fb10537..3afc17ad4 100644
--- a/documentation/dev-manual/debugging.rst
+++ b/documentation/dev-manual/debugging.rst
@@ -152,7 +152,7 @@ Shell functions and tasks can also be inspected with the same mechanism::
 
 For Python functions and tasks, ``bitbake -e recipename`` can be used instead.
 
-Moreover, the output of the ``bitbake -e`` and ``bitbake -e`` recipe commands
+Moreover, the output of the ``bitbake -e`` and ``bitbake -e`` recipe commands
 includes the following information:
 
 -  The output starts with a tree listing all configuration files and
@@ -187,7 +187,7 @@ Here are a few of the available ``oe-pkgdata-util`` subcommands.
    that have been built, optionally limiting the match to packages that
    match pattern.
 
--  ``oe-pkgdata-util list-pkg-files package ...``: Lists the
+-  ``oe-pkgdata-util list-pkg-files package ...``: Lists the
    files and directories contained in the given packages.
 
    .. note::
@@ -205,7 +205,7 @@ Here are a few of the available ``oe-pkgdata-util`` subcommands.
       directory, make sure that :ref:`ref-classes-rm-work` is not
       enabled when you build the recipe.
 
--  ``oe-pkgdata-util find-path path ...``: Lists the names of
+-  ``oe-pkgdata-util find-path path ...``: Lists the names of
    the packages that contain the given paths. For example, the following
    tells us that ``/usr/share/man/man1/make.1`` is contained in the
    ``make-doc`` package::
@@ -213,7 +213,7 @@ Here are a few of the available ``oe-pkgdata-util`` subcommands.
       $ oe-pkgdata-util find-path /usr/share/man/man1/make.1
       make-doc: /usr/share/man/man1/make.1
 
--  ``oe-pkgdata-util lookup-recipe package ...``: Lists the name
+-  ``oe-pkgdata-util lookup-recipe package ...``: Lists the name
    of the recipes that produce the given packages.
 
 For more information on the ``oe-pkgdata-util`` command, use the help
@@ -362,7 +362,7 @@ You can also use BitBake to dump out the signature construction
 information without executing tasks by using either of the following
 BitBake command-line options::
 
-   ‐‐dump-signatures=SIGNATURE_HANDLER
+   --dump-signatures=SIGNATURE_HANDLER
    -S SIGNATURE_HANDLER
 
 
@@ -1072,7 +1072,7 @@ debugger.
       the actual image (e.g. ``gdb-cross-i586``). The suggestion is usually the
       actual name you want to use.
 
-#. *Set up the* ``debugfs``\ *:*
+#. *Set up the* ``debugfs``\ *:*
 
    Run the following commands to set up the ``debugfs``::
 
@@ -1106,7 +1106,7 @@ debugger.
 
    .. code-block:: shell
 
-      root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help
+      root@qemux86:~# gdbserver localhost:1234 /bin/gzip --help
 
    For
    additional gdbserver options, see the `GDB Server
diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst
index 6888bb46a..d1c863117 100644
--- a/documentation/dev-manual/new-recipe.rst
+++ b/documentation/dev-manual/new-recipe.rst
@@ -99,14 +99,14 @@ command::
                        otherwise $EDITOR, otherwise vi.
    Use recipetool <subcommand> --help to get help on a specific command
 
-Running ``recipetool create -o OUTFILE`` creates the base recipe and
+Running ``recipetool create -o OUTFILE`` creates the base recipe and
 locates it properly in the layer that contains your source files.
 Here are some syntax examples:
 
  - Use this syntax to generate a recipe based on source. Once generated,
    the recipe resides in the existing source code layer::
 
-      recipetool create -o OUTFILE source
+      recipetool create -o OUTFILE source
 
  - Use this syntax to generate a recipe using code that
    you extract from source. The extracted code is placed in its own layer
diff --git a/documentation/dev-manual/prebuilt-libraries.rst b/documentation/dev-manual/prebuilt-libraries.rst
index 9cc8bd2d9..cf8cf54d9 100644
--- a/documentation/dev-manual/prebuilt-libraries.rst
+++ b/documentation/dev-manual/prebuilt-libraries.rst
@@ -30,30 +30,30 @@ Libraries are built for several target architecture variants and packaged in
 an archive as follows::
 
    ├── build-arm-hisiv300
-   │   └── libft4222.so.1.4.4.44
+   │   └── libft4222.so.1.4.4.44
    ├── build-arm-v5-sf
-   │   └── libft4222.so.1.4.4.44
+   │   └── libft4222.so.1.4.4.44
    ├── build-arm-v6-hf
-   │   └── libft4222.so.1.4.4.44
+   │   └── libft4222.so.1.4.4.44
    ├── build-arm-v7-hf
-   │   └── libft4222.so.1.4.4.44
+   │   └── libft4222.so.1.4.4.44
    ├── build-arm-v8
-   │   └── libft4222.so.1.4.4.44
+   │   └── libft4222.so.1.4.4.44
    ├── build-i386
-   │   └── libft4222.so.1.4.4.44
+   │   └── libft4222.so.1.4.4.44
    ├── build-i486
-   │   └── libft4222.so.1.4.4.44
+   │   └── libft4222.so.1.4.4.44
    ├── build-mips-eglibc-hf
-   │   └── libft4222.so.1.4.4.44
+   │   └── libft4222.so.1.4.4.44
    ├── build-pentium
-   │   └── libft4222.so.1.4.4.44
+   │   └── libft4222.so.1.4.4.44
    ├── build-x86_64
-   │   └── libft4222.so.1.4.4.44
+   │   └── libft4222.so.1.4.4.44
    ├── examples
-   │   ├── get-version.c
-   │   ├── i2cm.c
-   │   ├── spim.c
-   │   └── spis.c
+   │   ├── get-version.c
+   │   ├── i2cm.c
+   │   ├── spim.c
+   │   └── spis.c
    ├── ftd2xx.h
    ├── install4222.sh
    ├── libft4222.h
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 136524e63..4e7d015e4 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -577,7 +577,7 @@ applies the new configuration before building the kernel.
 For a detailed example showing how to configure the kernel, see the
 ":ref:`kernel-dev/common:configuring the kernel`" section.
 
-Using an "In-Tree"  ``defconfig`` File
+Using an "In-Tree"  ``defconfig`` File
 --------------------------------------
 
 It might be desirable to have kernel configuration fragment support
@@ -973,7 +973,7 @@ possible.
 For more information on kernel configuration, see the
 ":ref:`kernel-dev/common:changing the configuration`" section.
 
-Using  ``menuconfig``
+Using  ``menuconfig``
 ---------------------
 
 The easiest way to define kernel configurations is to set them through
@@ -1079,7 +1079,7 @@ kernel layer.
    Be sure to make a copy of the ``.config`` file and do not just rename it.
    The build system needs an existing ``.config`` file from which to work.
 
-Creating a  ``defconfig`` File
+Creating a  ``defconfig`` File
 ------------------------------
 
 A ``defconfig`` file in the context of the Yocto Project is often a
@@ -1708,12 +1708,12 @@ Showing a Particular Feature or Branch Change
 ---------------------------------------------
 
 Tags in the Yocto Project kernel tree divide changes for significant
-features or branches. The ``git show`` tag command shows changes based
+features or branches. The ``git show`` tag command shows changes based
 on a tag. Here is an example that shows ``systemtap`` changes::
 
    $ git show systemtap
 
-You can use the ``git branch --contains`` tag command to
+You can use the ``git branch --contains`` tag command to
 show the branches that contain a particular feature. This command shows
 the branches that contain the ``systemtap`` feature::
 
diff --git a/documentation/migration-guides/release-notes-4.1.rst b/documentation/migration-guides/release-notes-4.1.rst
index 81d541fac..45f47d82b 100644
--- a/documentation/migration-guides/release-notes-4.1.rst
+++ b/documentation/migration-guides/release-notes-4.1.rst
@@ -191,7 +191,7 @@ Known Issues in 4.1
 ~~~~~~~~~~~~~~~~~~~
 
 - The change to :ref:`migration-4.1-complementary-deps` means that images
-  built with the ``ptest-pkgs`` :term:`IMAGE_FEATURES` don’t automatically
+  built with the ``ptest-pkgs`` :term:`IMAGE_FEATURES` don't automatically
   install ``ptest-runner``, as that package is a recommendation of the
   individual ``-ptest`` packages.  This will be resolved in the next point
   release, and can be worked around by explicitly installing ``ptest-runner``
@@ -305,7 +305,7 @@ Recipe Upgrades in 4.1
 - fontconfig 2.13.1 -> 2.14.0
 - freetype 2.11.1 -> 2.12.1
 - gcc 11.3.0 -> 12.2.0
-- gcompat 1.0.0+1.1+gitX (4d6a5156a6eb…) -> 1.0.0+1.1+gitX (c6921a1aa454…)
+- gcompat 1.0.0+1.1+gitX (4d6a5156a6eb...) -> 1.0.0+1.1+gitX (c6921a1aa454...)
 - gdb 11.2 -> 12.1
 - ghostscript 9.55.0 -> 9.56.1
 - git 2.35.4 -> 2.37.3
@@ -315,7 +315,7 @@ Recipe Upgrades in 4.1
 - gnu-efi 3.0.14 -> 3.0.15
 - gnutls 3.7.4 -> 3.7.7
 - go 1.17.13 -> 1.19
-- go-helloworld 0.1 (787a929d5a0d…) -> 0.1 (2e68773dfca0…)
+- go-helloworld 0.1 (787a929d5a0d...) -> 0.1 (2e68773dfca0...)
 - gpgme 1.17.1 -> 1.18.0
 - gptfdisk 1.0.8 -> 1.0.9
 - harfbuzz 4.0.1 -> 5.1.0
@@ -333,7 +333,7 @@ Recipe Upgrades in 4.1
 - kea 2.0.2 -> 2.2.0
 - kexec-tools 2.0.23 -> 2.0.25
 - kmod 29 -> 30
-- kmscube git (9f63f359fab1…) -> git (3bf6ee1a0233…)
+- kmscube git (9f63f359fab1...) -> git (3bf6ee1a0233...)
 - less 600 -> 608
 - libaio 0.3.112 -> 0.3.113
 - libbsd 0.11.5 -> 0.11.6
@@ -391,13 +391,13 @@ Recipe Upgrades in 4.1
 - mesa-demos 8.4.0 -> 8.5.0
 - mesa-gl 22.0.3 -> 22.2.0
 - meson 0.61.3 -> 0.63.2
-- mmc-utils 0.1+gitX (b7e4d5a6ae99…) -> 0.1+gitX (d7b343fd2628…)
+- mmc-utils 0.1+gitX (b7e4d5a6ae99...) -> 0.1+gitX (d7b343fd2628...)
 - mpg123 1.29.3 -> 1.30.2
 - msmtp 1.8.20 -> 1.8.22
 - mtools 4.0.38 -> 4.0.40
-- musl 1.2.3+gitX (7a43f6fea908…) -> 1.2.3+gitX (37e18b7bf307…)
+- musl 1.2.3+gitX (7a43f6fea908...) -> 1.2.3+gitX (37e18b7bf307...)
 - musl-obstack 1.1 -> 1.2
-- ncurses 6.3+20220423 (a0bc708bc695…) -> 6.3+20220423 (20db1fb41ec9…)
+- ncurses 6.3+20220423 (a0bc708bc695...) -> 6.3+20220423 (20db1fb41ec9...)
 - neard 0.16 -> 0.18
 - nettle 3.7.3 -> 3.8.1
 - nfs-utils 2.6.1 -> 2.6.2
@@ -415,11 +415,11 @@ Recipe Upgrades in 4.1
 - pciutils 3.7.0 -> 3.8.0
 - perl 5.34.1 -> 5.36.0
 - perlcross 1.3.7 -> 1.4
-- piglit 1.0+gitrX (2f80c7cc9c02…) -> 1.0+gitrX (265896c86f90…)
+- piglit 1.0+gitrX (2f80c7cc9c02...) -> 1.0+gitrX (265896c86f90...)
 - pkgconf 1.8.0 -> 1.9.3
 - psmisc 23.4 -> 23.5
 - pulseaudio 15.0 -> 16.1
-- puzzles 0.0+gitX (c43a34fbfe43…) -> 0.0+gitX (8399cff6a3b9…)
+- puzzles 0.0+gitX (c43a34fbfe43...) -> 0.0+gitX (8399cff6a3b9...)
 - python3 3.10.4 -> 3.10.6
 - python3-atomicwrites 1.4.0 -> 1.4.1
 - python3-attrs 21.4.0 -> 22.1.0
@@ -513,12 +513,12 @@ Recipe Upgrades in 4.1
 - vte 0.66.2 -> 0.68.0
 - vulkan-headers 1.3.204.1 -> 1.3.216.0
 - vulkan-loader 1.3.204.1 -> 1.3.216.0
-- vulkan-samples git (28ca2dad83ce…) -> git (74d45aace02d…)
+- vulkan-samples git (28ca2dad83ce...) -> git (74d45aace02d...)
 - vulkan-tools 1.3.204.1 -> 1.3.216.0
 - wayland 1.20.0 -> 1.21.0
 - wayland-protocols 1.25 -> 1.26
 - webkitgtk 2.36.5 -> 2.36.7
-- x264 r3039+gitX (5db6aa6cab1b…) -> r3039+gitX (baee400fa9ce…)
+- x264 r3039+gitX (5db6aa6cab1b...) -> r3039+gitX (baee400fa9ce...)
 - xauth 1.1.1 -> 1.1.2
 - xcb-proto 1.14.1 -> 1.15.2
 - xf86-video-cirrus 1.5.3 -> 1.6.0
diff --git a/documentation/migration-guides/release-notes-5.0.rst b/documentation/migration-guides/release-notes-5.0.rst
index 61ea4aa5a..54f4d1cb8 100644
--- a/documentation/migration-guides/release-notes-5.0.rst
+++ b/documentation/migration-guides/release-notes-5.0.rst
@@ -426,7 +426,7 @@ Recipe Upgrades in 5.0
 -  cross-localedef-native 2.38+git -> 2.39+git
 -  cups 2.4.6 -> 2.4.7
 -  curl 8.4.0 -> 8.7.1
--  dbus-wait 0.1+git (6cc6077a36fe…) -> 0.1+git (64bc7c8fae61…)
+-  dbus-wait 0.1+git (6cc6077a36fe...) -> 0.1+git (64bc7c8fae61...)
 -  debianutils 5.13 -> 5.16
 -  desktop-file-utils 0.26 -> 0.27
 -  dhcpcd 10.0.2 -> 10.0.6
@@ -572,7 +572,7 @@ Recipe Upgrades in 5.0
 -  mesa-gl 23.2.1 -> 24.0.2
 -  meson 1.2.2 -> 1.3.1
 -  minicom 2.8 -> 2.9
--  mmc-utils 0.1+git (613495ecaca9…) -> 0.1+git (b5ca140312d2…)
+-  mmc-utils 0.1+git (613495ecaca9...) -> 0.1+git (b5ca140312d2...)
 -  mpg123 1.31.3 -> 1.32.5
 -  newlib 4.3.0+git -> 4.4.0+git
 -  nghttp2 1.57.0 -> 1.61.0
@@ -588,12 +588,12 @@ Recipe Upgrades in 5.0
 -  p11-kit 0.25.0 -> 0.25.3
 -  pango 1.51.0 -> 1.52.0
 -  pciutils 3.10.0 -> 3.11.1
--  piglit 1.0+gitr (71c21b1157c4…) -> 1.0+gitr (22eaf6a91cfd…)
+-  piglit 1.0+gitr (71c21b1157c4...) -> 1.0+gitr (22eaf6a91cfd...)
 -  pkgconf 2.0.3 -> 2.1.1
--  psplash 0.1+git (44afb7506d43…) -> 0.1+git (ecc191375669…)
+-  psplash 0.1+git (44afb7506d43...) -> 0.1+git (ecc191375669...)
 -  ptest-runner 2.4.2+git -> 2.4.3+git
 -  pulseaudio 16.1 -> 17.0
--  puzzles 0.0+git (2d9e414ee316…) -> 0.0+git (80aac3104096…)
+-  puzzles 0.0+git (2d9e414ee316...) -> 0.0+git (80aac3104096...)
 -  python3 3.11.5 -> 3.12.3
 -  python3-alabaster 0.7.13 -> 0.7.16
 -  python3-attrs 23.1.0 -> 23.2.0
@@ -693,7 +693,7 @@ Recipe Upgrades in 5.0
 -  ttyrun 2.29.0 -> 2.31.0
 -  u-boot 2023.10 -> 2024.01
 -  u-boot-tools 2023.10 -> 2024.01
--  update-rc.d 0.8 (8636cf478d42…) -> 0.8 (b8f950105010…)
+-  update-rc.d 0.8 (8636cf478d42...) -> 0.8 (b8f950105010...)
 -  usbutils 015 -> 017
 -  util-linux 2.39.2 -> 2.39.3
 -  util-linux-libuuid 2.39.2 -> 2.39.3
diff --git a/documentation/migration-guides/release-notes-5.1.rst b/documentation/migration-guides/release-notes-5.1.rst
index dc770ebc3..5de2f662c 100644
--- a/documentation/migration-guides/release-notes-5.1.rst
+++ b/documentation/migration-guides/release-notes-5.1.rst
@@ -498,7 +498,7 @@ Recipe Upgrades in 5.1
 -  ``boost`` 1.84.0 -> 1.86.0
 -  ``boost-build-native`` 1.84.0 -> 1.86.0
 -  ``btrfs-tools`` 6.7.1 -> 6.10.1
--  ``build-appliance-image`` 15.0.0 (bf88a67b4523…) -> 15.0.0 (7cc8bf7af794…)
+-  ``build-appliance-image`` 15.0.0 (bf88a67b4523...) -> 15.0.0 (7cc8bf7af794...)
 -  ``ca-certificates`` 20211016 -> 20240203
 -  ``cairo`` 1.18.0 -> 1.18.2
 -  ``cargo`` 1.75.0 -> 1.79.0
@@ -560,7 +560,7 @@ Recipe Upgrades in 5.1
 -  ``gnu-efi`` 3.0.17 -> 3.0.18
 -  ``gnupg`` 2.4.4 -> 2.5.0
 -  ``gnutls`` 3.8.4 -> 3.8.6
--  ``go-helloworld`` 0.1 (d9923f6970e9…) -> 0.1 (39e772fc2670…)
+-  ``go-helloworld`` 0.1 (d9923f6970e9...) -> 0.1 (39e772fc2670...)
 -  ``gobject-introspection`` 1.78.1 -> 1.80.1
 -  ``gptfdisk`` 1.0.9 -> 1.0.10
 -  ``gsettings-desktop-schemas`` 46.0 -> 47.1
@@ -589,7 +589,7 @@ Recipe Upgrades in 5.1
 -  ``kea`` 2.4.1 -> 2.6.1
 -  ``kexec-tools`` 2.0.28 -> 2.0.29
 -  ``kmod`` 31 -> 33
--  ``kmscube`` 0.0.1+git (6ab022fdfcfe…) -> 0.0.1+git (467e86c5cbeb…)
+-  ``kmscube`` 0.0.1+git (6ab022fdfcfe...) -> 0.0.1+git (467e86c5cbeb...)
 -  ``less`` 643 -> 661
 -  ``libadwaita`` 1.5.2 -> 1.6.0
 -  ``libassuan`` 2.5.6 -> 3.0.1
@@ -669,7 +669,7 @@ Recipe Upgrades in 5.1
 -  ``mdadm`` 4.2 -> 4.3
 -  ``meson`` 1.3.1 -> 1.5.1
 -  ``mkfontscale`` 1.2.2 -> 1.2.3
--  ``mmc-utils`` 0.1+git (b5ca140312d2…) -> 0.1+git (123fd8b2ac39…)
+-  ``mmc-utils`` 0.1+git (b5ca140312d2...) -> 0.1+git (123fd8b2ac39...)
 -  ``mpg123`` 1.32.6 -> 1.32.7
 -  ``msmtp`` 1.8.25 -> 1.8.26
 -  ``mtd-utils`` 2.1.6 -> 2.2.0
@@ -695,12 +695,12 @@ Recipe Upgrades in 5.1
 -  ``pciutils`` 3.11.1 -> 3.13.0
 -  ``perl`` 5.38.2 -> 5.40.0
 -  ``perlcross`` 1.5.2 -> 1.6
--  ``piglit`` 1.0+gitr (22eaf6a91cfd…) -> 1.0+gitr (c11c9374c144…)
+-  ``piglit`` 1.0+gitr (22eaf6a91cfd...) -> 1.0+gitr (c11c9374c144...)
 -  ``pinentry`` 1.2.1 -> 1.3.1
 -  ``pkgconf`` 2.1.1 -> 2.3.0
 -  ``psmisc`` 23.6 -> 23.7
 -  ``ptest-runner`` 2.4.4+git -> 2.4.5+git
--  ``puzzles`` 0.0+git (80aac3104096…) -> 0.0+git (1c1899ee1c4e…)
+-  ``puzzles`` 0.0+git (80aac3104096...) -> 0.0+git (1c1899ee1c4e...)
 -  ``python3-alabaster`` 0.7.16 -> 1.0.0
 -  ``python3-attrs`` 23.2.0 -> 24.2.0
 -  ``python3-babel`` 2.14.0 -> 2.16.0
@@ -811,7 +811,7 @@ Recipe Upgrades in 5.1
 -  ``vte`` 0.74.2 -> 0.76.3
 -  ``vulkan-headers`` 1.3.275.0 -> 1.3.290.0
 -  ``vulkan-loader`` 1.3.275.0 -> 1.3.290.0
--  ``vulkan-samples`` git (2307c3eb5608…) -> git (fdce530c0295…)
+-  ``vulkan-samples`` git (2307c3eb5608...) -> git (fdce530c0295...)
 -  ``vulkan-tools`` 1.3.275.0 -> 1.3.290.0
 -  ``vulkan-utility-libraries`` 1.3.275.0 -> 1.3.290.0
 -  ``vulkan-validation-layers`` 1.3.275.0 -> 1.3.290.0
@@ -823,7 +823,7 @@ Recipe Upgrades in 5.1
 -  ``weston`` 13.0.1 -> 13.0.3
 -  ``wget`` 1.21.4 -> 1.24.5
 -  ``wpa-supplicant`` 2.10 -> 2.11
--  ``x264`` r3039+git (baee400fa9ce…) -> r3039+git (31e19f92f00c…)
+-  ``x264`` r3039+git (baee400fa9ce...) -> r3039+git (31e19f92f00c...)
 -  ``xauth`` 1.1.2 -> 1.1.3
 -  ``xcb-proto`` 1.16.0 -> 1.17.0
 -  ``xev`` 1.2.5 -> 1.2.6
diff --git a/documentation/migration-guides/release-notes-5.2.rst b/documentation/migration-guides/release-notes-5.2.rst
index b5483c903..df56486ba 100644
--- a/documentation/migration-guides/release-notes-5.2.rst
+++ b/documentation/migration-guides/release-notes-5.2.rst
@@ -947,8 +947,8 @@ Recipe Upgrades in |yocto-ver|
      - 6.10.1
      - 6.13
    * - ``build-appliance-image``
-     - 15.0.0 (6a5ba188b79e…)
-     - 15.0.0 (2fe7f46e1779…)
+     - 15.0.0 (6a5ba188b79e...)
+     - 15.0.0 (2fe7f46e1779...)
    * - ``busybox``
      - 1.36.1
      - 1.37.0
@@ -1151,8 +1151,8 @@ Recipe Upgrades in |yocto-ver|
      - 1.22.12
      - 1.24.1
    * - ``go-helloworld``
-     - 0.1 (39e772fc2670…)
-     - 0.1 (d7b0ac127859…)
+     - 0.1 (39e772fc2670...)
+     - 0.1 (d7b0ac127859...)
    * - ``go-runtime``
      - 1.22.12
      - 1.24.1
@@ -1244,8 +1244,8 @@ Recipe Upgrades in |yocto-ver|
      - 2.6.4
      - 2.7.1
    * - ``kern-tools-native``
-     - 0.3+git (7160ebe8b865…)
-     - 0.3+git (bfca22a52ec5…)
+     - 0.3+git (7160ebe8b865...)
+     - 0.3+git (bfca22a52ec5...)
    * - ``kexec-tools``
      - 2.0.29
      - 2.0.30
@@ -1253,8 +1253,8 @@ Recipe Upgrades in |yocto-ver|
      - 33
      - 34.1
    * - ``kmscube``
-     - 0.0.1+git (b2f97f53e01e…)
-     - 0.0.1+git (311eaaaa473d…)
+     - 0.0.1+git (b2f97f53e01e...)
+     - 0.0.1+git (311eaaaa473d...)
    * - ``less``
      - 661
      - 668
@@ -1511,8 +1511,8 @@ Recipe Upgrades in |yocto-ver|
      - 2.9
      - 2.10
    * - ``mmc-utils``
-     - 0.1+git (123fd8b2ac39…)
-     - 0.1+git (2aef4cd9a84d…)
+     - 0.1+git (123fd8b2ac39...)
+     - 0.1+git (2aef4cd9a84d...)
    * - ``mpg123``
      - 1.32.7
      - 1.32.10
@@ -1526,8 +1526,8 @@ Recipe Upgrades in |yocto-ver|
      - 4.0.44
      - 4.0.48
    * - ``musl``
-     - 1.2.5+git (dd1e63c3638d…)
-     - 1.2.5+git (c47ad25ea3b4…)
+     - 1.2.5+git (dd1e63c3638d...)
+     - 1.2.5+git (c47ad25ea3b4...)
    * - ``nativesdk-libtool``
      - 2.5.2
      - 2.5.4
@@ -1571,8 +1571,8 @@ Recipe Upgrades in |yocto-ver|
      - 1.54.0
      - 1.56.2
    * - ``piglit``
-     - 1.0+gitr (c11c9374c144…)
-     - 1.0+gitr (fc8179d31904…)
+     - 1.0+gitr (c11c9374c144...)
+     - 1.0+gitr (fc8179d31904...)
    * - ``pixman``
      - 0.42.2
      - 0.44.2
@@ -1586,14 +1586,14 @@ Recipe Upgrades in |yocto-ver|
      - 4.0.4
      - 4.0.5
    * - ``psplash``
-     - 0.1+git (ecc191375669…)
-     - 0.1+git (1f64c654129f…)
+     - 0.1+git (ecc191375669...)
+     - 0.1+git (1f64c654129f...)
    * - ``ptest-runner``
      - 2.4.5+git
      - 2.4.5.1
    * - ``puzzles``
-     - 0.0+git (1c1899ee1c4e…)
-     - 0.0+git (7da464122232…)
+     - 0.0+git (1c1899ee1c4e...)
+     - 0.0+git (7da464122232...)
    * - ``python3``
      - 3.12.9
      - 3.13.2
@@ -1964,8 +1964,8 @@ Recipe Upgrades in |yocto-ver|
      - 1.3.290.0
      - 1.4.309.0
    * - ``vulkan-samples``
-     - git (fdce530c0295…)
-     - git (8547ce1022a1…)
+     - git (fdce530c0295...)
+     - git (8547ce1022a1...)
    * - ``vulkan-tools``
      - 1.3.290.0
      - 1.4.309.0
diff --git a/documentation/migration-guides/release-notes-5.3.rst b/documentation/migration-guides/release-notes-5.3.rst
index fdc092e51..bf34e3113 100644
--- a/documentation/migration-guides/release-notes-5.3.rst
+++ b/documentation/migration-guides/release-notes-5.3.rst
@@ -1169,7 +1169,7 @@ The following recipes have been upgraded:
      - 6.13
      - 6.17
    * - ``build-appliance-image``
-     - 15.0.0 (316baad50b45…)
+     - 15.0.0 (316baad50b45...)
      - 15.0.0
    * - ``ca-certificates``
      - 20241223
@@ -1385,8 +1385,8 @@ The following recipes have been upgraded:
      - 1.24.6
      - 1.25.4
    * - ``go-helloworld``
-     - 0.1 (d7b0ac127859…)
-     - 0.1 (8b405629c4a5…)
+     - 0.1 (d7b0ac127859...)
+     - 0.1 (8b405629c4a5...)
    * - ``go-runtime``
      - 1.24.6
      - 1.25.4
@@ -1484,8 +1484,8 @@ The following recipes have been upgraded:
      - 2.6.3
      - 3.0.1
    * - ``kern-tools-native``
-     - 0.3+git (c8c1f17867d0…)
-     - 0.3+git (f589e1df2325…)
+     - 0.3+git (c8c1f17867d0...)
+     - 0.3+git (f589e1df2325...)
    * - ``kexec-tools``
      - 2.0.30
      - 2.0.31
@@ -1493,8 +1493,8 @@ The following recipes have been upgraded:
      - 34.1
      - 34.2
    * - ``kmscube``
-     - 0.0.1+git (311eaaaa473d…)
-     - 0.0.1+git (f60e50e887d3…)
+     - 0.0.1+git (311eaaaa473d...)
+     - 0.0.1+git (f60e50e887d3...)
    * - ``less``
      - 668
      - 685
@@ -1508,8 +1508,8 @@ The following recipes have been upgraded:
      - 7.8.2
      - 7.8.4
    * - ``libc-test``
-     - 0+git (18e28496adee…)
-     - 0+git (f2bac7711bec…)
+     - 0+git (18e28496adee...)
+     - 0+git (f2bac7711bec...)
    * - ``libcap``
      - 2.75
      - 2.77
@@ -1736,8 +1736,8 @@ The following recipes have been upgraded:
      - 1.8.28
      - 1.8.31
    * - ``musl``
-     - 1.2.5+git (c47ad25ea3b4…)
-     - 1.2.5+git (0ccaf0572e9c…)
+     - 1.2.5+git (c47ad25ea3b4...)
+     - 1.2.5+git (0ccaf0572e9c...)
    * - ``nettle``
      - 3.10.1
      - 3.10.2
@@ -1784,8 +1784,8 @@ The following recipes have been upgraded:
      - 3.13.0
      - 3.14.0
    * - ``piglit``
-     - 1.0+gitr (fc8179d31904…)
-     - 1.0+gitr (a0a27e528f64…)
+     - 1.0+gitr (fc8179d31904...)
+     - 1.0+gitr (a0a27e528f64...)
    * - ``pinentry``
      - 1.3.1
      - 1.3.2
@@ -1799,11 +1799,11 @@ The following recipes have been upgraded:
      - 1.9.0+git
      - 1.9.2+git
    * - ``psplash``
-     - 0.1+git (1f64c654129f…)
-     - 0.1+git (53ae74a36bf1…)
+     - 0.1+git (1f64c654129f...)
+     - 0.1+git (53ae74a36bf1...)
    * - ``puzzles``
-     - 0.0+git (7da464122232…)
-     - 0.0+git (a7c7826bce5c…)
+     - 0.0+git (7da464122232...)
+     - 0.0+git (a7c7826bce5c...)
    * - ``python3``
      - 3.13.4
      - 3.13.9
@@ -2036,8 +2036,8 @@ The following recipes have been upgraded:
      - 1.7.0
      - 1.9.0
    * - ``rpm-sequoia-crypto-policy``
-     - git (032b418a6db8…)
-     - git (ae1df75b1155…)
+     - git (032b418a6db8...)
+     - git (ae1df75b1155...)
    * - ``rt-tests``
      - 2.8
      - 2.9
@@ -2168,8 +2168,8 @@ The following recipes have been upgraded:
      - 1.4.309.0
      - 1.4.328.1
    * - ``vulkan-samples``
-     - git (8547ce1022a1…)
-     - git (d27205d14d01…)
+     - git (8547ce1022a1...)
+     - git (d27205d14d01...)
    * - ``vulkan-tools``
      - 1.4.309.0
      - 1.4.328.1
diff --git a/documentation/migration-guides/release-notes-6.0.rst b/documentation/migration-guides/release-notes-6.0.rst
index 1ce7d5120..5395d8996 100644
--- a/documentation/migration-guides/release-notes-6.0.rst
+++ b/documentation/migration-guides/release-notes-6.0.rst
@@ -1019,14 +1019,14 @@ The following recipes have been upgraded:
      - 2.42+git
      - 2.43+git
    * - ``cryptodev-linux``
-     - 1.14 (135cbff90af2…)
-     - 1.14 (08644db02d43…)
+     - 1.14 (135cbff90af2...)
+     - 1.14 (08644db02d43...)
    * - ``cryptodev-module``
-     - 1.14 (135cbff90af2…)
-     - 1.14 (08644db02d43…)
+     - 1.14 (135cbff90af2...)
+     - 1.14 (08644db02d43...)
    * - ``cryptodev-tests``
-     - 1.14 (135cbff90af2…)
-     - 1.14 (08644db02d43…)
+     - 1.14 (135cbff90af2...)
+     - 1.14 (08644db02d43...)
    * - ``cups``
      - 2.4.15
      - 2.4.16
@@ -1154,8 +1154,8 @@ The following recipes have been upgraded:
      - 1.4.328.1
      - 1.4.341.0
    * - ``gn``
-     - 0+git (81b24e01531e…)
-     - 0+git (9d19a7870add…)
+     - 0+git (81b24e01531e...)
+     - 0+git (9d19a7870add...)
    * - ``gnu-efi``
      - 4.0.2
      - 4.0.4
@@ -1181,8 +1181,8 @@ The following recipes have been upgraded:
      - 1.25.9
      - 1.26.2
    * - ``go-helloworld``
-     - 0.1 (8b405629c4a5…)
-     - 0.1 (7f05d217867b…)
+     - 0.1 (8b405629c4a5...)
+     - 0.1 (7f05d217867b...)
    * - ``go-runtime``
      - 1.25.9
      - 1.26.2
@@ -1274,14 +1274,14 @@ The following recipes have been upgraded:
      - 3.0.1
      - 3.0.3
    * - ``kern-tools-native``
-     - 0.3+git (f589e1df2325…)
-     - 0.3+git (a4a362d9f4f0…)
+     - 0.3+git (f589e1df2325...)
+     - 0.3+git (a4a362d9f4f0...)
    * - ``kexec-tools``
      - 2.0.31
      - 2.0.32
    * - ``kmscube``
-     - 0.0.1+git (2c1f2646c5e5…)
-     - 0.0.1+git (f60e50e887d3…)
+     - 0.0.1+git (2c1f2646c5e5...)
+     - 0.0.1+git (f60e50e887d3...)
    * - ``less``
      - 679
      - 692
@@ -1613,8 +1613,8 @@ The following recipes have been upgraded:
      - 1.9.3+git
      - 1.9.5
    * - ``puzzles``
-     - 0.0+git (a7c7826bce5c…)
-     - 0.0+git (ecb576fb2a0a…)
+     - 0.0+git (a7c7826bce5c...)
+     - 0.0+git (ecb576fb2a0a...)
    * - ``python3``
      - 3.13.12
      - 3.14.4
@@ -1841,8 +1841,8 @@ The following recipes have been upgraded:
      - 1.9.0
      - 1.10.1
    * - ``rpm-sequoia-crypto-policy``
-     - git (ae1df75b1155…)
-     - git (f3f5fa454345…)
+     - git (ae1df75b1155...)
+     - git (f3f5fa454345...)
    * - ``rt-tests``
      - 2.9
      - 2.10
@@ -1970,8 +1970,8 @@ The following recipes have been upgraded:
      - 1.4.328.1
      - 1.4.341.0
    * - ``vulkan-samples``
-     - git (d27205d14d01…)
-     - git (fa2cf45adde0…)
+     - git (d27205d14d01...)
+     - git (fa2cf45adde0...)
    * - ``vulkan-tools``
      - 1.4.328.1
      - 1.4.341.0
@@ -2000,8 +2000,8 @@ The following recipes have been upgraded:
      - 1.16.0
      - 1.16.1
    * - ``x264``
-     - r3039+git (31e19f92f00c…)
-     - r3039+git (0480cb05fa18…)
+     - r3039+git (31e19f92f00c...)
+     - r3039+git (0480cb05fa18...)
    * - ``xauth``
      - 1.1.4
      - 1.1.5
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 98dff1bac..f3d1aa64e 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -152,7 +152,7 @@ barebox, enabling tasks such as :ref:`ref-tasks-menuconfig` and
 
 The generated barebox binaries are deployed to
 :term:`DEPLOY_DIR_IMAGE` as well as installed to ``BAREBOX_INSTALL_PATH``
-(``/boot`` by default) making them part of the recipe’s base package.
+(``/boot`` by default) making them part of the recipe's base package.
 This setup supports both using the barebox binaries as independent artifacts
 and installing them into a rootfs.
 :term:`BAREBOX_BINARY` can be used to select a distinct binary to deploy and
@@ -3687,7 +3687,7 @@ for details.
 The :ref:`ref-classes-upstream-stable-release-point` class automatically
 generates the :term:`UPSTREAM_STABLE_RELEASE_REGEX` variable for recipes
 whose version uses a dot-separated scheme. This enables stable point release
-upgrades — version upgrades constrained to the same stable series (e.g.
+upgrades -- version upgrades constrained to the same stable series (e.g.
 ``1.4.2`` to ``1.4.3`` but not to ``1.5.0``).
 
 The class uses the :term:`STABLE_VERSION_PARTS` variable (defaults to ``"2"``)
diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 863825b06..6b21d302f 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -517,7 +517,7 @@ Deploying Your Software on the Target Machine
 Use the ``devtool deploy-target`` command to deploy the recipe's build
 output to the live target machine::
 
-   $ devtool deploy-target recipe target
+   $ devtool deploy-target recipe target
 
 The target is the address of the target machine, which must be running
 an SSH server (i.e. ``user@hostname[:destdir]``).
@@ -588,7 +588,7 @@ command to work, you must have previously used the
 ":ref:`devtool deploy-target <ref-manual/devtool-reference:deploying your software on the target machine>`"
 command::
 
-   $ devtool undeploy-target recipe target
+   $ devtool undeploy-target recipe target
 
 The target is the
 address of the target machine, which must be running an SSH server (i.e.
diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst
index 315a078f7..55c00712b 100644
--- a/documentation/ref-manual/structure.rst
+++ b/documentation/ref-manual/structure.rst
@@ -22,7 +22,7 @@ Directory` are organized as follows:
 .. code-block:: text
 
    ├── build/
-   │   └── ...
+   │   └── ...
    └── layers/
        ├── bitbake/
        ├── meta-yocto/
@@ -385,13 +385,13 @@ makes the :ref:`structure-build-conf-site.conf` file a symbolic link to a common
 ``site.conf`` file::
 
    ├── poky-master-poky-distro_poky-machine_qemux86-64/
-   │   └── build/
-   │       └── conf/
-   │           └── site.conf -> ../../../site.conf
+   │   └── build/
+   │       └── conf/
+   │           └── site.conf -> ../../../site.conf
    ├── poky-master-poky-with-sstate-distro_poky-machine_qemux86-64/
-   │   └── build/
-   │       └── conf/
-   │           └── site.conf -> ../../../site.conf
+   │   └── build/
+   │       └── conf/
+   │           └── site.conf -> ../../../site.conf
    └── site.conf
 
 This way, site-specific settings can be shared for multiple build
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index b124e9c30..e42c0a57c 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -9913,7 +9913,7 @@ system and gives an overview of their function and contents.
 
           meta-acme/recipes-core/psplash
           ├── files
-          │   └── logo-acme.png
+          │   └── logo-acme.png
           └── psplash_%.bbappend
 
       And here are the contents of the ``psplash_%.bbappend`` file in
diff --git a/documentation/ref-manual/yocto-project-supported-features.rst b/documentation/ref-manual/yocto-project-supported-features.rst
index d7229f1c2..e209e54c4 100644
--- a/documentation/ref-manual/yocto-project-supported-features.rst
+++ b/documentation/ref-manual/yocto-project-supported-features.rst
@@ -164,7 +164,7 @@ to support, however there isn't wide enough interest and support to justify
 testing all incoming changes on it. There are however project member
 organisations and maintainers willing to run tests and review fixes.
 
-This category may be applicable as support/usage in an area develops and grows,
+This category may be applicable as support/usage in an area develops and grows,
 or as support/usage fades but we continue to have tests. It can also apply where
 resourcing isn't available for full primary support but there is
 member/maintainer support for running tests.
@@ -173,21 +173,21 @@ We therefore have the following criteria and policies for such items:
 
 -  It can be clearly isolated and defined by specific configuration.
 
--  There is a clear documented group of maintainers agreeing to maintain it.
+-  There is a clear documented group of maintainers agreeing to maintain it.
 
 -  Those maintainers are active and responsive.
 
 -  It is being actively and publicly tested (potentially using
-   the :ref:`Autobuilder <test-manual/intro:Yocto Project Autobuilder Overview>`
+   the :ref:`Autobuilder <test-manual/intro:Yocto Project Autobuilder Overview>`
    by agreement, or otherwise).
 
--  Testing would not be part of standard incoming change testing and regressions
+-  Testing would not be part of standard incoming change testing and regressions
    would not block incoming patches.
 
 -  The :yocto_wiki:`SWAT </Yocto_Build_Failure_Swat_Team>` team would not handle
    any test builds on the Autobuilder.
 
--  Test results can be submitted as part of the release process if desired.
+-  Test results can be submitted as part of the release process if desired.
 
 The Yocto Project :yocto_wiki:`Technical Steering Committee (TSC) </TSC>` makes
 decisions on features in this status and Autobuilder testing. Such support would
diff --git a/documentation/test-manual/yocto-project-compatible.rst b/documentation/test-manual/yocto-project-compatible.rst
index 7a2e00a99..b4da178ec 100644
--- a/documentation/test-manual/yocto-project-compatible.rst
+++ b/documentation/test-manual/yocto-project-compatible.rst
@@ -115,7 +115,7 @@ Here are key best practices the program tries to encourage:
    user changes a configuration setting to activate the layer, by selecting
    a :term:`MACHINE`, a :term:`DISTRO` or a :term:`DISTRO_FEATURES` setting.
 
--  Layers should be documenting where they don’t support normal "core"
+-  Layers should be documenting where they don't support normal "core"
    functionality such as where debug symbols are disabled or missing, where
    development headers and on-target library usage may not work or where
    functionality like the SDK/eSDK would not be expected to work.
diff --git a/documentation/transitioning-to-a-custom-environment.rst b/documentation/transitioning-to-a-custom-environment.rst
index c69ab5361..b4dbc5224 100644
--- a/documentation/transitioning-to-a-custom-environment.rst
+++ b/documentation/transitioning-to-a-custom-environment.rst
@@ -33,7 +33,7 @@ Transitioning to a custom environment for systems development
    Layer Index <>` to find and acquire the best BSP for your
    target board. The Yocto Project layer index BSPs are regularly validated. The
    best place to get your first BSP is from your silicon manufacturer or board
-   vendor – they can point you to their most qualified efforts. In general, for
+   vendor - they can point you to their most qualified efforts. In general, for
    Intel silicon use ``meta-intel``, for Texas Instruments use ``meta-ti``, and so
    forth. Choose a BSP that has been tested with the same Yocto Project release
    that you've downloaded. Be aware that some BSPs may not be immediately
diff --git a/documentation/what-i-wish-id-known.rst b/documentation/what-i-wish-id-known.rst
index d89f43304..a8b9fabad 100644
--- a/documentation/what-i-wish-id-known.rst
+++ b/documentation/what-i-wish-id-known.rst
@@ -86,13 +86,13 @@ contact us with other suggestions.
    pinpoint where trouble is occurring and how the build is breaking. The
    workflow breaks down into the following steps:
 
-   #. Fetch – get the source code
-   #. Extract – unpack the sources
-   #. Patch – apply patches for bug fixes and new capability
-   #. Configure – set up your environment specifications
-   #. Build – compile and link
-   #. Install – copy files to target directories
-   #. Package – bundle files for installation
+   #. Fetch - get the source code
+   #. Extract - unpack the sources
+   #. Patch - apply patches for bug fixes and new capability
+   #. Configure - set up your environment specifications
+   #. Build - compile and link
+   #. Install - copy files to target directories
+   #. Package - bundle files for installation
 
    During "fetch", there may be an inability to find code. During "extract",
    there is likely an invalid zip or something similar. In other words, the
-- 
2.47.3

[PATCH v2 5/5] tools: Add check-confusables pre-commit hook

[niko.mauno]

From: Niko Mauno <niko.mauno@vaisala.com>

Add a check-confusables script, in the same fashion as
check-glossaries, that scans the documentation .rst sources for
non-ASCII "confusable" characters (curly quotes, en/em dashes,
horizontal ellipsis, non-breaking and zero-width spaces, etc.) and
reports each occurrence with its location and suggested ASCII
replacement, exiting non-zero if any are found. This guards against
the class of breakage fixed in the preceding commit, e.g. curly quotes
causing recipe ParseErrors.

Legitimate non-ASCII such as box-drawing characters used in directory
trees, accented letters in contributor names and CJK characters are
intentionally left untouched.

Wire it up both as a local pre-commit hook and in the Makefile "checks"
target, alongside check-glossaries.

Suggested-by: Quentin Schulz <quentin.schulz@cherry.de>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Niko Mauno <niko.mauno@vaisala.com>
---
 .pre-commit-config.yaml               |  5 ++
 documentation/Makefile                |  1 +
 documentation/tools/check-confusables | 77 +++++++++++++++++++++++++++
 3 files changed, 83 insertions(+)
 create mode 100755 documentation/tools/check-confusables

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index f2b73a481..d6008b609 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -6,3 +6,8 @@ repos:
         entry: ./documentation/tools/check-glossaries
         language: python
         pass_filenames: false
+      - id: check-confusables
+        name: Check for non-ASCII confusable characters
+        entry: ./documentation/tools/check-confusables
+        language: python
+        pass_filenames: false
diff --git a/documentation/Makefile b/documentation/Makefile
index fe0574537..87a6f8a8b 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -37,6 +37,7 @@ clean:
 
 checks:
 	$(SOURCEDIR)/tools/check-glossaries --docs-dir $(SOURCEDIR)
+	$(SOURCEDIR)/tools/check-confusables --docs-dir $(SOURCEDIR)
 
 stylecheck:
 	vale sync
diff --git a/documentation/tools/check-confusables b/documentation/tools/check-confusables
new file mode 100755
index 000000000..f79ee046c
--- /dev/null
+++ b/documentation/tools/check-confusables
@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+
+import argparse
+import sys
+
+from pathlib import Path
+
+
+def parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Check documentation sources for non-ASCII typographic "
+                    "characters that should be plain ASCII")
+
+    parser.add_argument("-d", "--docs-dir",
+                        type=Path,
+                        default=Path(__file__).resolve().parent.parent,
+                        help="Path to documentation/ directory in yocto-docs")
+
+    return parser.parse_args()
+
+
+# Map of "confusable" characters that are frequently introduced by editors,
+# word processors or copy-pasting, to their plain ASCII replacement. These
+# look almost identical to regular ASCII but break tooling, e.g. a curly
+# quote in a recipe example causes:
+#
+#   ERROR: ParseError ...: unparsed line: 'RDEPENDS:${PN} = "foo"'
+#
+# Only these characters are flagged; legitimate non-ASCII such as box-drawing
+# characters used in directory trees, accented letters in contributor names
+# and CJK characters are intentionally left alone.
+confusables = {
+    "‘": "'",      # LEFT SINGLE QUOTATION MARK
+    "’": "'",      # RIGHT SINGLE QUOTATION MARK
+    "“": '"',      # LEFT DOUBLE QUOTATION MARK
+    "”": '"',      # RIGHT DOUBLE QUOTATION MARK
+    "′": "'",      # PRIME
+    "″": '"',      # DOUBLE PRIME
+    "–": "-",      # EN DASH
+    "—": "--",     # EM DASH
+    "‐": "-",      # HYPHEN
+    "‑": "-",      # NON-BREAKING HYPHEN
+    "−": "-",      # MINUS SIGN
+    "…": "...",    # HORIZONTAL ELLIPSIS
+    " ": " ",      # NO-BREAK SPACE
+    " ": " ",      # NARROW NO-BREAK SPACE
+    "​": "",       # ZERO WIDTH SPACE
+    "": "",       # ZERO WIDTH NO-BREAK SPACE / BOM
+    "­": "",       # SOFT HYPHEN
+}
+
+
+def main():
+
+    args = parse_arguments()
+    exit_code = 0
+
+    for rst_path in sorted(Path(args.docs_dir).rglob("*.rst")):
+        rel = rst_path.relative_to(args.docs_dir)
+
+        with open(rst_path, "r", encoding="utf-8") as f:
+            for lineno, line in enumerate(f, start=1):
+                for col, char in enumerate(line, start=1):
+                    if char in confusables:
+                        replacement = confusables[char]
+                        hint = (f"'{replacement}'" if replacement
+                                else "(remove)")
+                        print(f"WARNING: {rel}:{lineno}:{col}: non-ASCII "
+                              f"character U+{ord(char):04X} should be "
+                              f"replaced with {hint}")
+                        exit_code = 1
+
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()
-- 
2.47.3

Re: [docs] [PATCH v2 2/5] ref-manual: Prune superfluous space with :append

[Antonin Godard]

Hi,

Just a note; but since Quentin gave you Reviewed-by on your v1, it's nice to
keep them for the unchanged patches in v2. I'll apply them manually for
unchanged patches.

Antonin

Re: [docs] [PATCH v2 5/5] tools: Add check-confusables pre-commit hook

[Antonin Godard]

Hi,

On Tue Jul 28, 2026 at 9:23 AM CEST, Niko Mauno via lists.yoctoproject.org wrote:
> From: Niko Mauno <niko.mauno@vaisala.com>
>
> Add a check-confusables script, in the same fashion as
> check-glossaries, that scans the documentation .rst sources for
> non-ASCII "confusable" characters (curly quotes, en/em dashes,
> horizontal ellipsis, non-breaking and zero-width spaces, etc.) and
> reports each occurrence with its location and suggested ASCII
> replacement, exiting non-zero if any are found. This guards against
> the class of breakage fixed in the preceding commit, e.g. curly quotes
> causing recipe ParseErrors.
>
> Legitimate non-ASCII such as box-drawing characters used in directory
> trees, accented letters in contributor names and CJK characters are
> intentionally left untouched.
>
> Wire it up both as a local pre-commit hook and in the Makefile "checks"
> target, alongside check-glossaries.
>
> Suggested-by: Quentin Schulz <quentin.schulz@cherry.de>
> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
> Signed-off-by: Niko Mauno <niko.mauno@vaisala.com>
> ---
>  .pre-commit-config.yaml               |  5 ++
>  documentation/Makefile                |  1 +
>  documentation/tools/check-confusables | 77 +++++++++++++++++++++++++++
>  3 files changed, 83 insertions(+)
>  create mode 100755 documentation/tools/check-confusables
>
> diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
> index f2b73a481..d6008b609 100644
> --- a/.pre-commit-config.yaml
> +++ b/.pre-commit-config.yaml
> @@ -6,3 +6,8 @@ repos:
>          entry: ./documentation/tools/check-glossaries
>          language: python
>          pass_filenames: false
> +      - id: check-confusables
> +        name: Check for non-ASCII confusable characters
> +        entry: ./documentation/tools/check-confusables
> +        language: python
> +        pass_filenames: false

I think we should pass filenames and check only the modified files, no need to
checking the entire tree each time?

> diff --git a/documentation/Makefile b/documentation/Makefile
> index fe0574537..87a6f8a8b 100644
> --- a/documentation/Makefile
> +++ b/documentation/Makefile
> @@ -37,6 +37,7 @@ clean:
>  
>  checks:
>  	$(SOURCEDIR)/tools/check-glossaries --docs-dir $(SOURCEDIR)
> +	$(SOURCEDIR)/tools/check-confusables --docs-dir $(SOURCEDIR)
>  
>  stylecheck:
>  	vale sync
> diff --git a/documentation/tools/check-confusables b/documentation/tools/check-confusables
> new file mode 100755
> index 000000000..f79ee046c
> --- /dev/null
> +++ b/documentation/tools/check-confusables
> @@ -0,0 +1,77 @@
> +#!/usr/bin/env python3
> +
> +import argparse
> +import sys
> +
> +from pathlib import Path
> +
> +
> +def parse_arguments() -> argparse.Namespace:
> +    parser = argparse.ArgumentParser(
> +        description="Check documentation sources for non-ASCII typographic "
> +                    "characters that should be plain ASCII")
> +
> +    parser.add_argument("-d", "--docs-dir",
> +                        type=Path,
> +                        default=Path(__file__).resolve().parent.parent,
> +                        help="Path to documentation/ directory in yocto-docs")
> +
> +    return parser.parse_args()
> +
> +
> +# Map of "confusable" characters that are frequently introduced by editors,
> +# word processors or copy-pasting, to their plain ASCII replacement. These
> +# look almost identical to regular ASCII but break tooling, e.g. a curly
> +# quote in a recipe example causes:
> +#
> +#   ERROR: ParseError ...: unparsed line: 'RDEPENDS:${PN} = "foo"'

I don't see the curly quote here

> +#
> +# Only these characters are flagged; legitimate non-ASCII such as box-drawing
> +# characters used in directory trees, accented letters in contributor names
> +# and CJK characters are intentionally left alone.
> +confusables = {
> +    "‘": "'",      # LEFT SINGLE QUOTATION MARK
> +    "’": "'",      # RIGHT SINGLE QUOTATION MARK
> +    "“": '"',      # LEFT DOUBLE QUOTATION MARK
> +    "”": '"',      # RIGHT DOUBLE QUOTATION MARK
> +    "′": "'",      # PRIME
> +    "″": '"',      # DOUBLE PRIME
> +    "–": "-",      # EN DASH
> +    "—": "--",     # EM DASH
> +    "‐": "-",      # HYPHEN
> +    "‑": "-",      # NON-BREAKING HYPHEN
> +    "−": "-",      # MINUS SIGN
> +    "…": "...",    # HORIZONTAL ELLIPSIS
> +    " ": " ",      # NO-BREAK SPACE

Actually, since the `tree` command uses no-break spaces, I think it's OK to keep
them otherwise we'd have to convert each tree output, which also might be
confusing.

> +    " ": " ",      # NARROW NO-BREAK SPACE
> +    "​": "",       # ZERO WIDTH SPACE
> +    "": "",       # ZERO WIDTH NO-BREAK SPACE / BOM
> +    "­": "",       # SOFT HYPHEN
> +}
> +
> +
> +def main():
> +
> +    args = parse_arguments()
> +    exit_code = 0
> +
> +    for rst_path in sorted(Path(args.docs_dir).rglob("*.rst")):
> +        rel = rst_path.relative_to(args.docs_dir)
> +
> +        with open(rst_path, "r", encoding="utf-8") as f:
> +            for lineno, line in enumerate(f, start=1):
> +                for col, char in enumerate(line, start=1):
> +                    if char in confusables:
> +                        replacement = confusables[char]
> +                        hint = (f"'{replacement}'" if replacement
> +                                else "(remove)")
> +                        print(f"WARNING: {rel}:{lineno}:{col}: non-ASCII "
> +                              f"character U+{ord(char):04X} should be "
> +                              f"replaced with {hint}")
> +                        exit_code = 1
> +
> +    sys.exit(exit_code)
> +
> +
> +if __name__ == "__main__":
> +    main()


Antonin

Re: [docs] [PATCH v2 5/5] tools: Add check-confusables pre-commit hook

[Niko Mauno]

On 7/28/26 10:53 AM, Antonin Godard wrote:
> Hi,
> 
> On Tue Jul 28, 2026 at 9:23 AM CEST, Niko Mauno via lists.yoctoproject.org wrote:
>> From: Niko Mauno <niko.mauno@vaisala.com>
>>
>> Add a check-confusables script, in the same fashion as
>> check-glossaries, that scans the documentation .rst sources for
>> non-ASCII "confusable" characters (curly quotes, en/em dashes,
>> horizontal ellipsis, non-breaking and zero-width spaces, etc.) and
>> reports each occurrence with its location and suggested ASCII
>> replacement, exiting non-zero if any are found. This guards against
>> the class of breakage fixed in the preceding commit, e.g. curly quotes
>> causing recipe ParseErrors.
>>
>> Legitimate non-ASCII such as box-drawing characters used in directory
>> trees, accented letters in contributor names and CJK characters are
>> intentionally left untouched.
>>
>> Wire it up both as a local pre-commit hook and in the Makefile "checks"
>> target, alongside check-glossaries.
>>
>> Suggested-by: Quentin Schulz <quentin.schulz@cherry.de>
>> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
>> Signed-off-by: Niko Mauno <niko.mauno@vaisala.com>
>> ---
>>   .pre-commit-config.yaml               |  5 ++
>>   documentation/Makefile                |  1 +
>>   documentation/tools/check-confusables | 77 +++++++++++++++++++++++++++
>>   3 files changed, 83 insertions(+)
>>   create mode 100755 documentation/tools/check-confusables
>>
>> diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
>> index f2b73a481..d6008b609 100644
>> --- a/.pre-commit-config.yaml
>> +++ b/.pre-commit-config.yaml
>> @@ -6,3 +6,8 @@ repos:
>>           entry: ./documentation/tools/check-glossaries
>>           language: python
>>           pass_filenames: false
>> +      - id: check-confusables
>> +        name: Check for non-ASCII confusable characters
>> +        entry: ./documentation/tools/check-confusables
>> +        language: python
>> +        pass_filenames: false
> 
> I think we should pass filenames and check only the modified files, no need to
> checking the entire tree each time?
> 
>> diff --git a/documentation/Makefile b/documentation/Makefile
>> index fe0574537..87a6f8a8b 100644
>> --- a/documentation/Makefile
>> +++ b/documentation/Makefile
>> @@ -37,6 +37,7 @@ clean:
>>   
>>   checks:
>>   	$(SOURCEDIR)/tools/check-glossaries --docs-dir $(SOURCEDIR)
>> +	$(SOURCEDIR)/tools/check-confusables --docs-dir $(SOURCEDIR)
>>   
>>   stylecheck:
>>   	vale sync
>> diff --git a/documentation/tools/check-confusables b/documentation/tools/check-confusables
>> new file mode 100755
>> index 000000000..f79ee046c
>> --- /dev/null
>> +++ b/documentation/tools/check-confusables
>> @@ -0,0 +1,77 @@
>> +#!/usr/bin/env python3
>> +
>> +import argparse
>> +import sys
>> +
>> +from pathlib import Path
>> +
>> +
>> +def parse_arguments() -> argparse.Namespace:
>> +    parser = argparse.ArgumentParser(
>> +        description="Check documentation sources for non-ASCII typographic "
>> +                    "characters that should be plain ASCII")
>> +
>> +    parser.add_argument("-d", "--docs-dir",
>> +                        type=Path,
>> +                        default=Path(__file__).resolve().parent.parent,
>> +                        help="Path to documentation/ directory in yocto-docs")
>> +
>> +    return parser.parse_args()
>> +
>> +
>> +# Map of "confusable" characters that are frequently introduced by editors,
>> +# word processors or copy-pasting, to their plain ASCII replacement. These
>> +# look almost identical to regular ASCII but break tooling, e.g. a curly
>> +# quote in a recipe example causes:
>> +#
>> +#   ERROR: ParseError ...: unparsed line: 'RDEPENDS:${PN} = "foo"'
> 
> I don't see the curly quote here
> 
>> +#
>> +# Only these characters are flagged; legitimate non-ASCII such as box-drawing
>> +# characters used in directory trees, accented letters in contributor names
>> +# and CJK characters are intentionally left alone.
>> +confusables = {
>> +    "‘": "'",      # LEFT SINGLE QUOTATION MARK
>> +    "’": "'",      # RIGHT SINGLE QUOTATION MARK
>> +    "“": '"',      # LEFT DOUBLE QUOTATION MARK
>> +    "”": '"',      # RIGHT DOUBLE QUOTATION MARK
>> +    "′": "'",      # PRIME
>> +    "″": '"',      # DOUBLE PRIME
>> +    "–": "-",      # EN DASH
>> +    "—": "--",     # EM DASH
>> +    "‐": "-",      # HYPHEN
>> +    "‑": "-",      # NON-BREAKING HYPHEN
>> +    "−": "-",      # MINUS SIGN
>> +    "…": "...",    # HORIZONTAL ELLIPSIS
>> +    " ": " ",      # NO-BREAK SPACE
> 
> Actually, since the `tree` command uses no-break spaces, I think it's OK to keep
> them otherwise we'd have to convert each tree output, which also might be
> confusing.
> 
>> +    " ": " ",      # NARROW NO-BREAK SPACE
>> +    "​": "",       # ZERO WIDTH SPACE
>> +    "": "",       # ZERO WIDTH NO-BREAK SPACE / BOM
>> +    "­": "",       # SOFT HYPHEN
>> +}
>> +
>> +
>> +def main():
>> +
>> +    args = parse_arguments()
>> +    exit_code = 0
>> +
>> +    for rst_path in sorted(Path(args.docs_dir).rglob("*.rst")):
>> +        rel = rst_path.relative_to(args.docs_dir)
>> +
>> +        with open(rst_path, "r", encoding="utf-8") as f:
>> +            for lineno, line in enumerate(f, start=1):
>> +                for col, char in enumerate(line, start=1):
>> +                    if char in confusables:
>> +                        replacement = confusables[char]
>> +                        hint = (f"'{replacement}'" if replacement
>> +                                else "(remove)")
>> +                        print(f"WARNING: {rel}:{lineno}:{col}: non-ASCII "
>> +                              f"character U+{ord(char):04X} should be "
>> +                              f"replaced with {hint}")
>> +                        exit_code = 1
>> +
>> +    sys.exit(exit_code)
>> +
>> +
>> +if __name__ == "__main__":
>> +    main()
> 
> 
> Antonin


Thank You Antonin, I have now submitted v3 which should address the 
observations You pointed out above, plus adds Quentin's Reviewed-by line 
in the bottom three commits which remained unchanged since v1, and also 
leaves out conversion of "horizontal ellipsis" characters which seemed 
to be used for denoting git hash truncation and therefore seemed to add 
just noise to the fix commit.
-Niko