Adapt ramalama script to a command with a dash in its name

Also remove some old cruft from the script.

Signed-off-by: Martin Skøtt <[email protected]>

Author: mskott

hack/man-page-checker

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+#
+# man-page-checker - validate and cross-reference man page names
+#
+verbose=
+for i; do
+    case "$i" in
+        -v|--verbose)   verbose=verbose ;;
+    esac
+done
+
+
+die() {
+    echo "$(basename $0): $*" >&2
+    exit 1
+}
+
+cd $(dirname $0)/../docs/ || die "Please run me from top-level libpod dir"
+
+rc=0
+
+for md in *.1.md;do
+    # Read the first line after '# NAME' (or '## NAME'). (FIXME: # and ##
+    #               are not the same; should we stick to one convention?)
+    # There may be more than one name, e.g. podman-bootc-info.1.md has
+    # podman-bootc-system-info then another line with podman-bootc-info. We
+    # care only about the first.
+    name=$(grep -E -A1 '^#* NAME' $md|tail -1|awk '{print $1}' | tr -d \\\\)
+
+    expect=$(basename $md .1.md)
+    if [ "$name" != "$expect" ]; then
+        echo
+        printf "Inconsistent program NAME in %s:\n" $md
+        printf "  NAME= %s  (expected: %s)\n" $name $expect
+        rc=1
+    fi
+done
+
+# Pass 2: compare descriptions.
+#
+# Make sure the descriptive text in podman-bootc-foo.1.md matches the one
+# in the table in podman-bootc.1.md. 
+for md in $(ls -1 *-*-*.1.md | grep -v remote);do
+    desc=$(grep -E -A1 '^#* NAME' $md|tail -1|sed -e 's/^podman-bootc[^ ]\+ - //')
+
+    # podman-bootc.1.md has a two-column table; podman-bootc-*-*.1.md all have three.
+    parent=$(echo $md | sed -e 's/^\(.*\)-.*$/\1.1.md/')
+    x=3
+    if expr -- "$parent" : ".*-.*-" >/dev/null; then
+        x=4
+    fi
+
+    # Find the descriptive text in the parent man page.
+    # Strip off the final period; let's not warn about such minutia.
+    parent_desc=$(grep $md $parent | awk -F'|' "{print \$$x}" | sed -e 's/^ \+//' -e 's/ \+$//' -e 's/\.$//')
+
+    if [ "$desc" != "$parent_desc" ]; then
+        echo
+        printf "Inconsistent subcommand descriptions:\n"
+        printf "  %-32s = '%s'\n" $md "$desc"
+        printf "  %-32s = '%s'\n" $parent "$parent_desc"
+        printf "Please ensure that the NAME section of $md\n"
+        printf "matches the subcommand description in $parent\n"
+        rc=1
+    fi
+done
+
+# Helper function: compares man page synopsis vs --help usage message
+function compare_usage() {
+    local cmd="$1"
+    local from_man="$2"
+
+    # Sometimes in CI we run before podman-bootc gets built.
+    test -x ../../../bin/podman-bootc || return
+
+    # Run 'cmd --help', grab the line immediately after 'Usage:'
+    local help_output=$(../../../bin/$cmd --help)
+    local from_help=$(echo "$help_output" | grep -A1 '^Usage:' | tail -1)
+
+    # strip off command name from both
+    from_man=$(sed -e "s/\*\*$cmd\*\*[[:space:]]*//" <<<"$from_man")
+    from_help=$(sed -e "s/^[[:space:]]*${cmd}[[:space:]]*//" <<<"$from_help")
+
+    # man page lists 'foo [*options*]', help msg shows 'foo [flags]'.
+    # Make sure if one has it, the other does too.
+    if expr "$from_man" : "\[\*options\*\]" >/dev/null; then
+        if expr "$from_help" : "\[options\]" >/dev/null; then
+            :
+        else
+            echo "WARNING: $cmd: man page shows '[*options*]', help does not show [options]"
+            rc=1
+       fi
+    elif expr "$from_help" : "\[flags\]" >/dev/null; then
+        echo "WARNING: $cmd: --help shows [flags], man page does not show [*options*]"
+        rc=1
+    fi
+
+    # Strip off options and flags; start comparing arguments
+    from_man=$(sed  -e 's/^\[\*options\*\][[:space:]]*//' <<<"$from_man")
+    from_help=$(sed -e 's/^\[flags\][[:space:]]*//'      <<<"$from_help")
+
+    # Args in man page are '*foo*', in --help are 'FOO'. Convert all to
+    # UPCASE simply because it stands out better to the eye.
+    from_man=$(sed -e 's/\*\([a-z-]\+\)\*/\U\1/g' <<<"$from_man")
+
+    # FIXME: one of the common patterns is for --help to show 'POD [POD...]'
+    # but man page show 'pod ...'. This conversion may help one day, but
+    # not yet: there are too many inconsistencies such as '[pod ...]'
+    # (brackets) and 'pod...' (no space between).
+#    from_help=$(sed -e 's/\([A-Z]\+\)[[:space:]]\+\[\1[[:space:]]*\.\.\.\]/\1 .../' <<<"$from_help")
+
+    # Compare man-page and --help usage strings. For now, do so only
+    # when run with --verbose.
+    if [[ "$from_man" != "$from_help" ]]; then
+        if [ -n "$verbose" ]; then
+            printf "%-25s man='%s' help='%s'\n" "$cmd:" "$from_man" "$from_help"
+            # Yeah, we're not going to enable this as a blocker any time soon.
+            # rc=1
+        fi
+    fi
+}
+
+# Pass 3: compare synopses.
+#
+# Make sure the SYNOPSIS line in podman-bootc-foo.1.md reads '**podman-bootc foo** ...'
+for md in *.1.md;do
+    # FIXME: several pages have a multi-line form of SYNOPSIS in which
+    #        many or all flags are enumerated. Some of these are trivial
+    #        and really should be made into one line (podman-bootc-container-exists,
+    #        container-prune, others); some are more complicated and I
+    #        would still like to see them one-lined (container-runlabel,
+    #        image-trust) but I'm not 100% comfortable doing so myself.
+    #        To view those:
+    #           $ less $(for i in docs/*.1.md;do x=$(grep -A2 '^#* SYNOPSIS' $i|tail -1); if [ -n "$x" ]; then echo $i;fi;done)
+    #
+    synopsis=$(grep -E -A1 '^#* SYNOPSIS' $md|tail -1)
+
+    # Command name must be bracketed by double asterisks; options and
+    # arguments are bracketed by single ones.
+    #   E.g. '**podman-bootc volume inspect** [*options*] *volume*...'
+    # Get the command name, and confirm that it matches the md file name.
+    cmd=$(echo "$synopsis" | sed -e 's/\(.*\)\*\*.*/\1/' | tr -d \*)
+    md_nodash=$(basename "$md" .1.md | sed 's/-/ /2')
+    if [[ "$cmd" != "$md_nodash" ]]; then
+        echo
+        printf "Inconsistent program name in SYNOPSIS in %s:\n" $md
+        printf "  SYNOPSIS = %s (expected: '%s')\n" "$cmd" "$md_nodash"
+        rc=1
+    fi
+
+    # The convention is to use UPPER CASE in 'podman-bootc foo --help',
+    # but *lower case bracketed by asterisks* in the man page
+    if expr "$synopsis" : ".*[A-Z]" >/dev/null; then
+        echo
+        printf "Inconsistent capitalization in SYNOPSIS in %s\n" $md
+        printf "  '%s' should not contain upper-case characters\n" "$synopsis"
+        rc=1
+    fi
+
+    # (for debugging, and getting a sense of standard conventions)
+    #printf "  %-32s ------ '%s'\n" $md "$synopsis"
+
+    # If bin/podman-bootc is available, run "cmd --help" and compare Usage
+    # messages. This is complicated, so do it in a helper function.
+    compare_usage "$md_nodash" "$synopsis"
+done
+
+exit $rc