Man pages: refactor common options: authfile

Refactor the --authfile option.

My suggestion for review:
  1) run hack/markdown-preprocess-review and immediately Ctrl-Q to
     quit out of diffuse, which is completely unusable for this
     many files; then
  2) cd /tmp/markdown-preprocess-review.diffs/authfile
     - this is the directory created by the review script
  3) rm podman-image-sign* podman-log* podman-search.1.md.in
     - because they're essentially identical to podman-create
  4) rm podman-manifest-* podman-push.*
     - because they're 100% identical to podman-kube-play
  5) rm podman-kube-play*
     - because it's apart-from-whitespace identical to podman-build
       (use "wdiff" to confirm)
  6) rm podman-auto-update*
     - because that's the one I chose (hence == zzz-chosen.md)

(You should obviously run your own diff/cmp before rm, to confirm
my assertions about which files are identical).

After all that, you have a manageable number of files which
you can scan, read, diff against zzz-chosen.md, even run diffuse.

This option is IMHO the poster child for why we need this kind
of man page refactoring.

Signed-off-by: Ed Santiago <santiago@redhat.com>

docs/source/markdown/.gitignore

@@ -1,8 +1,17 @@
+podman-auto-update.1.md
 podman-build.1.md
 podman-container-clone.1.md
+podman-container-runlabel.1.md
 podman-create.1.md
+podman-image-sign.1.md
 podman-kube-play.1.md
+podman-login.1.md
+podman-logout.1.md
+podman-manifest-add.1.md
+podman-manifest-push.1.md
 podman-pod-clone.1.md
 podman-pod-create.1.md
 podman-pull.1.md
+podman-push.1.md
 podman-run.1.md
+podman-search.1.md

docs/source/markdown/options/authfile.md

@@ -0,0 +1,6 @@
+#### **--authfile**=*path*
+
+Path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json`, which is set using **[podman login](podman-login.1.md)**.
+If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using **docker login**.
+
+Note: There is also the option to override the default path of the authentication file by setting the `REGISTRY_AUTH_FILE` environment variable. This can be done with **export REGISTRY_AUTH_FILE=_path_**.

docs/source/markdown/podman-auto-update.1.md.in

@@ -34,12 +34,8 @@ Systemd units that start and stop a container cannot run a new image.
 Podman ships with a `podman-auto-update.service` systemd unit. This unit is triggered daily at midnight by the `podman-auto-update.timer` systemd timer.  The timer can be altered for custom time-based updates if desired.  The unit can further be invoked by other systemd units (e.g., via the dependency tree) or manually via **systemctl start podman-auto-update.service**.
 
 ## OPTIONS
-#### **--authfile**=*path*
 
-Path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json`, which is set using **[podman login](podman-login.1.md)**.
+@@option authfile
-If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using **docker login**.
-
-Note: There is also the option to override the default path of the authentication file by setting the `REGISTRY_AUTH_FILE` environment variable. This can be done with **export REGISTRY_AUTH_FILE=_path_**.
 
 #### **--dry-run**
 

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

@@ -68,16 +68,7 @@ pulled, if the build uses one, to the provided value instead of using the
 architecture of the build host. (Examples: arm, arm64, 386, amd64, ppc64le,
 s390x)
 
-#### **--authfile**=*path*
+@@option authfile
-
-Path of the authentication file. Default is
-${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
-If the authorization state is not found there, $HOME/.docker/config.json is
-checked, which is set using `docker login`.
-
-Note: You can also override the default path of the authentication file by
-setting the REGISTRY\_AUTH\_FILE environment variable.
-`export REGISTRY_AUTH_FILE=path`
 
 #### **--build-arg**=*arg=value*
 

docs/source/markdown/podman-container-runlabel.1.md.in

@@ -29,11 +29,8 @@ As specified by the `--name` option.  The format is identical to the one of the
 Will be replaced with the current working directory.
 
 ## OPTIONS
-#### **--authfile**=*path*
 
-Path of the containers-auth.json(5) file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.  If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
+@@option authfile
-
-Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path`
 
 #### **--cert-dir**=*path*
 

docs/source/markdown/podman-create.1.md.in

@@ -83,12 +83,7 @@ error. It can even pretend to be a TTY (this is what most command line
 executables expect) and pass along signals. The **-a** option can be set for
 each of stdin, stdout, and stderr.
 
-#### **--authfile**=*path*
+@@option authfile
-
-Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json
-
-Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
-environment variable. `export REGISTRY_AUTH_FILE=path`
 
 @@option blkio-weight
 

docs/source/markdown/podman-image-sign.1.md.in

@@ -19,12 +19,7 @@ By default, the signature will be written into `/var/lib/containers/sigstore` fo
 
 Sign all the manifests of the multi-architecture image (default false).
 
-#### **--authfile**=*path*
+@@option authfile
-
-Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json
-
-Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
-environment variable. `export REGISTRY_AUTH_FILE=path`
 
 #### **--cert-dir**=*path*
 

docs/source/markdown/podman-kube-play.1.md.in

@@ -112,13 +112,7 @@ and as a result environment variable `FOO` will be set to `bar` for container `c
 
 @@option annotation.container
 
-#### **--authfile**=*path*
+@@option authfile
-
-Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
-If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
-
-Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
-environment variable. `export REGISTRY_AUTH_FILE=path`
 
 #### **--build**
 

docs/source/markdown/podman-login.1.md.in

@@ -28,12 +28,7 @@ For more details about format and configurations of the auth.json file, please r
 
 ## OPTIONS
 
-#### **--authfile**=*path*
+@@option authfile
-
-Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json.
-
-Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
-environment variable. `export REGISTRY_AUTH_FILE=path`
 
 #### **--cert-dir**=*path*
 

docs/source/markdown/podman-logout.1.md.in

@@ -25,12 +25,7 @@ All the cached credentials can be removed by setting the **all** flag.
 
 Remove the cached credentials for all registries in the auth file
 
-#### **--authfile**=*path*
+@@option authfile
-
-Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json.
-
-Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
-environment variable. `export REGISTRY_AUTH_FILE=path`
 
 #### **--help**, **-h**
 

docs/source/markdown/podman-manifest-add.1.md.in

@@ -33,13 +33,7 @@ the image.  If *imageName* refers to a manifest list or image index, the
 architecture information will be retrieved from it.  Otherwise, it will be
 retrieved from the image's configuration information.
 
-#### **--authfile**=*path*
+@@option authfile
-
-Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
-If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
-
-Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
-environment variable. `export REGISTRY_AUTH_FILE=path`
 
 #### **--cert-dir**=*path*
 

docs/source/markdown/podman-manifest-push.1.md.in

@@ -19,13 +19,7 @@ The list image's ID and the digest of the image's manifest.
 Push the images mentioned in the manifest list or image index, in addition to
 the list or index itself. (Default true)
 
-#### **--authfile**=*path*
+@@option authfile
-
-Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
-If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
-
-Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
-environment variable. `export REGISTRY_AUTH_FILE=path`
 
 #### **--cert-dir**=*path*
 

docs/source/markdown/podman-pull.1.md.in

@@ -51,13 +51,7 @@ All tagged images in the repository will be pulled.
 
 @@option arch
 
-#### **--authfile**=*path*
+@@option authfile
-
-Path of the authentication file. If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using `docker login`.
-
-Default is `${XDG\_RUNTIME\_DIR}/containers/auth.json`, which is set using `podman login`.
-
-*IMPORTANT: The default path of the authentication file can be overwritten by setting the `REGISTRY\_AUTH\_FILE` environment variable. `export REGISTRY_AUTH_FILE=path`*
 
 #### **--cert-dir**=*path*
 

docs/source/markdown/podman-push.1.md.in

@@ -47,13 +47,7 @@ $ podman push myimage oci-archive:/tmp/myimage
 
 ## OPTIONS
 
-#### **--authfile**=*path*
+@@option authfile
-
-Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
-If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
-
-Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
-environment variable. `export REGISTRY_AUTH_FILE=path`
 
 #### **--cert-dir**=*path*
 

docs/source/markdown/podman-run.1.md.in

@@ -100,12 +100,7 @@ error. It can even pretend to be a TTY (this is what most commandline
 executables expect) and pass along signals. The **-a** option can be set for
 each of **stdin**, **stdout**, and **stderr**.
 
-#### **--authfile**=*[path]*
+@@option authfile
-
-Path to the authentication file. Default is *${XDG_RUNTIME_DIR}/containers/auth.json*.
-
-Note: You can also override the default path of the authentication file by setting the **REGISTRY_AUTH_FILE**
-environment variable.
 
 @@option blkio-weight
 

docs/source/markdown/podman-search.1.md.in

@@ -30,12 +30,7 @@ Further note that searching without a search term will only work for registries
 
 ## OPTIONS
 
-#### **--authfile**=*path*
+@@option authfile
-
-Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json
-
-Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
-environment variable. `export REGISTRY_AUTH_FILE=path`
 
 #### **--compatible**