podman

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
187