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 <[email protected]>
containers · Aug 16, 2022 · f0e8640 · f0e8640
1 parent 3dace12
commit f0e8640
Show file tree

Hide file tree

Showing 16 changed files with 29 additions and 90 deletions.
diff --git 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
@@ -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 → ...ource/markdown/podman-auto-update.1.md.in b/docs/source/markdown/podman-auto-update.1.md → ...ource/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
@@ -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/...e/markdown/podman-container-runlabel.1.md → ...arkdown/podman-container-runlabel.1.md.in b/...e/markdown/podman-container-runlabel.1.md → ...arkdown/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
@@ -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 → ...source/markdown/podman-image-sign.1.md.in b/docs/source/markdown/podman-image-sign.1.md → ...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
@@ -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 → docs/source/markdown/podman-login.1.md.in b/docs/source/markdown/podman-login.1.md → 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 → docs/source/markdown/podman-logout.1.md.in b/docs/source/markdown/podman-logout.1.md → 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/.../source/markdown/podman-manifest-add.1.md → ...urce/markdown/podman-manifest-add.1.md.in b/.../source/markdown/podman-manifest-add.1.md → ...urce/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/...source/markdown/podman-manifest-push.1.md → ...rce/markdown/podman-manifest-push.1.md.in b/...source/markdown/podman-manifest-push.1.md → ...rce/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
@@ -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 → docs/source/markdown/podman-push.1.md.in b/docs/source/markdown/podman-push.1.md → 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
@@ -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 → docs/source/markdown/podman-search.1.md.in b/docs/source/markdown/podman-search.1.md → 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**