build: extract halcompile manpages via adoc, drop troff sed hacks#4091
Open
grandixximo wants to merge 1 commit into
Open
build: extract halcompile manpages via adoc, drop troff sed hacks#4091grandixximo wants to merge 1 commit into
grandixximo wants to merge 1 commit into
Conversation
BsAtHome
reviewed
May 31, 2026
9 tasks
Per @BsAtHome's review on PR LinuxCNC#4086. The old COMP_MANPAGES / COMP_DRIVER_MANPAGES rules ran halcompile in --document mode (troff straight out) and sed-edited the troff to escape .als / .URL groff directives the old dblatex-based PDF pipeline could not parse. Asciidoctor now reads the component adoc directly, so the sed hacks are obsolete. New chain: - halcompile --adoc -o objects/man/man9/<comp>.9.adoc <comp>.comp - asciidoctor --doctype=manpage --backend=manpage -> ../docs/man/man9/<comp>.9 The adoc extraction only needs Python + halcompile.py (yapps-generated, not the C build), so a fresh-tree docs-only build (make htmldocs / pdfdocs / docs) extracts and renders component manpages without first compiling the rest of LinuxCNC. Previously a docs-only build silently omitted them. Also adds homecomp.9 to COMP_MANPAGES alongside tpcomp.9 (both .comp files are filtered out of COMPS because they do not compile to .o modules, but their manpages are still worth shipping). Surfaces in @hansu's review of PR LinuxCNC#4081 as a 'gen_complist: Broken link: ../man/man9/homecomp.9.html' warning. .9.adoc suffix matches the convention the docs HTML manpage rule already expects under objects/man/. Tested: clean-tree make docs (English-only) builds 207 troff + 154 extracted component adocs, link checker clean. Standalone make ../docs/man/man9/abs.9 from a tree with no halcompile binary rebuilds halcompile and produces the manpage without touching C code.
907b0d5 to
b43f00e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Per @BsAtHome's review on #4086. The old
COMP_MANPAGES/COMP_DRIVER_MANPAGESrules ranhalcompile --document(troff straightout) and sed-escaped
.als/.URLgroff directives the old dblatexPDF pipeline could not parse. Asciidoctor now reads the component
adoc directly, so the sed hacks are obsolete.
New chain:
halcompile --adoc -o objects/man/man9/<comp>.9.adoc <comp>.compasciidoctor --doctype=manpage --backend=manpage->../docs/man/man9/<comp>.9The adoc extraction only needs Python + halcompile.py (yapps-generated,
not the C build), so a fresh-tree docs-only build (
make htmldocs/pdfdocs/docs) extracts and renders component manpages withoutfirst compiling the rest of LinuxCNC. Previously a docs-only build
silently omitted them.
Also adds
homecomp.9toCOMP_MANPAGESalongsidetpcomp.9(both.compfiles are filtered out ofCOMPSbecause they do not compileto
.omodules, but their manpages are still worth shipping).Surfaces in @hansu's review of #4081 as a
gen_complist: Broken link: ../man/man9/homecomp.9.htmlwarning..9.adocsuffix matches the convention the docs HTML manpage rulealready expects under
objects/man/.Test plan
make docs(English-only): 207 troff + 154 extractedcomponent adocs, link checker clean.
make ../docs/man/man9/homecomp.9produces troff (was silentlymissing before).
make ../docs/man/man9/abs.9from a tree with nohalcompile binary rebuilds halcompile and produces the manpage
without touching C code.