markdown-preprocess: cross-reference where opts are used

In each options/foo.md, keep a list of where the option is used.
This will be valuable to anyone making future edits, and to
those reviewing those edits.

This may be a controversial commit, because those crossref lists
are autogenerated as a side effect of the script that reads them.
It definitely violates POLA. And one day, some kind person will
reconcile (e.g.) --label, using it in more man pages, and maybe
forget to git-commit the rewritten file, and CI will fail.

I think this is a tough tradeoff, but worth doing. Without this,
it's much too easy for someone to change an option file in a way
that renders it inapplicable/misleading for some podman commands.

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

Makefile

@@ -438,7 +438,7 @@ pkg/api/swagger.yaml:
 	make -C pkg/api
 
 $(MANPAGES_MD_GENERATED): %.md: %.md.in $(MANPAGES_SOURCE_DIR)/options/*.md
-	hack/markdown-preprocess $<
+	hack/markdown-preprocess
 
 $(MANPAGES): %: %.md .install.md2man docdir
 

docs/source/markdown/options/add-host.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman build, create, pod create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--add-host**=*host:ip*
 
 Add a custom host-to-IP mapping (host:ip)

docs/source/markdown/options/annotation.container.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, kube play, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--annotation**=*key=value*
 
 Add an annotation to the container<<| or pod>>. This option can be set multiple times.

docs/source/markdown/options/annotation.manifest.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman manifest add, manifest annotate
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--annotation**=*annotation=value*
 
 Set an annotation on the entry for the image.

docs/source/markdown/options/arch.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, pull, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--arch**=*ARCH*
 Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`.
 Unless overridden, subsequent lookups of the same image in the local storage will match this architecture, regardless of the host.

docs/source/markdown/options/attach.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--attach**, **-a**=*stdin* | *stdout* | *stderr*
 
 Attach to STDIN, STDOUT or STDERR.

docs/source/markdown/options/authfile.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman auto update, build, container runlabel, create, image sign, kube play, login, logout, manifest add, manifest push, pull, push, run, search
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--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)**.

docs/source/markdown/options/blkio-weight-device.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman container clone, create, pod clone, pod create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--blkio-weight-device**=*device:weight*
 
 Block IO relative device weight.

docs/source/markdown/options/blkio-weight.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman container clone, create, pod clone, pod create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--blkio-weight**=*weight*
 
 Block IO relative weight. The _weight_ is a value between **10** and **1000**.

docs/source/markdown/options/cap-add.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cap-add**=*capability*
 
 Add Linux capabilities.

docs/source/markdown/options/cap-drop.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cap-drop**=*capability*
 
 Drop Linux capabilities.

docs/source/markdown/options/cert-dir.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman build, container runlabel, image sign, kube play, login, manifest add, manifest push, pull, push
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cert-dir**=*path*
 
 Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d)

docs/source/markdown/options/cgroup-conf.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cgroup-conf**=*KEY=VALUE*
 
 When running on cgroup v2, specify the cgroup file to write to and its value. For example **--cgroup-conf=memory.high=1073741824** sets the memory.high limit to 1GB.

docs/source/markdown/options/cgroup-parent.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman build, create, pod clone, pod create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cgroup-parent**=*path*
 
 Path to cgroups under which the cgroup for the <<container|pod>> will be created. If the

docs/source/markdown/options/cgroupns.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cgroupns**=*mode*
 
 Set the cgroup namespace mode for the container.

docs/source/markdown/options/cgroups.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cgroups**=*how*
 
 Determines whether the container will create CGroups.

docs/source/markdown/options/chrootdirs.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--chrootdirs**=*path*
 
 Path to a directory inside the container that should be treated as a `chroot` directory.

docs/source/markdown/options/cidfile.read.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman kill, pause, rm, stop, unpause
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cidfile**=*file*
 
 Read container ID from the specified *file* and <<subcommand>> the container.

docs/source/markdown/options/cidfile.write.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cidfile**=*file*
 
 Write the container ID to *file*.

docs/source/markdown/options/color.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman logs, pod logs
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--color**
 
 Output the containers with different colors in the log.

docs/source/markdown/options/compression-format.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman manifest push, push
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--compression-format**=**gzip** | *zstd* | *zstd:chunked*
 
 Specifies the compression format to use.  Supported values are: `gzip`, `zstd` and `zstd:chunked`.  The default is `gzip` unless overridden in the containers.conf file.

docs/source/markdown/options/conmon-pidfile.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--conmon-pidfile**=*file*
 
 Write the pid of the **conmon** process to a file. As **conmon** runs in a separate process than Podman, this is necessary when using systemd to restart Podman containers.

docs/source/markdown/options/cpu-period.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman build, container clone, create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cpu-period**=*limit*
 
 Set the CPU period for the Completely Fair Scheduler (CFS), which is a

docs/source/markdown/options/cpu-quota.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman build, container clone, create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cpu-quota**=*limit*
 
 Limit the CPU Completely Fair Scheduler (CFS) quota.

docs/source/markdown/options/cpu-rt-period.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman container clone, create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cpu-rt-period**=*microseconds*
 
 Limit the CPU real-time period in microseconds.

docs/source/markdown/options/cpu-rt-runtime.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman container clone, create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cpu-rt-runtime**=*microseconds*
 
 Limit the CPU real-time runtime in microseconds.

docs/source/markdown/options/cpu-shares.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman build, container clone, create, pod clone, pod create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cpu-shares**, **-c**=*shares*
 
 CPU shares (relative weight).

docs/source/markdown/options/cpus.container.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cpus**=*number*
 
 Number of CPUs. The default is *0.0* which means no limit. This is shorthand

docs/source/markdown/options/cpuset-cpus.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman build, container clone, create, pod clone, pod create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cpuset-cpus**=*number*
 
 CPUs in which to allow execution. Can be specified as a comma-separated list

docs/source/markdown/options/cpuset-mems.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman build, container clone, create, pod clone, pod create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--cpuset-mems**=*nodes*
 
 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on

docs/source/markdown/options/creds.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman build, container runlabel, kube play, manifest add, manifest push, pull, push
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--creds**=*[username[:password]]*
 
 The [username[:password]] to use to authenticate with the registry, if required.

docs/source/markdown/options/destroy.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman container clone, pod clone
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--destroy**
 
 Remove the original <<container|pod>> that we are cloning once used to mimic the configuration.

docs/source/markdown/options/detach-keys.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman attach, exec, run, start
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--detach-keys**=*sequence*
 
 Specify the key sequence for detaching a container. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is *ctrl-p,ctrl-q*.

docs/source/markdown/options/device-cgroup-rule.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--device-cgroup-rule**=*"type major:minor mode"*
 
 Add a rule to the cgroup allowed devices list. The rule is expected to be in the format specified in the Linux kernel documentation (Documentation/cgroup-v1/devices.txt):

docs/source/markdown/options/device-read-bps.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman container clone, create, pod clone, pod create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--device-read-bps**=*path:rate*
 
 Limit read rate (in bytes per second) from a device (e.g. **--device-read-bps=/dev/sda:1mb**).

docs/source/markdown/options/device-read-iops.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--device-read-iops**=*path:rate*
 
 Limit read rate (in IO operations per second) from a device (e.g. **--device-read-iops=/dev/sda:1000**).

docs/source/markdown/options/device-write-bps.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman container clone, create, pod clone, pod create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--device-write-bps**=*path:rate*
 
 Limit write rate (in bytes per second) to a device (e.g. **--device-write-bps=/dev/sda:1mb**).

docs/source/markdown/options/device-write-iops.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run, update
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--device-write-iops**=*path:rate*
 
 Limit write rate (in IO operations per second) to a device (e.g. **--device-write-iops=/dev/sda:1000**).

docs/source/markdown/options/device.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman build, create, pod clone, pod create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--device**=*host-device[:container-device][:permissions]*
 
 Add a host device to the <<container|pod>>. Optional *permissions* parameter

docs/source/markdown/options/digestfile.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman manifest push, push
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--digestfile**=*Digestfile*
 
 After copying the image, write the digest of the resulting image to the file.

docs/source/markdown/options/disable-content-trust.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman build, create, pull, push, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--disable-content-trust**
 
 This is a Docker-specific option to disable image verification to a container

docs/source/markdown/options/dns-option.container.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--dns-option**=*option*
 
 Set custom DNS options. Invalid if using **--dns-option** with **--network** that is set to **none** or **container:**_id_.

docs/source/markdown/options/dns-search.container.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--dns-search**=*domain*
 
 Set custom DNS search domains. Invalid if using **--dns-search** with **--network** that is set to **none** or **container:**_id_.

docs/source/markdown/options/dns.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman build, create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--dns**=*ipaddr*
 
 Set custom DNS servers.

docs/source/markdown/options/entrypoint.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--entrypoint**=*"command"* | *'["command", "arg1", ...]'*
 
 Overwrite the default ENTRYPOINT of the image.

docs/source/markdown/options/env-file.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, exec, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--env-file**=*file*
 
 Read in a line-delimited file of environment variables.

docs/source/markdown/options/env-host.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--env-host**
 
 Use host environment inside of the container. See **Environment** note below for precedence. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)

docs/source/markdown/options/env-merge.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--env-merge**=*env*
 
 Preprocess default environment variables for the containers. For example

docs/source/markdown/options/env.md

@@ -1,3 +1,7 @@
+####> This option file is used in:
+####>   podman create, exec, run
+####> If you edit this file, make sure your changes
+####> are applicable to all of those.
 #### **--env**, **-e**=*env*
 
 Set environment variables.