Man pages: refactor common options: --pod-id-file

Much like --cidfile (#15414), --pod-id-file has two meanings.
One is used in pod-related commands, one in container ones.
Both meanings read the file, so the read/write split used
in --cidfile is not applicable here.

podman-pod-create keeps its --pod-id-file option because
that one cannot be refactored: that's the only command (now)
that writes a pod-id file.

Reviewable using hack/markdown-preprocess-review but I
did take some liberties with the #### args because they
were wrong. And, since I had to much with the description
text anyway (resulting in diffs), I also took the liberty
of cleaning up a double space.

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

8 files changed, 15 insertions, 16 deletions

diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore
index 5a30aab78..2bdcce197 100644
--- a/docs/source/markdown/.gitignore
+++ b/docs/source/markdown/.gitignore
@@ -13,6 +13,9 @@ podman-manifest-push.1.md
 podman-pause.1.md
 podman-pod-clone.1.md
 podman-pod-create.1.md
+podman-pod-rm.1.md
+podman-pod-start.1.md
+podman-pod-stop.1.md
 podman-pull.1.md
 podman-push.1.md
 podman-rm.1.md
diff --git a/docs/source/markdown/options/pod-id-file.container.md b/docs/source/markdown/options/pod-id-file.container.md
new file mode 100644
index 000000000..1c102dc6b
--- /dev/null
+++ b/docs/source/markdown/options/pod-id-file.container.md
@@ -0,0 +1,4 @@
+#### **--pod-id-file**=*file*
+
+Run container in an existing pod and read the pod's ID from the specified *file*.
+If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is.
diff --git a/docs/source/markdown/options/pod-id-file.pod.md b/docs/source/markdown/options/pod-id-file.pod.md
new file mode 100644
index 000000000..69e2ac6e9
--- /dev/null
+++ b/docs/source/markdown/options/pod-id-file.pod.md
@@ -0,0 +1,3 @@
+#### **--pod-id-file**=*file*
+
+Read pod ID from the specified *file* and <<subcommand>> the pod. Can be specified multiple times.
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
index 2827964f7..b943783cb 100644
--- a/docs/source/markdown/podman-create.1.md.in
+++ b/docs/source/markdown/podman-create.1.md.in
@@ -476,9 +476,7 @@ Default is to create a private PID namespace for the container
 Run container in an existing pod. If you want Podman to make the pod for you, preference the pod name with `new:`.
 To make a pod with more granular options, use the `podman pod create` command before creating a container.
 
-#### **--pod-id-file**=*path*
-
-Run container in an existing pod and read the pod's ID from the specified file. If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is.
+@@option pod-id-file.container
 
 #### **--privileged**
 
diff --git a/docs/source/markdown/podman-pod-rm.1.md b/docs/source/markdown/podman-pod-rm.1.md.in
index befab6791..54646ebe3 100644
--- a/docs/source/markdown/podman-pod-rm.1.md
+++ b/docs/source/markdown/podman-pod-rm.1.md.in
@@ -29,9 +29,7 @@ ExecStop directive of a systemd service referencing that pod.
 
 Instead of providing the pod name or ID, remove the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
 
-#### **--pod-id-file**
-
-Read pod ID from the specified file and remove the pod.  Can be specified multiple times.
+@@option pod-id-file.pod
 
 #### **--time**, **-t**=*seconds*
 
diff --git a/docs/source/markdown/podman-pod-start.1.md b/docs/source/markdown/podman-pod-start.1.md.in
index 45fc50c51..6a47ce1b9 100644
--- a/docs/source/markdown/podman-pod-start.1.md
+++ b/docs/source/markdown/podman-pod-start.1.md.in
@@ -20,9 +20,7 @@ Starts all pods
 
 Instead of providing the pod name or ID, start the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
 
-#### **--pod-id-file**
-
-Read pod ID from the specified file and start the pod.  Can be specified multiple times.
+@@option pod-id-file.pod
 
 ## EXAMPLE
 
diff --git a/docs/source/markdown/podman-pod-stop.1.md b/docs/source/markdown/podman-pod-stop.1.md.in
index bded0ba7d..879645cd9 100644
--- a/docs/source/markdown/podman-pod-stop.1.md
+++ b/docs/source/markdown/podman-pod-stop.1.md.in
@@ -25,9 +25,7 @@ ExecStop directive of a systemd service referencing that pod.
 
 Instead of providing the pod name or ID, stop the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
 
-#### **--pod-id-file**
-
-Read pod ID from the specified file and stop the pod.  Can be specified multiple times.
+@@option pod-id-file.pod
 
 #### **--time**, **-t**=*seconds*
 
diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in
index cdfa9366a..077ad7a4a 100644
--- a/docs/source/markdown/podman-run.1.md.in
+++ b/docs/source/markdown/podman-run.1.md.in
@@ -496,10 +496,7 @@ Run container in an existing pod. If you want Podman to make the pod for you, pr
 To make a pod with more granular options, use the **podman pod create** command before creating a container.
 If a container is run with a pod, and the pod has an infra-container, the infra-container will be started before the container is.
 
-#### **--pod-id-file**=*path*
-
-Run container in an existing pod and read the pod's ID from the specified file.
-If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is.
+@@option pod-id-file.container
 
 #### **--preserve-fds**=*N*