Rewrite the Quadlet documentation

docs/source/markdown/.gitignore

@@ -34,6 +34,7 @@ podman-manifest-create.1.md
 podman-manifest-inspect.1.md
 podman-manifest-push.1.md
 podman-mount.1.md
+podman-network-create.1.md
 podman-network-ls.1.md
 podman-network-reload.1.md
 podman-pause.1.md
@@ -69,3 +70,11 @@ podman-unpause.1.md
 podman-update.1.md
 podman-volume-ls.1.md
 podman-wait.1.md
+podman-build.unit.5.md
+podman-container.unit.5.md
+podman-image.unit.5.md
+podman-kube.unit.5.md
+podman-kube-down.1.md
+podman-network.unit.5.md
+podman-pod.unit.5.md
+podman-volume.unit.5.md

docs/source/markdown/options/README.md

@@ -17,6 +17,8 @@ mechanism:
 
 ```
 @@option foo           ! includes options/foo.md
+@@option quadlet:foo   ! includes options/foo.md with `is_quadlet=True`
+                       ! See "Jinja2 Templating" below.
 ```
 
 The tool that does this is `hack/markdown-preprocess`. It is a python
@@ -25,6 +27,41 @@ file, this script creates a `.md` file that can then be read by
 `go-md2man`, `sphinx`, anything that groks markdown. This runs as
 part of `make docs`.
 
+Conditionals
+============
+
+Some options are used as both Podman command line options and Quadlet
+options. To reduce the duplication, the very limited conditionals are
+supported in the Markdown files.
+
+The basic condition:
+
+```
+<< if variable >>
+...
+<< endif >>
+```
+
+It is possible to use the `not` keyword and `else` keyword:
+
+```
+<< if not variable >>
+...
+<< else >>
+...
+<< endif >>
+```
+
+It is also possible to do inline conditions like this:
+
+```
+<< "foo" if variable else "bar" >>
+```
+
+The following variables are available for Jinja2 Templates:
+
+- `is_quadlet`: True if file is imported using `@@option quadlet:foo`.
+
 Special Substitutions
 =====================
 

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

@@ -1,8 +1,12 @@
 ####> This option file is used in:
-####>   podman build, create, farm build, pod create, run
+####>   podman build, podman-container.unit.5.md.in, create, farm build, pod create, podman-pod.unit.5.md.in, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `AddHost=hostname[;hostname[;...]]:ip`
+<< else >>
 #### **--add-host**=*hostname[;hostname[;...]]*:*ip*
+<< endif >>
 
 Add a custom host-to-IP mapping to the <<container|pod>>'s `/etc/hosts` file.
 

docs/source/markdown/options/all-tags.md

@@ -0,0 +1,13 @@
+####> This option file is used in:
+####>   podman podman-image.unit.5.md.in, pull
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+<< if is_quadlet >>
+### `AllTags=true`
+<< else >>
+#### **--all-tags**, **-a**
+<< endif >>
+
+All tagged images in the repository are pulled.
+
+*IMPORTANT: When using the all-tags flag, Podman does not iterate over the search registries in the **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** but always uses docker.io for unqualified image names.*

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

@@ -1,7 +1,11 @@
 ####> This option file is used in:
-####>   podman create, kube play, run
+####>   podman podman-container.unit.5.md.in, create, kube play, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `Annotation=key=value`
+<< else >>
 #### **--annotation**=*key=value*
+<< endif >>
 
 Add an annotation to the container<<| or pod>>. This option can be set multiple times.

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

@@ -1,8 +1,12 @@
 ####> This option file is used in:
-####>   podman build, farm build
+####>   podman build, podman-build.unit.5.md.in, farm build
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `Annotation=annotation=value [annotation=value ...]`
+<< else >>
 #### **--annotation**=*annotation=value*
+<< endif >>
 
 Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can
 be used multiple times.

docs/source/markdown/options/arch.md

@@ -1,7 +1,12 @@
 ####> This option file is used in:
-####>   podman create, pull, run
+####>   podman podman-build.unit.5.md.in, create, podman-image.unit.5.md.in, pull, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `Arch=ARCH`
+<< else >>
 #### **--arch**=*ARCH*
+<< endif >>
+
 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 matches this architecture, regardless of the host.

docs/source/markdown/options/authfile.md

@@ -1,8 +1,12 @@
 ####> This option file is used in:
-####>   podman artifact pull, artifact push, auto update, build, container runlabel, create, farm build, image sign, kube play, login, logout, manifest add, manifest inspect, manifest push, pull, push, run, search
+####>   podman artifact pull, artifact push, auto update, build, podman-build.unit.5.md.in, container runlabel, create, farm build, image sign, podman-image.unit.5.md.in, kube play, login, logout, manifest add, manifest inspect, manifest push, pull, push, run, search
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `AuthFile=path`
+<< else >>
 #### **--authfile**=*path*
+<< endif >>
 
 Path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json` on Linux, and `$HOME/.config/containers/auth.json` on Windows/macOS.
 The file is created by **[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**.

docs/source/markdown/options/auto-update.md

@@ -0,0 +1,11 @@
+####> This option file is used in:
+####>   podman podman-container.unit.5.md.in
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+### `AutoUpdate=registry`
+
+Indicates whether the container will be auto-updated ([podman-auto-update(1)](podman-auto-update.1.md)). The following values are supported:
+
+* `registry`: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which image to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore.
+
+* `local`: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the container.

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

@@ -2,7 +2,12 @@
 ####>   podman build, farm build
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `AddCapability=CAP_xxx`
+<< else >>
 #### **--cap-add**=*CAP\_xxx*
+<< endif >>
+
 
 When executing RUN instructions, run the command specified in the instruction
 with the specified capability added to its capability set.

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

@@ -1,8 +1,12 @@
 ####> This option file is used in:
-####>   podman create, run
+####>   podman podman-container.unit.5.md.in, create, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `AddCapability=capability`
+<< else >>
 #### **--cap-add**=*capability*
+<< endif >>
 
 Add Linux capabilities.
 

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

@@ -1,7 +1,13 @@
 ####> This option file is used in:
-####>   podman create, run
+####>   podman podman-container.unit.5.md.in, create, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `DropCapability=capability`
+<< else >>
 #### **--cap-drop**=*capability*
+<< endif >>
 
-Drop Linux capabilities.
+Drop these capabilities from the default podman capability set, or `all` to drop all capabilities.
+
+This is a space separated list of capabilities.

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

@@ -1,8 +1,12 @@
 ####> This option file is used in:
-####>   podman artifact pull, artifact push, build, container runlabel, create, farm build, image sign, kube play, login, manifest add, manifest push, pull, push, run, search
+####>   podman artifact pull, artifact push, build, container runlabel, create, farm build, image sign, podman-image.unit.5.md.in, kube play, login, manifest add, manifest push, pull, push, run, search
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `CertDir=path`
+<< else >>
 #### **--cert-dir**=*path*
+<< endif >>
 
 Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d)
 For details, see **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**.

docs/source/markdown/options/cgroups.md

@@ -1,12 +1,24 @@
 ####> This option file is used in:
-####>   podman create, run
+####>   podman podman-container.unit.5.md.in, create, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `CgroupsMode=how`
+<< else >>
 #### **--cgroups**=*how*
+<< endif >>
 
 Determines whether the container creates CGroups.
 
+<< if is_quadlet >>
+By default, the cgroups mode of the container created by Quadlet is `split`,
+which differs from the default (`enabled`) used by the Podman CLI.
+
+If the container joins a pod (i.e. `Pod=` is specified), you may want to change this to
+`no-conmon` or `enabled` so that pod level cgroup resource limits can take effect.
+<< else >>
 Default is **enabled**.
+<< endif >>
 
 The **enabled** option creates a new cgroup under the cgroup-parent.
 The **disabled** option forces the container to not create CGroups, and thus conflicts with CGroup options (**--cgroupns** and **--cgroup-parent**).

docs/source/markdown/options/configmap.md

@@ -0,0 +1,18 @@
+####> This option file is used in:
+####>   podman kube play, podman-kube.unit.5.md.in
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+<< if is_quadlet >>
+### `ConfigMap=path`
+<< else >>
+#### **--configmap**=*path*
+<< endif >>
+
+Use Kubernetes configmap YAML at path to provide a source for environment variable values within the containers of the pod.  (This option is not available with the remote Podman client)
+
+<< if is_quadlet >>
+The value may contain only one path but it may be absolute or relative to the location of the unit file.
+<< else >>
+Note: The **--configmap** option can be used multiple times or a comma-separated list of paths can be used to pass multiple Kubernetes configmap YAMLs.
+The YAML file may be in a multi-doc YAML format. But, it must contain only configmaps.
+<< endif >>

docs/source/markdown/options/creds.md

@@ -1,8 +1,12 @@
 ####> This option file is used in:
-####>   podman artifact pull, artifact push, build, container runlabel, create, farm build, kube play, manifest add, manifest push, pull, push, run, search
+####>   podman artifact pull, artifact push, build, container runlabel, create, farm build, podman-image.unit.5.md.in, kube play, manifest add, manifest push, pull, push, run, search
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `Creds=[username[:password]]`
+<< else >>
 #### **--creds**=*[username[:password]]*
+<< endif >>
 
 The [username[:password]] to use to authenticate with the registry, if required.
 If one or both values are not supplied, a command line prompt appears and the

docs/source/markdown/options/decryption-key.md

@@ -1,7 +1,11 @@
 ####> This option file is used in:
-####>   podman artifact pull, build, create, farm build, pull, run
+####>   podman artifact pull, build, create, farm build, podman-image.unit.5.md.in, pull, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `DecryptionKey=key[:passphrase]`
+<< else >>
 #### **--decryption-key**=*key[:passphrase]*
+<< endif >>
 
 The [key[:passphrase]] to be used for decryption of images. Key can point to keys and/or certificates. Decryption is tried with all keys. If the key is protected by a passphrase, it is required to be passed in the argument and omitted otherwise.

docs/source/markdown/options/device.md

@@ -1,12 +1,18 @@
 ####> This option file is used in:
-####>   podman build, create, farm build, pod clone, pod create, run
+####>   podman build, podman-container.unit.5.md.in, create, farm build, pod clone, pod create, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `AddDevice=host-device[:container-device][:permissions]`
+<< else >>
 #### **--device**=*host-device[:container-device][:permissions]*
+<< endif >>
 
-Add a host device to the <<container|pod>>. Optional *permissions* parameter
-can be used to specify device permissions by combining
-**r** for read, **w** for write, and **m** for **mknod**(2).
+Add a host device to the <<container|pod>>. The format of this is
+`HOST-DEVICE[:CONTAINER-DEVICE][:PERMISSIONS]`, where `HOST-DEVICE` is the path of
+the device node on the host, `CONTAINER-DEVICE` is the path of the device node in
+the container, and `PERMISSIONS` is a list of permissions combining 'r' for read,
+'w' for write, and 'm' for mknod(2).
 
 Example: **--device=/dev/sdc:/dev/xvdc:rwm**.
 

docs/source/markdown/options/disable-dns.md

@@ -0,0 +1,12 @@
+####> This option file is used in:
+####>   podman network create, podman-network.unit.5.md.in
+####> If file is edited, make sure the changes
+####> are applicable to all of those.
+<< if is_quadlet >>
+### `DisableDNS=true`
+<< else >>
+#### **--disable-dns**
+<< endif >>
+
+Disables the DNS plugin for this network which if enabled, can perform container to container name
+resolution. It is only supported with the `bridge` driver, for other drivers it is always disabled.

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

@@ -1,7 +1,12 @@
 ####> This option file is used in:
-####>   podman create, run
+####>   podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `DNSOption=option`
+<< else >>
 #### **--dns-option**=*option*
+<< endif >>
 
-Set custom DNS options. Invalid if using **--dns-option** with **--network** that is set to **none** or **container:**_id_.
+Set custom DNS options. Invalid if using << '**DNSOption=**' if is_quadlet else '**--dns-option**' >>
+with << '**Network=**' if is_quadlet else '**--network**' >> that is set to **none** or **container:**_id_.

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

@@ -1,7 +1,11 @@
 ####> This option file is used in:
-####>   podman build, farm build
+####>   podman build, podman-build.unit.5.md.in, farm build
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `DNSOption=option`
+<< else >>
 #### **--dns-option**=*option*
+<< endif >>
 
 Set custom DNS options to be used during the build.

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

@@ -1,8 +1,13 @@
 ####> This option file is used in:
-####>   podman create, run
+####>   podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `DNSSearch=domain`
+<< else >>
 #### **--dns-search**=*domain*
+<< endif >>
 
-Set custom DNS search domains. Invalid if using **--dns-search** with **--network** that is set to **none** or **container:**_id_.
-Use **--dns-search=.** to remove the search domain.
+Set custom DNS search domains. Invalid if using << '**DNSSearch=**' if is_quadlet else '**--dns-search**' >>
+with with << '**Network=**' if is_quadlet else '**--network**' >> that is set to **none** or **container:**_id_.
+Use << '**DNSSearch=.**' if is_quadlet else '**--dns-search=.**' >> to remove the search domain.

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

@@ -1,7 +1,11 @@
 ####> This option file is used in:
-####>   podman build, farm build
+####>   podman build, podman-build.unit.5.md.in, farm build
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+<< if is_quadlet >>
+### `DNSSearch=domain`
+<< else >>
 #### **--dns-search**=*domain*
+<< endif >>
 
 Set custom DNS search domains to be used during the build.