From 3a9d14d4e93fb10b1ad9e02799480201783af398 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 14 Feb 2023 07:46:27 -0700 Subject: [PATCH] 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 --- docs/source/markdown/podman-history.1.md | 4 +- .../markdown/podman-machine-list.1.md.in | 6 +- .../markdown/podman-network-inspect.1.md | 16 +++--- .../source/markdown/podman-network-ls.1.md.in | 16 +++--- docs/source/markdown/podman-search.1.md.in | 6 +- .../podman-system-connection-list.1.md | 6 +- hack/xref-helpmsgs-manpages | 55 ++++++++++++++++++- 7 files changed, 81 insertions(+), 28 deletions(-) diff --git a/docs/source/markdown/podman-history.1.md b/docs/source/markdown/podman-history.1.md index 62503a1f71..ef40f9783f 100644 --- a/docs/source/markdown/podman-history.1.md +++ b/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** diff --git a/docs/source/markdown/podman-machine-list.1.md.in b/docs/source/markdown/podman-machine-list.1.md.in index 6f79f0fb3f..80373906fb 100644 --- a/docs/source/markdown/podman-machine-list.1.md.in +++ b/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** diff --git a/docs/source/markdown/podman-network-inspect.1.md b/docs/source/markdown/podman-network-inspect.1.md index c54a4e832c..4824841771 100644 --- a/docs/source/markdown/podman-network-inspect.1.md +++ b/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 diff --git a/docs/source/markdown/podman-network-ls.1.md.in b/docs/source/markdown/podman-network-ls.1.md.in index dc327de52a..709555a0f8 100644 --- a/docs/source/markdown/podman-network-ls.1.md.in +++ b/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** diff --git a/docs/source/markdown/podman-search.1.md.in b/docs/source/markdown/podman-search.1.md.in index 89df8c29f0..61926ad154 100644 --- a/docs/source/markdown/podman-search.1.md.in +++ b/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. diff --git a/docs/source/markdown/podman-system-connection-list.1.md b/docs/source/markdown/podman-system-connection-list.1.md index 99804f77fd..a344564608 100644 --- a/docs/source/markdown/podman-system-connection-list.1.md +++ b/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** diff --git a/hack/xref-helpmsgs-manpages b/hack/xref-helpmsgs-manpages index 378acb7ca1..2c75ce620c 100755 --- a/hack/xref-helpmsgs-manpages +++ b/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-.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; } } }