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

[Jonathan Corbet <corbet@lwn.net>]

Yulong Han <wheatfox17@icloud.com> writes:

> From: wheatfox <wheatfox17@icloud.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@icloud.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