linux-kernel - Re: [PATCH] docs: automarkup.py: Skip common English words as C identifiers

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <87cy2v9ckz.fsf@trenco.lwn.net>
Date: Tue, 27 Jan 2026 10:42:36 -0700
From: Jonathan Corbet <corbet@....net>
To: Yulong Han <wheatfox17@...oud.com>, mchehab@...nel.org
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, wheatfox
 <wheatfox17@...oud.com>
Subject: Re: [PATCH] docs: automarkup.py: Skip common English words as C
 identifiers

Yulong Han <wheatfox17@...oud.com> writes:

> From: wheatfox <wheatfox17@...oud.com>
>
> The automarkup extension incorrectly recognizes common English words
> as C identifiers when they follow struct/union/enum/typedef keywords,
> causing normal text like "... (a simple) struct that" (in `workqueue.rst`)
> to be rendered as code blocks.
>
> This patch adds Skipidentifiers list to filter out these words.
>
> Signed-off-by: Yulong Han <wheatfox17@...oud.com>
> ---
>  Documentation/sphinx/automarkup.py | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
> index 1d9dada40a74..c2227ab0a891 100644
> --- a/Documentation/sphinx/automarkup.py
> +++ b/Documentation/sphinx/automarkup.py
> @@ -46,6 +46,12 @@ RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
>  #
>  Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ]
>  
> +#
> +# Common English words that should not be recognized as C identifiers
> +# when following struct/union/enum/typedef keywords.
> +# Example: "a simple struct that" in workqueue.rst should not be marked as code.
> +#
> +Skipidentifiers = [ 'that', 'which', 'where', 'whose' ]
>  
>  #
>  # Many places in the docs refer to common system calls.  It is
> @@ -163,6 +169,10 @@ def markup_c_ref(docname, app, match):
>      if c_namespace:
>          possible_targets.insert(0, c_namespace + "." + base_target)
>  
> +    # Skip common English words that match identifier pattern but are not C code.
> +    if base_target in Skipidentifiers:
> +        return target_text
> +
>      if base_target not in Skipnames:
>          for target in possible_targets:
>              if not (match.re == RE_function and target in Skipfuncs):

I've applied this as an obvious improvement.  I do suspect, though, that
a better fix would be to have the automarkup code just not do markup for
"struct" references that don't exist.

Thanks,

jon