From c2eab5cc8748d4161fdd5d724f42753b015ea814 Mon Sep 17 00:00:00 2001 From: Thomas Lamprecht Date: Wed, 6 Mar 2024 17:54:05 +0100 Subject: [PATCH] docbook: render 4th section level for manpages In the manpage output the sections get rendered as refsections, but those only go up to level 3: > In DocBook, RefSect3 is the lowest-level section allowed in a > RefEntry. There is no element analogous to a Sect4. -- https://tdg.docbook.org/tdg/4.5/refsect3 While nesting refsect3 would work output wise, the DTD schema does not allows this, and disabling schema validation can lead to graver issues, so rather avoid that and use a formalpara [0], a paragraph with a title, instead, but only for the title, as the inner content will be a simpara (simple paragraph) that cannot be nested inside a formalpara, but the resulting rendering works out well enough. [0]: https://tdg.docbook.org/tdg/4.5/formalpara Signed-off-by: Thomas Lamprecht --- asciidoc/pve-docbook.conf | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/asciidoc/pve-docbook.conf b/asciidoc/pve-docbook.conf index 95436ec..e179342 100644 --- a/asciidoc/pve-docbook.conf +++ b/asciidoc/pve-docbook.conf @@ -5,6 +5,7 @@ # # modified for Proxmox VE docs # - add thumbnail attribute +# - render sect4 sections in manpages as formalpara title [miscellaneous] outfilesuffix=.xml @@ -693,6 +694,16 @@ template::[docinfo] | +# Proxmox: add custom section 4 level for manpages, as there is no refsect4 and +# the XML DTD schema does not allows nesting refsect3 (even if it would render +# OK). Use a formalpara, which is a paragraph with a title. As docbook always +# outputs a simpara (simple paragraph, very limited) for the inner content, we +# cannot nest that either, but rather just create an empty formalpara which can +# then be followed by whatever the original inner content is. +[sect4] +{title} +| + endif::doctype-manpage[] #-------------------------