From nobody Sat Apr 11 08:55:19 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