Man pages: refactor common options: --preserve-fds, -it

Three simple options shared among podman-create, exec, run. I mostly went with the podman-run versions. For --tty, this means that create and exec get the long stdout/stderr note. (The example, though, remains only in podman-run). For -i, mostly boldspace changes. For --preserve-fds, podman-exec now has the "not with remote" note (which it didn't until now) Signed-off-by: Ed Santiago <[email protected]>
containers · Sep 14, 2022 · b6c75a3 · b6c75a3
1 parent e1b3d98
commit b6c75a3
Show file tree

Hide file tree

Showing 8 changed files with 27 additions and 41 deletions.
diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore
@@ -26,6 +26,7 @@ podman-push.1.md
 podman-rm.1.md
 podman-run.1.md
 podman-search.1.md
+podman-start.1.md
 podman-stop.1.md
 podman-unpause.1.md
 podman-update.1.md
diff --git a/docs/source/markdown/options/interactive.md b/docs/source/markdown/options/interactive.md
@@ -0,0 +1,3 @@
+#### **--interactive**, **-i**
+
+When set to **true**, keep stdin open even if not attached. The default is **false**.
diff --git a/docs/source/markdown/options/preserve-fds.md b/docs/source/markdown/options/preserve-fds.md
@@ -0,0 +1,5 @@
+#### **--preserve-fds**=*N*
+
+Pass down to the process N additional file descriptors (in addition to 0, 1, 2).
+The total FDs will be 3+N.
+(This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
diff --git a/docs/source/markdown/options/tty.md b/docs/source/markdown/options/tty.md
@@ -0,0 +1,9 @@
+#### **--tty**, **-t**
+
+Allocate a pseudo-TTY. The default is **false**.
+
+When set to **true**, Podman will allocate a pseudo-tty and attach to the standard
+input of the container. This can be used, for example, to run a throwaway
+interactive shell.
+
+**NOTE**: The --tty flag prevents redirection of standard output.  It combines STDOUT and STDERR, it can insert control characters, and it can hang pipes. This option should only be used when run interactively in a terminal. When feeding input to Podman, use -i only, not -it.
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
@@ -224,9 +224,7 @@ pod when that pod is not running.
 
 @@option init-path
 
-#### **--interactive**, **-i**
-
-Keep STDIN open even if not attached. The default is *false*.
+@@option interactive
 
 @@option ip
 
@@ -438,16 +436,7 @@ When size is `0`, there is no limit on the amount of memory used for IPC by the
 
 @@option tmpfs
 
-#### **--tty**, **-t**
-
-Allocate a pseudo-TTY. The default is *false*.
-
-When set to true Podman will allocate a pseudo-tty and attach to the standard
-input of the container. This can be used, for example, to run a throwaway
-interactive shell. The default is false.
-
-Note: The **-t** option is incompatible with a redirection of the Podman client
-standard input.
+@@option tty
 
 @@option tz
 

diff --git a/docs/source/markdown/podman-exec.1.md.in b/docs/source/markdown/podman-exec.1.md.in
@@ -31,24 +31,18 @@ This option allows arbitrary environment variables that are available for the pr
 
 Read in a line delimited file of environment variables.
 
-#### **--interactive**, **-i**
-
-When set to true, keep stdin open even if not attached. The default is *false*.
+@@option interactive
 
 #### **--latest**, **-l**
 
 Instead of providing the container name or ID, use the last created container. If you use methods other than Podman
 to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
 
-#### **--preserve-fds**=*N*
-
-Pass down to the process N additional file descriptors (in addition to 0, 1, 2).  The total FDs will be 3+N.
+@@option preserve-fds
 
 @@option privileged
 
-#### **--tty**, **-t**
-
-Allocate a pseudo-TTY.
+@@option tty
 
 #### **--user**, **-u**
 

diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in
@@ -245,9 +245,7 @@ Print usage statement
 
 @@option init-path
 
-#### **--interactive**, **-i**
-
-When set to **true**, keep stdin open even if not attached. The default is **false**.
+@@option interactive
 
 @@option ip
 
@@ -366,10 +364,7 @@ If a container is run with a pod, and the pod has an infra-container, the infra-
 
 @@option pod-id-file.container
 
-#### **--preserve-fds**=*N*
-
-Pass down to the process N additional file descriptors (in addition to 0, 1, 2).
-The total FDs will be 3+N. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
+@@option preserve-fds
 
 @@option privileged
 
@@ -478,15 +473,7 @@ Sets whether the signals sent to the **podman run** command are proxied to the c
 
 @@option tmpfs
 
-#### **--tty**, **-t**
-
-Allocate a pseudo-TTY. The default is **false**.
-
-When set to **true**, Podman will allocate a pseudo-tty and attach to the standard
-input of the container. This can be used, for example, to run a throwaway
-interactive shell. The default is **false**.
-
-**NOTE**: The --tty flag prevents redirection of standard output.  It combines STDOUT and STDERR, it can insert control characters, and it can hang pipes. This option should only be used when run interactively in a terminal. When feeding input to Podman, use -i only, not -it.
+@@option tty
 
 ```
 echo "asdf" | podman run --rm -i someimage /bin/cat

diff --git a/docs/source/markdown/podman-start.1.md → docs/source/markdown/podman-start.1.md.in b/docs/source/markdown/podman-start.1.md → docs/source/markdown/podman-start.1.md.in
@@ -53,9 +53,7 @@ Valid filters are listed below:
 | pod             | [Pod] name or full or partial ID of pod                                          |
 | network         | [Network] name or full ID of network                                             |
 
-#### **--interactive**, **-i**
-
-Attach container's STDIN. The default is false.
+@@option interactive
 
 #### **--latest**, **-l**
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		#### --interactive, -i

		When set to true, keep stdin open even if not attached. The default is false.