Rewrite the Quadlet documentation.

This commit does the following:

- Splits the podman-systemd.unit.5.md into multiple files - one for each
  quadlet file type, podman-quadlet.7.md for general quadlet information
  and podman-quadlet-basic-usage.7.md for quadlet examples.
- Removes the original podman-systemd.unit.5.md file.
- Adds support for jinja2 templating language in the markdown_preprocess.
- Uses jinja2 in options/*.md to use the single .md file for both podman
  subcommands man-pages and quadlet man-pages. This deduplicates
  the Quadlet man-pages a lot.
- Adds new `@@option quadlet:source.md` preprocess command to import
  such .md files from options directory.

Signed-off-by: Jan Kaluza <[email protected]>

Author: Jan Kaluza

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,37 @@ 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`.
 
+Jinja2 Templating
+=================
+
+Some options are used as both Podman command line option and Quadlet
+option. To reduce the duplication, the Jinja2 templating system can be
+used to define parts which should be rendered only in Quadlet man-pages:
+
+```
+    {% if is_quadlet %}
+    ### `DNS=`
+    {% else %}
+    #### **--dns**=*ipaddr*
+    {% endif %}
+```
+
+It is also possible to use in-line condition:
+
+```
+    {{{ '**DNS=.**' if is_quadlet else '**--dns**' }}}
+```
+
+Following variables are available for Jinja2 Templates:
+
+- `is_quadlet`: True if file is imported using `@@option quadlet:foo`.
+- `subcommand`: Same as `<<subcommand>>`, see below.
+This allows the shared use of examples in the option file:
+- `fullcommand`: Same as `<<fullsubcommand>>`, see below.
+
+For more information about Jinja2, check
+https://jinja.palletsprojects.com/en/stable/.
+
 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, container.unit.5.md.in, create, farm build, pod create, 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/annotation.container.md

@@ -1,7 +1,11 @@
 ####> This option file is used in:
-####>   podman create, kube play, run
+####>   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

@@ -2,7 +2,11 @@
 ####>   podman build, farm build
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
+{% if is_quadlet %}
+### `Annotation=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 build.unit.5.md.in, create, 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, build.unit.5.md.in, container runlabel, create, farm build, image sign, 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/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 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 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, 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)**.