[PATCH] docs: kdoc: Fix pdfdocs build for tools

[PATCH] docs: kdoc: Fix pdfdocs build for tools

[Mauro Carvalho Chehab]

the "\1" inside a docstring requires proper scaping to not be
considered a hex character and break the build.

Reported-by: Akira Yokosawa <akiyks@gmail.com>
Closes: https://lore.kernel.org/linux-doc/63e99049-cc72-4156-83af-414fdde34312@gmail.com/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/lib/python/kdoc/kdoc_re.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_re.py
index 2816bd9f90f8..dae5a9136fbf 100644
--- a/tools/lib/python/kdoc/kdoc_re.py
+++ b/tools/lib/python/kdoc/kdoc_re.py
@@ -228,7 +228,7 @@ class NestedMatch:
             yield line[t[0]:t[2]]
 
     def sub(self, regex, sub, line, count=0):
-        """
+        r"""
         This is similar to re.sub:
 
         It matches a regex that it is followed by a delimiter,
-- 
2.52.0

Re: [PATCH] docs: kdoc: Fix pdfdocs build for tools

[Akira Yokosawa]

On Sat, 24 Jan 2026 06:48:41 +0100, Mauro Carvalho Chehab wrote:
> the "\1" inside a docstring requires proper scaping to not be
> considered a hex character and break the build.
> 
> Reported-by: Akira Yokosawa <akiyks@gmail.com>
> Closes: https://lore.kernel.org/linux-doc/63e99049-cc72-4156-83af-414fdde34312@gmail.com/

This doesn't look like working as expected.

I see:

    if r’1’ is used ...

in both the HTML and PDF outputs.  I think what you expect is:

    if r’\1’ is used ...

> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  tools/lib/python/kdoc/kdoc_re.py | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_re.py
> index 2816bd9f90f8..dae5a9136fbf 100644
> --- a/tools/lib/python/kdoc/kdoc_re.py
> +++ b/tools/lib/python/kdoc/kdoc_re.py
> @@ -228,7 +228,7 @@ class NestedMatch:
>              yield line[t[0]:t[2]]
>  
>      def sub(self, regex, sub, line, count=0):
> -        """
> +        r"""
>          This is similar to re.sub:
>  
>          It matches a regex that it is followed by a delimiter,

To get the expected "\1", I guess you also need:

@@ -234,7 +234,7 @@ class NestedMatch:
         It matches a regex that it is followed by a delimiter,
         replacing occurrences only if all delimiters are paired.
 
-        if r'\1' is used, it works just like re: it places there the
+        if r'\\1' is used, it works just like re: it places there the
         matched paired data with the delimiter stripped.
 
         If count is different than zero, it will replace at most count

as well.  No?

Thanks, Akira

Re: [PATCH] docs: kdoc: Fix pdfdocs build for tools

[Mauro Carvalho Chehab]

On Sat, 24 Jan 2026 15:56:46 +0900
Akira Yokosawa <akiyks@gmail.com> wrote:

> On Sat, 24 Jan 2026 06:48:41 +0100, Mauro Carvalho Chehab wrote:
> > the "\1" inside a docstring requires proper scaping to not be
> > considered a hex character and break the build.
> > 
> > Reported-by: Akira Yokosawa <akiyks@gmail.com>
> > Closes: https://lore.kernel.org/linux-doc/63e99049-cc72-4156-83af-414fdde34312@gmail.com/  
> 
> This doesn't look like working as expected.
> 
> I see:
> 
>     if r’1’ is used ...
> 
> in both the HTML and PDF outputs.  I think what you expect is:
> 
>     if r’\1’ is used ...
> 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  tools/lib/python/kdoc/kdoc_re.py | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_re.py
> > index 2816bd9f90f8..dae5a9136fbf 100644
> > --- a/tools/lib/python/kdoc/kdoc_re.py
> > +++ b/tools/lib/python/kdoc/kdoc_re.py
> > @@ -228,7 +228,7 @@ class NestedMatch:
> >              yield line[t[0]:t[2]]
> >  
> >      def sub(self, regex, sub, line, count=0):
> > -        """
> > +        r"""
> >          This is similar to re.sub:
> >  
> >          It matches a regex that it is followed by a delimiter,  
> 
> To get the expected "\1", I guess you also need:
> 
> @@ -234,7 +234,7 @@ class NestedMatch:
>          It matches a regex that it is followed by a delimiter,
>          replacing occurrences only if all delimiters are paired.
>  
> -        if r'\1' is used, it works just like re: it places there the
> +        if r'\\1' is used, it works just like re: it places there the
>          matched paired data with the delimiter stripped.
>  
>          If count is different than zero, it will replace at most count
> 
> as well.  No?

True, but this makes it harder for people reading the code to understand 
what it means. I wish Python regex would support "$1" also
as a replacement for "\1" like Perl, but it doesn't.

Sent a v2 using a code-block instead.


Thanks,
Mauro