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.
- Adds the podman-quadlet-basic-usage.7.md for quadlet examples.
- Majority of the text in the new files is copied from the podman-systemd.unit.5.md
- Adds support for very simple condditional in the markdown_preprocess.
- Uses new logic in markdown_preprocess in options/*.md to use a 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

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