From b43f00e538f795ab6955e517d7c0f00e4e715e71 Mon Sep 17 00:00:00 2001
From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com>
Date: Sun, 31 May 2026 16:40:19 +0800
Subject: [PATCH] build: extract halcompile manpages via adoc, drop troff sed
 hacks

Per @BsAtHome's review on PR #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 #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.
---
 src/hal/components/Submakefile | 43 ++++++++++++++++++++++++----------
 1 file changed, 31 insertions(+), 12 deletions(-)

diff --git a/src/hal/components/Submakefile b/src/hal/components/Submakefile
index 62e5d937132..2c37b2043f8 100644
--- a/src/hal/components/Submakefile
+++ b/src/hal/components/Submakefile
@@ -33,7 +33,7 @@ CONVERTERS :=  \
     conv_u64_u32.comp \
     conv_u64_s64.comp
 COMPS := $(filter-out hal/components/tpcomp.comp hal/components/homecomp.comp, $(sort $(wildcard hal/components/*.comp) $(addprefix hal/components/, $(CONVERTERS))))
-COMP_MANPAGES := $(patsubst hal/components/%.comp, ../docs/man/man9/%.9, $(COMPS)) ../docs/man/man9/tpcomp.9
+COMP_MANPAGES := $(patsubst hal/components/%.comp, ../docs/man/man9/%.9, $(COMPS)) ../docs/man/man9/tpcomp.9 ../docs/man/man9/homecomp.9
 ifeq ($(BUILD_SYS),uspace)
 COMP_DRIVERS += hal/drivers/serport.comp
 COMP_DRIVERS += hal/drivers/mesa_7i65.comp
@@ -54,19 +54,38 @@ endif
 
 obj-m += $(patsubst hal/drivers/%.comp, %.o, $(patsubst hal/components/%.comp, %.o, $(COMPS) $(COMP_DRIVERS)))
 
-$(COMP_MANPAGES): ../docs/man/man9/%.9: hal/components/%.comp ../bin/halcompile
-	$(ECHO) Making halcompile manpage $(notdir $@)
-	@mkdir -p $(dir $@) objects/man/man9
-	$(Q)../bin/halcompile -U --document --keep-adoc=$@.adoc -o $@ $<
-	$(Q)sed -i -e's/^\.als /.\\" .als /' $@
-	$(Q)mv -f $@.adoc objects/man/man9/
+COMP_MANPAGE_ADOCS := $(patsubst hal/components/%.comp, objects/man/man9/%.9.adoc, $(COMPS)) objects/man/man9/tpcomp.9.adoc objects/man/man9/homecomp.9.adoc
+COMP_DRIVER_MANPAGE_ADOCS := $(patsubst hal/drivers/%.comp, objects/man/man9/%.9.adoc, $(COMP_DRIVERS))
+
+# Extract adoc from .comp via halcompile --adoc.  Only needs Python +
+# halcompile.py (yapps-generated, not the C build), so a docs-only build
+# can run this rule without first compiling the rest of LinuxCNC.  The
+# .9.adoc suffix matches the convention the docs HTML manpage rule
+# expects under objects/man/.
+$(COMP_MANPAGE_ADOCS): objects/man/man9/%.9.adoc: hal/components/%.comp ../bin/halcompile
+	$(ECHO) Extracting adoc manpage $(notdir $@)
+	@mkdir -p $(dir $@)
+	$(Q)../bin/halcompile -U --adoc -o $@ $<
 
-$(COMP_DRIVER_MANPAGES): ../docs/man/man9/%.9: hal/drivers/%.comp ../bin/halcompile
+$(COMP_DRIVER_MANPAGE_ADOCS): objects/man/man9/%.9.adoc: hal/drivers/%.comp ../bin/halcompile
+	$(ECHO) Extracting adoc manpage $(notdir $@)
+	@mkdir -p $(dir $@)
+	$(Q)../bin/halcompile -U --adoc -o $@ $<
+
+# Build troff from the adoc via asciidoctor.  Used to be halcompile
+# emitting troff directly with sed post-processing to escape .als / .URL
+# directives that the old dblatex-based PDF pipeline choked on; with the
+# asciidoctor toolchain reading adoc straight through, that hack is gone.
+$(COMP_MANPAGES) $(COMP_DRIVER_MANPAGES): ../docs/man/man9/%.9: objects/man/man9/%.9.adoc
 	$(ECHO) Making halcompile manpage $(notdir $@)
-	@mkdir -p $(dir $@) objects/man/man9
-	$(Q)../bin/halcompile -U --document --keep-adoc=$@.adoc -o $@ $<
-	$(Q)sed -i -e's/^\.als /.\\" .als /' -e's/^\.URL / /' $@
-	$(Q)mv -f $@.adoc objects/man/man9/
+	@mkdir -p $(dir $@)
+	$(Q)asciidoctor --doctype=manpage \
+	    --backend=manpage \
+	    --destination-dir="$(dir $@)" \
+	    -a compat-mode \
+	    -a mansource=LinuxCNC \
+	    -a manmanual='LinuxCNC Documentation' \
+	    $<
 
 objects/%.mak: %.comp hal/components/Submakefile
 	$(ECHO) "Creating $(notdir $@)"