man pages: sort flags, and keep them that way

Command flags (OPTIONS) in man pages have to date been in
haphazard order. Sometimes that order is sensible, e.g.,
most-important options first, but more often they're
just in arbitrary places. This makes life hard for users.

Here, I update the man-page-check Makefile script so it
checks and enforces alphabetical order in OPTIONS sections.
Then -- the hard part -- update all existing man pages to
conform to this requirement.

Signed-off-by: Ed Santiago <[email protected]>

Author: edsantiago

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

@@ -312,23 +312,23 @@ environment variable.  `export BUILDAH_FORMAT=docker`
 Overrides the first `FROM` instruction within the Containerfile.  If there are multiple
 FROM instructions in a Containerfile, only the first is changed.
 
-**-h**, **--help**
+#### **--help**, **-h**
 
 Print usage statement
 
 #### **--http-proxy**
 
 Pass through HTTP Proxy environment variables.
 
+#### **--ignorefile**
+
+Path to an alternative .containerignore file.
+
 #### **--iidfile**=*ImageIDfile*
 
 Write the built image's ID to the file.  When `--platform` is specified more
 than once, attempting to use this option will trigger an error.
 
-#### **--ignorefile**
-
-Path to an alternative .containerignore file.
-
 #### **--ipc**=*how*
 
 Sets the configuration for IPC namespaces when handling `RUN` instructions.
@@ -643,47 +643,62 @@ the user namespace in which `podman` itself is being run should be reused, or
 it can be the path to a user namespace which is already in use by another
 process.
 
-#### **--userns-uid-map**=*mapping*
+#### **--userns-gid-map**=*mapping*
 
-Directly specifies a UID mapping which should be used to set ownership, at the
+Directly specifies a GID mapping which should be used to set ownership, at the
 filesystem level, on the working container's contents.
 Commands run when handling `RUN` instructions will default to being run in
 their own user namespaces, configured using the UID and GID maps.
 
 Entries in this map take the form of one or more triples of a starting
-in-container UID, a corresponding starting host-level UID, and the number of
+in-container GID, a corresponding starting host-level GID, and the number of
 consecutive IDs which the map entry represents.
 
-This option overrides the *remap-uids* setting in the *options* section of
+This option overrides the *remap-gids* setting in the *options* section of
 /etc/containers/storage.conf.
 
-If this option is not specified, but a global --userns-uid-map setting is
+If this option is not specified, but a global --userns-gid-map setting is
 supplied, settings from the global option will be used.
 
-If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-uid-map
-are specified, but --userns-gid-map is specified, the UID map will be set to
-use the same numeric values as the GID map.
+If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-gid-map
+are specified, but --userns-uid-map is specified, the GID map will be set to
+use the same numeric values as the UID map.
 
-#### **--userns-gid-map**=*mapping*
+#### **--userns-gid-map-group**=*group*
 
-Directly specifies a GID mapping which should be used to set ownership, at the
+Specifies that a GID mapping which should be used to set ownership, at the
+filesystem level, on the working container's contents, can be found in entries
+in the `/etc/subgid` file which correspond to the specified group.
+Commands run when handling `RUN` instructions will default to being run in
+their own user namespaces, configured using the UID and GID maps.
+If --userns-uid-map-user is specified, but --userns-gid-map-group is not
+specified, `podman` will assume that the specified user name is also a
+suitable group name to use as the default setting for this option.
+
+**NOTE:** When this option is specified by a rootless user, the specified
+mappings are relative to the rootless user namespace in the container, rather
+than being relative to the host as it would be when run rootfull.
+
+#### **--userns-uid-map**=*mapping*
+
+Directly specifies a UID mapping which should be used to set ownership, at the
 filesystem level, on the working container's contents.
 Commands run when handling `RUN` instructions will default to being run in
 their own user namespaces, configured using the UID and GID maps.
 
 Entries in this map take the form of one or more triples of a starting
-in-container GID, a corresponding starting host-level GID, and the number of
+in-container UID, a corresponding starting host-level UID, and the number of
 consecutive IDs which the map entry represents.
 
-This option overrides the *remap-gids* setting in the *options* section of
+This option overrides the *remap-uids* setting in the *options* section of
 /etc/containers/storage.conf.
 
-If this option is not specified, but a global --userns-gid-map setting is
+If this option is not specified, but a global --userns-uid-map setting is
 supplied, settings from the global option will be used.
 
-If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-gid-map
-are specified, but --userns-uid-map is specified, the GID map will be set to
-use the same numeric values as the UID map.
+If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-uid-map
+are specified, but --userns-gid-map is specified, the UID map will be set to
+use the same numeric values as the GID map.
 
 #### **--userns-uid-map-user**=*user*
 
@@ -700,21 +715,6 @@ suitable user name to use as the default setting for this option.
 mappings are relative to the rootless user namespace in the container, rather
 than being relative to the host as it would be when run rootfull.
 
-#### **--userns-gid-map-group**=*group*
-
-Specifies that a GID mapping which should be used to set ownership, at the
-filesystem level, on the working container's contents, can be found in entries
-in the `/etc/subgid` file which correspond to the specified group.
-Commands run when handling `RUN` instructions will default to being run in
-their own user namespaces, configured using the UID and GID maps.
-If --userns-uid-map-user is specified, but --userns-gid-map-group is not
-specified, `podman` will assume that the specified user name is also a
-suitable group name to use as the default setting for this option.
-
-**NOTE:** When this option is specified by a rootless user, the specified
-mappings are relative to the rootless user namespace in the container, rather
-than being relative to the host as it would be when run rootfull.
-
 #### **--uts**=*how*
 
 Sets the configuration for UTS namespaces when handling `RUN` instructions.

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

@@ -60,14 +60,14 @@ Set commit message for committed image.\
 Pause the container when creating an image.\
 The default is **false**.
 
-#### **--squash**, **-s**
+#### **--quiet**, **-q**
 
-Squash newly built layers into a single new layer.\
+Suppresses output.\
 The default is **false**.
 
-#### **--quiet**, **-q**
+#### **--squash**, **-s**
 
-Suppresses output.\
+Squash newly built layers into a single new layer.\
 The default is **false**.
 
 ## EXAMPLES

docs/source/markdown/podman-container-checkpoint.1.md

@@ -35,6 +35,14 @@ to import the *container* on another system and thus enabling container live
 migration. This checkpoint archive also includes all changes to the *container's*
 root file-system, if not explicitly disabled using **--ignore-rootfs**.
 
+#### **--file-locks**
+
+Checkpoint a *container* with file locks. If an application running in the container
+is using file locks, this OPTION is required during checkpoint and restore. Otherwise
+checkpointing *containers* with file locks is expected to fail. If file locks are not
+used, this option is ignored.\
+The default is **false**.
+
 #### **--ignore-rootfs**
 
 If a checkpoint is exported to a tar.gz file it is possible with the help of **--ignore-rootfs** to explicitly disable including changes to the root file-system into the checkpoint archive file.\
@@ -119,14 +127,6 @@ restore. Defaults to not checkpointing *containers* with established TCP
 connections.\
 The default is **false**.
 
-#### **--file-locks**
-
-Checkpoint a *container* with file locks. If an application running in the container
-is using file locks, this OPTION is required during checkpoint and restore. Otherwise
-checkpointing *containers* with file locks is expected to fail. If file locks are not
-used, this option is ignored.\
-The default is **false**.
-
 #### **--with-previous**
 
 Check out the *container* with previous criu image files in pre-dump. It only works on `runc 1.0-rc3` or `higher`.\

docs/source/markdown/podman-container-clone.1.md

@@ -11,25 +11,6 @@ podman\-container\-clone - Creates a copy of an existing container
 
 ## OPTIONS
 
-#### **--name**
-
-Set a custom name for the cloned container. The default if not specified is of the syntax: **<ORIGINAL_NAME>-clone**
-
-#### **--destroy**
-
-Remove the original container that we are cloning once used to mimic the configuration.
-
-#### **--cpus**
-
-Set a number of CPUs for the container that overrides the original containers CPU limits. If none are specified, the original container's Nano CPUs are used.
-
-This is shorthand
-for **--cpu-period** and **--cpu-quota**, so only **--cpus** or either both the **--cpu-period** and **--cpu-quota** options can be set.
-
-#### **--cpuset-cpus**
-
-CPUs in which to allow execution (0-3, 0,1). If none are specified, the original container's CPUset is used.
-
 #### **--cpu-period**=*limit*
 
 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
@@ -43,6 +24,43 @@ https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-c
 
 If none is specified, the original container's cpu period is used
 
+#### **--cpu-quota**=*limit*
+
+Limit the CPU Completely Fair Scheduler (CFS) quota.
+
+Limit the container's CPU usage. By default, containers run with the full
+CPU resource. The limit is a number in microseconds. If a number is provided,
+the container will be allowed to use that much CPU time until the CPU period
+ends (controllable via **--cpu-period**).
+
+On some systems, changing the CPU limits may not be allowed for non-root
+users. For more details, see
+https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
+
+If none is specified, the original container's CPU quota are used.
+
+#### **--cpu-rt-period**=*microseconds*
+
+Limit the CPU real-time period in microseconds
+
+Limit the container's Real Time CPU usage. This option tells the kernel to restrict the container's Real Time CPU usage to the period specified.
+
+This option is not supported on cgroups V2 systems.
+
+If none is specified, the original container's CPU runtime period is used.
+
+
+#### **--cpu-rt-runtime**=*microseconds*
+
+Limit the CPU real-time runtime in microseconds.
+
+Limit the containers Real Time CPU usage. This option tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex:
+Period of 1,000,000us and Runtime of 950,000us means that this container could consume 95% of available CPU and leave the remaining 5% to normal priority tasks.
+
+The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup.
+
+This option is not supported on cgroup V2 systems.
+
 #### **--cpu-shares**=*shares*
 
 CPU shares (relative weight)
@@ -82,6 +100,17 @@ PID    container	CPU	CPU share
 
 If none are specified, the original container's CPU shares are used.
 
+#### **--cpus**
+
+Set a number of CPUs for the container that overrides the original containers CPU limits. If none are specified, the original container's Nano CPUs are used.
+
+This is shorthand
+for **--cpu-period** and **--cpu-quota**, so only **--cpus** or either both the **--cpu-period** and **--cpu-quota** options can be set.
+
+#### **--cpuset-cpus**
+
+CPUs in which to allow execution (0-3, 0,1). If none are specified, the original container's CPUset is used.
+
 #### **--cpuset-mems**=*nodes*
 
 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
@@ -92,42 +121,9 @@ two memory nodes.
 
 If none are specified, the original container's CPU memory nodes are used.
 
-#### **--cpu-quota**=*limit*
-
-Limit the CPU Completely Fair Scheduler (CFS) quota.
-
-Limit the container's CPU usage. By default, containers run with the full
-CPU resource. The limit is a number in microseconds. If a number is provided,
-the container will be allowed to use that much CPU time until the CPU period
-ends (controllable via **--cpu-period**).
-
-On some systems, changing the CPU limits may not be allowed for non-root
-users. For more details, see
-https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
-
-If none is specified, the original container's CPU quota are used.
-
-#### **--cpu-rt-period**=*microseconds*
-
-Limit the CPU real-time period in microseconds
-
-Limit the container's Real Time CPU usage. This option tells the kernel to restrict the container's Real Time CPU usage to the period specified.
-
-This option is not supported on cgroups V2 systems.
-
-If none is specified, the original container's CPU runtime period is used.
-
-
-#### **--cpu-rt-runtime**=*microseconds*
-
-Limit the CPU real-time runtime in microseconds.
-
-Limit the containers Real Time CPU usage. This option tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex:
-Period of 1,000,000us and Runtime of 950,000us means that this container could consume 95% of available CPU and leave the remaining 5% to normal priority tasks.
-
-The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup.
+#### **--destroy**
 
-This option is not supported on cgroup V2 systems.
+Remove the original container that we are cloning once used to mimic the configuration.
 
 #### **--memory**, **-m**=*limit*
 
@@ -141,6 +137,10 @@ system's page size (the value would be very large, that's millions of trillions)
 
 If no memory limits are specified, the original container's will be used.
 
+#### **--name**
+
+Set a custom name for the cloned container. The default if not specified is of the syntax: **<ORIGINAL_NAME>-clone**
+
 #### **--run**
 
 When set to true, this flag runs the newly created container after the

docs/source/markdown/podman-container-restore.1.md

@@ -16,25 +16,14 @@ Restore all checkpointed *containers*.\
 The default is **false**.\
 *IMPORTANT: This OPTION does not need a container name or ID as input argument.*
 
-#### **--keep**, **-k**
+#### **--file-locks**
 
-Keep all temporary log and statistics files created by `CRIU` during
-checkpointing as well as restoring. These files are not deleted if restoring
-fails for further debugging. If restoring succeeds these files are
-theoretically not needed, but if these files are needed Podman can keep the
-files for further analysis. This includes the checkpoint directory with all
-files created during checkpointing. The size required by the checkpoint
-directory is roughly the same as the amount of memory required by the
-processes in the checkpointed *container*.\
-Without the **--keep**, **-k** option the checkpoint will be consumed and cannot be used again.\
+Restore a *container* with file locks. This option is required to
+restore file locks from a checkpoint image. If the checkpoint image
+does not contain file locks, this option is ignored. Defaults to not
+restoring file locks.\
 The default is **false**.
 
-#### **--latest**, **-l**
-
-Instead of providing the *container ID* or *name*, use the last created *container*. If other tools than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either tool.\
-The default is **false**.\
-*IMPORTANT: This OPTION is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines. This OPTION does not need a container name or ID as input argument.*
-
 #### **--ignore-rootfs**
 
 If a *container* is restored from a checkpoint tar.gz file it is possible that it also contains all root file-system changes. With **--ignore-rootfs** it is possible to explicitly disable applying these root file-system changes to the restored *container*.\
@@ -89,6 +78,25 @@ Import a pre-checkpoint tar.gz file which was exported by Podman. This option
 must be used with **-i** or **--import**. It only works on `runc 1.0-rc3` or `higher`.
 *IMPORTANT: This OPTION is not supported on the remote client, including Mac and Windows (excluding WSL2) machines.*
 
+#### **--keep**, **-k**
+
+Keep all temporary log and statistics files created by `CRIU` during
+checkpointing as well as restoring. These files are not deleted if restoring
+fails for further debugging. If restoring succeeds these files are
+theoretically not needed, but if these files are needed Podman can keep the
+files for further analysis. This includes the checkpoint directory with all
+files created during checkpointing. The size required by the checkpoint
+directory is roughly the same as the amount of memory required by the
+processes in the checkpointed *container*.\
+Without the **--keep**, **-k** option the checkpoint will be consumed and cannot be used again.\
+The default is **false**.
+
+#### **--latest**, **-l**
+
+Instead of providing the *container ID* or *name*, use the last created *container*. If other tools than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either tool.\
+The default is **false**.\
+*IMPORTANT: This OPTION is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines. This OPTION does not need a container name or ID as input argument.*
+
 #### **--name**, **-n**=*name*
 
 If a *container* is restored from a checkpoint tar.gz file it is possible to rename it with **--name, -n**. This way it is possible to restore a *container* from a checkpoint multiple times with different
@@ -149,14 +157,6 @@ option is ignored. Defaults to not restoring *containers* with established TCP
 connections.\
 The default is **false**.
 
-#### **--file-locks**
-
-Restore a *container* with file locks. This option is required to
-restore file locks from a checkpoint image. If the checkpoint image
-does not contain file locks, this option is ignored. Defaults to not
-restoring file locks.\
-The default is **false**.
-
 ## EXAMPLE
 Restores the container "mywebserver".
 ```