man page --format xref: tighten the autocompletion check

Followup to #17486: stricter checks on --format.

  * If a subcommand offers autocompletion for templates,
    it must also offer a '--format json' option.

  * If a subcommand has a --format option that DOES NOT
    offer autocompletion for templates, it must be listed
    in a hardcoded grandparented-in table of commands
    where that's not applicable. (Mostly commands
    like build, commit, save, where "format" is used
    in the context of "oci/docker").

Only likely to trigger on PRs which add new subcommands,
and is intended to catch oversights.

Also, test for alphanumeric order in man page tables.
Sort all existing tables.

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

docs/source/markdown/podman-history.1.md

@@ -27,13 +27,13 @@ Valid placeholders for the Go template are listed below:
 
 | **Placeholder**        | **Description**                                                           |
 |------------------------|---------------------------------------------------------------------------|
-| .ID                    | Image ID                                                                  |
+| .Comment               | Comment for the layer                                                     |
 | .Created               | if --human, time elapsed since creation, otherwise time stamp of creation |
 | .CreatedAt             | Time when the image layer was created                                     |
 | .CreatedBy             | Command used to create the layer                                          |
 | .CreatedSince          | Elapsed time since the image layer was created                            |
+| .ID                    | Image ID                                                                  |
 | .Size                  | Size of layer on disk                                                     |
-| .Comment               | Comment for the layer                                                     |
 | .Tags                  | Image tags                                                                |
 
 #### **--help**, **-h**

docs/source/markdown/podman-machine-list.1.md.in

@@ -38,16 +38,16 @@ Valid placeholders for the Go template are listed below:
 | .Created        | Time since VM creation          |
 | .Default        | Is default machine              |
 | .DiskSize       | Disk size of machine            |
+| .IdentityPath   | Path to ssh identity file       |
 | .LastUp         | Time machine was last up        |
 | .LastUp         | Time since the VM was last run  |
 | .Memory         | Allocated memory for machine   |
 | .Name           | VM name                         |
+| .Port           | SSH Port to use to connect to VM|
+| .RemoteUsername | VM Username for rootless Podman |
 | .Running        | Is machine running              |
 | .Stream         | Stream name                     |
 | .VMType         | VM type                         |
-| .Port           | SSH Port to use to connect to VM|
-| .RemoteUsername | VM Username for rootless Podman |
-| .IdentityPath   | Path to ssh identity file       |
 
 #### **--help**
 

docs/source/markdown/podman-network-inspect.1.md

@@ -16,18 +16,18 @@ Pretty-print networks to JSON or using a Go template.
 
 | **Placeholder**    | **Description**                           |
 |--------------------|-------------------------------------------|
-| .ID                | Network ID                                |
-| .Name              | Network name                              |
-| .Driver            | Network driver                            |
-| .Labels            | Network labels                            |
-| .Options           | Network options                           |
-| .IPAMOptions       | Network ipam options                      |
 | .Created           | Timestamp when the network was created    |
-| .Internal          | Network is internal (boolean)             |
-| .IPv6Enabled       | Network has ipv6 subnet (boolean)         |
 | .DNSEnabled        | Network has dns enabled (boolean)         |
+| .Driver            | Network driver                            |
+| .ID                | Network ID                                |
+| .Internal          | Network is internal (boolean)             |
+| .IPAMOptions       | Network ipam options                      |
+| .IPv6Enabled       | Network has ipv6 subnet (boolean)         |
+| .Labels            | Network labels                            |
+| .Name              | Network name                              |
 | .NetworkDNSServers | Array of DNS servers used in this network |
 | .NetworkInterface  | Name of the network interface on the host |
+| .Options           | Network options                           |
 | .Subnets           | List of subnets on this network           |
 
 ## EXAMPLE

docs/source/markdown/podman-network-ls.1.md.in

@@ -44,18 +44,18 @@ Valid placeholders for the Go template are listed below:
 
 | **Placeholder**    | **Description**                           |
 |--------------------|-------------------------------------------|
-| .ID                | Network ID                                |
-| .Name              | Network name                              |
-| .Driver            | Network driver                            |
-| .Labels            | Network labels                            |
-| .Options           | Network options                           |
-| .IPAMOptions       | Network ipam options                      |
 | .Created           | Timestamp when the network was created    |
-| .Internal          | Network is internal (boolean)             |
-| .IPv6Enabled       | Network has ipv6 subnet (boolean)         |
 | .DNSEnabled        | Network has dns enabled (boolean)         |
+| .Driver            | Network driver                            |
+| .ID                | Network ID                                |
+| .Internal          | Network is internal (boolean)             |
+| .IPAMOptions       | Network ipam options                      |
+| .IPv6Enabled       | Network has ipv6 subnet (boolean)         |
+| .Labels            | Network labels                            |
+| .Name              | Network name                              |
 | .NetworkDNSServers | Array of DNS servers used in this network |
 | .NetworkInterface  | Name of the network interface on the host |
+| .Options           | Network options                           |
 | .Subnets           | List of subnets on this network           |
 
 #### **--no-trunc**

docs/source/markdown/podman-search.1.md.in

@@ -55,12 +55,12 @@ Valid placeholders for the Go template are listed below:
 
 | **Placeholder** | **Description**              |
 | --------------- | ---------------------------- |
+| .Automated      | "[OK]" if image is automated |
+| .Description    | Image description            |
 | .Index          | Registry                     |
 | .Name           | Image name                   |
-| .Description    | Image description            |
-| .Stars          | Star count of image          |
 | .Official       | "[OK]" if image is official  |
-| .Automated      | "[OK]" if image is automated |
+| .Stars          | Star count of image          |
 | .Tag            | Repository tag               |
 
 Note: use .Tag only if the --list-tags is set.

docs/source/markdown/podman-system-connection-list.1.md

@@ -20,10 +20,10 @@ Valid placeholders for the Go template listed below:
 
 | **Placeholder** | **Description**                                                               |
 | --------------- | ----------------------------------------------------------------------------- |
-| .Name           | Connection Name/Identifier |
-| .Identity       | Path to file containing SSH identity |
-| .URI            | URI to podman service. Valid schemes are ssh://[user@]*host*[:port]*Unix domain socket*[?secure=True], unix://*Unix domain socket*, and tcp://localhost[:*port*] |
 | .Default        | Indicates whether connection is the default |
+| .Identity       | Path to file containing SSH identity |
+| .Name           | Connection Name/Identifier |
+| .URI            | URI to podman service. Valid schemes are ssh://[user@]*host*[:port]*Unix domain socket*[?secure=True], unix://*Unix domain socket*, and tcp://localhost[:*port*] |
 
 #### **--quiet**, **-q**
 

hack/xref-helpmsgs-manpages

@@ -72,6 +72,29 @@ for my $line (split "\n", $Format_Exceptions) {
     $Format_Exceptions{"podman-$subcommand"} = \@fields;
 }
 
+# Hardcoded list of podman commands for which '--format' does NOT mean
+# a Go format.
+#
+# I realize that it looks stupid to hardcode these: I could instead
+# check "--format ''" and look for completion strings, 'oci', 'json',
+# doesn't matter: if anything shows up, we excuse the missing '{{.'.
+# (We'd still have to make a special exception for 'podman inspect').
+#
+# My reason for hardcoding is that these should be rare exceptions
+# and we want to account for every single one. If a new command gets
+# added, with a --format option that does not autocomplete '{{.',
+# let's make sure it gets extra eyeballs.
+my %Format_Option_Is_Special = map { $_ => 1 } (
+    'build',  'image build',                    # oci | docker
+    'commit', 'container commit',               #  "  "  " "
+    'diff',   'container diff', 'image diff',   # only supports "json"
+    'generate systemd',                         #  "    "  "      "
+    'mount',  'container mount', 'image mount', #  "    "  "      "
+    'push',   'image push', 'manifest push',    # oci | v2s*
+    'save',   'image save',                     # image formats (oci-*, ...)
+    'inspect',                                  # ambiguous (container/image)
+ );
+
 # END   user-customizable section
 ###############################################################################
 
@@ -359,6 +382,30 @@ sub podman_help {
                         $help{$opt}{$1} = 1;
                     }
                 }
+
+                # If subcommand supports '--format {{.x', it should also
+                # support '--format json'
+                if (ref $help{$opt}) {
+                    my @json = _completions(@_, '--format', 'json');
+                    if (! grep { $_ eq 'json' } @json) {
+                        warn "$ME: podman @_ --format json is unimplemented\n";
+                        ++$Errs;
+                    }
+                }
+
+                else {
+                    # --format option for this subcommand does not support
+                    # completion for Go templates. This is OK for an
+                    # existing set of commands (see table at top of script)
+                    # but is a fatal error for any others, presumably a
+                    # new subcommand. Either the subcommand must be fixed
+                    # to support autocompletion, or the subcommand must be
+                    # added to our exclusion list at top.
+                    unless ($Format_Option_Is_Special{"@_"}) {
+                        warn "$ME: podman @_ --format '{{.' does not offer autocompletion\n";
+                        ++$Errs;
+                    }
+                }
            }
         }
     }
@@ -385,6 +432,7 @@ sub podman_man {
     my @most_recent_flags;
     my $previous_subcmd = '';
     my $previous_flag = '';
+    my $previous_format = '';
     while (my $line = <$fh>) {
         chomp $line;
         next unless $line;		# skip empty lines
@@ -431,7 +479,6 @@ sub podman_man {
             # In podman-<subcommand>.1.md
             #                      1   1        2  3   3    4   4         2
             elsif ($line =~ /^\|\s+(\S+)\s+\|\s+(\[(\S+)\]\((\S+)\.1\.md\))/) {
-                # $1 will be changed by recursion _*BEFORE*_ left-hand assignment
                 my ($subcmd, $blob, $shown_name, $link_name) = ($1, $2, $3, $4);
                 if ($previous_subcmd gt $subcmd) {
                     warn "$ME: $subpath:$.: '$previous_subcmd' and '$subcmd' are out of order\n";
@@ -552,6 +599,12 @@ sub podman_man {
                     # will be '...' which indicates that $format has
                     # too many subformats to document individually.
                     $man{$previous_flag}{$format} = $etc || 1;
+
+                    if (lc($format) lt lc($previous_format)) {
+                        warn "$ME: $subpath:$.: format specifier '$format' should precede '$previous_format'\n";
+                        ++$Errs;
+                    }
+                    $previous_format = $format;
                 }
             }
         }