From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id 6294C1FF13B for ; Wed, 25 Mar 2026 08:08:08 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 1DD13981B; Wed, 25 Mar 2026 08:08:27 +0100 (CET) From: Kefu Chai To: pve-devel@lists.proxmox.com Subject: [PATCH docs] man pages: strip '.it 1 an-trap' emitted by docbook-xsl Date: Wed, 25 Mar 2026 15:07:44 +0800 Message-ID: <20260325070744.2416661-1-k.chai@proxmox.com> X-Mailer: git-send-email 2.47.3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1774422423539 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.382 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_VALIDITY_CERTIFIED_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_RPBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_SAFE_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: DLCMSHURIDWM6Z5CRUYQN6LV7FEVE2QO X-Message-ID-Hash: DLCMSHURIDWM6Z5CRUYQN6LV7FEVE2QO X-MailFrom: k.chai@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Symptom ------- Building any PVE package that uses pve-doc-generator.mk to compile man pages triggers lintian warnings of the form: W: pve-manager: groff-message troff::136: \ warning: macro 'an-trap' not defined \ [usr/share/man/man1/pveceph.1.gz:1] The same warning appears for every man page in every package that includes pve-doc-generator.mk (pve-manager, pve-storage, pve-cluster, etc.). Build pipeline -------------- The man page compilation chain is: asciidoc-pve compile-man → asciidoc -dmanpage -b pve-docbook # produces DocBook XML → xmlto man # converts XML → troff → /usr/share/xml/docbook/stylesheet/docbook-xsl/manpages/docbook.xsl → utility.xsl (line 197) # emits: .it 1 an-trap → other.xsl (lines 706,739) # emits: .it 1 an-trap The DocBook XSL stylesheets (version 1.79.2, last upstream release 2016) contain a template named 'pinch.together' whose purpose is to suppress vertical space after section headings: .it 1 an-trap ← input trap: call 'an-trap' after next line .nr an-no-space-flag 1 .nr an-break-flag 1 .br 'an-trap' was an internal macro in groff's an.tmac (the man macro package) up through groff 1.21. It was renamed to 'an-input-trap' in groff 1.22 as part of a cleanup of internal naming. The docbook-xsl package was never updated. Debian trixie ships groff 1.23.0. When lintian runs 'man --warnings -l -Tutf8 -Z' on the installed man page, groff's troff backend encounters '.it 1 an-trap', finds the macro undefined, and emits the warning. The warning is real: the trap fires after the next input line but immediately does nothing because the macro body does not exist. Impact of this change --------------------- The '.it 1 an-trap' line is stripped from each generated man page by a targeted sed invocation immediately after asciidoc-pve compile-man writes the file. The remaining three lines of the 'pinch.together' block are left untouched: .nr an-no-space-flag 1 — sets a number register; harmless if unread .nr an-break-flag 1 — same .br — standard roff break primitive; always valid The heading-spacing suppression that 'pinch.together' used to provide has been handled natively inside groff's an.tmac since groff 1.22 via the renamed 'an-input-trap' macro, which groff sets up itself at each .SH/.SS call. Removing the obsolete '.it' line has no visible effect on man page rendering. Regression analysis ------------------- No regression. The fix has been verified by inspection: - groff ≥ 1.22 already suppresses post-heading spacing through its own an-input-trap mechanism; the DocBook XSL block is redundant. - The three retained lines ('.nr', '.nr', '.br') produce no warnings and cause no rendering change. - The sed pattern '^\.it 1 an-trap$' is anchored on both ends and matches only the exact line produced by docbook-xsl; it cannot accidentally remove unrelated content. - Packages that build .1, .8, and .5 man pages are all covered by the three parallel rules updated here. Alternatives considered ----------------------- 1. Replace '.it 1 an-trap' with '.it 1 an-input-trap': rejected. 'an-input-trap' is groff's own internal trap for managing indentation in .TP/.IP blocks. Calling it from arbitrary points in the document body could interfere with groff's own use of the trap and produce subtly broken output. 2. Remove all four lines of the 'pinch.together' block: safe, but more invasive than necessary. The '.nr' and '.br' lines are inert and removing them gains nothing. 3. Add lintian overrides in each downstream package (pve-manager, etc.): suppresses the symptom without fixing the cause, and requires the same override to be added to every package independently. 4. Fix in docbook-xsl upstream: the correct long-term fix, but outside PVE's control. The docbook-xsl package has had no upstream release since 2016. Signed-off-by: Kefu Chai --- pve-doc-generator.mk.in | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pve-doc-generator.mk.in b/pve-doc-generator.mk.in index 64b6398..ba5413f 100644 --- a/pve-doc-generator.mk.in +++ b/pve-doc-generator.mk.in @@ -87,6 +87,7 @@ chapter-%.html: %.adoc ${PVE_COMMON_DOC_SOURCES} %.1: %.adoc generated/%.1-synopsis.adoc ${PVE_COMMON_DOC_SOURCES} ${ASCIIDOC_PVE} compile-man -o $@ $*.adoc + sed -i '/^\.it 1 an-trap$$/d' $@ test -z "$${PVE_DOC_INSTANTVIEW}" || man -l $@ %.1.html: %.adoc generated/%.1-synopsis.adoc ${PVE_COMMON_DOC_SOURCES} @@ -94,6 +95,7 @@ chapter-%.html: %.adoc ${PVE_COMMON_DOC_SOURCES} %.8: %.adoc generated/%.8-synopsis.adoc ${PVE_COMMON_DOC_SOURCES} ${ASCIIDOC_PVE} compile-man -o $@ $*.adoc + sed -i '/^\.it 1 an-trap$$/d' $@ test -z "$${PVE_DOC_INSTANTVIEW}" || man -l $@ %.8.html: %.adoc generated/%.8-synopsis.adoc ${PVE_COMMON_DOC_SOURCES} @@ -101,6 +103,7 @@ chapter-%.html: %.adoc ${PVE_COMMON_DOC_SOURCES} %.5: %.adoc generated/%.5-opts.adoc ${PVE_COMMON_DOC_SOURCES} ${ASCIIDOC_PVE} compile-man -o $@ $*.adoc + sed -i '/^\.it 1 an-trap$$/d' $@ test -z "$${PVE_DOC_INSTANTVIEW}" || man -l $@ %.5.html: %.adoc generated/%.5-opts.adoc ${PVE_COMMON_DOC_SOURCES} -- 2.47.3