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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

On Mon, 04 May 2026 20:19:50 -0700
Joe Perches <joe@perches.com> wrote:

> On Mon, 2026-05-04 at 14:20 -0700, Randy Dunlap wrote:
> > On 5/4/26 8:51 AM, Mauro Carvalho Chehab wrote:
> > From: Matteo Croce <[teknoraver@meta.com](mailto:teknoraver@meta.com)>  
> > > 
> > > 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'.  
> []
> > 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.

The logic actually does that already:

        #
        # Mark paths (and regexes) as literal text for improved
        # readability and to escape any escapes.
        #
        if field in ['F', 'N', 'X', 'K']:
            # But only if not already marked :)
            if not ':doc:' in details:
                details = '``%s``' % (details)

The only reason why this patch is needed is for the header part, which
describes that "**" is allowed. If you look at the final code, this
replace code will be only at the header parsing logic:

    def parse_descriptions(self, line):
        """Handle contents of the descriptions section."""

    ...
        # Escape the escapes in preformatted text.
        line = self.linkify(line).replace("\\", "\\\\").replace("**", "\\**")
        self.header += "| " + line

> > 
> > 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.  
> 
> Please stop trying to format MAINTAINERS into rst.
> It shouldn't be formatted.
> It's simple text.

MAINTAINERS is not a simple text. It is a machine-readable text
database.

Thanks,
Mauro