diff options
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 |