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, as GitHub warning annotations plus a job summary, never failing.
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,63 @@
+#!/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 emits warning annotations and a job summary, 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
+    if [ -n "${GITHUB_ACTIONS:-}" ]; then
+        printf '::warning title=manpage NAME mismatch::%s: %s has NAME %s\n' "$lang" "$stem" "$th"
+    else
+        printf 'W: %s: %s has NAME %s\n' "$lang" "$stem" "$th"
+    fi
+    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
+
+exit 0