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 <santiago@redhat.com>

1 files changed, 36 insertions, 36 deletions

diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md
index c96f60c48..c8707521f 100644
--- a/docs/source/markdown/podman-build.1.md
+++ b/docs/source/markdown/podman-build.1.md
@@ -312,7 +312,7 @@ 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
 
@@ -320,15 +320,15 @@ Print usage statement
 
 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.