Skip to content

build: extract halcompile manpages via adoc, drop troff sed hacks#4091

Open
grandixximo wants to merge 1 commit into
LinuxCNC:masterfrom
grandixximo:fix/halcompile-adoc-extract
Open

build: extract halcompile manpages via adoc, drop troff sed hacks#4091
grandixximo wants to merge 1 commit into
LinuxCNC:masterfrom
grandixximo:fix/halcompile-adoc-extract

Conversation

@grandixximo
Copy link
Copy Markdown
Contributor

Summary

Per @BsAtHome's review on #4086. The old COMP_MANPAGES /
COMP_DRIVER_MANPAGES rules ran halcompile --document (troff straight
out) and sed-escaped .als / .URL groff directives the old dblatex
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 #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/.

Test plan

  • Clean-tree make docs (English-only): 207 troff + 154 extracted
    component adocs, link checker clean.
  • make ../docs/man/man9/homecomp.9 produces troff (was silently
    missing before).
  • Standalone make ../docs/man/man9/abs.9 from a tree with no
    halcompile binary rebuilds halcompile and produces the manpage
    without touching C code.

Comment thread src/hal/components/Submakefile Outdated
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.
@grandixximo grandixximo force-pushed the fix/halcompile-adoc-extract branch from 907b0d5 to b43f00e Compare May 31, 2026 12:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants