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: jankaluza

docs/source/markdown/.gitignore

@@ -69,3 +69,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-network.unit.5.md
+podman-pod.unit.5.md
+podman-volume.unit.5.md
+

docs/source/markdown/links/quadlet.5

@@ -1 +1 @@
-.so man5/podman-systemd.unit.5
+.so man7/podman-quadlet.7

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, 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/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

@@ -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 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/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.