docs: cross-link manpage references from the narrative manuals

Extend the man_xref postprocessor to the User/HAL/Integrator HTML
manuals, which cite man pages in the same name(section) form. A
per-page manxref-linkbase attribute carries the depth-adjusted path to
the language's man/man<N>/ tree; manpages keep the sibling default.
Index-gated as before, so only real pages link and prose like TRUE(1)
stays plain.

Author: grandixximo

docs/src/Submakefile

@@ -1205,6 +1205,14 @@ $(DOC_OUT_ADOC)/%.html: LCNC_CSSREL=$(shell python3 -c "print('../' * '$*'.count
 # of the output depth.  Add the +1 here, matching the $(DOC_SRCDIR) rule above.
 $(DOC_OUT_ADOC)/en/%.html: LCNC_CSSREL=$(shell python3 -c "print('../' * (1 + '$*'.count('/')))")
 
+# man_xref linkbase: relative path from this html page to its language's
+# man/man<N>/ dirs.  CSSREL points one level above the lang root (at the html
+# root, where the css lives); the man tree sits inside the lang root, so this
+# is CSSREL with one fewer "../" plus "man/".  Translated stems include the
+# lang dir; the English stem omits it, hence the extra step, mirroring CSSREL.
+$(DOC_OUT_ADOC)/%.html: MANXREF_LINKBASE=$(shell python3 -c "print('../' * ('$*'.count('/') - 1) + 'man/')")
+$(DOC_OUT_ADOC)/en/%.html: MANXREF_LINKBASE=$(shell python3 -c "print('../' * '$*'.count('/') + 'man/')")
+
 # asciidoctor HTML rule used for every language.
 #	$1 lang tag (en, de, ...)
 #	$2 source root: $(DOC_SRCDIR) for English (DOC_SRCS_EN paths have no
@@ -1216,13 +1224,16 @@ $(DOC_OUT_ADOC)/en/%.html: LCNC_CSSREL=$(shell python3 -c "print('../' * (1 + '$
 define ASCIIDOCTOR_HTML_RULE
 # Order-only dep on .adoc-images-stamp so translated images are staged before
 # the resolver probes for them at render (it also falls back to docs/src).
-$$(patsubst %.adoc,$2/%.html,$$(DOC_SRCS_$(call toUC,$1)_SMALL)): $2/%.html: $2/%.adoc $$(DOC_SRCDIR)/docinfo.html $$(DOC_SRCDIR)/docinfo-header.html | .adoc-images-stamp
+$$(patsubst %.adoc,$2/%.html,$$(DOC_SRCS_$(call toUC,$1)_SMALL)): $2/%.html: $2/%.adoc $$(DOC_SRCDIR)/docinfo.html $$(DOC_SRCDIR)/docinfo-header.html | .adoc-images-stamp manpages
 	$$(ECHO) "Building '$1' adoc to html: " $$<
 	$$(Q)asciidoctor -r $$(realpath $$(DOC_SRCDIR))/extensions/xref_resolver.rb \
 		 -r $$(realpath $$(DOC_SRCDIR))/extensions/image_resolver.rb \
 		 -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 \
+		 -a "manxref-root=$$(realpath $$(if $$(filter en,$1),$$(DOC_MAN),$$(DOC_MAN)/$1))" \
+		 -a "manxref-linkbase=$$(MANXREF_LINKBASE)" \
 		 -a compat-mode \
 		 -a "doc-languages=$$(LANGUAGES)" \
 		 -a "lcnc-lang=$1" \

docs/src/extensions/man_xref.rb

@@ -13,9 +13,15 @@
 #     so code samples, tag attributes and existing links are left untouched.
 #   * Case-insensitive match ("AXIS(1)" => axis.1); visible text kept verbatim.
 #
+# Used for both the HTML manpages (sibling links under man/) and the narrative
+# manuals (User/HAL/Integrator), which reference man pages in the same
+# name(section) form and now link across into ../man/man<N>/.
+#
 # manxref-root (passed from the Submakefile) points at the troff man tree
 # docs/build/man[/<lang>], whose man<N>/ dirs enumerate every page including
 # generated component pages and .so stubs.  Absent => no-op, safe to always load.
+# manxref-linkbase is the relative path from the page to those man<N>/ dirs
+# (default "../" for a sibling manpage; narrative pages pass their own depth).
 
 require 'asciidoctor'
 require 'asciidoctor/extensions'
@@ -93,6 +99,12 @@ def process(document, output)
       self_name = (document.attr('mantitle') || '').downcase
       self_vol  = (document.attr('manvolnum') || '').to_s
 
+      # Relative path from this page to the man<N>/ dirs.  Manpages sit beside
+      # each other under man/, so the default reaches a sibling section dir;
+      # narrative pages pass their own depth-adjusted base (../man/, ../../man/).
+      base = document.attr('manxref-linkbase')
+      base = '../' if base.nil? || base.empty?
+
       self.class.each_editable_text(output) do |text|
         text.gsub(TOKEN) do
           whole = Regexp.last_match(0)
@@ -101,7 +113,7 @@ def process(document, output)
           # Never link a page to itself.
           next whole if name.downcase == self_name && sec == self_vol
           href = idx["#{name.downcase}\t#{sec}"]
-          href ? %(<a class="man-xref" href="../#{href}">#{whole}</a>) : whole
+          href ? %(<a class="man-xref" href="#{base}#{href}">#{whole}</a>) : whole
         end
       end
     end