docs: report manpage NAME drift as a CI warning

The pin keeps the build correct, but a translated command name still drifts
from the filename and is worth seeing. scripts/manpage-name-check.sh scans
the built man tree and reports any page whose .TH name disagrees with its
filename. It never fails; in CI it writes a job summary of the drift and one
warning pointing to it (per-page annotations are capped by GitHub and just
hide the count). A CI step runs it after the doc build. The NAME lines live
in Weblate.

Author: grandixximo

.github/workflows/ci.yml

@@ -175,6 +175,8 @@ jobs:
       run: |
         set -x
         .github/scripts/build-doc.sh
+    - name: Check manpage names match filenames
+      run: scripts/manpage-name-check.sh docs/build/man
     - name: Verify no untracked or modified files after build
       run: |
         #*.po and documentation.pot are modifyed by build. Ignore them for now.

scripts/manpage-name-check.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# Report man pages whose rendered NAME does not match their filename.
+# asciidoctor takes the .TH name from the page's NAME section, the build pins the filename with -o, so a translated NAME just leaves the two disagreeing.
+# Never fails the build: under GitHub Actions it writes a job summary of the drift and one warning pointing to it, otherwise plain lines.
+# The NAME lines are managed in Weblate, so fixes go there.
+# Argument: the built man tree to scan (default docs/build/man).
+
+set -u
+
+ROOT="${1:-docs/build/man}"
+
+if [ ! -d "$ROOT" ]; then
+    echo "I: $ROOT not found, build the man pages first"
+    exit 0
+fi
+
+# Lowercase and drop the roff backslash .TH escapes into names.
+norm() { local s=${1//\\/}; printf '%s' "${s,,}"; }
+
+count=0
+summary=""
+while IFS= read -r -d '' f; do
+    # Skip .so alias stubs: redirects with no .TH of their own.
+    case "$(head -n 1 "$f")" in
+    ".so "*) continue ;;
+    esac
+    th=$(sed -ne 's/^\.TH "\([^"]*\)".*/\1/p' "$f" | head -n 1)
+    [ -n "$th" ] || continue
+    base=${f##*/}
+    stem=${base%.*}
+    [ "$(norm "$th")" = "$(norm "$stem")" ] && continue
+
+    rel=${f#"$ROOT"/}
+    lang=${rel%%/*}
+    case "$lang" in man[0-9]*) lang=en ;; esac
+    # Plain line for a local run.  In CI the full list goes to the job summary
+    # below; per-page annotations are capped by GitHub and just hide the count.
+    [ -n "${GITHUB_ACTIONS:-}" ] || printf 'W: %s: %s has NAME %s\n' "$lang" "$stem" "$th"
+    summary="${summary}| ${lang} | ${stem} | ${th} |"$'\n'
+    count=$((count + 1))
+done < <(find "$ROOT" -type f -name '*.[0-9]' -print0 | sort -z)
+
+echo "I: $count manpage NAME/filename mismatch(es)"
+
+if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+    {
+        echo "## Manpage NAME mismatches: $count"
+        if [ "$count" -gt 0 ]; then
+            echo
+            echo "Translated NAME lines that drifted from the command name."
+            echo "The left side of a NAME line is a command identifier and must"
+            echo "stay verbatim; fix these in Weblate."
+            echo
+            echo "| lang | page | rendered NAME |"
+            echo "| ---- | ---- | ------------- |"
+            printf '%s' "$summary"
+        fi
+    } >> "$GITHUB_STEP_SUMMARY"
+fi
+
+# One annotation pointing at the summary, rather than one per page.
+if [ -n "${GITHUB_ACTIONS:-}" ] && [ "$count" -gt 0 ]; then
+    echo "::warning title=manpage NAME drift::$count manpage NAME line(s) disagree with their filename, see the job summary for the list"
+fi
+
+exit 0