Import LinuxCNC source tree

scripts/manpage-name-check.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+# Report man pages whose rendered NAME drifted from 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.
+# Run after building the docs.  Argument: the built man tree (default docs/build/man).
+# Quiet when nothing drifted.  When something has, it prints each page with the
+# string to search in Weblate and its current value, so a translator can fix it.
+# Never fails the build unless --enforce or MANPAGE_NAME_CHECK_ENFORCE is set:
+# under GitHub Actions it writes the same list to the job
+# summary and emits one warning pointing at it.  The NAME lines are managed in
+# Weblate, so fixes go there.
+
+import os
+import re
+import sys
+import glob
+
+# The script lives in scripts/, the docs are one level up at ../docs, so it runs from anywhere.
+HERE = os.path.dirname(os.path.realpath(__file__, strict=True))
+DOCS = os.path.normpath(os.path.join(HERE, '..', 'docs'))
+MAN = os.path.join(DOCS, 'build/man')
+PO = os.path.join(DOCS, 'po')
+SRC = os.path.join(DOCS, 'src/man')
+
+def th_name(troff):
+    """The .TH page name, lowercased with the roff backslash stripped, or None for an .so alias stub."""
+    with open(troff, encoding='utf-8', errors='replace') as f:
+        if f.readline().startswith('.so '):
+            return None
+        f.seek(0)
+        for line in f:
+            m = re.match(r'\.TH "([^"]*)"', line)
+            if m:
+                return m.group(1).replace('\\', '').lower()
+    return None
+
+def name_line(page):
+    """The first line of the NAME section of a page's AsciiDoc source, or None for a comp page rendered straight to troff."""
+    for adoc in sorted(glob.glob(f'{SRC}/man*/{page}.*.adoc')):
+        lines = open(adoc, encoding='utf-8', errors='replace').read().splitlines()
+        for i, line in enumerate(lines):
+            if line.strip() == '== NAME':
+                for rest in lines[i + 1:]:
+                    if rest.strip():
+                        return rest.strip()
+    return None
+
+_po = {}
+def po(lang):
+    """Parse docs/po/<lang>.po into {msgid: msgstr}, joining the continuation lines that wrap one string."""
+    if lang not in _po:
+        d = {}
+        mid = mstr = mode = None
+        for line in open(f'{PO}/{lang}.po', encoding='utf-8', errors='replace'):
+            if line.startswith('msgid '):
+                if mid is not None:
+                    d[mid] = mstr or ''
+                mid, mstr, mode = line[6:].strip().strip('"'), None, 'id'
+            elif line.startswith('msgstr '):
+                mstr, mode = line[7:].strip().strip('"'), 'str'
+            elif line.startswith('"'):
+                s = line.strip().strip('"')
+                if mode == 'id':
+                    mid += s
+                elif mode == 'str':
+                    mstr += s
+            elif not line.strip() and mid is not None:
+                d[mid] = mstr or ''
+                mid = mstr = mode = None
+        if mid is not None:
+            d[mid] = mstr or ''
+        _po[lang] = d
+    return _po[lang]
+
+def weblate_string(lang, page):
+    """Return (search, current): the text to search for in Weblate and its current translation."""
+    d = po(lang)
+    th = page.upper()
+    # A comp page's name is a troff .TH string, searched by the uppercase name.
+    if d.get(th, '').strip() and d[th].strip().lower() != page.lower():
+        return th, d[th]
+    # An AsciiDoc page's name lives in the NAME line, searched by its text.
+    nl = name_line(page)
+    if nl:
+        cur = d.get(nl)
+        if cur is None:                                  # the source line and the msgid can differ in trailing text
+            for mid, mstr in d.items():
+                if mid.startswith(page) and ' - ' in mid:
+                    nl, cur = mid, mstr
+                    break
+        return nl, cur if cur is not None else '(search the text)'
+    return page, '(unknown)'
+
+def drifted(man):
+    """Yield (lang, page) for every built man page whose .TH name does not match its filename."""
+    for dirpath, _dirs, files in os.walk(man):
+        for fn in files:
+            if not re.search(r'\.\d$', fn):
+                continue
+            th = th_name(os.path.join(dirpath, fn))
+            page = re.sub(r'\.\d+$', '', fn)
+            if th is None or th == page.lower():
+                continue
+            lang = os.path.relpath(dirpath, man).split(os.sep)[0]
+            yield ('en' if re.fullmatch(r'man\d+', lang) else lang), page
+
+def collect(man):
+    """All drifted rows as (lang, search, current), sorted, English dropped."""
+    rows = []
+    for lang, page in drifted(man):
+        if lang == 'en':                                 # English is the reference, it never drifts
+            continue
+        search, current = weblate_string(lang, page)
+        rows.append((lang, search, current))
+    rows.sort()
+    return rows
+
+def print_local(rows):
+    print(f'# {len(rows)} man-page NAME mismatches. Search the "search" text in the Weblate docs component, language in brackets.')
+    for lang, search, current in rows:
+        print(f'\n[{lang}]')
+        print(f'    search:  {search}')
+        print(f'    current: {current}')
+
+def write_summary(rows, fh):
+    fh.write(f'## Manpage NAME mismatches: {len(rows)}\n\n')
+    fh.write('Translated NAME lines that drifted from the command name.\n')
+    fh.write('Search the "search" text in the Weblate docs component for the language and fix it there.\n\n')
+    fh.write('| lang | search | current |\n')
+    fh.write('| ---- | ------ | ------- |\n')
+    for lang, search, current in rows:
+        cells = (c.replace('|', '\\|') for c in (lang, search, current))
+        fh.write('| %s | %s | %s |\n' % tuple(cells))
+
+def main(argv):
+    enforce = '--enforce' in argv or os.environ.get('MANPAGE_NAME_CHECK_ENFORCE')
+    args = [a for a in argv if a != '--enforce']
+    man = args[1] if len(args) > 1 else MAN
+    # A built tree has troff pages; without them the docs are not built and a
+    # silent "all clean" would read as success when nothing was actually scanned.
+    if not any(re.search(r'\.\d$', f) for _root, _dirs, files in os.walk(man) for f in files):
+        print(f'{man}: no built man pages found, build the docs first (make manpages docs).', file=sys.stderr)
+        return 1
+    rows = collect(man)
+    if not rows:
+        return 0                                         # quiet when nothing drifted
+    print_local(rows)
+    summary = os.environ.get('GITHUB_STEP_SUMMARY')
+    if summary:
+        with open(summary, 'a', encoding='utf-8') as fh:
+            write_summary(rows, fh)
+    if os.environ.get('GITHUB_ACTIONS'):
+        print(f'::warning title=manpage NAME drift::{len(rows)} manpage NAME line(s) disagree with their filename, see the job summary for the list to fix in Weblate')
+    return 1 if enforce else 0
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))