Maintain consistent order of short and long flag names in docs

Make the order of short and long flag names in the documentation consistent. Also adjust the man page validaten script to only allow the `**--long**, **-s**` syntax. Signed-off-by: Paul Holzinger <[email protected]>
containers · Nov 12, 2020 · f5a2e57 · f5a2e57
1 parent 7774f63
commit f5a2e57
Show file tree

Hide file tree

Showing 21 changed files with 59 additions and 52 deletions.
diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md
@@ -394,7 +394,7 @@ The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes),
 `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you don't specify a
 unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap.
 
-#### **--net**, **--network**=*string*
+#### **--network**=*mode*
 
 Sets the configuration for network namespaces when handling `RUN` instructions.
 
@@ -405,7 +405,7 @@ Valid _mode_ values are:
 container full access to local system services such as D-bus and is therefore
 considered insecure.
 - **ns:**_path_: path to a network namespace to join.
-- `private`: create a new namespace for the container (default).
+- **private**: create a new namespace for the container (default).
 
 #### **--no-cache**
 

diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
@@ -342,7 +342,7 @@ The initialization time needed for a container to bootstrap. The value can be ex
 The maximum time allowed to complete the healthcheck before an interval is considered failed.  Like start-period, the
 value can be expressed in a time format such as `1m22s`.  The default value is `30s`.
 
-#### **-h**, **--hostname**=*name*
+#### **--hostname**=*name*, **-h**
 
 Container host name
 
@@ -574,20 +574,20 @@ to the container with **--name** then it will generate a random
 string name. The name is useful any place you need to identify a container.
 This works for both background and foreground containers.
 
-#### **--network**, **--net**="*bridge*"
+#### **--network**=*bridge*, **--net**
 
-Set the Network mode for the container. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** that is set to 'none' or 'container:<name|id>'.
+Set the network mode for the container. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** that is set to **none** or **container:**_id_.
 
-Valid values are:
+Valid _mode_ values are:
 
-- `bridge`: create a network stack on the default bridge
-- `none`: no networking
-- `container:<name|id>`: reuse another container's network stack
-- `host`: use the Podman host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
-- `<network-name>|<network-id>`: connect to a user-defined network, multiple networks should be comma separated
-- `ns:<path>`: path to a network namespace to join
-- `private`: create a new namespace for the container (default)
-- `slirp4netns[:OPTIONS,...]`: use slirp4netns to create a user network stack.  This is the default for rootless containers.  It is possible to specify these additional options:
+- **bridge**: create a network stack on the default bridge;
+- **none**: no networking;
+- **container:**_id_: reuse another container's network stack;
+- **host**: use the Podman host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure;
+- _network-id_: connect to a user-defined network, multiple networks should be comma separated;
+- **ns:**_path_: path to a network namespace to join;
+- **private**: create a new namespace for the container (default)
+- **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack.  This is the default for rootless containers.  It is possible to specify these additional options:
   - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`). Default is false.
   - **cidr=CIDR**: Specify ip range to use for this network. (Default is `10.0.2.0/24`).
   - **enable_ipv6=true|false**: Enable IPv6. Default is false. (Required for `outbound_addr6`).

diff --git a/docs/source/markdown/podman-image-trust.1.md b/docs/source/markdown/podman-image-trust.1.md
@@ -37,15 +37,15 @@ Require signature (“signedBy”).
 Trust may be updated using the command **podman image trust set** for an existing trust scope.
 
 ## OPTIONS
-#### **-h**, **--help**
+#### **--help**, **-h**
   Print usage statement.
 
-#### **-f**, **--pubkeysfile**=*KEY1*
+#### **--pubkeysfile**=*KEY1*, **-f**
   A path to an exported public key on the local system. Key paths
   will be referenced in policy.json. Any path to a file may be used but locating the file in **/etc/pki/containers** is recommended. Options may be used multiple times to
   require an image be signed by multiple keys.  The **--pubkeysfile** option is required for the **signedBy** type.
 
-#### **-t**, **--type**=*value*
+#### **--type**=*value*, **-t**
   The trust type for this policy entry.
   Accepted values:
     **signedBy** (default): Require signatures with corresponding list of
@@ -59,7 +59,7 @@ Trust may be updated using the command **podman image trust set** for an existin
 #### **--raw**
   Output trust policy file as raw JSON
 
-#### **-j**, **--json**
+#### **--json**, **-j**
   Output trust as JSON for machine parsing
 
 ## EXAMPLES

diff --git a/docs/source/markdown/podman-images.1.md b/docs/source/markdown/podman-images.1.md
@@ -15,15 +15,15 @@ Displays locally stored images, their names, and their IDs.
 
 ## OPTIONS
 
-#### **-a**, **--all**
+#### **--all**, **-a**
 
 Show all images (by default filter out the intermediate image layers). The default is false.
 
 #### **--digests**
 
 Show image digests
 
-#### **-f**, **--filter**=*filter*
+#### **--filter**=*filter*, **-f**
 
 Filter output based on conditions provided
 

diff --git a/docs/source/markdown/podman-import.1.md b/docs/source/markdown/podman-import.1.md
@@ -18,7 +18,7 @@ Note: `:` is a restricted character and cannot be part of the file name.
 
 ## OPTIONS
 
-#### **-c**, **--change**=*instruction*
+#### **--change**=*instruction*, **-c**
 
 Apply the following possible instructions to the created image:
 **CMD** | **ENTRYPOINT** | **ENV** | **EXPOSE** | **LABEL** | **STOPSIGNAL** | **USER** | **VOLUME** | **WORKDIR**

diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md
@@ -15,11 +15,11 @@ Displays information pertinent to the host, current storage stats, configured co
 
 ## OPTIONS
 
-#### **-D**, **--debug**
+#### **--debug**, **-D**
 
 Show additional information
 
-#### **-f**, **--format**=*format*
+#### **--format**=*format*, **-f**
 
 Change output format to "json" or a Go template.
 

diff --git a/docs/source/markdown/podman-logs.1.md b/docs/source/markdown/podman-logs.1.md
@@ -30,7 +30,7 @@ to run containers such as CRI-O, the last started container could be from either
 
 The latest option is not supported on the remote client.
 
-#### **-n**, **--names**
+#### **--names**, **-n**
 
 Output the container name in the log
 

diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md
@@ -22,7 +22,7 @@ Upon completion of creating the network, Podman will display the path to the new
 Disables the DNS plugin for this network which if enabled, can perform container to container name
 resolution.
 
-#### **-d**, **--driver**
+#### **--driver**, **-d**
 
 Driver to manage the network (default "bridge").  Currently only `bridge` is supported.
 

diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md
@@ -46,7 +46,7 @@ value can be entered.  The password is entered without echo.
 
 Set logging driver for all created containers.
 
-#### **--network**=*cni networks*
+#### **--network**=*networks*, **--net**
 
 A comma-separated list of the names of CNI networks the pod should join.
 

diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md
@@ -63,7 +63,7 @@ The image that will be created for the infra container. Default: "k8s.gcr.io/pau
 
 Set a static IP for the pod's shared network.
 
-#### **-l**, **--label**=*label*
+#### **--label**=*label*, **-l**
 
 Add metadata to a pod (e.g., --label com.example.key=value).
 
@@ -75,17 +75,17 @@ Read in a line delimited file of labels.
 
 Set a static MAC address for the pod's shared network.
 
-#### **-n**, **--name**=*name*
+#### **--name**=*name*, **-n**
 
 Assign a name to the pod.
 
-#### **--network**=*mode*
+#### **--network**=*mode*, **--net**
 
 Set network mode for the pod. Supported values are
-- `bridge`: Create a network stack on the default bridge. This is the default for rootful containers.
-- `host`: Do not create a network namespace, all containers in the pod will use the host's network. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
+- **bridge**: Create a network stack on the default bridge. This is the default for rootful containers.
+- **host**: Do not create a network namespace, all containers in the pod will use the host's network. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
 - Comma-separated list of the names of CNI networks the pod should join.
-- `slirp4netns[:OPTIONS,...]`: use slirp4netns to create a user network stack.  This is the default for rootless containers.  It is possible to specify these additional options:
+- **slirp4netns[:OPTIONS,...]**: use slirp4netns to create a user network stack.  This is the default for rootless containers.  It is possible to specify these additional options:
   - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`). Default is false.
   - **cidr=CIDR**: Specify ip range to use for this network. (Default is `10.0.2.0/24`).
   - **enable_ipv6=true|false**: Enable IPv6. Default is false. (Required for `outbound_addr6`).
@@ -108,7 +108,7 @@ Disable creation of /etc/hosts for the pod.
 
 Write the pod ID to the file.
 
-#### **-p**, **--publish**=*port*
+#### **--publish**=*port*, **-p**
 
 Publish a port or range of ports from the pod to the host.
 

diff --git a/docs/source/markdown/podman-pod-inspect.1.md b/docs/source/markdown/podman-pod-inspect.1.md
@@ -18,7 +18,7 @@ to run pods such as CRI-O, the last started pod could be from either of those me
 
 The latest option is not supported on the remote client.
 
-#### **-f**, **--format**=*format*
+#### **--format**=*format*, **-f**
 
 Change the default output format.  This can be of a supported type like 'json'
 or a Go template.

diff --git a/docs/source/markdown/podman-restart.1.md b/docs/source/markdown/podman-restart.1.md
@@ -26,7 +26,7 @@ The latest option is not supported on the remote client.
 #### **--running**
 Restart all containers that are already in the *running* state.
 
-#### **-t**, **--time**=*time*
+#### **--time**=*time*, **-t**
 Timeout to wait before forcibly stopping the container.
 
 

diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
@@ -380,7 +380,7 @@ value can be expressed in a time format such as **1m22s**.  The default value is
 
 Print usage statement
 
-#### **-h**, **--hostname**=*name*
+#### **--hostname**=*name*, **-h**
 
 Container host name
 
@@ -600,7 +600,7 @@ to the container with **--name** then it will generate a random
 string name. The name is useful any place you need to identify a container.
 This works for both background and foreground containers.
 
-#### **--network**, **--net**=*mode*
+#### **--network**=*mode*, **--net**
 
 Set the network mode for the container. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** that is set to **none** or **container:**_id_.
 
@@ -612,7 +612,7 @@ Valid _mode_ values are:
 - **host**: use the Podman host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure;
 - _network-id_: connect to a user-defined network, multiple networks should be comma separated;
 - **ns:**_path_: path to a network namespace to join;
-- `private`: create a new namespace for the container (default)
+- **private**: create a new namespace for the container (default)
 - **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack.  This is the default for rootless containers.  It is possible to specify these additional options:
   - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`). Default is false.
   - **cidr=CIDR**: Specify ip range to use for this network. (Default is `10.0.2.0/24`).

diff --git a/docs/source/markdown/podman-system-connection-add.1.md b/docs/source/markdown/podman-system-connection-add.1.md
@@ -15,7 +15,7 @@ The user will be prompted for the remote ssh login password or key file pass phr
 
 ## OPTIONS
 
-#### **-d**, **--default**=*false*
+#### **--default**=*false*, **-d**
 
 Make the new destination the default for this user.
 
@@ -25,7 +25,7 @@ Path to ssh identity file. If the identity file has been encrypted, Podman promp
 If no identity file is provided and no user is given, Podman defaults to the user running the podman command.
 Podman prompts for the login password on the remote server.
 
-#### **-p**, **--port**=*port*
+#### **--port**=*port*, **-p**
 
 Port for ssh destination. The default value is `22`.
 

diff --git a/docs/source/markdown/podman-system-df.1.md b/docs/source/markdown/podman-system-df.1.md
@@ -14,7 +14,7 @@ Show podman disk usage
 
 Pretty-print images using a Go template
 
-#### **-v**, **--verbose**[=*true|false*]
+#### **--verbose**, **-v**
 Show detailed information on space usage
 
 ## EXAMPLE

diff --git a/docs/source/markdown/podman-volume-create.1.md b/docs/source/markdown/podman-volume-create.1.md
@@ -23,11 +23,11 @@ Specify the volume driver name (default local).
 
 Print usage statement
 
-#### **-l**, **--label**=*label*
+#### **--label**=*label*, **-l**
 
 Set metadata for a volume (e.g., --label mykey=value).
 
-#### **-o**, **--opt**=*option*
+#### **--opt**=*option*, **-o**
 
 Set driver specific options.
 For the default driver, `local`, this allows a volume to be configured to mount a filesystem on the host.

diff --git a/docs/source/markdown/podman-volume-inspect.1.md b/docs/source/markdown/podman-volume-inspect.1.md
@@ -16,11 +16,11 @@ Volumes can be queried individually by providing their full name or a unique par
 
 ## OPTIONS
 
-#### **-a**, **--all**
+#### **--all**, **-a**
 
 Inspect all volumes.
 
-#### **-f**, **--format**=*format*
+#### **--format**=*format*, **-f**
 
 Format volume output using Go template
 

diff --git a/docs/source/markdown/podman-volume-ls.1.md b/docs/source/markdown/podman-volume-ls.1.md
@@ -14,7 +14,7 @@ flag. Use the **--quiet** flag to print only the volume names.
 
 ## OPTIONS
 
-#### **-f**, **--filter**=*filter*
+#### **--filter**=*filter*, **-f**
 
 Filter volume output.
 
@@ -26,7 +26,7 @@ Format volume output using Go template.
 
 Print usage statement.
 
-#### **-q**, **--quiet**
+#### **--quiet**, **-q**
 
 Print volume output in quiet mode. Only print the volume names.
 

diff --git a/docs/source/markdown/podman-volume-prune.1.md b/docs/source/markdown/podman-volume-prune.1.md
@@ -14,7 +14,7 @@ unused volumes. To bypass the confirmation, use the **--force** flag.
 
 ## OPTIONS
 
-#### **-f**, **--force**
+#### **--force**, **-f**
 
 Do not prompt for confirmation.
 

diff --git a/docs/source/markdown/podman-volume-rm.1.md b/docs/source/markdown/podman-volume-rm.1.md
@@ -15,11 +15,11 @@ Volumes can be removed individually by providing their full name or a unique par
 
 ## OPTIONS
 
-#### **-a**, **--all**
+#### **--all**, **-a**
 
 Remove all volumes.
 
-#### **-f**, **--force**
+#### **--force**, **-f**
 
 Remove a volume by force.
 If it is being used by containers, the containers will be removed first.

diff --git a/hack/xref-helpmsgs-manpages b/hack/xref-helpmsgs-manpages
@@ -331,8 +331,15 @@ sub podman_man {
             @most_recent_flags = ();
             # As of PR #8292, all options are <h4> and anchored
             if ($line =~ s/^\#{4}\s+//) {
-                # Handle any variation of '**--foo**, **-f**'
-                while ($line =~ s/^\*\*((--[a-z0-9-]+)|(-.))\*\*(,\s+)?//g) {
+                # If option has long and short form, long must come first.
+                # This is a while-loop because there may be multiple long
+                # option names, e.g. --net/--network
+                while ($line =~ s/^\*\*(--[a-z0-9-]+)\*\*(=\*[a-zA-Z0-9-]+\*)?(,\s+)?//g) {
+                    $man{$1} = 1;
+                    push @most_recent_flags, $1;
+                }
+                # Short form
+                if ($line =~ s/^\*\*(-[a-zA-Z0-9])\*\*(=\*[a-zA-Z0-9-]+\*)?//g) {
                     $man{$1} = 1;
 
                     # Keep track of them, in case we see 'Not implemented' below