Support both asciidoctor and asciidoc-py for man pages - #2479
Conversation
Man pages can now be built with either toolchain (#2395): asciidoctor's native manpage backend (preferred, no extra dependencies), or classic Python asciidoc via docbook XML + xsltproc, as asciidoc has no manpage backend. The new cmake/Modules/adoc-manpage.xsl supplements stock docbook-xsl with the same adjustments a2x applies, plus maps the asciidoc-br processing instruction (dropped by stock docbook-xsl) to roff .br requests. CMake prefers asciidoctor, falls back to asciidoc + xsltproc, then to the pre-generated docs/man cache; ASCIIDOC_TOOL=asciidoc forces the docbook pipeline. To keep the sources renderable by both tools: - NAME sections now start with the page's own name (docbook-xsl names its output after the first refname, and it is the correct whatis name) - librnp(3) SYNOPSIS uses a literal block instead of + hard line breaks - email-shaped text and quotes nested in emphasis markers are avoided (asciidoctor macro-ifies user@domain and disagrees with asciidoc on where strong spans containing quotes end) ci/check-man-pages.sh, run by the new man-pages workflow, builds every page with both toolchains and fails on warnings or render divergence, modeled on git's ci/test-documentation.sh. docs/man/ is refreshed.
asciidoc-py < 10.2.1 emits Python SyntaxWarnings from its own config on Python 3.12+, which tripped the zero-stderr policy on ubuntu-24.04. Filter that line, as git ci/test-documentation.sh does.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #2479 +/- ##
==========================================
- Coverage 85.47% 85.46% -0.01%
==========================================
Files 125 125
Lines 22962 22962
==========================================
- Hits 19626 19625 -1
- Misses 3336 3337 +1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
@eli-schwartz thank you again for the report and for the correction about a2x -- we went ahead and did it the git way! Man pages can now be built with either toolchain: asciidoctor with its native manpage backend when available, or classic Python asciidoc via docbook + xsltproc (the same a2x pipeline you described). CMake auto-detects whichever is installed, so no asciidoctor is needed; Following git's example, CI now builds all the pages with both toolchains and fails on any warning or rendering divergence, so the sources cannot drift into tool-specific syntax. Could you give it a spin and let us know whether this covers your packaging use case? Thank you! |
ni4
left a comment
ni4
left a comment
There was a problem hiding this comment.
LGTM, thanks! @ronaldtse I believe we could merge it with a single approval?
|
Yes, agree! Please help merge it! |
2 participants
Summary
Implements #2395 the "git way": man pages can now be generated with either supported AsciiDoc toolchain, and CI keeps the sources honest about it.
cmake/Modules/AdocMan.cmakenow picks a backend:asciidoctor -b manpage(preferred, no extra deps) →asciidoc+xsltproc(the a2x docbook pipeline distros already ship) → pre-generateddocs/man/cache.ASCIIDOC_TOOL=asciidocforces the docbook pipeline.cmake/Modules/adoc-manpage.xsl: stock docbook-xsl manpages sheet plus the adjustments a2x's bundled sheet applies (ulink text-only, no auto-REFERENCES, quiet output), and a template mapping the<?asciidoc-br?>PI (+hard line breaks, which stock docbook-xsl silently drops) to roff.br.rnp,rnpkeys,librnp) — required because docbook-xsl names its output after the first refname, and the correct whatis name anyway;librnp(3)SYNOPSIS uses a literal block instead of+-joined bold lines;*"quoted text"*/*_-_*(span-end disagreement) and bare<user@domain>/user@domainshapes in running text (asciidoctor macro-ifies emails, asciidoc-py does not).ci/check-man-pages.sh+ newman-pagesworkflow: builds all three pages with both toolchains, fails on any stderr output (like git'sci/test-documentation.sh), and diffs the normalized rendered output so silent divergence cannot creep in.docs/develop.adocdocuments the two toolchains and the common-subset rules;docs/man/cache refreshed (asciidoctor stays canonical for the cache).Rendered output from both toolchains is verified identical modulo known cosmetics (sentence spacing, footer date format, AUTHOR section shape), which the check normalizes away.
Test plan
cmake -DASCIIDOC_TOOL=asciidocbuild +DESTDIRinstall of all three man pages via asciidoc-py 10.2.1 + docbook-xsl 1.79.2--no-toolchainconfigure falls back to thedocs/mancacheci/check-man-pages.shpasses (both toolchains, zero warnings, identical normalized renders); shellcheck cleanman-pagesworkflow green on ubuntu (apt asciidoctor + asciidoc + docbook-xsl)Closes #2395