17 files changed, 59 insertions, 72 deletions
diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore
index 2bdcce197..85aed3be0 100644
--- a/docs/source/markdown/.gitignore
+++ b/docs/source/markdown/.gitignore
@@ -3,6 +3,7 @@ podman-build.1.md
 podman-container-clone.1.md
 podman-container-runlabel.1.md
 podman-create.1.md
+podman-exec.1.md
 podman-image-sign.1.md
 podman-kill.1.md
 podman-kube-play.1.md
diff --git a/docs/source/markdown/options/device-cgroup-rule.md b/docs/source/markdown/options/device-cgroup-rule.md
new file mode 100644
index 000000000..0ba3d4668
--- /dev/null
+++ b/docs/source/markdown/options/device-cgroup-rule.md
@@ -0,0 +1,6 @@
+#### **--device-cgroup-rule**=*"type major:minor mode"*
+
+Add a rule to the cgroup allowed devices list. The rule is expected to be in the format specified in the Linux kernel documentation (Documentation/cgroup-v1/devices.txt):
+       - type: a (all), c (char), or b (block);
+       - major and minor: either a number, or * for all;
+       - mode: a composition of r (read), w (write), and m (mknod(2)).
diff --git a/docs/source/markdown/options/env-merge.md b/docs/source/markdown/options/env-merge.md
new file mode 100644
index 000000000..aa1aa003d
--- /dev/null
+++ b/docs/source/markdown/options/env-merge.md
@@ -0,0 +1,5 @@
+#### **--env-merge**=*env*
+
+Preprocess default environment variables for the containers. For example
+if image contains environment variable `hello=world` user can preprocess
+it using `--env-merge hello=${hello}-some` so new value will be `hello=world-some`.
diff --git a/docs/source/markdown/options/gidmap.container.md b/docs/source/markdown/options/gidmap.container.md
new file mode 100644
index 000000000..a3c9df33d
--- /dev/null
+++ b/docs/source/markdown/options/gidmap.container.md
@@ -0,0 +1,8 @@
+#### **--gidmap**=*container_gid:host_gid:amount*
+
+Run the container in a new user namespace using the supplied GID mapping. This
+option conflicts with the **--userns** and **--subgidname** options. This
+option provides a way to map host GIDs to container GIDs in the same way as
+__--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__.
+
+Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod.
diff --git a/docs/source/markdown/options/gidmap.pod.md b/docs/source/markdown/options/gidmap.pod.md
new file mode 100644
index 000000000..0d58cc527
--- /dev/null
+++ b/docs/source/markdown/options/gidmap.pod.md
@@ -0,0 +1,4 @@
+#### **--gidmap**=*pod_gid:host_gid:amount*
+
+GID map for the user namespace. Using this flag will run all containers in the pod with user namespace enabled.
+It conflicts with the **--userns** and **--subgidname** flags.
diff --git a/docs/source/markdown/options/ignore.md b/docs/source/markdown/options/ignore.md
new file mode 100644
index 000000000..231d75957
--- /dev/null
+++ b/docs/source/markdown/options/ignore.md
@@ -0,0 +1,5 @@
+#### **--ignore**, **-i**
+
+Ignore errors when specified <<containers|pods>> are not in the container store.  A user
+might have decided to manually remove a <<container|pod>> which would lead to a failure
+during the ExecStop directive of a systemd service referencing that <<container|pod>>.
diff --git a/docs/source/markdown/options/workdir.md b/docs/source/markdown/options/workdir.md
new file mode 100644
index 000000000..12f3ddd44
--- /dev/null
+++ b/docs/source/markdown/options/workdir.md
@@ -0,0 +1,7 @@
+#### **--workdir**, **-w**=*dir*
+
+Working directory inside the container.
+
+The default working directory for running binaries within a container is the root directory (**/**).
+The image developer can set a different default with the WORKDIR instruction. The operator
+can override the working directory by using the **-w** option.
diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in
index 87a21a7ae..693e0d3b9 100644
--- a/docs/source/markdown/podman-build.1.md.in
+++ b/docs/source/markdown/podman-build.1.md.in
@@ -293,6 +293,12 @@ environment variable.  `export BUILDAH_FORMAT=docker`
 Overrides the first `FROM` instruction within the Containerfile.  If there are multiple
 FROM instructions in a Containerfile, only the first is changed.
 
+With the remote podman client, not all container transports will work as
+expected. For example, oci-archive:/x.tar will reference /x.tar on the remote
+machine instead of on the client. If you need to support remote podman clients,
+it is best to restrict yourself to containers-storage: and docker://
+transports.
+
 #### **--help**, **-h**
 
 Print usage statement
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
index c83083674..71935a647 100644
--- a/docs/source/markdown/podman-create.1.md.in
+++ b/docs/source/markdown/podman-create.1.md.in
@@ -144,12 +144,7 @@ Podman may load kernel modules required for using the specified
 device. The devices that podman will load modules when necessary are:
 /dev/fuse.
 
-#### **--device-cgroup-rule**=*"type major:minor mode"*
-
-Add a rule to the cgroup allowed devices list. The rule is expected to be in the format specified in the Linux kernel documentation (Documentation/cgroup-v1/devices.txt):
-       - type: a (all), c (char), or b (block);
-       - major and minor: either a number, or * for all;
-       - mode: a composition of r (read), w (write), and m (mknod(2)).
+@@option device-cgroup-rule
 
 #### **--device-read-bps**=*path*
 
@@ -213,16 +208,11 @@ Read in a line delimited file of environment variables. See **Environment** note
 
 @@option env-host
 
-@@option expose
-
-#### **--gidmap**=*container_gid:host_gid:amount*
+@@option env-merge
 
-Run the container in a new user namespace using the supplied GID mapping. This
-option conflicts with the **--userns** and **--subgidname** options. This
-option provides a way to map host GIDs to container GIDs in the same way as
-__--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__.
+@@option expose
 
-Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod.
+@@option gidmap.container
 
 @@option group-add
 
@@ -980,13 +970,7 @@ If the location of the volume from the source container overlaps with
 data residing on a target container, then the volume hides
 that data on the target.
 
-#### **--workdir**, **-w**=*dir*
-
-Working directory inside the container
-
-The default working directory for running binaries within a container is the root directory (/).
-The image developer can set a different default with the WORKDIR instruction. The operator
-can override the working directory by using the **-w** option.
+@@option workdir
 
 ## EXAMPLES
 
diff --git a/docs/source/markdown/podman-exec.1.md b/docs/source/markdown/podman-exec.1.md.in
index da61f3456..4f78f1c31 100644
--- a/docs/source/markdown/podman-exec.1.md
+++ b/docs/source/markdown/podman-exec.1.md.in
@@ -70,13 +70,7 @@ Sets the username or UID used and optionally the groupname or GID for the specif
 The following examples are all valid:
 --user [user | user:group | uid | uid:gid | user:gid | uid:group ]
 
-#### **--workdir**, **-w**=*path*
-
-Working directory inside the container
-
-The default working directory for running binaries within a container is the root directory (/).
-The image developer can set a different default with the WORKDIR instruction, which can be overridden
-when creating the container.
+@@option workdir
 
 ## Exit Status
 
diff --git a/docs/source/markdown/podman-pod-clone.1.md.in b/docs/source/markdown/podman-pod-clone.1.md.in
index a5746fd84..c040f1c27 100644
--- a/docs/source/markdown/podman-pod-clone.1.md.in
+++ b/docs/source/markdown/podman-pod-clone.1.md.in
@@ -56,9 +56,7 @@ Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sd
 
 Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb)
 
-#### **--gidmap**=*pod_gid:host_gid:amount*
-
-GID map for the user namespace. Using this flag will run all containers in the pod with user namespace enabled. It conflicts with the `--userns` and `--subgidname` flags.
+@@option gidmap.pod
 
 #### **--help**, **-h**
 
diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in
index c12f296b4..702780c65 100644
--- a/docs/source/markdown/podman-pod-create.1.md.in
+++ b/docs/source/markdown/podman-pod-create.1.md.in
@@ -94,9 +94,7 @@ Set the exit policy of the pod when the last container exits.  Supported policie
 | *continue*         | The pod continues running, by keeping its infra container alive, when the last container exits. Used by default.           |
 | *stop*             | The pod (including its infra container) is stopped when the last container exits. Used in `kube play`.                     |
 
-#### **--gidmap**=*container_gid:host_gid:amount*
-
-GID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `--userns` and `--subgidname` flags.
+@@option gidmap.pod
 
 #### **--help**, **-h**
 
diff --git a/docs/source/markdown/podman-pod-rm.1.md.in b/docs/source/markdown/podman-pod-rm.1.md.in
index 54646ebe3..82e28acb1 100644
--- a/docs/source/markdown/podman-pod-rm.1.md.in
+++ b/docs/source/markdown/podman-pod-rm.1.md.in
@@ -19,11 +19,7 @@ Remove all pods.  Can be used in conjunction with \-f as well.
 
 Stop running containers and delete all stopped containers before removal of pod.
 
-#### **--ignore**, **-i**
-
-Ignore errors when specified pods are not in the container store.  A user might
-have decided to manually remove a pod which would lead to a failure during the
-ExecStop directive of a systemd service referencing that pod.
+@@option ignore
 
 #### **--latest**, **-l**
 
diff --git a/docs/source/markdown/podman-pod-stop.1.md.in b/docs/source/markdown/podman-pod-stop.1.md.in
index 879645cd9..3655c3938 100644
--- a/docs/source/markdown/podman-pod-stop.1.md.in
+++ b/docs/source/markdown/podman-pod-stop.1.md.in
@@ -15,11 +15,7 @@ Stop containers in one or more pods.  You may use pod IDs or names as input.
 
 Stops all pods
 
-#### **--ignore**, **-i**
-
-Ignore errors when specified pods are not in the container store.  A user might
-have decided to manually remove a pod which would lead to a failure during the
-ExecStop directive of a systemd service referencing that pod.
+@@option ignore
 
 #### **--latest**, **-l**
 
diff --git a/docs/source/markdown/podman-rm.1.md.in b/docs/source/markdown/podman-rm.1.md.in
index fa3031b29..c0fa94d82 100644
--- a/docs/source/markdown/podman-rm.1.md.in
+++ b/docs/source/markdown/podman-rm.1.md.in
@@ -56,11 +56,7 @@ Containers could have been created by a different container engine.
 In addition, forcing can be used to remove unusable containers, e.g. containers
 whose OCI runtime has become unavailable.
 
-#### **--ignore**, **-i**
-
-Ignore errors when specified containers are not in the container store.  A user
-might have decided to manually remove a container which would lead to a failure
-during the ExecStop directive of a systemd service referencing that container.
+@@option ignore
 
 #### **--latest**, **-l**
 
diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in
index 7fb7a455b..16b5ffcab 100644
--- a/docs/source/markdown/podman-run.1.md.in
+++ b/docs/source/markdown/podman-run.1.md.in
@@ -178,9 +178,7 @@ Podman may load kernel modules required for using the specified
 device. The devices that Podman will load modules when necessary are:
 /dev/fuse.
 
-#### **--device-cgroup-rule**=*rule*
-
-Add a rule to the cgroup allowed devices list
+@@option device-cgroup-rule
 
 #### **--device-read-bps**=*path:rate*
 
@@ -245,16 +243,11 @@ Read in a line delimited file of environment variables. See **Environment** note
 
 @@option env-host
 
-@@option expose
-
-#### **--gidmap**=*container_gid:host_gid:amount*
+@@option env-merge
 
-Run the container in a new user namespace using the supplied GID mapping. This
-option conflicts with the **--userns** and **--subgidname** options. This
-option provides a way to map host GIDs to container GIDs in the same way as
-__--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__.
+@@option expose
 
-Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod.
+@@option gidmap.container
 
 @@option group-add
 
@@ -1036,13 +1029,7 @@ If the location of the volume from the source container overlaps with
 data residing on a target container, then the volume hides
 that data on the target.
 
-#### **--workdir**, **-w**=*dir*
-
-Working directory inside the container.
-
-The default working directory for running binaries within a container is the root directory (**/**).
-The image developer can set a different default with the WORKDIR instruction. The operator
-can override the working directory by using the **-w** option.
+@@option workdir
 
 ## Exit Status
 
diff --git a/docs/source/markdown/podman-stop.1.md.in b/docs/source/markdown/podman-stop.1.md.in
index 04fc9387f..9aaccdfaa 100644
--- a/docs/source/markdown/podman-stop.1.md.in
+++ b/docs/source/markdown/podman-stop.1.md.in
@@ -47,11 +47,7 @@ Valid filters are listed below:
 | pod             | [Pod] name or full or partial ID of pod                                          |
 | network         | [Network] name or full ID of network                                             |
 
-#### **--ignore**, **-i**
-
-Ignore errors when specified containers are not in the container store.  A user
-might have decided to manually remove a container which would lead to a failure
-during the ExecStop directive of a systemd service referencing that container.
+@@option ignore
 
 #### **--latest**, **-l**