Merge pull request #8318 from Luap99/doc-consistent-flag-order

[CI:DOCS] Maintain consistent order of short and long flag names in docs

21 files changed, 59 insertions, 52 deletions

diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md
index a411d32ab..f9568b5d3 100644
--- 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
index 5922e0675..a6083201d 100644
--- 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
index 29dfee87e..002f42bff 100644
--- 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
index 531570666..9ee62ef2b 100644
--- a/docs/source/markdown/podman-images.1.md
+++ b/docs/source/markdown/podman-images.1.md
@@ -15,7 +15,7 @@ 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.
 
@@ -23,7 +23,7 @@ Show all images (by default filter out the intermediate image layers). The defau
 
 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
index ba512ca12..ebedf90b4 100644
--- 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
index 78895fa15..dd01a0f49 100644
--- 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
index c93e4c9d7..772668c8b 100644
--- 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
index 8b8399c3e..cbf9d26dc 100644
--- 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
index c8391861d..e14d1ed79 100644
--- 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
index 6fd42f800..22eb07bf3 100644
--- 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
index ece3ab885..99cac6f9c 100644
--- 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
index 60c90ada1..acca0ccfe 100644
--- 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
index f67b7c652..db9c98073 100644
--- 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
index c8c6476bf..32c16d6a1 100644
--- 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
index 6c21a20b4..f3db2d020 100644
--- 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
index 4fd911c1f..118f024df 100644
--- 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
index e6be69e73..ea0ee91b4 100644
--- 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
index a3f3ff9ba..98c3fae54 100644
--- 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
index 097dded86..b5f1b7e94 100644
--- 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
index 5f2137f73..c066d1c6e 100644
--- 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
index 082cc63f2..c5447c5d6 100755
--- 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