From 8facf1ee881d434927dc6d2fcf3c66677638d609 Mon Sep 17 00:00:00 2001
From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com>
Date: Thu, 18 Jun 2026 21:40:24 +0800
Subject: [PATCH] docs: generate translated .so manpage stubs from the English
 original

A .so alias stub is a language-invariant redirect (just a path).
asciidoctor emits these stubs as a byproduct of rendering a translated
primary page, deriving the path from the translated NAME line, so a
stray space in a translation can break the alias and abort the htmldocs
build. Overwrite every translated stub with the canonical English one,
after the primaries that emit them are built. The stub list is found at
recipe time because the wildcard-based MAN_SRCS is empty on a clean build.
---
 docs/src/Submakefile | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/src/Submakefile b/docs/src/Submakefile
index 2bdafc3d491..911289bdd03 100644
--- a/docs/src/Submakefile
+++ b/docs/src/Submakefile
@@ -1306,6 +1306,8 @@ docclean:
 	-rm -f .include-stamp
 	-rm -f $(DOC_DIR)/.translateddocs-stamp
 	-rm -f $(DOC_DIR)/.gen_complist-stamp
+	-rm -f $(DOC_DIR)/.checkref-*-stamp
+	-rm -f $(DOC_DIR)/.manso-canonical-stamp
 	-rm -f $(OTHER_DOTFILES:.dot=.svg)
 
 
@@ -1406,6 +1408,27 @@ TRANSLATED_MAN_HTML_TARGETS := $(foreach L,$(LANGUAGES),$(MAN_HTML_TARGETS_$(cal
 TRANSLATED_GENERATED_MANPAGES := $(foreach L,$(LANGUAGES), \
     $(patsubst $(DOC_OUT_ADOC)/$(L)/man/%.adoc, $(DOC_MAN)/$(L)/%, \
         $(wildcard $(DOC_OUT_ADOC)/$(L)/man/man?/*.adoc)))
+
+# A .so alias stub is a language-invariant redirect (just a path).  asciidoctor
+# derives it from the translated NAME line, so a stray space in a translation
+# can break the alias and abort the build.  Overwrite every translated stub
+# with the canonical English one, after the translated primaries that emit them
+# are built.  Stubs are found at recipe time: wildcard MAN_SRCS is empty on a
+# clean build.
+$(DOC_DIR)/.manso-canonical-stamp: $(GENERATED_MANPAGES) $(TRANSLATED_GENERATED_MANPAGES)
+	$(Q)set -e; \
+	for S in $$(cd $(DOC_MAN) && grep -rl '^\.so ' man1 man3 man9 2>/dev/null); do \
+		for L in $(LANGUAGES); do \
+			mkdir -p "$(DOC_MAN)/$$L/$$(dirname "$$S")"; \
+			cp -f "$(DOC_MAN)/$$S" "$(DOC_MAN)/$$L/$$S"; \
+		done; \
+	done
+	@touch $@
+
+# Translated manpage HTML must see the canonical stubs, so order it after the
+# fixup (order-only: the stub troff is already a normal prerequisite).
+$(TRANSLATED_MAN_HTML_TARGETS): | $(DOC_DIR)/.manso-canonical-stamp
+
 docs: $(TRANSLATED_MAN_HTML_TARGETS)
 .SECONDARY: $(TRANSLATED_MAN_HTML_TARGETS) $(TRANSLATED_GENERATED_MANPAGES)
 endif