Refactor common man page options, phase 2

Followup to #15174. These are the options that are easy(ish)
to review: those that have only drifted slightly, and need
only minor tweaks to bring back to sanity. For the most part,
I went with the text in podman-run because that was cleaned up
in #5192 way back in 2020. These diffs primarily consist of
using '**' (star star) instead of backticks, plus other
formatting and punctuation changes.

This PR also adds a README in the options dir, and a new
convention: <<container text...|pod text...>> which tries
to do the right thing based on whether the man page name
includes "-pod-" or not. Since that's kind of hairy code,
I've also added a test suite for it.

Finally, since this is impossible to review by normal means,
I'm temporarily committing hack/markdown-preprocess-review,
a script that will diff option-by-option. I will remove it
once we finish this cleanup, but be advised that there are
still 130+ options left to examine, and some of those are
going to be really hard to reunite.

Review script usage: simply run it (you need to have 'diffuse'
installed). It isn't exactly obvious, but it shouldn't take more
than a minute to figure out. The rightmost column (zzz-chosen.md)
is the "winner", the actual content that will be used henceforth.
You really want an ultrawide screen here.

Signed-off-by: Ed Santiago <santiago@redhat.com>

1 files changed, 22 insertions, 0 deletions

diff --git a/docs/source/markdown/options/secret.md b/docs/source/markdown/options/secret.md
new file mode 100644
index 000000000..ff2c0ab83
--- /dev/null
+++ b/docs/source/markdown/options/secret.md
@@ -0,0 +1,22 @@
+#### **--secret**=*secret[,opt=opt ...]*
+
+Give the container access to a secret. Can be specified multiple times.
+
+A secret is a blob of sensitive data which a container needs at runtime but
+should not be stored in the image or in source control, such as usernames and passwords,
+TLS certificates and keys, SSH keys or other important generic strings or binary content (up to 500 kb in size).
+
+When secrets are specified as type `mount`, the secrets are copied and mounted into the container when a container is created.
+When secrets are specified as type `env`, the secret will be set as an environment variable within the container.
+Secrets are written in the container at the time of container creation, and modifying the secret using `podman secret` commands
+after the container is created will not affect the secret inside the container.
+
+Secrets and its storage are managed using the `podman secret` command.
+
+Secret Options
+
+- `type=mount|env`    : How the secret will be exposed to the container. Default mount.
+- `target=target`     : Target of secret. Defaults to secret name.
+- `uid=0`             : UID of secret. Defaults to 0. Mount secret type only.
+- `gid=0`             : GID of secret. Defaults to 0. Mount secret type only.
+- `mode=0`            : Mode of secret. Defaults to 0444. Mount secret type only.