Re: [PATCH 2/9] docs: escape ** glob pattern in MAINTAINERS descriptions

[Randy Dunlap]

On 5/4/26 8:51 AM, Mauro Carvalho Chehab wrote:
> From: Matteo Croce <teknoraver@xxxxxxxx>
> 
> Escape '**' in the MAINTAINERS descriptions section to prevent
> reStructuredText from interpreting it as bold/strong inline markup,
> which causes a warning when running 'make htmldocs'.
> 
> Fixes: 420849332f9f ("get_maintainer: add ** glob pattern support")
> Signed-off-by: Matteo Croce <teknoraver@xxxxxxxx>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> ---
>  Documentation/sphinx/maintainers_include.py | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
> index c7f9911ae45b..e679acf0633d 100755
> --- a/Documentation/sphinx/maintainers_include.py
> +++ b/Documentation/sphinx/maintainers_include.py
> @@ -127,7 +127,8 @@ class MaintainersParser:
>              output = None
>              if descriptions:
>                  # Escape the escapes in preformatted text.
> -                output = "| %s" % (line.replace("\\", "\\\\"))
> +                output = "| %s" % (line.replace("\\", "\\\\")
> +                                        .replace("**", "\\**"))
>                  # Look for and record field letter to field name mappings:
>                  #   R: Designated *reviewer*: FullName <address@domain>
>                  m = re.search(r"\s(\S):\s", line)

These comments still apply from my review of this patch on 4/9/26:

It's nice to eliminate one warning from 'make htmldocs', so this is good
in that regard. However, there are still multiple problems (not Warnings)
with '*' characters in the MAINTAINERS file:

1) 	   F:	*/net/*		all files in "any top level directory"/net

In the html output, it shows "/net/" italicized (that's what one * does).

2)	   F:	fs/**/*foo*.c	all *foo*.c files in any subdirectory of fs

In the html output, it shows

	F: fs/**/foo.c all foo.c files in any subdirectory of fs

with both occurrences of "foo.c" italicized (dropping the '*' characters).

These 2 examples are actively wrong.

[adding new:]
We would be better served by just putting file patterns inside ``fs/**/*foo*.c``
quotation marks IMO.

Ah, similar to what you do in the table output.

Oh, with one little glitch:
E.g., in the very first entry for 3C59X NETWORK DRIVER,
  F:	Documentation/networking/device_drivers/ethernet/3com/vortex.rst
  F:	drivers/net/ethernet/3com/3c59x.c
it looks like automarkup is applied to the Documentation file so these
2 files are displayed as:

networking/device_drivers/ethernet/3com/vortex, drivers/net/ethernet/3com/3c59x.c

with the Doc file underlined and missing both Documentation and .rst.
Or maybe that's what you intended since the automarkup link does work.
It's just not what I expected. Oh well.


-- 
~Randy