From 52850ce7049277df028fc8839ab99a15be08ead1 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 12 Jul 2022 10:55:23 -0600 Subject: man page checker: enforce stricter options format Followup to #14906, in which a nonexistent option was found in a man page. The xref script was designed to catch that, but I was too lax in my parsing: the option was documented using wrong syntax, and the script didn't catch it. Solution: do not allow *any* unrecognized cruft in the option description lines. And fix all improperly-written entries to conform to the rule: **--option**=*value(s)* Two asterisks around option, which must have two dashes. One asterisk around value(s). This is going to cause headaches for some people adding new options, but I don't think I can fix that: there are many factors that make an unparseable line. Adding 'hint' code would make the script even more complex than it is. I have to assume that our contributors are smart enough to look at surrounding context and figure out the right way to specify options. Signed-off-by: Ed Santiago Signed-off-by: Matthew Heon --- docs/source/markdown/podman-build.1.md | 49 +++++++++++++++++----------------- 1 file changed, 25 insertions(+), 24 deletions(-) (limited to 'docs/source/markdown/podman-build.1.md') diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index bf710022e..ba7081ff5 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -259,7 +259,7 @@ keys and/or certificates. Decryption will be tried with all keys. If the key is protected by a passphrase, it is required to be passed in the argument and omitted otherwise. -#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_] +#### **--device**=*host-device[:container-device][:permissions]* Add a host device to the container. Optional *permissions* parameter can be used to specify device permissions, it is combination of @@ -267,13 +267,13 @@ can be used to specify device permissions, it is combination of Example: **--device=/dev/sdc:/dev/xvdc:rwm**. -Note: if _host_device_ is a symbolic link then it will be resolved first. +Note: if *host-device* is a symbolic link then it will be resolved first. The container will only store the major and minor numbers of the host device. Note: if the user only has access rights via a group, accessing the device from inside a rootless container will fail. The **[crun(1)](https://github.com/containers/crun/tree/main/crun.1.md)** runtime offers a workaround for this by adding the option -#### **--annotation run.oci.keep_original_groups=1**. +**--annotation run.oci.keep_original_groups=1**. #### **--disable-compression**, **-D** @@ -311,7 +311,7 @@ Set custom DNS options to be used during the build. Set custom DNS search domains to be used during the build. -#### **--env** *env[=value]* +#### **--env**=*env[=value]* Add a value (e.g. env=*value*) to the built image. Can be used multiple times. If neither `=` nor a `*value*` are specified, but *env* is set in the current @@ -430,7 +430,7 @@ specified file instead of to standard output and standard error. This option is not supported on the remote client, including Mac and Windows (excluding WSL2) machines. -#### **--logsplit** *bool-value* +#### **--logsplit**=*bool-value* If `--logfile` and `--platform` are specified, the `--logsplit` option allows end-users to split the log file for each platform into different files in the @@ -438,7 +438,7 @@ following format: `${logfile}_${platform-os}_${platform-arch}`. This option is not supported on the remote client, including Mac and Windows (excluding WSL2) machines. -#### **--manifest** "manifest" +#### **--manifest**=*manifest* Name of the manifest list to which the image will be added. Creates the manifest list if it does not exist. This option is useful for building multi architecture images. @@ -507,7 +507,7 @@ Set the OS of the image to be built, and that of the base image to be pulled, if the build uses one, instead of using the current operating system of the build host. -#### **--os-feature** *feature* +#### **--os-feature**=*feature* Set the name of a required operating system *feature* for the image which will be built. By default, if the image is not based on *scratch*, the base image's @@ -517,7 +517,7 @@ is typically only meaningful when the image's OS is Windows. If *feature* has a trailing `-`, then the *feature* is removed from the set of required features which will be listed in the image. -#### **--os-version** *version* +#### **--os-version**=*version* Set the exact required operating system *version* for the image which will be built. By default, if the image is not based on *scratch*, the base image's @@ -525,7 +525,7 @@ required OS version is kept, if the base image specified one. This option is typically only meaningful when the image's OS is Windows, and is typically set in Windows base images, so using this option is usually unnecessary. -#### **--output**, **-o**="" +#### **--output**, **-o**=*output-opts* Output destination (format: type=local,dest=path) @@ -553,9 +553,9 @@ that the PID namespace in which `podman` itself is being run should be reused, or it can be the path to a PID namespace which is already in use by another process. -#### **--platform**="OS/ARCH[/VARIANT][,...]" +#### **--platform**=*os/arch[/variant][,...]* -Set the OS/ARCH of the built image (and its base image, if your build uses one) +Set the *os/arch* of the built image (and its base image, if your build uses one) to the provided value instead of using the current operating system and architecture of the host (for example `linux/arm`). If `--platform` is set, then the values of the `--arch`, `--os`, and `--variant` options will be @@ -566,8 +566,8 @@ comma-separated list of values as its argument. When more than one platform is specified, the `--manifest` option should be used instead of the `--tag` option. -OS/ARCH pairs are those used by the Go Programming Language. In several cases -the ARCH value for a platform differs from one produced by other tools such as +Os/arch pairs are those used by the Go Programming Language. In several cases +the *arch* value for a platform differs from one produced by other tools such as the `arch` command. Valid OS and architecture name combinations are listed as values for $GOOS and $GOARCH at https://golang.org/doc/install/source#environment, and can also be found by running `go tool dist list`. @@ -576,7 +576,7 @@ While `podman build` is happy to use base images and build images for any platform that exists, `RUN` instructions will not be able to succeed without the help of emulation provided by packages like `qemu-user-static`. -#### **--pull**=**always**|**missing**|**never**|**newer** +#### **--pull**=*policy* Pull image policy. The default is **always**. @@ -655,7 +655,7 @@ layers are not squashed. Squash all of the new image's layers (including those inherited from a base image) into a single new layer. -#### **--ssh**=*default|id[=socket>|[,]* +#### **--ssh**=*default* | *id[=socket>* SSH agent socket or keys to expose to the build. The socket path can be left empty to use the value of `default=$SSH_AUTH_SOCK` @@ -683,7 +683,7 @@ Set the target build stage to build. When building a Containerfile with multiple build stages, --target can be used to specify an intermediate build stage by name as the final stage for the resulting image. Commands after the target stage will be skipped. -#### **--timestamp** *seconds* +#### **--timestamp**=*seconds* Set the create timestamp to seconds since epoch to allow for deterministic builds (defaults to current time). By default, the created timestamp is changed @@ -699,7 +699,7 @@ timestamp. Require HTTPS and verify certificates when talking to container registries (defaults to true). (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--ulimit**=*type*=*soft-limit*[:*hard-limit*] +#### **--ulimit**=*type=soft-limit[:hard-limit]* Specifies resource limits to apply to processes launched when processing `RUN` instructions. This option can be specified multiple times. Recognized resource @@ -720,7 +720,7 @@ types include: "sigpending": maximum number of pending signals (ulimit -i) "stack": maximum stack size (ulimit -s) -#### **--unsetenv** *env* +#### **--unsetenv**=*env* Unset environment variables from the final image. @@ -814,19 +814,20 @@ that the UTS namespace in which `podman` itself is being run should be reused, or it can be the path to a UTS namespace which is already in use by another process. -#### **--variant**="" +#### **--variant**=*variant* Set the architecture variant of the image to be built, and that of the base image to be pulled, if the build uses one, to the provided value instead of using the architecture variant of the build host. -#### **--volume**, **-v**[=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*] +#### **--volume**, **-v**=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]* - Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman - bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman - container. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) +Create a bind mount. If you specify `-v /HOST-DIR:/CONTAINER-DIR`, Podman +bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman +container. (This option is not available with the remote Podman client, +including Mac and Windows (excluding WSL2) machines) - The `OPTIONS` are a comma-separated list and can be: [[1]](#Footnote1) +The `OPTIONS` are a comma-separated list and can be: [[1]](#Footnote1) * [rw|ro] * [z|Z|O] -- cgit v1.2.3-54-g00ecf