opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-06-24 03:08:13 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #17500 from edsantiago/xref_format_json_and_sort

Browse Source 
[CI:DOCS] man page --format xref: tighten the autocompletion check
This commit is contained in:
OpenShift Merge Robot
2023-02-14 21:27:23 -05:00
committed by GitHub
parent c542fbe923 3a9d14d4e9
commit 26abb3afd2
7 changed files with 81 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/source/markdown/podman-history.1.md
View File

@ -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**

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

@ -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**

16
docs/source/markdown/podman-network-inspect.1.md
View File

@ -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

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

@ -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**

6
docs/source/markdown/podman-search.1.md.in
View File

@ -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.

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

@ -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**

55
hack/xref-helpmsgs-manpages
View File

@ -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;
}
}
}