From 8c76738571f2a2c4b177a3523aae8f29cf9703fa Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Wed, 10 Aug 2022 07:00:42 -0600 Subject: [PATCH] Man pages: refactor common options (misc) Accumulated cleanup from the man-page deduplication effort. Various minor things that slipped. --publish-all : remove duplicate "default is false" (toth @dilyanpalauzov) --shm-size : rephrase 'you' and 'y'all' --tls-verify : make narrower, add asterisks to true/false, and linkify containers-registries.conf --volume : incorporate feedback from @mheon rename pid.md to pid.container.md, because there's a pid.pod.md for the --pid option used in pod-related man pages. ...and some whitespace, comma, other minor edits Fixes: #15356 Signed-off-by: Ed Santiago --- docs/source/markdown/options/creds.md | 4 ++-- .../markdown/options/{pid.md => pid.container.md} | 0 docs/source/markdown/options/publish-all.md | 4 ++-- docs/source/markdown/options/shm-size.md | 2 +- docs/source/markdown/options/tls-verify.md | 8 +++++--- docs/source/markdown/options/volume.md | 14 +++++++------- docs/source/markdown/podman-create.1.md.in | 2 +- docs/source/markdown/podman-run.1.md.in | 2 +- 8 files changed, 19 insertions(+), 17 deletions(-) rename docs/source/markdown/options/{pid.md => pid.container.md} (100%) diff --git a/docs/source/markdown/options/creds.md b/docs/source/markdown/options/creds.md index 23399dda47..5ea7a13718 100644 --- a/docs/source/markdown/options/creds.md +++ b/docs/source/markdown/options/creds.md @@ -1,5 +1,5 @@ #### **--creds**=*[username[:password]]* -The [username[:password]] to use to authenticate with the registry if required. +The [username[:password]] to use to authenticate with the registry, if required. If one or both values are not supplied, a command line prompt will appear and the -value can be entered. The password is entered without echo. +value can be entered. The password is entered without echo. diff --git a/docs/source/markdown/options/pid.md b/docs/source/markdown/options/pid.container.md similarity index 100% rename from docs/source/markdown/options/pid.md rename to docs/source/markdown/options/pid.container.md diff --git a/docs/source/markdown/options/publish-all.md b/docs/source/markdown/options/publish-all.md index 6651599a0b..9c19712331 100644 --- a/docs/source/markdown/options/publish-all.md +++ b/docs/source/markdown/options/publish-all.md @@ -2,8 +2,8 @@ Publish all exposed ports to random ports on the host interfaces. The default is **false**. -When set to **true**, publish all exposed ports to the host interfaces. The -default is **false**. If the operator uses **-P** (or **-p**) then Podman will make the +When set to **true**, publish all exposed ports to the host interfaces. +If the operator uses **-P** (or **-p**) then Podman will make the exposed port accessible on the host and the ports will be available to any client that can reach the host. diff --git a/docs/source/markdown/options/shm-size.md b/docs/source/markdown/options/shm-size.md index 18cafcb860..45b3bb03a0 100644 --- a/docs/source/markdown/options/shm-size.md +++ b/docs/source/markdown/options/shm-size.md @@ -1,6 +1,6 @@ #### **--shm-size**=*number[unit]* Size of _/dev/shm_. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). -If you omit the unit, the system uses bytes. If you omit the size entirely, the default is **64m**. +If the unit is omitted, the system uses bytes. If the size is omitted, the default is **64m**. When _size_ is **0**, there is no limit on the amount of memory used for IPC by the <>. This option conflicts with **--ipc=host**. diff --git a/docs/source/markdown/options/tls-verify.md b/docs/source/markdown/options/tls-verify.md index e3d6f491fb..b6fbaef07c 100644 --- a/docs/source/markdown/options/tls-verify.md +++ b/docs/source/markdown/options/tls-verify.md @@ -1,5 +1,7 @@ #### **--tls-verify** -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, -then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, -TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. +Require HTTPS and verify certificates when contacting registries (default: **true**). +If explicitly set to **true**, TLS verification will be used. +If set to **false**, TLS verification will not be used. +If not specified, TLS verification will be used unless the target registry +is listed as an insecure registry in **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** diff --git a/docs/source/markdown/options/volume.md b/docs/source/markdown/options/volume.md index 9c4a7f9810..36a8a8430f 100644 --- a/docs/source/markdown/options/volume.md +++ b/docs/source/markdown/options/volume.md @@ -3,8 +3,13 @@ Create a bind mount. If `-v /HOST-DIR:/CONTAINER-DIR` is specified, Podman bind mounts `/HOST-DIR` from the host into `/CONTAINER-DIR` in the Podman container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the named -volume from the host into the container. If no such named volume exists, Podman will -create one. (Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes will be mounted from the remote server, not necessarily the client machine.) +volume from the host into the container. If no such named volume exists, +Podman will create one. If no source is given, the volume will be created +as an anonymously named volume with a randomly generated name, and will be +removed when the <> is removed via the `--rm` flag or +the `podman rm --volumes` command. + +(Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes will be mounted from the remote server, not necessarily the client machine.) The _OPTIONS_ is a comma-separated list and can be: [[1]](#Footnote1) @@ -22,11 +27,6 @@ The _OPTIONS_ is a comma-separated list and can be: [[1]](#Footnote1) The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume will be mounted into the container at this directory. -Volumes may specify a source as well, as either a directory on the host -or the name of a named volume. If no source is given, the volume will be created as an -anonymously named volume with a randomly generated name, and will be removed when -the <> is removed via the `--rm` flag or the `podman rm --volumes` command. - If a volume source is specified, it must be a path on the host or the name of a named volume. Host paths are allowed to be absolute or relative; relative paths are resolved relative to the directory Podman is run in. If the source does not diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 4460e8b281..36d071bdbd 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -259,7 +259,7 @@ This option conflicts with **--add-host**. @@option personality -@@option pid +@@option pid.container @@option pidfile diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index ecbf8296dd..fdd24ba6d1 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -281,7 +281,7 @@ This is used to override the Podman provided user setup in favor of entrypoint c @@option personality -@@option pid +@@option pid.container @@option pidfile