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.
- Majority of the text in the new files is copied from
  the podman-systemd.unit.5.md
- Removes the original podman-systemd.unit.5.md file and links to the
  podman-quadlet.7.md instead.
- 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/links/podman-systemd.unit.5

@@ -0,0 +1 @@
+.so man7/podman-quadlet.7

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,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 option and Quadlet
+option. 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" >>
+```
+
+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**.