github.com/containers/podman/v5@v5.1.0-rc1/hack/man-page-checker (about) 1 #!/usr/bin/env bash 2 # 3 # man-page-checker - validate and cross-reference man page names 4 # 5 6 verbose= 7 for i; do 8 case "$i" in 9 -v|--verbose) verbose=verbose ;; 10 esac 11 done 12 13 14 die() { 15 echo "$(basename $0): $*" >&2 16 exit 1 17 } 18 19 cd $(dirname $0)/../docs/source/markdown || die "Please run me from top-level libpod dir" 20 21 rc=0 22 23 for md in *.1.md;do 24 # Read the first line after '# NAME' (or '## NAME'). (FIXME: # and ## 25 # are not the same; should we stick to one convention?) 26 # There may be more than one name, e.g. podman-info.1.md has 27 # podman-system-info then another line with podman-info. We 28 # care only about the first. 29 name=$(grep -E -A1 '^#* NAME' $md|tail -1|awk '{print $1}' | tr -d \\\\) 30 31 expect=$(basename $md .1.md) 32 if [ "$name" != "$expect" ]; then 33 echo 34 printf "Inconsistent program NAME in %s:\n" $md 35 printf " NAME= %s (expected: %s)\n" $name $expect 36 rc=1 37 fi 38 done 39 40 # Pass 2: compare descriptions. 41 # 42 # Make sure the descriptive text in podman-foo.1.md matches the one 43 # in the table in podman.1.md. podman-remote is not a podman subcommand, 44 # so it is excluded here. 45 for md in $(ls -1 *-*.1.md | grep -v remote);do 46 desc=$(grep -E -A1 '^#* NAME' $md|tail -1|sed -e 's/^podman[^ ]\+ - //') 47 48 # podman.1.md has a two-column table; podman-*.1.md all have three. 49 parent=$(echo $md | sed -e 's/^\(.*\)-.*$/\1.1.md/') 50 if [[ $parent =~ "podman-auto" ]]; then 51 # podman-auto-update.1.md is special cased as it's structure differs 52 # from that of other man pages where main and sub-commands split by 53 # dashes. 54 parent="podman.1.md" 55 fi 56 x=3 57 if expr -- "$parent" : ".*-" >/dev/null; then 58 x=4 59 fi 60 61 # Find the descriptive text in the parent man page. 62 # Strip off the final period; let's not warn about such minutia. 63 parent_desc=$(grep $md $parent | awk -F'|' "{print \$$x}" | sed -e 's/^ \+//' -e 's/ \+$//' -e 's/\.$//') 64 65 if [ "$desc" != "$parent_desc" ]; then 66 echo 67 printf "Inconsistent subcommand descriptions:\n" 68 printf " %-32s = '%s'\n" $md "$desc" 69 printf " %-32s = '%s'\n" $parent "$parent_desc" 70 printf "Please ensure that the NAME section of $md\n" 71 printf "matches the subcommand description in $parent\n" 72 rc=1 73 fi 74 done 75 76 # Helper function: compares man page synopsis vs --help usage message 77 function compare_usage() { 78 local cmd="$1" 79 local from_man="$2" 80 81 # Special case: this is an external call to docker 82 if [[ $cmd = "podman compose" ]] || [[ $cmd = "podmansh" ]]; then 83 return 84 fi 85 86 # Sometimes in CI we run before podman gets built. 87 test -x ../../../bin/podman || return 88 89 # Run 'cmd --help', grab the line immediately after 'Usage:' 90 local help_output=$(../../../bin/$cmd --help) 91 local from_help=$(echo "$help_output" | grep -A1 '^Usage:' | tail -1) 92 93 # strip off command name from both 94 from_man=$(sed -e "s/\*\*$cmd\*\*[[:space:]]*//" <<<"$from_man") 95 from_help=$(sed -e "s/^[[:space:]]*${cmd}[[:space:]]*//" <<<"$from_help") 96 97 # man page lists 'foo [*options*]', help msg shows 'foo [flags]'. 98 # Make sure if one has it, the other does too. 99 if expr "$from_man" : "\[\*options\*\]" >/dev/null; then 100 if expr "$from_help" : "\[options\]" >/dev/null; then 101 : 102 else 103 echo "WARNING: $cmd: man page shows '[*options*]', help does not show [options]" 104 rc=1 105 fi 106 elif expr "$from_help" : "\[flags\]" >/dev/null; then 107 echo "WARNING: $cmd: --help shows [flags], man page does not show [*options*]" 108 rc=1 109 fi 110 111 # Strip off options and flags; start comparing arguments 112 from_man=$(sed -e 's/^\[\*options\*\][[:space:]]*//' <<<"$from_man") 113 from_help=$(sed -e 's/^\[flags\][[:space:]]*//' <<<"$from_help") 114 115 # Args in man page are '*foo*', in --help are 'FOO'. Convert all to 116 # UPCASE simply because it stands out better to the eye. 117 from_man=$(sed -e 's/\*\([a-z-]\+\)\*/\U\1/g' <<<"$from_man") 118 119 # FIXME: one of the common patterns is for --help to show 'POD [POD...]' 120 # but man page show 'pod ...'. This conversion may help one day, but 121 # not yet: there are too many inconsistencies such as '[pod ...]' 122 # (brackets) and 'pod...' (no space between). 123 # from_help=$(sed -e 's/\([A-Z]\+\)[[:space:]]\+\[\1[[:space:]]*\.\.\.\]/\1 .../' <<<"$from_help") 124 125 # Compare man-page and --help usage strings. For now, do so only 126 # when run with --verbose. 127 if [[ "$from_man" != "$from_help" ]]; then 128 if [ -n "$verbose" ]; then 129 printf "%-25s man='%s' help='%s'\n" "$cmd:" "$from_man" "$from_help" 130 # Yeah, we're not going to enable this as a blocker any time soon. 131 # rc=1 132 fi 133 fi 134 } 135 136 # Pass 3: compare synopses. 137 # 138 # Make sure the SYNOPSIS line in podman-foo.1.md reads '**podman foo** ...' 139 for md in *.1.md;do 140 # FIXME: several pages have a multi-line form of SYNOPSIS in which 141 # many or all flags are enumerated. Some of these are trivial 142 # and really should be made into one line (podman-container-exists, 143 # container-prune, others); some are more complicated and I 144 # would still like to see them one-lined (container-runlabel, 145 # image-trust) but I'm not 100% comfortable doing so myself. 146 # To view those: 147 # $ less $(for i in docs/*.1.md;do x=$(grep -A2 '^#* SYNOPSIS' $i|tail -1); if [ -n "$x" ]; then echo $i;fi;done) 148 # 149 synopsis=$(grep -E -A1 '^#* SYNOPSIS' $md|tail -1) 150 151 # Command name must be bracketed by double asterisks; options and 152 # arguments are bracketed by single ones. 153 # E.g. '**podman volume inspect** [*options*] *volume*...' 154 # Get the command name, and confirm that it matches the md file name. 155 cmd=$(echo "$synopsis" | sed -e 's/\(.*\)\*\*.*/\1/' | tr -d \*) 156 md_nodash=$(basename "$md" .1.md | tr '-' ' ') 157 if [[ $md_nodash = 'podman auto update' ]]; then 158 # special case: the command is "auto-update", with a hyphen 159 md_nodash='podman auto-update' 160 fi 161 if [[ "$cmd" != "$md_nodash" ]] && [[ "$cmd" != "podman-remote" ]]; then 162 echo 163 printf "Inconsistent program name in SYNOPSIS in %s:\n" $md 164 printf " SYNOPSIS = %s (expected: '%s')\n" "$cmd" "$md_nodash" 165 rc=1 166 fi 167 168 # The convention is to use UPPER CASE in 'podman foo --help', 169 # but *lower case bracketed by asterisks* in the man page 170 if expr "$synopsis" : ".*[A-Z]" >/dev/null; then 171 echo 172 printf "Inconsistent capitalization in SYNOPSIS in %s\n" $md 173 printf " '%s' should not contain upper-case characters\n" "$synopsis" 174 rc=1 175 fi 176 177 # (for debugging, and getting a sense of standard conventions) 178 #printf " %-32s ------ '%s'\n" $md "$synopsis" 179 180 # If bin/podman is available, run "cmd --help" and compare Usage 181 # messages. This is complicated, so do it in a helper function. 182 compare_usage "$md_nodash" "$synopsis" 183 done 184 185 186 exit $rc