CI check for --help vs man pages: usability fix

The output of this CI script leaves much to be desired: it is
output from 'diff' with little clarity on what exactly is wrong.

The proper fix is to make the output clear and readable:

    podman containers --help lists a 'foo' subcommand that
     is not present in docs/podman-containers.1.md

Doing this in bash would take many hours and be fragile
gibberish code. This does not seem worth the effort: the
likely case is that breakages reported by this script
will be due to a newly added subcommand, and the PR
author will find it obvious what to do. Ergo, plan B:
if the test fails, display a blurb at the end describing
how to interpret results. Three minutes' effort, plus
five for writing this commit message.

Signed-off-by: Ed Santiago <santiago@redhat.com>

1 files changed, 22 insertions, 0 deletions

diff --git a/hack/podman-commands.sh b/hack/podman-commands.sh
index eb599763c..7530e20d0 100755
--- a/hack/podman-commands.sh
+++ b/hack/podman-commands.sh
@@ -82,4 +82,26 @@ function compare_help_and_man() {
 
 compare_help_and_man
 
+if [ $rc -ne 0 ]; then
+    cat <<EOF
+
+**************************
+** INTERPRETING RESULTS **
+**************************************************************************
+*
+* The above results show differences between 'podman --help' and
+* podman man pages.
+*
+* The 'checking:' header indicates the specific command (and possibly
+* subcommand) being tested, e.g. podman --help vs docs/podman.1.md.
+*
+* A '-' indicates a subcommand present in 'podman --help' but not the
+* corresponding man page.
+*
+* A '+' indicates a subcommand present in the man page but not --help.
+*
+**************************************************************************
+EOF
+fi
+
 exit $rc