Merge pull request containers#16743 from ashley-cui/secdocs

[CI:DOCS] Clarify secret target behavior

docs/source/markdown/options/secret.md

@@ -19,8 +19,28 @@ 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.
+- `type=mount|env`    : How the secret will be exposed to the container.
+                        `mount` mounts the secret into the container as a file.
+                        `env` exposes the secret as a environment variable.
+                        Defaults to `mount`.
+- `target=target`     : Target of secret.
+                        For mounted secrets, this is the path to the secret inside the container.
+                        If a fully qualified path is provided, the secret will be mounted at that location.
+                        Otherwise, the secret will be mounted to `/run/secrets/target`.
+                        If target is not set, by default the secret will be mounted to `/run/secrets/secretname`.
+                        For env secrets, this is the environment variable key. Defaults to `secretname`.
 - `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.
+
+
+Examples
+
+Mount at `/my/location/mysecret` with UID 1.
+```--secret mysecret,target=/my/location/mysecret,uid=1```
+
+Mount at `/run/secrets/customtarget` with mode 0777.
+```--secret mysecret,target=customtarget,mode=0777```
+
+Create a secret environment variable called `ENVSEC`.
+```--secret mysecret,type=env,target=ENVSEC```