* [PATCH docs] man pages: strip '.it 1 an-trap' emitted by docbook-xsl
@ 2026-03-25 7:07 Kefu Chai
2026-03-25 7:11 ` Kefu Chai
0 siblings, 1 reply; 2+ messages in thread
From: Kefu Chai @ 2026-03-25 7:07 UTC (permalink / raw)
To: pve-devel
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:<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 (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 | 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
^ permalink raw reply [flat|nested] 2+ messages in thread* Re: [PATCH docs] man pages: strip '.it 1 an-trap' emitted by docbook-xsl
2026-03-25 7:07 [PATCH docs] man pages: strip '.it 1 an-trap' emitted by docbook-xsl Kefu Chai
@ 2026-03-25 7:11 ` Kefu Chai
0 siblings, 0 replies; 2+ messages in thread
From: Kefu Chai @ 2026-03-25 7:11 UTC (permalink / raw)
To: pve-devel
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
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2026-03-25 7:11 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2026-03-25 7:07 [PATCH docs] man pages: strip '.it 1 an-trap' emitted by docbook-xsl Kefu Chai
2026-03-25 7:11 ` Kefu Chai
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.