Merge tag 'docs-7.3' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux

Pull documentation updates from Jonathan Corbet:
 "It has been a not-too-busy cycle for docs; here's the highlights:

   - A (hopefully) consensus change to our LLM-attribution requirements,
     removing the specific model name from the Assisted-by tag

   - A couple of new realtime documents

   - Various docs-build-system fixes

   - Ongoing work with the Chinese, Portuguese, and Japanese
     translations

  ...and lots of typo fixes, grammar tweaks, etc"

* tag 'docs-7.3' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (85 commits)
  Doc: admin-guide: pm: Remove unnecessary backticks and fix a spell
  Documentation: Extend the real-time hardware bits with some firmware bits
  docs: pt_BR: Reorganize process/index.rst to follow english structure
  docs: conf.py: fix the 'utf-8' typo
  doc tools: fix 'path' typos
  Documentation: real-time: Add kernel configuration guide
  docs: python: abi_regex: convert adjacent index placeholders
  docs: python: abi_regex: catch the right exception for a bad regex
  docs: sphinx-build-wrapper: include localversion in kernel version string
  Documentation: html: adjust sidebar section titles styling
  Documentation: html: show sections in the sidebar
  checkpatch.pl: adapt to new Assisted-by: format
  MAINTAINERS: update Traditional Chinese documentation maintainers
  docs: pt_BR: process: Translate CVE documentation
  docs: pt_BR: translate the management-style.rst to Brazilian Portuguese
  docs: xforms_lists: support DEFINE_IDTENTRY_IRQ()
  coding-assistants: simplify attribution
  docs: translations: pt_BR: translate email-clients.rst
  docs: pt_BR: process: Translate the security-bugs.rst
  doc:it_IT: align doc-guide translation
  ...

6 files changed, 72 insertions, 15 deletions

diff --git a/tools/docs/documentation-file-ref-check b/tools/docs/documentation-file-ref-check
index 0cad42f6943b..93b53f3a5567 100755
--- a/tools/docs/documentation-file-ref-check
+++ b/tools/docs/documentation-file-ref-check
@@ -143,7 +143,7 @@ while (<IN>) {
 		# Check if exists, evaluating wildcards
 		next if (grep -e, glob("$ref $fulref"));
 
-		# Accept relative Documentation patches for tools/
+		# Accept relative Documentation paths for tools/
 		if ($f =~ m/tools/) {
 			my $path = $f;
 			$path =~ s,(.*)/.*,$1,;
diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 1bb962202784..6f1163333a47 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -99,9 +99,9 @@ class SphinxBuilder:
 
     def get_path(self, path, use_cwd=False, abs_path=False):
         """
-        Ancillary routine to handle patches the right way, as shell does.
+        Ancillary routine to handle paths the right way, as shell does.
 
-        It first expands "~" and "~user". Then, if patch is not absolute,
+        It first expands "~" and "~user". Then, if path is not absolute,
         join self.srctree. Finally, if requested, convert to abspath.
         """
 
@@ -220,6 +220,15 @@ class SphinxBuilder:
         self.pdflatex = os.environ.get("PDFLATEX", "xelatex")
 
         #
+        # Add localversion* to kernelversion if present
+        #
+        for file in glob(os.environ["srctree"] + "/localversion*"):
+            if not file.endswith(".orig"):
+                with open(file, 'r', encoding='utf-8') as f:
+                    text = f.read()
+                    self.kernelversion += text
+
+        #
         # Kernel main Makefile defines a PYTHON3 variable whose default is
         # "python3". When set to a different value, it allows running a
         # diferent version than the default official python3 package.
diff --git a/tools/lib/python/abi/abi_regex.py b/tools/lib/python/abi/abi_regex.py
index d0c5e3ede6b5..198ecbf49c51 100644
--- a/tools/lib/python/abi/abi_regex.py
+++ b/tools/lib/python/abi/abi_regex.py
@@ -65,8 +65,7 @@ class AbiRegex(AbiParser):
         (re.compile(r"\[[^\]]+\]"), "\\\\w\xf7"),
 
         (re.compile(r"XX+"), "\\\\w\xf7"),
-        (re.compile(r"([^A-Z])[XYZ]([^A-Z])"), "\\1\\\\w\xf7\\2"),
-        (re.compile(r"([^A-Z])[XYZ]$"), "\\1\\\\w\xf7"),
+        (re.compile(r"(?<![A-Z])[XYZ](?![A-Z])"), "\\\\w\xf7"),
         (re.compile(r"_[AB]_"), "_\\\\w\xf7_"),
 
         # Recover [0-9] type of patterns
@@ -155,7 +154,7 @@ class AbiRegex(AbiParser):
             if self.search_string:
                 if what.find(self.search_string) >= 0:
                     print(f"What: {what}")
-        except re.PatternError:
+        except re.error:
             self.log.warning("Ignoring '%s' as it produced an invalid regex:\n"
                              "           '%s'", what, new)
 
@@ -194,7 +193,7 @@ class AbiRegex(AbiParser):
 
                 try:
                     self.re_string = re.compile(self.search_string)
-                except re.PatternError as e:
+                except re.error as e:
                     msg = f"{self.search_string} is not a valid regular expression"
                     raise ValueError(msg) from e
 
@@ -223,9 +222,9 @@ class AbiRegex(AbiParser):
                 for r, s in self.re_whats:
                     try:
                         new = r.sub(s, new)
-                    except re.PatternError as e:
+                    except re.error as e:
                         # Help debugging troubles with new regexes
-                        raise re.PatternError(f"{e}\nwhile re.sub('{r.pattern}', {s}, str)") from e
+                        raise re.error(f"{e}\nwhile re.sub('{r.pattern}', {s}, str)") from e
 
                 v["regex"].append(new)
 
diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/kdoc_output.py
index de107ab4a281..618b0d765ef5 100644
--- a/tools/lib/python/kdoc/kdoc_output.py
+++ b/tools/lib/python/kdoc/kdoc_output.py
@@ -624,7 +624,7 @@ class ManFormat(OutputFormat):
     ``manual``
         Defaults to ``Kernel API Manual``.
 
-    The above controls the output of teh corresponding fields on troff
+    The above controls the output of the corresponding fields on troff
     title headers, which will be filled like this::
 
         .TH "{name}" {section} "{date}" "{modulename}" "{manual}"
diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index 2dedda215c22..d9ad1ddc87dd 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -11,6 +11,7 @@ and extract embedded documentation comments from it.
 
 import sys
 import re
+import difflib
 from pprint import pformat
 
 from kdoc.c_lex import CTokenizer, tokenizer_set_log
@@ -558,6 +559,51 @@ class KernelDoc:
                         self.push_parameter(ln, decl_type, param, dtype,
                                             arg, declaration_name)
 
+    def get_suggestions_hint(self, decl_name, possible_names):
+        # For decl name 'flags' or 'flgas', suggests 'substruct.flags'
+        submember_exact = []
+        submember_substrings = []
+        submember_suggestions = []
+        for possible_name in possible_names:
+            parts = possible_name.strip().split('.')
+            if len(parts) < 2:
+                continue
+
+            final_part = parts[-1]
+            if decl_name == final_part:
+                submember_exact.append(possible_name)
+            elif decl_name in final_part:
+                submember_substrings.append(possible_name)
+            elif difflib.get_close_matches(decl_name, [final_part]):
+                submember_suggestions.append(possible_name)
+
+        # For decl name 'flgas', suggests 'flags'
+        full_suggestions = difflib.get_close_matches(decl_name, possible_names)
+
+        # For decl name 'member', suggests 'longer_member'
+        full_substrings = [name for name in possible_names if decl_name in name]
+
+        ordered_lists = [
+            submember_exact,
+            submember_substrings,
+            submember_suggestions,
+            full_suggestions,
+            full_substrings,
+        ]
+
+        # Deduplicate but maintain order from most to least likely:
+        unique_suggestions = {}
+        for suggestion_list in ordered_lists:
+            for suggestion in suggestion_list:
+                unique_suggestions[suggestion] = None
+
+        suggestions = list(unique_suggestions.keys())
+        if not suggestions:
+            return ""
+
+        joined_suggestions = "', '".join(suggestions)
+        return f"(did you mean one of: '{joined_suggestions}')"
+
     def check_sections(self, ln, decl_name, decl_type):
         """
         Check for errors inside sections, emitting warnings if not found
@@ -566,12 +612,13 @@ class KernelDoc:
         for section in self.entry.sections:
             if section not in self.entry.parameterlist and \
                not known_sections.search(section):
+                hint = self.get_suggestions_hint(section, self.entry.parameterlist)
                 if decl_type == 'function':
                     dname = f"{decl_type} parameter"
                 else:
                     dname = f"{decl_type} member"
                 self.emit_msg(ln,
-                              f"Excess {dname} '{section}' description in '{decl_name}'")
+                              f"Excess {dname} '{section}' description in '{decl_name}' {hint}".strip())
 
         #
         # Check that documented parameter names (from doc comments, including
@@ -591,12 +638,13 @@ class KernelDoc:
             if param_name in self.entry.parameterlist:
                 continue
 
+            hint = self.get_suggestions_hint(param_name, self.entry.parameterlist)
             if decl_type == 'function':
                 dname = f"{decl_type} parameter"
             else:
                 dname = f"{decl_type} member"
             self.emit_msg(ln,
-                          f"Excess {dname} '{param_name}' description in '{decl_name}'")
+                          f"Excess {dname} '{param_name}' description in '{decl_name}' {hint}".strip())
 
     def check_return_section(self, ln, declaration_name, return_type):
         """
@@ -791,7 +839,7 @@ class KernelDoc:
 
         if self.entry.identifier != declaration_name:
             self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. "
-                          f"Prototype was for {decl_type} {declaration_name} instead\n")
+                          f"Prototype was for {decl_type} {declaration_name} instead")
             return
         #
         # Go through the list of members applying all of our transformations.
@@ -1108,7 +1156,7 @@ class KernelDoc:
 
             if self.entry.identifier != declaration_name:
                 self.emit_msg(ln,
-                              f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
+                              f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead")
                 return
 
             self.create_parameter_list(ln, 'function', args, ',', declaration_name)
@@ -1128,7 +1176,7 @@ class KernelDoc:
 
             if self.entry.identifier != declaration_name:
                 self.emit_msg(ln,
-                              f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
+                              f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead")
                 return
 
             self.output_declaration('typedef', declaration_name,
diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
index 4251f7c6673a..e3dda2fe8a53 100644
--- a/tools/lib/python/kdoc/xforms_lists.py
+++ b/tools/lib/python/kdoc/xforms_lists.py
@@ -90,6 +90,7 @@ class CTransforms:
         (CMatch("__(?:re)?alloc_size"), ""),
         (CMatch("__diagnose_as"), ""),
         (CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"),
+        (CMatch("DEFINE_IDTENTRY_IRQ"), r"static void \1(struct pt_regs *regs, u32 vector)"),
         (CMatch("__cond_acquires"), ""),
         (CMatch("__cond_releases"), ""),
         (CMatch("__acquires"), ""),