Man pages: refactor common options: --volumes-from

Removed a spurious right-bracket; went with upper-case for options;
removed 'you's; added some <<container|pod>>s.

Hard to review because none of the existing man pages had it
quite right.

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

5 files changed, 36 insertions, 130 deletions

diff --git a/docs/source/markdown/options/volumes-from.md b/docs/source/markdown/options/volumes-from.md
new file mode 100644
index 000000000..ebef116e7
--- /dev/null
+++ b/docs/source/markdown/options/volumes-from.md
@@ -0,0 +1,32 @@
+#### **--volumes-from**=*CONTAINER[:OPTIONS]*
+
+Mount volumes from the specified container(s). Used to share volumes between
+containers<<| and pods>>. The *options* is a comma-separated list with the following available elements:
+
+* **rw**|**ro**
+* **z**
+
+Mounts already mounted volumes from a source container onto another
+<<container|pod>>. _CONTAINER_ may be a name or ID.
+To share a volume, use the --volumes-from option when running
+the target container. Volumes can be shared even if the source container
+is not running.
+
+By default, Podman mounts the volumes in the same mode (read-write or
+read-only) as it is mounted in the source container.
+This can be changed by adding a `ro` or `rw` _option_.
+
+Labeling systems like SELinux require that proper labels are placed on volume
+content mounted into a <<container|pod>>. Without a label, the security system might
+prevent the processes running inside the container from using the content. By
+default, Podman does not change the labels set by the OS.
+
+To change a label in the <<container|pod>> context, add `z` to the volume mount.
+This suffix tells Podman to relabel file objects on the shared volumes. The `z`
+option tells Podman that two entities share the volume content. As a result,
+Podman labels the content with a shared content label. Shared volume labels allow
+all containers to read/write content.
+
+If the location of the volume from the source container overlaps with
+data residing on a target <<container|pod>>, then the volume hides
+that data on the target.
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
index 17ef704e6..0d03c8671 100644
--- a/docs/source/markdown/podman-create.1.md.in
+++ b/docs/source/markdown/podman-create.1.md.in
@@ -543,38 +543,7 @@ Use _VARIANT_ instead of the default architecture variant of the container image
 
 Use the **--group-add keep-groups** option to pass the user's supplementary group access into the container.
 
-#### **--volumes-from**=*CONTAINER[:OPTIONS]]*
-
-Mount volumes from the specified container(s). Used to share volumes between
-containers. The *options* is a comma-separated list with the following available elements:
-
-* **rw**|**ro**
-* **z**
-
-Mounts already mounted volumes from a source container onto another
-container. You must supply the source's container-id or container-name.
-To share a volume, use the --volumes-from option when running
-the target container. You can share volumes even if the source container
-is not running.
-
-By default, Podman mounts the volumes in the same mode (read-write or
-read-only) as it is mounted in the source container.
-You can change this by adding a `ro` or `rw` _option_.
-
-Labeling systems like SELinux require that proper labels are placed on volume
-content mounted into a container. Without a label, the security system might
-prevent the processes running inside the container from using the content. By
-default, Podman does not change the labels set by the OS.
-
-To change a label in the container context, you can add `z` to the volume mount.
-This suffix tells Podman to relabel file objects on the shared volumes. The `z`
-option tells Podman that two containers share the volume content. As a result,
-Podman labels the content with a shared content label. Shared volume labels allow
-all containers to read/write content.
-
-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.
+@@option volumes-from
 
 @@option workdir
 
diff --git a/docs/source/markdown/podman-pod-clone.1.md.in b/docs/source/markdown/podman-pod-clone.1.md.in
index 1d7b1f259..15f7ec208 100644
--- a/docs/source/markdown/podman-pod-clone.1.md.in
+++ b/docs/source/markdown/podman-pod-clone.1.md.in
@@ -124,39 +124,7 @@ clone process has completed. All containers within the pod are started.
 
 @@option volume
 
-#### **--volumes-from**=*container[:options]]*
-
-Mount volumes from the specified container(s). Used to share volumes between
-containers and pods. The *options* is a comma-separated list with the following available elements:
-
-* **rw**|**ro**
-* **z**
-
-Mounts already mounted volumes from a source container into another
-pod. Must supply the source's container-id or container-name.
-To share a volume, use the --volumes-from option when running
-the target container. Volumes can be shared even if the source container
-is not running.
-
-By default, Podman mounts the volumes in the same mode (read-write or
-read-only) as it is mounted in the source container.
-This can be changed by adding a `ro` or `rw` _option_.
-
-Labeling systems like SELinux require that proper labels are placed on volume
-content mounted into a pod. Without a label, the security system might
-prevent the processes running inside the container from using the content. By
-default, Podman does not change the labels set by the OS.
-
-To change a label in the pod context, add `z` to the volume mount.
-This suffix tells Podman to relabel file objects on the shared volumes. The `z`
-option tells Podman that two entities share the volume content. As a result,
-Podman labels the content with a shared content label. Shared volume labels allow
-all containers to read/write content.
-
-If the location of the volume from the source container overlaps with
-data residing on a target pod, then the volume hides
-that data on the target.
-
+@@option volumes-from
 
 ## EXAMPLES
 ```
diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in
index 3a3909340..f1fdc3e6b 100644
--- a/docs/source/markdown/podman-pod-create.1.md.in
+++ b/docs/source/markdown/podman-pod-create.1.md.in
@@ -265,39 +265,7 @@ When size is `0`, there is no limit on the amount of memory used for IPC by the
 
 @@option volume
 
-#### **--volumes-from**=*container[:options]]*
-
-Mount volumes from the specified container(s). Used to share volumes between
-containers and pods. The *options* is a comma-separated list with the following available elements:
-
-* **rw**|**ro**
-* **z**
-
-Mounts already mounted volumes from a source container into another
-pod. You must supply the source's container-id or container-name.
-To share a volume, use the --volumes-from option when running
-the target container. You can share volumes even if the source container
-is not running.
-
-By default, Podman mounts the volumes in the same mode (read-write or
-read-only) as it is mounted in the source container.
-You can change this by adding a `ro` or `rw` _option_.
-
-Labeling systems like SELinux require that proper labels are placed on volume
-content mounted into a pod. Without a label, the security system might
-prevent the processes running inside the container from using the content. By
-default, Podman does not change the labels set by the OS.
-
-To change a label in the pod context, you can add `z` to the volume mount.
-This suffix tells Podman to relabel file objects on the shared volumes. The `z`
-option tells Podman that two entities share the volume content. As a result,
-Podman labels the content with a shared content label. Shared volume labels allow
-all containers to read/write content.
-
-If the location of the volume from the source container overlaps with
-data residing on a target pod, then the volume hides
-that data on the target.
-
+@@option volumes-from
 
 ## EXAMPLES
 
diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in
index 493a7494a..7b762d060 100644
--- a/docs/source/markdown/podman-run.1.md.in
+++ b/docs/source/markdown/podman-run.1.md.in
@@ -588,38 +588,7 @@ Use _VARIANT_ instead of the default architecture variant of the container image
 
 Use the **--group-add keep-groups** option to pass the user's supplementary group access into the container.
 
-#### **--volumes-from**=*CONTAINER[:OPTIONS]*
-
-Mount volumes from the specified container(s). Used to share volumes between
-containers. The *options* is a comma-separated list with the following available elements:
-
-* **rw**|**ro**
-* **z**
-
-Mounts already mounted volumes from a source container onto another
-container. You must supply the source's container-id or container-name.
-To share a volume, use the --volumes-from option when running
-the target container. You can share volumes even if the source container
-is not running.
-
-By default, Podman mounts the volumes in the same mode (read-write or
-read-only) as it is mounted in the source container.
-You can change this by adding a `ro` or `rw` _option_.
-
-Labeling systems like SELinux require that proper labels are placed on volume
-content mounted into a container. Without a label, the security system might
-prevent the processes running inside the container from using the content. By
-default, Podman does not change the labels set by the OS.
-
-To change a label in the container context, you can add `z` to the volume mount.
-This suffix tells Podman to relabel file objects on the shared volumes. The `z`
-option tells Podman that two containers share the volume content. As a result,
-Podman labels the content with a shared content label. Shared volume labels allow
-all containers to read/write content.
-
-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.
+@@option volumes-from
 
 @@option workdir