Messages in this thread |  | | Date | Tue, 5 May 2026 07:57:25 +0200 | | From | Mauro Carvalho Chehab <> | | Subject | Re: [PATCH 2/9] docs: escape ** glob pattern in MAINTAINERS descriptions |
| |
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
|  |