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

[Mauro Carvalho Chehab]

On Tue, 5 May 2026 07:57:25 +0200
Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> wrote:

> On Mon, 04 May 2026 20:19:50 -0700
> Joe Perches <joe@xxxxxxxxxxx> 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@xxxxxxxx](mailto: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'.  
> > []
> > > 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.

Heh, I read this too quickly: you're talking about the header descriptions
where we have:

    F: *Files* and directories wildcard patterns.
       A trailing slash includes all files and subdirectory files.
       F:   drivers/net/    all files in and below drivers/net
       F:   drivers/net/*   all files in drivers/net, but not below
       F:   */net/*     all files in "any top level directory"/net
       F:   fs/**/*foo*.c   all *foo*.c files in any subdirectory of fs

Yeah, you're right: the header parsing logic won't handle this well.
This should do the trick:

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

        # Have we reached the end of the preformatted Descriptions text?
        if line.startswith("Maintainers"):
            self.descriptions = False
            self.header += "\n" + line
            return

        # Look for and record field letter to field name mappings:
        #   R: Designated *reviewer*: FullName <address@domain>
        m = re.match(r"\s+(\S):\s+(\S+)", line)
        if m:
            field = m.group(1)
            details = m.group(2)

            if field not in self.fields:
                m = re.search(r"\*([^\*]+)\*", line)
                if m:
                    self.fields[field] = m.group(1)
            elif field in ['F', 'N', 'X', 'K']:
                line = line.replace(details, f'``{details}``')

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

I'll address it in v2.

Thanks,

Thanks,
Mauro