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

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

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