[PATCH 31/38] docs: kdoc_re: Fix NestedMatch.sub() which causes PDF builds to break

Mauro Carvalho Chehab
2026-02-18T10:13:30Z

Having a "\digit" inside a docstring with normal strings causes
PDF output to break, as it will add a weird character inside the
string. It should be using a raw string instead.

Yet, having r"\0" won't solve, as this would be converted in
Sphinx as "0". So, this has to be inside a pre formatted text.

That's said, the comment itself is probably not the best one.

Rewrite the entire comment to properly document each parameter
and add a "delim" parameter that will be passed to the
ancillary function.

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 | 30 ++++++++++++++++++------------
1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_re.py
index 44af43aa1e93..f67ebe86c458 100644
--- a/tools/lib/python/kdoc/kdoc_re.py
+++ b/tools/lib/python/kdoc/kdoc_re.py
@@ -323,22 +323,28 @@ class NestedMatch:

return args

- def sub(self, sub, line, count=0):
- """
- This is similar to re.sub:
+ def sub(self, sub, line, delim=",", count=0):
+ r"""
+ Perform a regex‑based replacement on ``line`` for all matches with
+ the ``self.regex`` pattern. It uses the following parameters:

- It matches a regex that it is followed by a delimiter,
- replacing occurrences only if all delimiters are paired.
+ ``sub``
+ Replacement string that may contain placeholders in the form
+ ``\{digit}``, where ``digit`` is an integer referring to the regex
+ capture group number.

- if the sub argument contains::
+ ``\{0}`` is a special case that expands to the entire matched text.

- r'\0'
+ ``line``
+ The string to operate on.

- it will work just like re: it places there the matched paired data
- with the delimiter stripped.
+ ``delim``
+ The delimiter used by identify the placeholder groups
+ (defaults to ",").

- If count is different than zero, it will replace at most count
- items.
+ ``count``
+ Maximum number of replacements per match. If 0 or omitted,
+ all matches are replaced.
"""
out = ""

@@ -358,7 +364,7 @@ class NestedMatch:
# replace arguments
new_sub = sub
if "\\" in sub:
- args = self._split_args(value)
+ args = self._split_args(value, delim=delim)

new_sub = re.sub(r'\\(\d+)',
lambda m: args[int(m.group(1))], new_sub)
--
2.52.0