Formalize our compare-against-docker mechanism

Long-term followup to containers#14917. This adds a new one-off script,
to be run periodically, which runs our man-page crossref
against docker, highlighting commands and options that docker
lists in its --help but we don't list in our man pages.

Signed-off-by: Ed Santiago <[email protected]>

hack/xref-docker-options

@@ -0,0 +1,73 @@
+#!/bin/bash
+#
+# Compare against docker options, see what (if anything) podman is missing.
+#
+
+# Hardcoded list of options we don't want to show. Some of these are
+# implemented in podman but hidden (so of course not in man pages);
+# some are not implemented and never will be (swarm).
+declare -a hidden=(
+    "docker --config"                    # Hidden
+    "docker --context"                   # Hidden
+    "docker --debug"                     # Hidden
+    "docker --host"                      # Hidden
+    "docker -D"                          # Hidden
+    "docker -H"                          # Hidden
+
+    "docker .* --gpus"                   # Not likely to be implemented
+    "docker .* --isolation"              # Only for Windows containers
+    "docker .* --kernel-memory"          # CGroupsV1 only, present but hidden
+    "docker .* --link"                   # Deprecated in docker
+    "docker .* --runtime"                # Global option under podman
+    "docker .* --storage-opt"            # Global option under podman
+
+    "docker (container|image) ls"        # Hidden alias to list
+    "docker context"                     # Hidden
+
+    # Hidden
+    "docker (container |)logs --details"
+    "docker manifest (create|inspect|push) --insecure"
+    "docker manifest inspect --verbose"
+    "docker manifest push --purge"
+    "docker run --dns-option"
+
+    # None of these will ever be implemented
+    "docker (node|plugin|service|stack|swarm)"
+)
+IFS='|' hidden_re="${hidden[*]}"
+
+XREF_SCRIPT=hack/xref-helpmsgs-manpages
+TMP_SCRIPT=${XREF_SCRIPT}-docker
+
+cp $XREF_SCRIPT $TMP_SCRIPT
+
+# docker --help differs from podman --help
+DIFF="diff --git a/$TMP_SCRIPT b/hack/$TMP_SCRIPT
+index de9ef8630..b9e4bd0ef 100755
+--- a/$TMP_SCRIPT
++++ b/$TMP_SCRIPT
+@@ -230,8 +230,8 @@ sub podman_help {
+         #       ....
+         #
+         # Start by identifying the section we're in...
+-        if (\$line =~ /^Available\\s+(Commands):/) {
+-            \$section = lc \$1;
++        if (\$line =~ /^(Available|Management\\s+)?(Commands):/) {
++            \$section = lc \$2;
+         }
+         elsif (\$line =~ /^(Options):/) {
+             \$section = lc \$1;
+"
+
+patch --quiet -p1 <<<"$DIFF"
+
+# Sometimes this produces no output at all. Likely cause is that you
+# have inconsistent .md files, solution is 'make docs'. If that doesn't
+# work, remove the '2>&1 \' from the line below and rerun. I don't feel
+# it's worth the time to improve the error handling here.
+PODMAN=/usr/bin/docker $TMP_SCRIPT 2>&1 \
+    | sed -ne 's/^.*podman \+\(.*\) --help. lists .\(.*\)., which is not.*/- [ ] docker \1 \2/p' \
+    | sed -e 's/ \+/ /g' \
+    | grep -vE "($hidden_re)\$"
+
+rm -f $TMP_SCRIPT