From 8c85fc1386258e19c11b52ec3e13546fe6b61c33 Mon Sep 17 00:00:00 2001 From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com> Date: Fri, 17 Jul 2026 08:45:00 +0800 Subject: [PATCH 1/4] docs: link manpage cross-references in HTML output Add an asciidoctor postprocessor that turns name(section) references in the HTML manpages into clickable links to the sibling page. Index-gated against the rendered troff tree so false positives (enum values, external and misspelled pages) stay plain text; self-links, code spans and existing links are left untouched. Wired into the manpage HTML rule via manxref-root. --- docs/src/Submakefile | 4 +- docs/src/extensions/man_xref.rb | 113 ++++++++++++++++++++++++++++++++ 2 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 docs/src/extensions/man_xref.rb diff --git a/docs/src/Submakefile b/docs/src/Submakefile index 911289bdd03..445aaa03960 100644 --- a/docs/src/Submakefile +++ b/docs/src/Submakefile @@ -743,7 +743,7 @@ $(foreach L,$(LANGUAGES), \ # from docs/build/man//manN. cssrel is ../../../ for both: each output # sits at docs/build/html//man/manN/X.html (4 levels under html/). define MAN_HTML_RULE -$(DOC_OUT_HTML)/$(1)/man/%.html: $(2)/% $(DOC_SRCDIR)/docinfo.html $(DOC_SRCDIR)/docinfo-header.html +$(DOC_OUT_HTML)/$(1)/man/%.html: $(2)/% $(DOC_SRCDIR)/docinfo.html $(DOC_SRCDIR)/docinfo-header.html | manpages @$$(ECHO) Formatting $$(notdir $$<) as HTML @mkdir -p $$(dir $$@) $$(Q)if grep -q '^\.so' $$<; then \ @@ -771,12 +771,14 @@ $(DOC_OUT_HTML)/$(1)/man/%.html: $(2)/% $(DOC_SRCDIR)/docinfo.html $(DOC_SRCDIR) -r $$(realpath $$(DOC_SRCDIR))/extensions/rouge_hal.rb \ -r $$(realpath $$(DOC_SRCDIR))/extensions/rouge_ngc.rb \ -r $$(realpath $$(DOC_SRCDIR))/extensions/rouge_ini.rb \ + -r $$(realpath $$(DOC_SRCDIR))/extensions/man_xref.rb \ --doctype=manpage \ --backend=html5 \ -a compat-mode \ -a mansource=LinuxCNC \ -a manmanual='LinuxCNC Documentation' \ -a "lcnc-cssrel=../../../" \ + -a "manxref-root=$$(realpath $(2))" \ -a "lcnc-lang-label=$(LANG_LABEL_$(1))" \ -a "lcnc-subpath=$$(patsubst $(DOC_OUT_HTML)/$(1)/%,%,$$@)" \ -a docinfo=shared \ diff --git a/docs/src/extensions/man_xref.rb b/docs/src/extensions/man_xref.rb new file mode 100644 index 00000000000..53d77e16633 --- /dev/null +++ b/docs/src/extensions/man_xref.rb @@ -0,0 +1,113 @@ +# docs/src/extensions/man_xref.rb +# +# Asciidoctor postprocessor that turns manpage cross-references in the +# conventional name(section) form (e.g. "halcmd(1)") into clickable links to +# the sibling HTML page ../man
/.
.html. +# +# * Index-gated: a token is linked only when a page .
exists +# in the troff tree, so false positives never resolve and stay plain text +# ("feed(2)"/"arc(3)" enum values in motion(9); external open(2)/udev(8); +# typo'd or renamed API names). +# * Never links a page to itself. +# * Skips text inside