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>

16 files changed, 29 insertions, 90 deletions

diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore
index 6689b5b71..70f1c2bd7 100644
--- a/docs/source/markdown/.gitignore
+++ b/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
diff --git a/docs/source/markdown/options/authfile.md b/docs/source/markdown/options/authfile.md
new file mode 100644
index 000000000..d6198aa24
--- /dev/null
+++ b/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_**.
diff --git a/docs/source/markdown/podman-auto-update.1.md b/docs/source/markdown/podman-auto-update.1.md.in
index 992c87432..bc92d6165 100644
--- a/docs/source/markdown/podman-auto-update.1.md
+++ b/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)**.
-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_**.
+@@option authfile
 
 #### **--dry-run**
 
diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in
index c0cf08f3c..b49beb3bf 100644
--- a/docs/source/markdown/podman-build.1.md.in
+++ b/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*
-
-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`
+@@option authfile
 
 #### **--build-arg**=*arg=value*
 
diff --git a/docs/source/markdown/podman-container-runlabel.1.md b/docs/source/markdown/podman-container-runlabel.1.md.in
index 40e5392ce..7f462bf70 100644
--- a/docs/source/markdown/podman-container-runlabel.1.md
+++ b/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`.
-
-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 authfile
 
 #### **--cert-dir**=*path*
 
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
index f5301c60a..3e6b07225 100644
--- a/docs/source/markdown/podman-create.1.md.in
+++ b/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*
-
-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 authfile
 
 @@option blkio-weight
 
diff --git a/docs/source/markdown/podman-image-sign.1.md b/docs/source/markdown/podman-image-sign.1.md.in
index 035e10743..340cdbd21 100644
--- a/docs/source/markdown/podman-image-sign.1.md
+++ b/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*
-
-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 authfile
 
 #### **--cert-dir**=*path*
 
diff --git a/docs/source/markdown/podman-kube-play.1.md.in b/docs/source/markdown/podman-kube-play.1.md.in
index 5fc183ee2..83b9f9904 100644
--- a/docs/source/markdown/podman-kube-play.1.md.in
+++ b/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*
-
-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`
+@@option authfile
 
 #### **--build**
 
diff --git a/docs/source/markdown/podman-login.1.md b/docs/source/markdown/podman-login.1.md.in
index c84b0cc99..6ec207a1e 100644
--- a/docs/source/markdown/podman-login.1.md
+++ b/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*
-
-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 authfile
 
 #### **--cert-dir**=*path*
 
diff --git a/docs/source/markdown/podman-logout.1.md b/docs/source/markdown/podman-logout.1.md.in
index 96ac98f35..6997bb36e 100644
--- a/docs/source/markdown/podman-logout.1.md
+++ b/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*
-
-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 authfile
 
 #### **--help**, **-h**
 
diff --git a/docs/source/markdown/podman-manifest-add.1.md b/docs/source/markdown/podman-manifest-add.1.md.in
index 5aa7f8341..a1c498e4f 100644
--- a/docs/source/markdown/podman-manifest-add.1.md
+++ b/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*
-
-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`
+@@option authfile
 
 #### **--cert-dir**=*path*
 
diff --git a/docs/source/markdown/podman-manifest-push.1.md b/docs/source/markdown/podman-manifest-push.1.md.in
index cfe2b9230..631ead376 100644
--- a/docs/source/markdown/podman-manifest-push.1.md
+++ b/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*
-
-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`
+@@option authfile
 
 #### **--cert-dir**=*path*
 
diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in
index 29c4f865d..cf06cc6a8 100644
--- a/docs/source/markdown/podman-pull.1.md.in
+++ b/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*
-
-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`*
+@@option authfile
 
 #### **--cert-dir**=*path*
 
diff --git a/docs/source/markdown/podman-push.1.md b/docs/source/markdown/podman-push.1.md.in
index d674975b0..1c936cd66 100644
--- a/docs/source/markdown/podman-push.1.md
+++ b/docs/source/markdown/podman-push.1.md.in
@@ -47,13 +47,7 @@ $ podman push myimage oci-archive:/tmp/myimage
 
 ## OPTIONS
 
-#### **--authfile**=*path*
-
-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`
+@@option authfile
 
 #### **--cert-dir**=*path*
 
diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in
index 81b635bc8..1c02eafe9 100644
--- a/docs/source/markdown/podman-run.1.md.in
+++ b/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]*
-
-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 authfile
 
 @@option blkio-weight
 
diff --git a/docs/source/markdown/podman-search.1.md b/docs/source/markdown/podman-search.1.md.in
index 5b49d7f8e..9dd8cebf8 100644
--- a/docs/source/markdown/podman-search.1.md
+++ b/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*
-
-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 authfile
 
 #### **--compatible**