From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 7D23E340280; Fri, 6 Mar 2026 15:45:58 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811958; cv=none; b=n43gjYcV5kc0M+00AhrDN33V6YfTJfpLpUIYigkbWvButsSbwJe3UJYWJKkhp2wBR05KrFH5T7HslfJb7cb6T9k74QnHbeMIxRsneNy7ResezslnIOEJFcn13ftidFcXb+gz4ZnAX8l2xWUSOUGkGi5ya8Z4Gxr6vDxBPiRbj7U= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811958; c=relaxed/simple; bh=J9gpBcUhWSmksHEje7HfFrvd/UJKiZjrUhxoxqAfK3o=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Hj1LNOmxE73oDY2Z3p4oyZy2BLSMYBBDc5ueju3+OgkjqXYDg2xzbJk/1gja9+p7iZ9Bclg8CIAO5mOaj8UphGknXk4cUni9691Ydup2l4QeGrYCKtU7lNHn0+WroQgDhCYIc8xL2K0tVAOw2aPEGxAlrY/KPD/OlFu7AaJf0gw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=N3y5g81e; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="N3y5g81e" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1A3DAC2BC86; Fri, 6 Mar 2026 15:45:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811958; bh=J9gpBcUhWSmksHEje7HfFrvd/UJKiZjrUhxoxqAfK3o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=N3y5g81e1jsc3Uqa9XffGD09QB7MIV3zIenkNspouvd1ZBDzKzuYuT24EsLbsrfiB hp1xSRv8Qnzo/8MS90zqN/GqDfkDufzYrcYjpVWtas/c+/wFJyvwER1+TWBqYGeira IBHmMVX76sUfT5je/Z09o+mbgWOqWxJuCErQH8MiGrGpFTH/gegmcxzsLNasqtC0+H ZZkC83wNDVSB7lNZ4UdJ9qPVb6b5QAg8caN3rw96HbMHkdIPeQ60dBa004yCSKcS5u Yae82qXyRmF7pgxGaNajZ/8GcEeTDx+Xe+dcq6G+4mm7mbkyHstcSY6gJNx15jyvYZ 7l2qGs9taSKcw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNE-00000007EW8-0myE; Fri, 06 Mar 2026 16:45:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH v2 01/13] docs: sphinx-build-wrapper: better handle troff .TH markups Date: Fri, 6 Mar 2026 16:45:39 +0100 Message-ID: <9436806316d33aaf68625c00ce068463d3917660.1772810752.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Using a regular expression to match .TH is problematic, as it doesn't handle well quotation marks. Use shlex instead. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/sphinx-build-wrapper | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index b7c149dff06b..e6418e22e2ff 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -576,7 +576,6 @@ class SphinxBuilder: """ =20 re_kernel_doc =3D re.compile(r"^\.\.\s+kernel-doc::\s*(\S+)") - re_man =3D re.compile(r'^\.TH "[^"]*" (\d+) "([^"]*)"') =20 if docs_dir =3D=3D src_dir: # @@ -616,8 +615,7 @@ class SphinxBuilder: fp =3D None try: for line in result.stdout.split("\n"): - match =3D re_man.match(line) - if not match: + if not line.startswith(".TH"): if fp: fp.write(line + '\n') continue @@ -625,7 +623,9 @@ class SphinxBuilder: if fp: fp.close() =20 - fname =3D f"{output_dir}/{match.group(2)}.{match.group(1)}" + # Use shlex here, as it handles well parameters with commas + args =3D shlex.split(line) + fname =3D f"{output_dir}/{args[3]}.{args[2]}" =20 if self.verbose: print(f"Creating {fname}") --=20 2.52.0 From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 9451E7FBAC; Fri, 6 Mar 2026 15:45:58 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811958; cv=none; b=BA7uSILwAi4kAxQuFZ9gMFbt11JURFW0DI42TgtAL38zewA2N+pl+a3r1yQZ6ijNGeEupi8QBjgxk7zXgKaEr7OoxlY9twJj/0/c6ImG+E4fTm9WyCEtEHvDejvzdR6YRVknVLNs9HnMnH+/vN+mslNGoizpydbcMfeNEHTstso= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811958; c=relaxed/simple; bh=btvMeOMee755n720r21IH04ZmlM8pztBlnW5wyMsB0k=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=GE31MOYoIQ+dO/MbfhQyve+KXuXk9OW9UdSGFpP2kc8+gapy9eVVtAndoJvrTjhFK69GTrnMe/l+bsfvUY2evkbJQMy5gNN9SnhquZ+8nOz6lP5WjBFo2Mp3wOWk7r2/eMt0Y4k/orxzFXo68hFdRjIhqefYMo93hoXcCpS6G5E= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Iq6uElCi; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="Iq6uElCi" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 45D71C2BC87; Fri, 6 Mar 2026 15:45:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811958; bh=btvMeOMee755n720r21IH04ZmlM8pztBlnW5wyMsB0k=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Iq6uElCiwwArigPnQoNbWCPdyoc65aymmL5pu8nchbIMFZBxZSaTjjFEZWTalm3wk mxpimZEJjL2V79XSLoTPpluxHh4o4dQ48dqfpWByRtH0M5X89kVDWzvdnw7fqJI/r5 h6FIB0F0faRBLZole36FvuxaabYWDDaeJFQ8s5CkxrjbM7lL1xjgwLF4DlFawHphxV pSTRoRoaAl40HEoQAkI4rGIhelN23Yyx/T7HKyylgP5AGgQYZ/z1ZdpqfaUbwFCfrJ jl/a3rnUFt5cfdByR3ZVPx6LScocm3iwVPgqtvJxYLloSWCCRzcUsNcKA1c2L6tvEW oYZs1ebGV7Z7w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNE-00000007EXL-1asH; Fri, 06 Mar 2026 16:45:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH v2 02/13] docs: sphinx-build-wrapper: don't allow "/" on file names Date: Fri, 6 Mar 2026 16:45:40 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab When handling "DOC:" sections, slash characters may be there. Prevent using it at the file names, as this is used for directory separator. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/sphinx-build-wrapper | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index e6418e22e2ff..d3f0dba13da1 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -625,7 +625,9 @@ class SphinxBuilder: =20 # Use shlex here, as it handles well parameters with commas args =3D shlex.split(line) - fname =3D f"{output_dir}/{args[3]}.{args[2]}" + fname =3D f"{args[3]}.{args[2]}" + fname =3D fname.replace("/", " ") + fname =3D f"{output_dir}/{fname}" =20 if self.verbose: print(f"Creating {fname}") --=20 2.52.0 From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C8E3F36C5BA; Fri, 6 Mar 2026 15:45:58 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811958; cv=none; b=YnM0zMkYJ7Z/BfBJoG0ZhiyvP95Kj+k4zLEZ/iycnjIGZIlMxOFQICYvbo7PzUS+jI6JhOH/LecSUVxX6fU/mgpwdULIQwT3HsblY8rFlazB5GBAUEQNQX704Rx3QMLDGzlj0q2mLPyfm/VOCth2RMpkgSC1ByGgnY/IzTZlCyk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811958; c=relaxed/simple; bh=XMzNqgRp0gmQJyWaL/t7SqMf5vJ/1MBUlDjM38i47fA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=OhGru5untn5wzUG71pXXJaamilhU5TKkEQv0N6j0x5h5PQDNjaM0s315moVe4Swj4+1eg4n+mGNbwP3ccwyXJAWpl6U0/wRq1uni/VXzm94y3lVAAUplXIBNDBf/imxQ2IleaJ8ug0RxuhAb3u6Bt8lKLIYGGlpDAOQcMaCikRc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Pe8tqRYx; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="Pe8tqRYx" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 74848C2BCAF; Fri, 6 Mar 2026 15:45:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811958; bh=XMzNqgRp0gmQJyWaL/t7SqMf5vJ/1MBUlDjM38i47fA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Pe8tqRYxiLf2hf+HD72SZUIrHGMcAGb1NRvdmmIpY35XeyUge5tikhhaZ7myFI48s 71zmALJqa/iBjpWKYk7edtleloxz1E5L7l/3zC7EoQAZR3g+BDEXfZVBjeinc3QT+N LlZjwEt8HrRi/t5YxEROao3MADkanvDCILNRTArWALdiAkc/mTpIez/Xhoe9/GuJFV pYsrSuCueTZPTOLzS7hExcZZLq+qJ/6KvEYUmlxBMExSpbuBsRjgPGcwbHZLCgkmTI OOtEat2qzW7wLi8fUsmTfMPaEFQYqmBrdgDoej7I41v/28Gcj2iSxv8Y2sCmGAIkSj 6st1GCbY9tT5w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNE-00000007EYt-2OV5; Fri, 06 Mar 2026 16:45:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH v2 03/13] docs: kdoc_output: use a method to emit the .TH header Date: Fri, 6 Mar 2026 16:45:41 +0100 Message-ID: <2e55fcfe8724fde08a78635a1a3f8b449a6adf82.1772810752.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab All man emit functions need to add a .TH header. Move the code to a common function, as we'll be addressing some issues at the common code. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 34 +++++++++++++++++++++------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 4210b91dde5f..fb6b90c54c8a 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -607,7 +607,20 @@ class ManFormat(OutputFormat): "%m %d %Y", ] =20 - def __init__(self, modulename): + def emit_th(self, name, modulename =3D None, manual=3DNone): + """Emit a title header line.""" + name =3D name.strip() + + if not manual: + manual =3D self.manual + + if not modulename: + modulename =3D self.modulename + + self.data +=3D f'.TH "{modulename}" {self.section} "{name}" ' + self.data +=3D f'"{self.date}" "{manual}" LINUX\n' + + def __init__(self, modulename, section=3D"9", manual=3D"API Manual"): """ Creates class variables. =20 @@ -616,7 +629,11 @@ class ManFormat(OutputFormat): """ =20 super().__init__() + self.modulename =3D modulename + self.section =3D section + self.manual =3D manual + self.symbols =3D [] =20 dt =3D None @@ -632,7 +649,7 @@ class ManFormat(OutputFormat): if not dt: dt =3D datetime.now() =20 - self.man_date =3D dt.strftime("%B %Y") + self.date =3D dt.strftime("%B %Y") =20 def arg_name(self, args, name): """ @@ -724,7 +741,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{self.modulename}" 9 "{out_name}" "{self.man= _date}" "API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" @@ -734,7 +751,8 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{name}" 9 "{out_name}" "{self.man_date}" "Ke= rnel Hacker\'s Manual" LINUX' + "\n" + self.emit_th(out_name, modulename =3D name, + manual=3D"Kernel Hacker\'s Manual") =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" @@ -780,7 +798,7 @@ class ManFormat(OutputFormat): def out_enum(self, fname, name, args): out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{self.modulename}" 9 "{out_name}" "{self.man= _date}" "API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"enum {name} \\- {args['purpose']}\n" @@ -813,7 +831,7 @@ class ManFormat(OutputFormat): out_name =3D self.arg_name(args, name) full_proto =3D args.other_stuff["full_proto"] =20 - self.data +=3D f'.TH "{self.modulename}" 9 "{out_name}" "{self.man= _date}" "API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" @@ -834,7 +852,7 @@ class ManFormat(OutputFormat): purpose =3D args.get('purpose') out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{module}" 9 "{out_name}" "{self.man_date}" "= API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"typedef {name} \\- {purpose}\n" @@ -849,7 +867,7 @@ class ManFormat(OutputFormat): definition =3D args.get('definition') out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{module}" 9 "{out_name}" "{self.man_date}" "= API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{args.type} {name} \\- {purpose}\n" --=20 2.52.0 From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D022436C9CF; Fri, 6 Mar 2026 15:45:58 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811958; cv=none; b=sPBIdRx0FD6j1k+wTLvx2AiA/bNHRdJm0BKwXs0aPk8o3cVwfPdYznoDglmEOxPLw9Kp0Iu3gmpxLRjMwwn30UQHTVJtN1tqGBjDN0bXJI08/r/IZSIh2osllfgESJ41SmloWuU6OBcHUrUMmUBdISmUkB9+auQpy7ODyplQ19s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811958; c=relaxed/simple; bh=GGvISdxmwoIbUjL//ZMtEtb0uZ7eg3KSR627MLJtNjo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=pb6SG9jVnz6lPjaP9yL0Du4+1Di3xRi2jLm9g2mE0QCzS8pJ21Ev+EsZul3ohP2nsHP59GPSotNU8J3UxoG3hb/dgMe+uHS1WsGwS8lPlX1hJHSAEk6uxWhB046z5XIz7U+Xh5AQNwkkm3pXp/tnGzalgrr6VNj70yBzxBzn8sE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=thgle8ID; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="thgle8ID" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 884B3C2BC9E; Fri, 6 Mar 2026 15:45:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811958; bh=GGvISdxmwoIbUjL//ZMtEtb0uZ7eg3KSR627MLJtNjo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=thgle8IDs8eLTweVjd/CHfBo48sdr0+OVMkeAf3oejNXr1Nlj0EXvJPdDOXKvGjUZ /tpcuFQrE+YVIDnfDdvC2FgiAK6QLxnb71w11gkXZCF4+SayDTFHT5IucgYvq4OlHe 6Jh2N2Po5d1YgV/LI85O5kjyjzoRtGmfrZMBMUi1mXKA68m0c2ez1hCqWKDsUuuTul qHGoGcbX0l1px04MfsjtI16tEf0r8fnE4d+CoPSy83js/tX2je7oGlNEnGwONt7ALu npERXFSQCc4M6q9Apo4Xhca9l7ON9xmLuuLNPOXwDSsvCjWAww104rjVdaTI69BVPq cXOO67POWS03Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNE-00000007Ea6-3C5Y; Fri, 06 Mar 2026 16:45:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH v2 04/13] docs: kdoc_output: remove extra attribute on man .TH headers Date: Fri, 6 Mar 2026 16:45:42 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab According with modern documents, groff .TH supports up to 5 arguments, but the logic passes 6. Drop the lastest one ("LINUX"). Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index fb6b90c54c8a..d0b237c09391 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -618,7 +618,7 @@ class ManFormat(OutputFormat): modulename =3D self.modulename =20 self.data +=3D f'.TH "{modulename}" {self.section} "{name}" ' - self.data +=3D f'"{self.date}" "{manual}" LINUX\n' + self.data +=3D f'"{self.date}" "{manual}"\n' =20 def __init__(self, modulename, section=3D"9", manual=3D"API Manual"): """ --=20 2.52.0 From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 598C63EBF0B; Fri, 6 Mar 2026 15:45:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811959; cv=none; b=Afxq/u0KyBZyYuKwQ2hssKryeUkartBvuzw+f2f2MQOKxWs6rbE58hWnHFM5hm6xxdWd1scx7W4zclyPAoysMbtfhaHLdGdL7QqsAM+sTbxLf22o80vp/UfI2lM3Hn9wcTixDsb4xDf7yI20Iq1QM3LYWRjhgLoIg0h+w8p7KeM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811959; c=relaxed/simple; bh=KClTBbHYRg20aly7xZCzAagKb8bY1y4ys0T0TfWzZRI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=qt5IkPwGYxuGPXcuHpyxsfdeqFACprmd2EuNo6L1Ts6INH5TMzjxWxTQvBuQ9A44VhbthVcyis0mt9RjeTU+gZWRcI8VWuxwwu4HTnWUIXuKwQ2Wi4rqicB+eiZdIPc2I741EyvH6fhCvZo2kuKxNPYOhYsj43mkMO+2aQ5yIiE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=TxwwWYeW; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="TxwwWYeW" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D4DF4C4CEF7; Fri, 6 Mar 2026 15:45:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811958; bh=KClTBbHYRg20aly7xZCzAagKb8bY1y4ys0T0TfWzZRI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=TxwwWYeWSLdsBGvSisythSmKV4XXhG0fpeQJxiazqjv/I9JpKb9/0KqUPopv6uqYM dnSGxzDsfAPY2t/AOobTf9XlC1jbHFqAXWkTgbONEu8IiD9rzo0n8tafvA8hcZRHMb Sc22X2xzVnMdANf5/q1LHNOXW4ObOtMCuGSL0TUwqk+XlrrWv6dZOQHXYspNeEaaxT U7/555AW/IAHFQIemY8/ImPzHBNpUkHTVpWE92ZOLMpjZKT98pR0QPI+PjQxKEgAzT +T2hekj4wbNVQNO0dY1QKOUceW1Nhfo/XxGtg6GrDaXJDANNB1/r3icu6doHBxwGqw NnptqV8WIZJug== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNE-00000007EbL-422w; Fri, 06 Mar 2026 16:45:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH v2 05/13] docs: kdoc_output: use a single manual for everything Date: Fri, 6 Mar 2026 16:45:43 +0100 Message-ID: <000e1174a551e97ad4710ad4f3750b22017bedd5.1772810752.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab There's no reason why functions will be on a different manual. Unify its name, calling it as "Kernel API Manual". Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index d0b237c09391..24ee1fad681e 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -607,20 +607,17 @@ class ManFormat(OutputFormat): "%m %d %Y", ] =20 - def emit_th(self, name, modulename =3D None, manual=3DNone): + def emit_th(self, name, modulename =3D None): """Emit a title header line.""" name =3D name.strip() =20 - if not manual: - manual =3D self.manual - if not modulename: modulename =3D self.modulename =20 self.data +=3D f'.TH "{modulename}" {self.section} "{name}" ' - self.data +=3D f'"{self.date}" "{manual}"\n' + self.data +=3D f'"{self.date}" "{self.manual}"\n' =20 - def __init__(self, modulename, section=3D"9", manual=3D"API Manual"): + def __init__(self, modulename, section=3D"9", manual=3D"Kernel API Man= ual"): """ Creates class variables. =20 @@ -751,8 +748,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name, modulename =3D name, - manual=3D"Kernel Hacker\'s Manual") + self.emit_th(out_name, modulename =3D name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" --=20 2.52.0 From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 599C33EBF14; Fri, 6 Mar 2026 15:45:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811959; cv=none; b=Pr+1T6afhrsuiat1Ox4OBPFqTNvIMmDMm2C4xV61SocyFzUECovWzimO3kPYwjUNOYE6tmKDNRnYitbNeUhrJwhiYN1/dul9ZBGXzMXyH5T3lebIL8Xbryj7AZVoXoJ1mIOeaIWsh6a5qfw9IQ2nx283c+V7JPjTNV4yvDfM1Rk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811959; c=relaxed/simple; bh=P85ihOR34EEBJ4aigkm1P5PoviijGjWWN5/y18JiWZo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=mlIYN5QB2ToIxyQCmaDK6/XpCj4/AWuA1+1bmw6tbNqB//FalNU4OyriemRs5US5e5wXqt+24cS3prUG5PbgXDEjKnSiI3XuhmxkE5nNttTyUDimsCJycFT7F/1mIj2r5fLj8UpapKYJw21kC/yZWlioWo0HCQBwN5IOj0e0i4U= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ljwJXY5D; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="ljwJXY5D" Received: by smtp.kernel.org (Postfix) with ESMTPSA id E0AECC2BC86; Fri, 6 Mar 2026 15:45:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811958; bh=P85ihOR34EEBJ4aigkm1P5PoviijGjWWN5/y18JiWZo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ljwJXY5DGeXwmepUd5oP5BZDV1PGY5fw/Bs8B8tzxG+ddAvW0xpgc0wPcTUnOjzSN IyQynFXPnO4fN0drHYLOwidE9KjQRXst21BUZcOgEhB+gY1Lzt0SJh6E+Pb3UNdoGp NS9EFBFqZSsLZhALRwitx2f0ugBZXw5IzMVN2yianiueq5PMv8QPmxjZfzCVO3803R pNuic2aJPa/IZcBydngE5wEBqT5O1FXRDmO1CcvVNWs1E3e4yIGfYsu2SEC+vYZI+v Ka1HWxps5j8hjKmcyfDPUVcI+fFrbY0ThxmX2xRPhmPl5yPetsRIDY0LEC6iJtf0Rl 9qqZB+a6abO6Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNF-00000007Eca-0d94; Fri, 06 Mar 2026 16:45:57 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH v2 06/13] docs: kdoc_output: don't use a different modulename for functions Date: Fri, 6 Mar 2026 16:45:44 +0100 Message-ID: <978259bdf3e8d310c646ecf76ce56d054f6d5738.1772810752.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab It doesn't make much sense to have a different modulename just for functions, but not for structs/enums/... Use the same header everywere. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 24ee1fad681e..62e300e65405 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -607,14 +607,11 @@ class ManFormat(OutputFormat): "%m %d %Y", ] =20 - def emit_th(self, name, modulename =3D None): + def emit_th(self, name): """Emit a title header line.""" name =3D name.strip() =20 - if not modulename: - modulename =3D self.modulename - - self.data +=3D f'.TH "{modulename}" {self.section} "{name}" ' + self.data +=3D f'.TH "{self.modulename}" {self.section} "{name}" ' self.data +=3D f'"{self.date}" "{self.manual}"\n' =20 def __init__(self, modulename, section=3D"9", manual=3D"Kernel API Man= ual"): @@ -748,7 +745,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name, modulename =3D name) + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" --=20 2.52.0 From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 6C6BC3EBF28; Fri, 6 Mar 2026 15:45:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811959; cv=none; b=dWh0+UbQD9EWc8EEZxebw5qLgamuntvCjQDCiBPdVOhhGuVqPnqO1mxBP9W4q0eYm+jGgY6KsdLY6XB0eltmLeEDb4aGw7HhPU0nQ0a0oPn3AhqYQK+a+kW4Fs8fc+iSBCWfHVa5JoVi4ceBQTWly0Z1DywmohrejrSZiaV3c4E= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811959; c=relaxed/simple; bh=aKvP29cXF0GJiPOdswGAUP5rFW3a8a2+GzBPBrAzC1g=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=cF7Xv/Dp2EHBT5G3f3CZT86kOWn46XazMXIPLa9oCLLjSk+2OnwX/+oDb4ZjcZB8RdxTQkJRIh2tROIDa3NSci3zO8SVYqaagSjyXb9qSwjE1ZobzRFKx2YjvFa31tEr72V9ilechIiuUef2s1622k+XalFpfs/BAgW5Ie5t1jI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=YUC+NM1y; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="YUC+NM1y" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 174CAC2BC9E; Fri, 6 Mar 2026 15:45:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811959; bh=aKvP29cXF0GJiPOdswGAUP5rFW3a8a2+GzBPBrAzC1g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YUC+NM1yp4roEYOexFeWOtB2/0rAlaI0f3tOIX9PpTCaxD9K4yyFKKY7be7uYY0X/ JDTYjr2gnbFYg0G9h0uQ4fnd4KcGvUt46L/2xxS0Ay8wg8E6QBEBbBjsIUmUJheeqm VS/E4ZgZ9ybwmyuR6r3Tb+c/UwV64FkKUeA4qlPW5aOoLVFOVttYkfdaexaUZvW8Pl eIS3IsmDQ/BgL9zJnS2ueTvNSLsSBRz3LASFF1DJ5GNoGFbza7mM2WzX8Bd5khieIc bETUlls+RDuapzGBwqUA1GsqIi7A7+vVley/Dc3S86B/YHN92hVi9VI9rC+mQapmKF g1Ag1Fw4E1ssg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNF-00000007Edn-1RF1; Fri, 06 Mar 2026 16:45:57 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Shuah Khan Subject: [PATCH v2 07/13] docs: kdoc_output: fix naming for DOC markups Date: Fri, 6 Mar 2026 16:45:45 +0100 Message-ID: <11d809e5c4bec23240d3ace3f342dbb2a9263446.1772810752.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Right now, DOC markups aren't being handled properly, as it was using the same name for all output. Fix it by filling the title argument on a different way. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/sphinx-build-wrapper | 2 +- tools/lib/python/kdoc/kdoc_output.py | 38 +++++++++++++++++----------- 2 files changed, 24 insertions(+), 16 deletions(-) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index d3f0dba13da1..2c63d28f639d 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -625,7 +625,7 @@ class SphinxBuilder: =20 # Use shlex here, as it handles well parameters with commas args =3D shlex.split(line) - fname =3D f"{args[3]}.{args[2]}" + fname =3D f"{args[1]}.{args[2]}" fname =3D fname.replace("/", " ") fname =3D f"{output_dir}/{fname}" =20 diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 62e300e65405..cf834dbf2725 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -607,14 +607,21 @@ class ManFormat(OutputFormat): "%m %d %Y", ] =20 - def emit_th(self, name): + def modulename(self, args): + if self._modulename: + return self._modulename + + return os.path.dirname(args.fname) + + def emit_th(self, name, args): """Emit a title header line.""" - name =3D name.strip() + title =3D name.strip() + module =3D self.modulename(args) =20 - self.data +=3D f'.TH "{self.modulename}" {self.section} "{name}" ' - self.data +=3D f'"{self.date}" "{self.manual}"\n' + self.data +=3D f'.TH "{name}" {self.section} "{self.date}" ' + self.data +=3D f'"{self.modulename}" "{self.manual}"\n' =20 - def __init__(self, modulename, section=3D"9", manual=3D"Kernel API Man= ual"): + def __init__(self, modulename=3DNone, section=3D"9", manual=3D"Kernel = API Manual"): """ Creates class variables. =20 @@ -624,7 +631,7 @@ class ManFormat(OutputFormat): =20 super().__init__() =20 - self.modulename =3D modulename + self._modulename =3D modulename self.section =3D section self.manual =3D manual =20 @@ -658,7 +665,8 @@ class ManFormat(OutputFormat): dtype =3D args.type =20 if dtype =3D=3D "doc": - return self.modulename + return name +# return os.path.basename(self.modulename(args)) =20 if dtype in ["function", "typedef"]: return name @@ -735,7 +743,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" @@ -745,7 +753,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" @@ -791,7 +799,7 @@ class ManFormat(OutputFormat): def out_enum(self, fname, name, args): out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"enum {name} \\- {args['purpose']}\n" @@ -824,7 +832,7 @@ class ManFormat(OutputFormat): out_name =3D self.arg_name(args, name) full_proto =3D args.other_stuff["full_proto"] =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" @@ -841,11 +849,11 @@ class ManFormat(OutputFormat): self.output_highlight(text) =20 def out_typedef(self, fname, name, args): - module =3D self.modulename + module =3D self.modulename(args) purpose =3D args.get('purpose') out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"typedef {name} \\- {purpose}\n" @@ -855,12 +863,12 @@ class ManFormat(OutputFormat): self.output_highlight(text) =20 def out_struct(self, fname, name, args): - module =3D self.modulename + module =3D self.modulename(args) purpose =3D args.get('purpose') definition =3D args.get('definition') out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{args.type} {name} \\- {purpose}\n" --=20 2.52.0 From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id B26F13EBF38; Fri, 6 Mar 2026 15:45:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811959; cv=none; b=JHjcL9/pLfmoink+6x+SnqAAgZthd99rB3eXsVwidxkATzvfRZFOAXesHXDVh6H+GHOqXD4OEA5ODDgL6ST/AEOLC46vubfRzolHZVVyx3DBGkf5Gu3TjSsAuBBuGE+C26lRumXYMUNC9DRJRUUzc/g3NtYt5MUu01UP2qQ5a9A= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811959; c=relaxed/simple; bh=eIvW6vOTsydL4ttyaabmt7sLOOgqDZhdhKgwjQj87GA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=FmIE4zJg0N+pkDJvbjYQkBGCyRb3veAdlv5HpQNb2Dw6WOBuH/A9mBzbNp3c30lUzqqadUfr9ZxZrctsIRJJLeHmFUiIbfCLj/PkmamEP5Jnh9e+RwfbFAiVguEZDHIME/zBzHJfw/ZmLm9xVdbTqga61Lt9CSCLDP+XSVBbnjw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=CIE5diok; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="CIE5diok" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 479A9C2BC87; Fri, 6 Mar 2026 15:45:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811959; bh=eIvW6vOTsydL4ttyaabmt7sLOOgqDZhdhKgwjQj87GA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=CIE5diok0VnlYtuLDOnlqXnf97pQYgslTMUcN2P6k3tWeJnIhEF2ZwmCwiKuTC8sD SmCCKgop+5Y877jW/jy98AaOkCcDYpiz23B9bITCvt+89kN9TGSj7b88jJGb7+/xBE w2A+XwxNRxRR7rb79+UoBAlwTEq9UW1uvqAJdNZ7OQ70/btsiUxm6okdeFcSHIZLRG qFxRtAkjDy3nYmU6jwSVyQETIu9+TjIzvoYvnlIBbLkPoLmiNoHWKI/ukyMU+ZFIcE eDbTLVWSmTSBrhrIhKedGt1Alzi0SdcsiDTsBxrX+YjhQeMUeh62OwxOogb04Wz+GY hOZPLFK0rePHw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNF-00000007Ef0-2EeU; Fri, 06 Mar 2026 16:45:57 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH v2 08/13] docs: kdoc_output: describe the class init parameters Date: Fri, 6 Mar 2026 16:45:46 +0100 Message-ID: <7c57f26150aae11fced259f30898a980b96efb68.1772810752.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab As this class is part of the ABI used by both Sphinx kerneldoc extension and docs/tools/kernel-doc, better describe what parmeters are used to initialize ManOutput class. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 29 +++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index cf834dbf2725..7a181b40810d 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -580,7 +580,34 @@ class RestFormat(OutputFormat): =20 =20 class ManFormat(OutputFormat): - """Consts and functions used by man pages output.""" + """ + Consts and functions used by man pages output. + + This class has one mandatory parameter and some optional ones, which + are needed to define the title header contents: + + ``modulename`` + Defines the module name to be used at the troff ``.TH`` output. + + This argument is mandatory. + + ``section`` + Usually a numeric value from 0 to 9, but man pages also accept + some strings like "p". + + Defauls to ``9`` + + ``manual`` + Defaults to ``Kernel API Manual``. + + The above controls the output of teh corresponding fields on troff + title headers, which will be filled like this:: + + .TH "{name}" {section} "{date}" "{modulename}" "{manual}" + + where ``name``` will match the API symbol name, and ``date`` will be + either the date where the Kernel was compiled or the current date + """ =20 highlights =3D ( (type_constant, r"\1"), --=20 2.52.0 From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 92FFC3EBF32; Fri, 6 Mar 2026 15:45:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811959; cv=none; b=X1P9GmwD2tFfMPlPVOcv7DKyYJoYDilDYo0Y8O5SbhhD/WRdaOghDWBUFY/g9/GOW33GAxrwcIlLTDf/solNUcGuZ454V2KNVLETkhaIZ7kKAakxz68G8ks8iFSbGX47ekjVD+pZltZEFpy5DNl8qG+6wXJpbIN/oPnGjhVvx1M= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811959; c=relaxed/simple; bh=J6aWOl4+bZyYo837nUHeE6Bf+UJ1MQRqQj8sRXyED9k=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=DNdvq7c02DpARn1ZnE151ZME5/TFm/o5DemrmmZjwlpFBnOYFycyaXsXg2Y9iUnxI12nXn2Gb5BXWFNmCUZ1FCC1NbksMiRk417yUlBzBGBkyspwKHnHodB2l/fmzqKUFr6dHLP3cbs7h7ipBgWboO5JrNKvHi3nYj/2NR82CMw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ddgTToKN; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="ddgTToKN" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 76ACFC2BCB4; Fri, 6 Mar 2026 15:45:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811959; bh=J6aWOl4+bZyYo837nUHeE6Bf+UJ1MQRqQj8sRXyED9k=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ddgTToKNEOaJKUD39fee/bXWQg6n2Jdc/bilzEvAT3fzSqHILrOd7zXtox37kZjOv my2q3DtUUqJNs5MUjH9h30rbAZmctqcHxywl3pxUi1nQpnFmfB+AEILXX86fR6w/Bq gG2Qy7GHsYDB2Nx3jssj3vAFVPXS3CFpFff/whSj/e3p4rq/SYIOAVCa58k38+4xhj IJSyLOeVf+GHI0LgxSt6CYnuNjAfqXVtefJdhr720dKlATmJP49l1SBf5FSPLjXntO AByLlxz9xNxhgpXRP4e8w9MZtvI8XEA8HEGMIbQjBoRfgs8d6+nWwsaS4Rhb8EVITp x4icBeWi6MnOg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNF-00000007EgG-32Oo; Fri, 06 Mar 2026 16:45:57 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH v2 09/13] docs: kdoc_output: pick a better default for modulename Date: Fri, 6 Mar 2026 16:45:47 +0100 Message-ID: <8a5d91c93c0b9b34c2f60e389f4464742804d0d6.1772810752.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Instead of placing the same data for modulename for all generated man pages, use the directory from the filename used to produce kernel docs as basis. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/kernel-doc | 1 - tools/lib/python/kdoc/kdoc_output.py | 7 ++++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc index aed09f9a54dd..3a932f95bdf5 100755 --- a/tools/docs/kernel-doc +++ b/tools/docs/kernel-doc @@ -210,7 +210,6 @@ def main(): help=3D"Enable debug messages") =20 parser.add_argument("-M", "-modulename", "--modulename", - default=3D"Kernel API", help=3D"Allow setting a module name at the output.= ") =20 parser.add_argument("-l", "-enable-lineno", "--enable_lineno", diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 7a181b40810d..c25f80a39cdc 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -589,7 +589,8 @@ class ManFormat(OutputFormat): ``modulename`` Defines the module name to be used at the troff ``.TH`` output. =20 - This argument is mandatory. + This argument is optional. If not specified, it will be filled + with the directory which contains the documented file. =20 ``section`` Usually a numeric value from 0 to 9, but man pages also accept @@ -645,8 +646,8 @@ class ManFormat(OutputFormat): title =3D name.strip() module =3D self.modulename(args) =20 - self.data +=3D f'.TH "{name}" {self.section} "{self.date}" ' - self.data +=3D f'"{self.modulename}" "{self.manual}"\n' + self.data +=3D f'.TH "{title}" {self.section} "{self.date}" ' + self.data +=3D f'"{module}" "{self.manual}"\n' =20 def __init__(self, modulename=3DNone, section=3D"9", manual=3D"Kernel = API Manual"): """ --=20 2.52.0 From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id BD2423EBF3A; Fri, 6 Mar 2026 15:45:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811959; cv=none; b=rbVIQQwoM0thMhw5hTBDGvg7En2gQ74l8UWRbC9nZIO+FTZN+CmQaJ5k2dys68hk7uWUbbMijwEHLVuUAExtDU/GzyndRkig9DU4ctctz9WOOlxzHzmclXtfBJQK5thecKAlqmEJaEXyyt+1WSsT3dHERDUp5GFgX1NyGZuPyVk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811959; c=relaxed/simple; bh=7COCcajjMpNCqEJgxqFWGc78MkIQYZ67DzkUU7rjqRQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=a2DsSNMtmOyd0SEJXxNE7gLeQSoRzbbDlMFeKiW17oPQEj7mf6/bMs1Oq28GKC1XrIAxosI9YVZeA/0kYm+FnH/NrqVMQQ2HdDO3xbVWW8okVtU4gUiEPYYC53lzICvi5uYY4JoHqXvg0U7pTf/zCdjVdOaLkJTXfcLDPzBLuVI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=IOhL2ByE; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="IOhL2ByE" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9EBB6C2BC86; Fri, 6 Mar 2026 15:45:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811959; bh=7COCcajjMpNCqEJgxqFWGc78MkIQYZ67DzkUU7rjqRQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=IOhL2ByEDIFS0CnFrHKGZFuEBlNYkixExxWTKmB+DsgpqtPFJP63Qpt/r3YEjzNUp LNgnreZ7FAtmLbuqzqlIWcG2PE2V7/5+mCcj8U1kBjiawAAkC3GXEGYXp3+cMUkeBR GP1iO1ZWtJopXrMR7s/u+6Nr/0pbzNz46tSw0RddIWMjKqB3CL6oKJ85YtKzSHpoLk gW6xty15axxJ1IEZaZOXgB6HqB8nXuAaD7J+uYmOyfuRWiKpdRllk3Kc8B/guwb7Ca Q9NJOtFq41G1nA5VoAuL4+xmgKZgVUYlY7xY2UmD6O0gDAZdJbOkALn9186ywxgMg1 1WW0FLEj5ncSQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNF-00000007EhU-3p6I; Fri, 06 Mar 2026 16:45:57 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH v2 10/13] docs: kdoc_output: Change the logic to handle man highlight Date: Fri, 6 Mar 2026 16:45:48 +0100 Message-ID: <6ae2301a40b3fcb4381dd9dda8c75d14f9616b46.1772810752.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The code inside ManFormat code to output man pages is too simple: it produces very bad results when the content has tables or code blocks. Change the way lines are parsed there to allow adding extra logic to handle some special cases. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index c25f80a39cdc..9caffe0d9753 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -755,15 +755,23 @@ class ManFormat(OutputFormat): if isinstance(contents, list): contents =3D "\n".join(contents) =20 - for line in contents.strip("\n").split("\n"): - line =3D KernRe(r"^\s*").sub("", line) - if not line: - continue - - if line[0] =3D=3D ".": - self.data +=3D "\\&" + line + "\n" - else: - self.data +=3D line + "\n" + lines =3D contents.strip("\n").split("\n") + i =3D 0 + + while i < len(lines): + org_line =3D lines[i] + + line =3D KernRe(r"^\s*").sub("", org_line) + + if line: + if line[0] =3D=3D ".": + self.data +=3D "\\&" + line + "\n" + i +=3D 1 + continue + + i +=3D 1 + + self.data +=3D line + "\n" =20 def out_doc(self, fname, name, args): if not self.check_doc(name, args): --=20 2.52.0 From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 64FDD3ECBF0; Fri, 6 Mar 2026 15:46:00 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811960; cv=none; b=AnnxCwGgz6wR0ZkMHHNUNHs47Ec1ToeANl9yPXNbjIwCGKfSd0ClxgtcmIa+l45n6FoQ2/PUZqzikZdy71ST0bVKG0WvHq35utmuMIHJqOkeu02LkBCB3XW04anrtH1/xptItZeBlzzr38/enNVXYI7g+faZk5gsFor2VwNI9uY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811960; c=relaxed/simple; bh=9wu4zIA922C3Stn1+dXiQYG1rhAOlEJZPy1s0WQ2X8I=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=qZFEM9WqbxgeVkAk77hj682ijm+qafXZZG7gcry6bhSCF8Opm6KHysXKF8BaIqWskfEftwGSLwecdCJ8QdRgPR8fVsC7lv+ArMrPzTw7fktuqcNJbBZgtCTotjL0QATZ20c6B2wwavd9CCBOMP5WlYEKSPWgZJOJBheDw6Q1T04= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=EfkJDEEn; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="EfkJDEEn" Received: by smtp.kernel.org (Postfix) with ESMTPSA id EF5C4C2BC87; Fri, 6 Mar 2026 15:45:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811960; bh=9wu4zIA922C3Stn1+dXiQYG1rhAOlEJZPy1s0WQ2X8I=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=EfkJDEEnAV8iTyjZ9yIB9BL73WQ4Y0BA1nL2W36lAqgVV6TtzX+cvn9b3g3pZLjJQ 50GsAwo3WoZK4ffkz6AfCNJIeFW3HDvngH7l/mFXpOSFxeecQQvt41fyWqyNDA0jH6 QHL9ZDvFASK+lCrc4XCtTSV6U0mHxRRhfQAprfNDON3UN1NFPunXG0YKnzGbjMm8tO o3xuxSbazrz0nGz11bZ2EvaGcgu6E9UBEpRcB+d3ow0335juYjU8fJLSz/8OMZoYFp LoE2TvZnAcwQrcXcOlv0idsgBorAWaPZG4oLy1k3p+Z4pEOR/FxojACCCVQM8gFIfP Xl1MLSSi+jiKQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNG-00000007Eih-0QU3; Fri, 06 Mar 2026 16:45:58 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH v2 11/13] docs: kdoc_output: add a logic to handle tables inside kernel-doc markups Date: Fri, 6 Mar 2026 16:45:49 +0100 Message-ID: <442ad76442c325044eb9f34a155d5f484341fb35.1772810752.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab specially when DOC is used, it is not uncommon to have tables inside a kernel-doc markup. Add support for simple tables and complex grid tables when output in groff format. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 130 +++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 9caffe0d9753..7848514a4d22 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -744,6 +744,126 @@ class ManFormat(OutputFormat): =20 return self.data =20 + def emit_table(self, colspec_row, rows): + + if not rows: + return "" + + out =3D "" + colspec =3D "\t".join(["l"] * len(rows[0])) + + out +=3D "\n.TS\n" + out +=3D "box;\n" + out +=3D f"{colspec}.\n" + + if colspec_row: + out_row =3D [] + + for text in colspec_row: + out_row.append(f"\\fB{text}\\fP") + + out +=3D "\t".join(out_row) + "\n_\n" + + for r in rows: + out +=3D "\t".join(r) + "\n" + + out +=3D ".TE\n" + + return out + + def grid_table(self, lines, start): + """ + Ancillary function to help handling a grid table inside the text. + """ + + i =3D start + 1 + rows =3D [] + colspec_row =3D None + + while i < len(lines): + line =3D lines[i] + + if KernRe(r"^\s*\|.*\|\s*$").match(line): + parts =3D [] + + for p in line.strip('|').split('|'): + parts.append(p.strip()) + + rows.append(parts) + + elif KernRe(r'^\+\=3D[\+\=3D]+\+\s*$').match(line): + if rows and rows[0]: + if not colspec_row: + colspec_row =3D [""] * len(rows[0]) + + for j in range(0, len(rows[0])): + content =3D [] + for row in rows: + content.append(row[j]) + + colspec_row[j] =3D " ".join(content) + + rows =3D [] + + elif KernRe(r"^\s*\+[-+]+\+.*$").match(line): + pass + + else: + break + + i +=3D 1 + + return i, self.emit_table(colspec_row, rows) + + def simple_table(self, lines, start): + """ + Ancillary function to help handling a simple table inside the text. + """ + + i =3D start + rows =3D [] + colspec_row =3D None + + pos =3D [] + for m in KernRe(r'\-+').finditer(lines[i]): + pos.append((m.start(), m.end() - 1)) + + i +=3D 1 + while i < len(lines): + line =3D lines[i] + + if KernRe(r"^\s*[\-]+[ \t\-]+$").match(line): + i +=3D 1 + break + + elif KernRe(r'^[\s=3D]+$').match(line): + if rows and rows[0]: + if not colspec_row: + colspec_row =3D [""] * len(rows[0]) + + for j in range(0, len(rows[0])): + content =3D [] + for row in rows: + content.append(row[j]) + + colspec_row[j] =3D " ".join(content) + + rows =3D [] + + else: + row =3D [""] * len(pos) + + for j in range(0, len(pos)): + start, end =3D pos[j] + + row[j] =3D line[start:end].strip() + + rows.append(row) + + i +=3D 1 + + return i, self.emit_table(colspec_row, rows) + def output_highlight(self, block): """ Outputs a C symbol that may require being highlighted with @@ -764,6 +884,16 @@ class ManFormat(OutputFormat): line =3D KernRe(r"^\s*").sub("", org_line) =20 if line: + if KernRe(r"^\+\-[-+]+\+.*$").match(line): + i, text =3D self.grid_table(lines, i) + self.data +=3D text + continue + + if KernRe(r"^\-+[ \t]\-[ \t\-]+$").match(line): + i, text =3D self.simple_table(lines, i) + self.data +=3D text + continue + if line[0] =3D=3D ".": self.data +=3D "\\&" + line + "\n" i +=3D 1 --=20 2.52.0 From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 70E9A3ECBF9; Fri, 6 Mar 2026 15:46:00 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811960; cv=none; b=Oi9aBT8nd+23gPLAQFsY82pnZJ1nmSJb8i2s685ibyKwh+TBiGm/3QEecOKduufsw6JM386DnXzcHVtVgtRxu/75gm5HuMfvY44VZznvAOaqSpoBacO2UT9xbmSeaC2f3VSbon3tJOiwp2vL32Xk6a7JRWggN//bda35xmLoyn8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811960; c=relaxed/simple; bh=MS/zYjbr+V2Nm7k+PjrM1v8QWG/dh6kCG5IJ1RaUFN0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=XdfXzFx3VK+WZ2CWZXcf9TbYaT1kalPJXwoVxOgSww7gi5oPhMmPywzfAUZdPQw5DETP15lQ3/jGLPLgOoOgsPAlZmg3nB4NYFcNtViJWXEFkNDC2FENZS8Th95FDlaWwwadCucrefN3pyO/PXuyL5SrV6b0SJnSVqDt7UfNJbs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=fch3smz4; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="fch3smz4" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 051A6C2BC86; Fri, 6 Mar 2026 15:46:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811960; bh=MS/zYjbr+V2Nm7k+PjrM1v8QWG/dh6kCG5IJ1RaUFN0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=fch3smz438CA+oTGrtqc5Ldt4nCK4gNkQlXQIrJHKMKVNUxUNIUyahabjRIioFQaM 9m45N7U6IOH5Gz62LdZcvJxyT9Uu1EteJ5oANIzpJvjx3TtBnGyLpgqd5FOrUkvEYe z9VSvr2wGA57p2z+tvu4Veide7TvvIC6cGDHngCXHlPX46KQ7SPlNG0rwBcrgK8NBW Z/HkQIDiXiJ3Tlw7fVVhRegmCpKttJZ6wel0hSzpeJwWgrO2OdYYBnaIPijygzvQEt O3v9LTi/IfROxCXqdncJlOcJtpnBGCJp70HIBdeJHfaMQ0CpyxJw3def2PwBKsDVMH B/RYwR/J3KHFQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNG-00000007Ejv-1CsT; Fri, 06 Mar 2026 16:45:58 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH v2 12/13] docs: kdoc_output: add support to handle code blocks Date: Fri, 6 Mar 2026 16:45:50 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab It is common to have code blocks inside kernel-doc markups. By default, troff will group all lines altogether, producing a very weird output. If a code block is detected by disabling filling inside code blocks, re-enabling it afterwards. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 64 ++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 7848514a4d22..df9af444da57 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -864,6 +864,65 @@ class ManFormat(OutputFormat): =20 return i, self.emit_table(colspec_row, rows) =20 + def code_block(self, lines, start): + """ + Ensure that code blocks won't be messed up at the output. + + By default, troff join lines at the same paragraph. Disable it, + on code blocks. + """ + + line =3D lines[start] + + if "code-block" in line: + out =3D "\n.nf\n" + elif line.startswith("..") and line.endswith("::"): + # + # Handle note, warning, error, ... markups + # + line =3D line[2:-1].strip().upper() + out =3D f"\n.nf\n\\fB{line}\\fP\n" + elif line.endswith("::"): + out =3D line[:-1] + out +=3D "\n.nf\n" + else: + # Just in case. Should never happen in practice + out =3D "\n.nf\n" + + i =3D start + 1 + ident =3D None + + while i < len(lines): + line =3D lines[i] + + m =3D KernRe(r"\S").match(line) + if not m: + out +=3D line + "\n" + i +=3D 1 + continue + + pos =3D m.start() + if not ident: + if pos > 0: + ident =3D pos + else: + out +=3D "\n.fi\n" + if i > start + 1: + return i - 1, out + else: + # Just in case. Should never happen in practice + return i, out + + if pos >=3D ident: + out +=3D line + "\n" + i +=3D 1 + continue + + break + + out +=3D "\n.fi\n" + return i, out + def output_highlight(self, block): """ Outputs a C symbol that may require being highlighted with @@ -894,6 +953,11 @@ class ManFormat(OutputFormat): self.data +=3D text continue =20 + if line.endswith("::") or KernRe(r"\.\.\s+code-block.*::")= .match(line): + i, text =3D self.code_block(lines, i) + self.data +=3D text + continue + if line[0] =3D=3D ".": self.data +=3D "\\&" + line + "\n" i +=3D 1 --=20 2.52.0 From nobody Thu Apr 9 16:32:27 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C94BC3ED10B; Fri, 6 Mar 2026 15:46:00 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811960; cv=none; b=NsSqPxCCU2YTPX3PWQkENbZ6nYirv5VsA7mNT3BVSe5Fpe/XZG7ySC7gCOsJwHBkVlrBB8v6n0qKcZiy6wcYHS0UEYOq4zvMRwnSgrVvZyMM0jHOJ3nGqx1rWrUUzjK2UXCzaq9eNn+Eg64fK5nITJf7OQA/eyhf8daw4nvdbOY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772811960; c=relaxed/simple; bh=I8pl1ObNgYBcBYQMqbLazkhnglEI29k6aw48idb2oew=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=bzCt9vC5GERgghrfbmLWY2WtPUFszhw3RAZZKZsQnkPcfTFHsigXb9Mfkyz0ss59oFZqtf2OUNsliRXuI11TdOjH+P6J7VmeCpiLff3uZxBIu5+WOgOTlMgGmzFlaeCw+YUbL2PX2y5bx1v3MqM/4OLo4phwc+r1w2KfPIXhGgI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=k4Nlu4cu; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="k4Nlu4cu" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 61A84C2BCAF; Fri, 6 Mar 2026 15:46:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772811960; bh=I8pl1ObNgYBcBYQMqbLazkhnglEI29k6aw48idb2oew=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=k4Nlu4cuybc12bpnN6RHsliagb4P49/Oejk962NY8Z5HC88jUv/+1FsiWZu6eXH0q jn0nZvtGXBJRS8/s8126f1RGd4Ca7HwFJYZZwd2lvURKKZRz5eUpTqFgN+Db8iNh/I 93dXA1hBgzocLNU9sqb7vL9AciTk747WJa66aZZ7c5T9w6uOhcAWM0ev5B5/wOfBxa qW6hqtmKK2RNZ871DECFWxsxTaWl6KUQRljlIJ91iSBR1glUUCZ1UAbHlbjoYacnxD J2wxmY3xu7jRaT9fiF59HHQ3/PR7edlhPb4c9EDkKciMOT5FlSkK4PjB+Rb4l83SBH bsRnvADvuWj4Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vyXNG-00000007ElA-20Da; Fri, 06 Mar 2026 16:45:58 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH v2 13/13] docs: kdoc_output: better handle lists Date: Fri, 6 Mar 2026 16:45:51 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab On several functions, the return values are inside a bullet list. Also, on some places, there are numbered lists as well. Use a troff markup to format them, to avoid placing everything on a single line. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index df9af444da57..08539dd92cbb 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -963,6 +963,14 @@ class ManFormat(OutputFormat): i +=3D 1 continue =20 + # + # Handle lists + # + line =3D KernRe(r'^[-*]\s+').sub(r'.IP \[bu]\n', line) + line =3D KernRe(r'^(\d+|a-z)[\.\)]\s+').sub(r'.IP \1\n', l= ine) + else: + line =3D ".PP\n" + i +=3D 1 =20 self.data +=3D line + "\n" --=20 2.52.0