hack/man_page_checker - improve diagnostics
Make the errors more readable, with clearer instructions on
what to look for, and which filename, and what we expect to
see, and perhaps even how to approach a fix.
@@ -30,8 +30,11 @@ for md in *.1.md;do
# care only about the first.
name=$(egrep -A1 '^#* NAME' $md|tail -1|awk '{print $1}' | tr -d \\\\)
- if [ "$name" != "$(basename $md .1.md)" ]; then
- printf "%-32s NAME= %s\n" $md $name
+ 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
@@ -57,8 +60,11 @@ for md in $(ls -1 *-*.1.md | grep -v remote);do
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
@@ -82,16 +88,21 @@ for md in *.1.md;do
# arguments are bracketed by single ones.
# E.g. '**podman 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 \* | tr ' ' '-')
- if [ "$md" != "$cmd.1.md" ]; then
- printf " %-32s SYNOPSIS = %s\n" $md "$cmd"
+ cmd=$(echo "$synopsis" | sed -e 's/\(.*\)\*\*.*/\1/' | tr -d \*)
+ md_nodash=$(basename "$md" .1.md | tr '-' ' ')
+ if [ "$cmd" != "$md_nodash" -a "$cmd" != "podman-remote" ]; 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 foo --help',
# but *lower case bracketed by asterisks* in the man page
if expr "$synopsis" : ".*[A-Z]" >/dev/null; then
- printf " %-32s UPPER-CASE '%s'\n" $md "$synopsis"
+ echo
+ printf "Inconsistent capitalization in SYNOPSIS in %s\n" $md
+ printf " '%s' should not contain upper-case characters\n" "$synopsis"
rc=1
fi
