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>

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

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.

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.

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**
 

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*
 

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
 

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*
 

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*