summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorEd Santiago <santiago@redhat.com>2019-03-20 08:15:56 -0600
committerEd Santiago <santiago@redhat.com>2019-03-20 14:37:59 -0600
commitbeb71323b1ffbb6efdce663ba9ba7719fa0709f5 (patch)
tree4ab50d66769599e7d3e40a0e726a05c6e28fa38c
parenta7098485969095197059fe27f3d636a689f642fd (diff)
downloadpodman-beb71323b1ffbb6efdce663ba9ba7719fa0709f5.tar.gz
podman-beb71323b1ffbb6efdce663ba9ba7719fa0709f5.tar.bz2
podman-beb71323b1ffbb6efdce663ba9ba7719fa0709f5.zip
man pages - consistency fixes
podman-generate and -play had the wrong NAMEs. podman-restart and -volume-prune the wrong SYNOPSIS. All the rest are varying degrees of minor: - missing a space between the NAME and description - multi-line SYNOPSIS that could be collapsed into one - use of UPPER CASE in synopsis instead of *asterisks* - improper use of **double asterisks** for options - varlink and version were transposed in podman-1 - fixed inconsistencies between the description in the man page and that in the parent manpage. These are too numerous for me to fix all. Added: script that could be used in CI to prevent future such inconsistencies. It cannot be enabled yet because there are still 35+ inconsistencies in need of cleaning. This will be difficult to review on github. I suggest pulling the PR and running 'git log -1 -p | cdif | less' 'cdif' is a handy tool for colorizing individual diffs between lines: http://kaz-utashiro.github.io/cdif/ There are other such tools; use your favorite. Comparing without visual highlights may be painful. I also encourage you to run hack/man-page-checker and suggest more fixes for the problems it's finding. Signed-off-by: Ed Santiago <santiago@redhat.com>
-rw-r--r--docs/podman-build.1.md2
-rw-r--r--docs/podman-container-exists.1.md6
-rw-r--r--docs/podman-container-prune.1.md3
-rw-r--r--docs/podman-cp.1.md44
-rw-r--r--docs/podman-events.1.md2
-rw-r--r--docs/podman-export.1.md2
-rw-r--r--docs/podman-generate-kube.1.md5
-rw-r--r--docs/podman-generate.1.md2
-rw-r--r--docs/podman-healthcheck-run.1.md2
-rw-r--r--docs/podman-healthcheck.1.md2
-rw-r--r--docs/podman-history.1.md2
-rw-r--r--docs/podman-image-exists.1.md6
-rw-r--r--docs/podman-image-prune.1.md4
-rw-r--r--docs/podman-image-sign.1.md2
-rw-r--r--docs/podman-image-tree.1.md2
-rw-r--r--docs/podman-image-trust.1.md4
-rw-r--r--docs/podman-image.1.md4
-rw-r--r--docs/podman-play-kube.1.md2
-rw-r--r--docs/podman-play.1.md2
-rw-r--r--docs/podman-pod-exists.1.md6
-rw-r--r--docs/podman-pod-top.1.md2
-rw-r--r--docs/podman-pod.1.md2
-rw-r--r--docs/podman-push.1.md2
-rw-r--r--docs/podman-restart.1.md4
-rw-r--r--docs/podman-volume-inspect.1.md2
-rw-r--r--docs/podman-volume-prune.1.md2
-rw-r--r--docs/podman-wait.1.md2
-rw-r--r--docs/podman.1.md20
-rwxr-xr-xhack/man-page-checker105
29 files changed, 169 insertions, 76 deletions
diff --git a/docs/podman-build.1.md b/docs/podman-build.1.md
index 3d51a5319..42fa9a359 100644
--- a/docs/podman-build.1.md
+++ b/docs/podman-build.1.md
@@ -1,7 +1,7 @@
% podman-build(1)
## NAME
-podman\-build - Build a container image using a Dockerfile.
+podman\-build - Build a container image using a Dockerfile
## SYNOPSIS
**podman build** [*options*] *context*
diff --git a/docs/podman-container-exists.1.md b/docs/podman-container-exists.1.md
index 76701e2c2..8feb736f8 100644
--- a/docs/podman-container-exists.1.md
+++ b/docs/podman-container-exists.1.md
@@ -2,12 +2,10 @@
% Brent Baude
% November 2018
# NAME
-podman-container-exists- Check if a container exists in local storage
+podman-container-exists - Check if a container exists in local storage
# SYNOPSIS
-**podman container exists**
-[**-h**|**--help**]
-CONTAINER
+**podman container exists** [*-h*|*--help*] *container*
# DESCRIPTION
**podman container exists** checks if a container exists in local storage. The **ID** or **Name**
diff --git a/docs/podman-container-prune.1.md b/docs/podman-container-prune.1.md
index 1f3ef1d41..194dd3dae 100644
--- a/docs/podman-container-prune.1.md
+++ b/docs/podman-container-prune.1.md
@@ -5,8 +5,7 @@
podman-container-prune - Remove all stopped containers
# SYNOPSIS
-**podman container prune**
-[**-h**|**--help**]
+**podman container prune** [*-h*|*--help*]
# DESCRIPTION
**podman container prune** removes all stopped containers from local storage.
diff --git a/docs/podman-cp.1.md b/docs/podman-cp.1.md
index 7774542e8..44612003d 100644
--- a/docs/podman-cp.1.md
+++ b/docs/podman-cp.1.md
@@ -4,12 +4,12 @@
podman\-cp - Copy files/folders between a container and the local filesystem
## SYNOPSIS
-**podman cp [CONTAINER:]SRC_PATH [CONTAINER:]DEST_PATH**
+**podman cp** [*container*:]*src_path* [*container*:]*dest_path*
## DESCRIPTION
-Copies the contents of **SRC_PATH** to the **DEST_PATH**. You can copy from the containers's filesystem to the local machine or the reverse, from the local filesystem to the container.
+Copies the contents of **src_path** to the **dest_path**. You can copy from the containers's filesystem to the local machine or the reverse, from the local filesystem to the container.
-The CONTAINER can be a running or stopped container. The **SRC_PATH** or **DEST_PATH** can be a file or directory.
+The CONTAINER can be a running or stopped container. The **src_path** or **dest_path** can be a file or directory.
The **podman cp** command assumes container paths are relative to the container's / (root) directory.
@@ -20,36 +20,36 @@ The command sees **compassionate_darwin:/tmp/foo/myfile.txt** and **compassionat
Local machine paths can be an absolute or relative value.
The command interprets a local machine's relative paths as relative to the current working directory where **podman cp** is run.
-Assuming a path separator of /, a first argument of **SRC_PATH** and second argument of **DEST_PATH**, the behavior is as follows:
+Assuming a path separator of /, a first argument of **src_path** and second argument of **dest_path**, the behavior is as follows:
-**SRC_PATH** specifies a file
- - **DEST_PATH** does not exist
- - the file is saved to a file created at **DEST_PATH**
- - **DEST_PATH** does not exist and ends with /
- - **DEST_PATH** is created as a directory and the file is copied into this directory using the basename from **SRC_PATH**
- - **DEST_PATH** exists and is a file
+**src_path** specifies a file
+ - **dest_path** does not exist
+ - the file is saved to a file created at **dest_path**
+ - **dest_path** does not exist and ends with /
+ - **dest_path** is created as a directory and the file is copied into this directory using the basename from **src_path**
+ - **dest_path** exists and is a file
- the destination is overwritten with the source file's contents
- - **DEST_PATH** exists and is a directory
- - the file is copied into this directory using the basename from **SRC_PATH**
+ - **dest_path** exists and is a directory
+ - the file is copied into this directory using the basename from **src_path**
-**SRC_PATH** specifies a directory
- - **DEST_PATH** does not exist
- - **DEST_PATH** is created as a directory and the contents of the source directory are copied into this directory
- - **DEST_PATH** exists and is a file
+**src_path** specifies a directory
+ - **dest_path** does not exist
+ - **dest_path** is created as a directory and the contents of the source directory are copied into this directory
+ - **dest_path** exists and is a file
- Error condition: cannot copy a directory to a file
- - **DEST_PATH** exists and is a directory
- - **SRC_PATH** ends with /
+ - **dest_path** exists and is a directory
+ - **src_path** ends with /
- the source directory is copied into this directory
- - **SRC_PATH** ends with /. (that is: slash followed by dot)
+ - **src_path** ends with /. (that is: slash followed by dot)
- the content of the source directory is copied into this directory
-The command requires **SRC_PATH** and **DEST_PATH** to exist according to the above rules.
+The command requires **src_path** and **dest_path** to exist according to the above rules.
-If **SRC_PATH** is local and is a symbolic link, the symbolic target, is copied by default.
+If **src_path** is local and is a symbolic link, the symbolic target, is copied by default.
A colon (:) is used as a delimiter between CONTAINER and its path.
-You can also use : when specifying paths to a **SRC_PATH** or **DEST_PATH** on a local machine, for example, `file:name.txt`.
+You can also use : when specifying paths to a **src_path** or **dest_path** on a local machine, for example, `file:name.txt`.
If you use a : in a local machine path, you must be explicit with a relative or absolute path, for example:
`/path/to/file:name.txt` or `./file:name.txt`
diff --git a/docs/podman-events.1.md b/docs/podman-events.1.md
index b4ebe7649..3463d2aaa 100644
--- a/docs/podman-events.1.md
+++ b/docs/podman-events.1.md
@@ -1,7 +1,7 @@
% podman-events(1)
## NAME
-podman\-events- Monitor Podman events
+podman\-events - Monitor Podman events
## SYNOPSIS
**podman events** [*options*]
diff --git a/docs/podman-export.1.md b/docs/podman-export.1.md
index a8810f534..d0e365056 100644
--- a/docs/podman-export.1.md
+++ b/docs/podman-export.1.md
@@ -1,7 +1,7 @@
% podman-export(1)
## NAME
-podman\-export - Export container's filesystem contents as a tar archive
+podman\-export - Export a container's filesystem contents as a tar archive
## SYNOPSIS
**podman export** [*options*] *container*
diff --git a/docs/podman-generate-kube.1.md b/docs/podman-generate-kube.1.md
index d4bed8ab1..b6fa78606 100644
--- a/docs/podman-generate-kube.1.md
+++ b/docs/podman-generate-kube.1.md
@@ -5,10 +5,7 @@
podman-generate-kube - Generate Kubernetes YAML
# SYNOPSIS
-**podman generate kube **
-[**-h**|**--help**]
-[**-s**][**--service**]
-CONTAINER|POD
+**podman generate kube** [*-s*][*--service*] *container* | *pod*
# DESCRIPTION
**podman generate kube** will generate Kubernetes Pod YAML (v1 specification) from a podman container or pod. Whether
diff --git a/docs/podman-generate.1.md b/docs/podman-generate.1.md
index 66afacd0b..d1736f38e 100644
--- a/docs/podman-generate.1.md
+++ b/docs/podman-generate.1.md
@@ -1,7 +1,7 @@
% podman-generate(1)
## NAME
-podman\-container - generate structured data based for a containers and pods
+podman\-generate - Generate structured data based for a containers and pods
## SYNOPSIS
**podman generate** *subcommand*
diff --git a/docs/podman-healthcheck-run.1.md b/docs/podman-healthcheck-run.1.md
index 8cecb8eaa..e19c6250c 100644
--- a/docs/podman-healthcheck-run.1.md
+++ b/docs/podman-healthcheck-run.1.md
@@ -1,7 +1,7 @@
% podman-healthcheck-run(1)
## NAME
-podman\-healthcheck\-run- Run a container healthcheck
+podman\-healthcheck\-run - Run a container healthcheck
## SYNOPSIS
**podman healthcheck run** [*options*] *container*
diff --git a/docs/podman-healthcheck.1.md b/docs/podman-healthcheck.1.md
index 68d403231..91c3e4345 100644
--- a/docs/podman-healthcheck.1.md
+++ b/docs/podman-healthcheck.1.md
@@ -1,7 +1,7 @@
% podman-healthcheck(1)
## NAME
-podman\-healthcheck- Manage healthchecks for containers
+podman\-healthcheck - Manage healthchecks for containers
## SYNOPSIS
**podman healthcheck** *subcommand*
diff --git a/docs/podman-history.1.md b/docs/podman-history.1.md
index bca8cb1d2..8335428a8 100644
--- a/docs/podman-history.1.md
+++ b/docs/podman-history.1.md
@@ -1,7 +1,7 @@
% podman-history(1)
## NAME
-podman\-history - Shows the history of an image
+podman\-history - Show the history of an image
## SYNOPSIS
**podman history** [*options*] *image*[:*tag*|@*digest*]
diff --git a/docs/podman-image-exists.1.md b/docs/podman-image-exists.1.md
index e04c23721..1dc264a6b 100644
--- a/docs/podman-image-exists.1.md
+++ b/docs/podman-image-exists.1.md
@@ -2,12 +2,10 @@
% Brent Baude
% November 2018
# NAME
-podman-image-exists- Check if an image exists in local storage
+podman-image-exists - Check if an image exists in local storage
# SYNOPSIS
-**podman image exists**
-[**-h**|**--help**]
-IMAGE
+**podman image exists** [*-h*|*--help*] *image*
# DESCRIPTION
**podman image exists** checks if an image exists in local storage. The **ID** or **Name**
diff --git a/docs/podman-image-prune.1.md b/docs/podman-image-prune.1.md
index df912c380..7d5fd2fc8 100644
--- a/docs/podman-image-prune.1.md
+++ b/docs/podman-image-prune.1.md
@@ -5,9 +5,7 @@
podman-image-prune - Remove all unused images
# SYNOPSIS
-**podman image prune**
-[**-a**|**--all**]
-[**-h**|**--help**]
+**podman image prune** [*-a*|*--all*] [*-h*|*--help*]
# DESCRIPTION
**podman image prune** removes all dangling images from local storage. With the `all` option,
diff --git a/docs/podman-image-sign.1.md b/docs/podman-image-sign.1.md
index 232bc87fe..804ee03db 100644
--- a/docs/podman-image-sign.1.md
+++ b/docs/podman-image-sign.1.md
@@ -1,7 +1,7 @@
% podman-image-sign(1)
# NAME
-podman-image-sign- Create a signature for an image
+podman-image-sign - Create a signature for an image
# SYNOPSIS
**podman image sign**
diff --git a/docs/podman-image-tree.1.md b/docs/podman-image-tree.1.md
index 014499d6a..acd5ffcbf 100644
--- a/docs/podman-image-tree.1.md
+++ b/docs/podman-image-tree.1.md
@@ -4,7 +4,7 @@
podman\-image\-tree - Prints layer hierarchy of an image in a tree format
## SYNOPSIS
-**podman image tree** [*image*:*tag*]**|**[*image-id*]
+**podman image tree** [*image*:*tag*]|[*image-id*]
[**--help**|**-h**]
## DESCRIPTION
diff --git a/docs/podman-image-trust.1.md b/docs/podman-image-trust.1.md
index 819035040..f96a7996f 100644
--- a/docs/podman-image-trust.1.md
+++ b/docs/podman-image-trust.1.md
@@ -1,11 +1,11 @@
% podman-image-trust "1"
# NAME
-podman\-trust - Manage container registry image trust policy
+podman\-image\-trust - Manage container registry image trust policy
# SYNOPSIS
-**podman image trust set|show**
+**podman image trust** set|show
[**-h**|**--help**]
[**-j**|**--json**]
[**--raw**]
diff --git a/docs/podman-image.1.md b/docs/podman-image.1.md
index 333a75b69..01cf08d62 100644
--- a/docs/podman-image.1.md
+++ b/docs/podman-image.1.md
@@ -14,13 +14,13 @@ The image command allows you to manage images
| Command | Man Page | Description |
| -------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
| build | [podman-build(1)](podman-build.1.md) | Build a container using a Dockerfile. |
-| exists | [podman-image-exists(1)](podman-image-exists.1.md) | Check if a image exists in local storage. |
+| exists | [podman-image-exists(1)](podman-image-exists.1.md) | Check if an image exists in local storage. |
| history | [podman-history(1)](podman-history.1.md) | Show the history of an image. |
| import | [podman-import(1)](podman-import.1.md) | Import a tarball and save it as a filesystem image. |
| inspect | [podman-inspect(1)](podman-inspect.1.md) | Display a image or image's configuration. |
| list | [podman-images(1)](podman-images.1.md) | List the container images on the system.(alias ls) |
| load | [podman-load(1)](podman-load.1.md) | Load an image from the docker archive. |
-| prune | [podman-image-prune(1)](podman-image-prune.1.md)| Removed all unused images from the local store. |
+| prune | [podman-image-prune(1)](podman-image-prune.1.md)| Remove all unused images from the local store. |
| pull | [podman-pull(1)](podman-pull.1.md) | Pull an image from a registry. |
| push | [podman-push(1)](podman-push.1.md) | Push an image from local storage to elsewhere. |
| rm | [podman-rmi(1)](podman-rmi.1.md) | Removes one or more locally stored images. |
diff --git a/docs/podman-play-kube.1.md b/docs/podman-play-kube.1.md
index 2264f7a88..a9af961cd 100644
--- a/docs/podman-play-kube.1.md
+++ b/docs/podman-play-kube.1.md
@@ -5,7 +5,7 @@
podman-play-kube - Create pods and containers based on Kubernetes YAML
# SYNOPSIS
-**podman play kube **
+**podman play kube**
[**-h**|**--help**]
[**--authfile**]
[**--cert-dir**]
diff --git a/docs/podman-play.1.md b/docs/podman-play.1.md
index 6d2a7beba..f0bf8ea41 100644
--- a/docs/podman-play.1.md
+++ b/docs/podman-play.1.md
@@ -1,7 +1,7 @@
% podman-play(1)
## NAME
-podman\-container - play pods and containers based on a structured input file
+podman\-play - Play pods and containers based on a structured input file
## SYNOPSIS
**podman play** *subcommand*
diff --git a/docs/podman-pod-exists.1.md b/docs/podman-pod-exists.1.md
index 8fb2fc90e..da3947511 100644
--- a/docs/podman-pod-exists.1.md
+++ b/docs/podman-pod-exists.1.md
@@ -2,12 +2,10 @@
% Brent Baude
% December 2018
# NAME
-podman-pod-exists- Check if a pod exists in local storage
+podman-pod-exists - Check if a pod exists in local storage
# SYNOPSIS
-**podman pod exists**
-[**-h**|**--help**]
-POD
+**podman pod exists** [*-h*|*--help*] *pod*
# DESCRIPTION
**podman pod exists** checks if a pod exists in local storage. The **ID** or **Name**
diff --git a/docs/podman-pod-top.1.md b/docs/podman-pod-top.1.md
index a77ca2b37..b235a70ad 100644
--- a/docs/podman-pod-top.1.md
+++ b/docs/podman-pod-top.1.md
@@ -4,7 +4,7 @@
podman\-pod\-top - Display the running processes of containers in a pod
## SYNOPSIS
-**podman top** [*options*] *pod* [*format-descriptors*]
+**podman pod top** [*options*] *pod* [*format-descriptors*]
## DESCRIPTION
Display the running process of containers in a pod. The *format-descriptors* are ps (1) compatible AIX format descriptors but extended to print additional information, such as the seccomp mode or the effective capabilities of a given process.
diff --git a/docs/podman-pod.1.md b/docs/podman-pod.1.md
index 8f8403a40..1846d0411 100644
--- a/docs/podman-pod.1.md
+++ b/docs/podman-pod.1.md
@@ -19,7 +19,7 @@ podman pod is a set of subcommands that manage pods, or groups of containers.
| kill | [podman-pod-kill(1)](podman-pod-kill.1.md) | Kill the main process of each container in pod. |
| pause | [podman-pod-pause(1)](podman-pod-pause.1.md) | Pause one or more pods. |
| ps | [podman-pod-ps(1)](podman-pod-ps.1.md) | Prints out information about pods. |
-| restart | [podman-pod-restart(1)](podman-pod-restart.1.md) | Restart one or mode pods. |
+| restart | [podman-pod-restart(1)](podman-pod-restart.1.md) | Restart one or more pods. |
| rm | [podman-pod-rm(1)](podman-pod-rm.1.md) | Remove one or more pods. |
| start | [podman-pod-start(1)](podman-pod-start.1.md) | Start one or more pods. |
| stats | [podman-pod-stats(1)](podman-pod-stats.1.md) | Display live stream resource usage stats for containers in one or more pods. |
diff --git a/docs/podman-push.1.md b/docs/podman-push.1.md
index 3ce156010..bb17c7e03 100644
--- a/docs/podman-push.1.md
+++ b/docs/podman-push.1.md
@@ -4,7 +4,7 @@
podman\-push - Push an image from local storage to elsewhere
## SYNOPSIS
-**podman push** [*options*] **image** [**destination**]
+**podman push** [*options*] *image* [*destination*]
## DESCRIPTION
Pushes an image from local storage to a specified destination.
diff --git a/docs/podman-restart.1.md b/docs/podman-restart.1.md
index dd28e34c7..a20eee243 100644
--- a/docs/podman-restart.1.md
+++ b/docs/podman-restart.1.md
@@ -1,10 +1,10 @@
% podman-restart(1)
## NAME
-podman\-restart - Restart a container
+podman\-restart - Restart one or more containers
## SYNOPSIS
-**podman attach** [*options*] *container* ...
+**podman restart** [*options*] *container* ...
## DESCRIPTION
The restart command allows containers to be restarted using their ID or name.
diff --git a/docs/podman-volume-inspect.1.md b/docs/podman-volume-inspect.1.md
index 6d5b184ee..c22c80bb7 100644
--- a/docs/podman-volume-inspect.1.md
+++ b/docs/podman-volume-inspect.1.md
@@ -4,7 +4,7 @@
podman\-volume\-inspect - Inspect one or more volumes
## SYNOPSIS
-**podman volume inspect** [*options*]
+**podman volume inspect** [*options*] *volume*...
## DESCRIPTION
diff --git a/docs/podman-volume-prune.1.md b/docs/podman-volume-prune.1.md
index a06bb2fa4..437cad4e5 100644
--- a/docs/podman-volume-prune.1.md
+++ b/docs/podman-volume-prune.1.md
@@ -4,7 +4,7 @@
podman\-volume\-prune - Remove all unused volumes
## SYNOPSIS
-**podman volume rm** [*options*]
+**podman volume prune** [*options*]
## DESCRIPTION
diff --git a/docs/podman-wait.1.md b/docs/podman-wait.1.md
index 672316eef..2d145527b 100644
--- a/docs/podman-wait.1.md
+++ b/docs/podman-wait.1.md
@@ -1,7 +1,7 @@
% podman-wait "1"
## NAME
-podman\-wait - Waits on one or more containers to stop and prints exit code
+podman\-wait - Wait on one or more containers to stop and print their exit codes
## SYNOPSIS
**podman wait** [*options*] *container*
diff --git a/docs/podman.1.md b/docs/podman.1.md
index c4dc168c7..b808a7fa5 100644
--- a/docs/podman.1.md
+++ b/docs/podman.1.md
@@ -131,9 +131,9 @@ the exit codes follow the `chroot` standard, see below:
| Command | Description |
| ----------------------------------------- | ------------------------------------------------------------------------------ |
| [podman-attach(1)](podman-attach.1.md) | Attach to a running container. |
-| [podman-build(1)](podman-build.1.md) | Build a container using a Dockerfile. |
+| [podman-build(1)](podman-build.1.md) | Build a container image using a Dockerfile. |
| [podman-commit(1)](podman-commit.1.md) | Create new image based on the changed container. |
-| [podman-container(1)](podman-container.1.md) | Manage Containers. |
+| [podman-container(1)](podman-container.1.md) | Manage containers. |
| [podman-cp(1)](podman-cp.1.md) | Copy files/folders between a container and the local filesystem. |
| [podman-create(1)](podman-create.1.md) | Create a new container. |
| [podman-diff(1)](podman-diff.1.md) | Inspect changes on a container or image's filesystem. |
@@ -143,13 +143,13 @@ the exit codes follow the `chroot` standard, see below:
| [podman-generate(1)](podman-generate.1.md)| Generate structured data based for a containers and pods. |
| [podman-healthcheck(1)](podman-healthcheck.1.md)| Manage healthchecks for containers |
| [podman-history(1)](podman-history.1.md) | Show the history of an image. |
-| [podman-image(1)](podman-image.1.md) | Manage Images. |
+| [podman-image(1)](podman-image.1.md) | Manage images. |
| [podman-images(1)](podman-images.1.md) | List images in local storage. |
| [podman-import(1)](podman-import.1.md) | Import a tarball and save it as a filesystem image. |
| [podman-info(1)](podman-info.1.md) | Displays Podman related system information. |
| [podman-inspect(1)](podman-inspect.1.md) | Display a container or image's configuration. |
| [podman-kill(1)](podman-kill.1.md) | Kill the main process in one or more containers. |
-| [podman-load(1)](podman-load.1.md) | Load an image from the docker archive. |
+| [podman-load(1)](podman-load.1.md) | Load an image from a container image archive into container storage. |
| [podman-login(1)](podman-login.1.md) | Login to a container registry. |
| [podman-logout(1)](podman-logout.1.md) | Logout of a container registry. |
| [podman-logs(1)](podman-logs.1.md) | Display the logs of a container. |
@@ -157,17 +157,17 @@ the exit codes follow the `chroot` standard, see below:
| [podman-pause(1)](podman-pause.1.md) | Pause one or more containers. |
| [podman-play(1)](podman-play.1.md) | Play pods and containers based on a structured input file. |
| [podman-pod(1)](podman-pod.1.md) | Management tool for groups of containers, called pods. |
-| [podman-port(1)](podman-port.1.md) | List port mappings for the container. |
+| [podman-port(1)](podman-port.1.md) | List port mappings for a container. |
| [podman-ps(1)](podman-ps.1.md) | Prints out information about containers. |
| [podman-pull(1)](podman-pull.1.md) | Pull an image from a registry. |
| [podman-push(1)](podman-push.1.md) | Push an image from local storage to elsewhere. |
| [podman-restart(1)](podman-restart.1.md) | Restart one or more containers. |
| [podman-rm(1)](podman-rm.1.md) | Remove one or more containers. |
| [podman-rmi(1)](podman-rmi.1.md) | Removes one or more locally stored images. |
-| [podman-run(1)](podman-run.1.md) | Run a command in a container. |
-| [podman-save(1)](podman-save.1.md) | Save an image to docker-archive or oci. |
+| [podman-run(1)](podman-run.1.md) | Run a command in a new container. |
+| [podman-save(1)](podman-save.1.md) | Save an image to a container archive. |
| [podman-search(1)](podman-search.1.md) | Search a registry for an image. |
-| [podman-start(1)](podman-start.1.md) | Starts one or more containers. |
+| [podman-start(1)](podman-start.1.md) | Start one or more containers. |
| [podman-stats(1)](podman-stats.1.md) | Display a live stream of one or more container's resource usage statistics. |
| [podman-stop(1)](podman-stop.1.md) | Stop one or more running containers. |
| [podman-system(1)](podman-system.1.md) | Manage podman. |
@@ -175,8 +175,8 @@ the exit codes follow the `chroot` standard, see below:
| [podman-top(1)](podman-top.1.md) | Display the running processes of a container. |
| [podman-umount(1)](podman-umount.1.md) | Unmount a working container's root filesystem. |
| [podman-unpause(1)](podman-unpause.1.md) | Unpause one or more containers. |
-| [podman-varlink(1)](podman-varlink.1.md) | Display the Podman version information. |
-| [podman-version(1)](podman-version.1.md) | Runs the varlink backend interface. |
+| [podman-version(1)](podman-varlink.1.md) | Runs the varlink backend interface. |
+| [podman-varlink(1)](podman-version.1.md) | Display the Podman version information. |
| [podman-volume(1)](podman-volume.1.md) | Manage Volumes. |
| [podman-wait(1)](podman-wait.1.md) | Wait on one or more containers to stop and print their exit codes. |
diff --git a/hack/man-page-checker b/hack/man-page-checker
new file mode 100755
index 000000000..8e9b5a50d
--- /dev/null
+++ b/hack/man-page-checker
@@ -0,0 +1,105 @@
+#!/bin/bash
+#
+# man-page-name-checker - validate and cross-reference man page names
+#
+# FIXME as of 2019-03-20 there are still four files with inconsistent names:
+#
+# podman-logs.1.md NAME= podman-container-logs
+# podman-info.1.md NAME= podman-system-info
+# podman-rm.1.md NAME= podman-container-rm
+# podman-rmi.1.md NAME= podman-image-rm
+#
+# If those four get renamed (with suitable symlink fixes), this script
+# can be enabled in CI to prevent future inconsistencies.
+#
+
+die() {
+ echo "$(basename $0): $*" >&2
+ exit 1
+}
+
+cd $(dirname $0)/../docs || die "Please run me from top-level libpod dir"
+
+rc=0
+
+for md in *.1.md;do
+ # Read the first line after '# NAME' (or '## NAME'). (FIXME: # and ##
+ # are not the same; should we stick to one convention?)
+ # There may be more than one name, e.g. podman-info.1.md has
+ # podman-system-info then another line with podman-info. We
+ # care only about the first.
+ name=$(egrep -A1 '^#* NAME' $md|tail -1|awk '{print $1}' | tr -d \\\\)
+
+ if [ "$name" != "$(basename $md .1.md)" ]; then
+ printf "%-32s NAME= %s\n" $md $name
+ rc=1
+ fi
+done
+
+# Pass 2: compare descriptions.
+#
+# Make sure the descriptive text in podman-foo.1.md matches the one
+# in the table in podman.1.md.
+for md in *.1.md;do
+ desc=$(egrep -A1 '^#* NAME' $md|tail -1|sed -e 's/^podman[^ ]\+ - //')
+
+ # podman.1.md has a two-column table; podman-*.1.md all have three.
+ parent=$(echo $md | sed -e 's/^\(.*\)-.*$/\1.1.md/')
+ x=3
+ if expr -- "$parent" : ".*-" >/dev/null; then
+ x=4
+ fi
+
+ # Find the descriptive text in the parent man page.
+ # Strip off the final period; let's not warn about such minutia.
+ parent_desc=$(grep $md $parent | awk -F'|' "{print \$$x}" | sed -e 's/^ \+//' -e 's/ \+$//' -e 's/\.$//')
+
+ if [ "$desc" != "$parent_desc" ]; then
+ echo
+ printf " %-32s = '%s'\n" $md "$desc"
+ printf " %-32s = '%s'\n" $parent "$parent_desc"
+ rc=1
+ fi
+done
+
+# Pass 3: compare synopses.
+#
+# Make sure the SYNOPSIS line in podman-foo.1.md reads '**podman foo** ...'
+for md in *.1.md;do
+ # FIXME: several pages have a multi-line form of SYNOPSIS in which
+ # many or all flags are enumerated. Some of these are trivial
+ # and really should be made into one line (podman-container-exists,
+ # container-prune, others); some are more complicated and I
+ # would still like to see them one-lined (container-runlabel,
+ # image-trust) but I'm not 100% comfortable doing so myself.
+ # To view those:
+ # $ less $(for i in docs/*.1.md;do x=$(grep -A2 '^#* SYNOPSIS' $i|tail -1); if [ -n "$x" ]; then echo $i;fi;done)
+ #
+ synopsis=$(egrep -A1 '^#* SYNOPSIS' $md|tail -1)
+
+ # Command name must be bracketed by double asterisks; options and
+ # arguments are bracketed by single ones.
+ # E.g. '**podman volume inspect** [*options*] *volume*...'
+ # Get the command name, and confirm that it matches the md file name.
+ cmd=$(echo "$synopsis" | sed -e 's/\(.*\)\*\*.*/\1/' | tr -d \* | tr ' ' '-')
+ if [ "$md" != "$cmd.1.md" ]; then
+ printf " %-32s SYNOPSIS = %s\n" $md "$cmd"
+ rc=1
+ fi
+
+ # The convention is to use UPPER CASE in 'podman foo --help',
+ # but *lower case bracketed by asterisks* in the man page
+ if expr "$synopsis" : ".*[A-Z]" >/dev/null; then
+ printf " %-32s UPPER-CASE '%s'\n" $md "$synopsis"
+ rc=1
+ fi
+
+ # (for debugging, and getting a sense of standard conventions)
+ #printf " %-32s ------ '%s'\n" $md "$synopsis"
+
+ # FIXME: some day: run ./bin/podman "args", extract Usage,
+ # strip off [flags] and [options], then compare arguments
+done
+
+
+exit $rc