Re: [PATCH docs] man pages: strip '.it 1 an-trap' emitted by docbook-xsl

[Kefu Chai <k.chai@proxmox.com>]

Just came across https://github.com/svarshavchik/courier/issues/58 [https://github.com/svarshavchik/courier/issues/58] . So we are not alone in this case.
On Wednesday, 03/25/2026, 15:07, Kefu Chai <k.chai@proxmox.com> wrote:

From : Kefu Chai <k.chai@proxmox.com>
Sent on : Wednesday, 03/25/2026, 15:07
To : pve-devel@lists.proxmox.com
Cc : Kefu Chai <k.chai@proxmox.com>
Subject : [PATCH docs] man pages: strip '.it 1 an-trap' emitted by docbook-xsl
Symptom
-------
Building any PVE package that uses pve-doc-generator.mk [http://pve-doc-generator.mk/] to compile man
pages triggers lintian warnings of the form:

  W: pve-manager: groff-message troff:<standard input>: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 [http://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 <file.xml>                # 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 <k.chai@proxmox.com>
---
 pve-doc-generator.mk.in [http://pve-doc-generator.mk.in/] | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/pve-doc-generator.mk.in [http://pve-doc-generator.mk.in/] b/pve-doc-generator.mk.in [http://pve-doc-generator.mk.in/]
index 64b6398..ba5413f 100644
--- a/pve-doc-generator.mk.in [http://pve-doc-generator.mk.in/]
+++ b/pve-doc-generator.mk.in [http://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