5 files changed, 59 insertions, 14 deletions
diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md
index 98c8251b4..15d936d17 100644
--- a/docs/source/markdown/podman-build.1.md
+++ b/docs/source/markdown/podman-build.1.md
@@ -64,8 +64,10 @@ discarded when writing images in Docker formats.
 
 #### **--arch**=*arch*
 
-Set the ARCH of the image to the provided value instead of the architecture of
-the host.
+Set the architecture 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 of the build host. (Examples: arm, arm64, 386, amd64, ppc64le,
+s390x)
 
 #### **--authfile**=*path*
 
@@ -321,7 +323,8 @@ Pass through HTTP Proxy environment variables.
 
 #### **--iidfile**=*ImageIDfile*
 
-Write the image ID to the file.
+Write the built image's ID to the file.  When `--platform` is specified more
+than once, attempting to use this option will trigger an error.
 
 #### **--ignorefile**
 
@@ -389,6 +392,7 @@ Name of the manifest list to which the image will be added. Creates the manifest
 if it does not exist. This option is useful for building multi architecture images.
 
 #### **--memory**, **-m**=*LIMIT*
+
 Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kilobytes),
 m (megabytes), or g (gigabytes))
 
@@ -430,8 +434,9 @@ with a new set of cached layers.
 
 #### **--os**=*string*
 
-Set the OS to the provided value instead of the current operating system of the
-host.
+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.
 
 #### **--pid**=*pid*
 
@@ -442,11 +447,28 @@ 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**="Linux"
+#### **--platform**="OS/ARCH[/VARIANT][,...]"
+
+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
+overridden.
+
+The `--platform` flag can be specified more than once, or given a
+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
+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`.
 
-This option has no effect on the build. Other container engines use this option
-to control the execution platform for the build (e.g., Windows, Linux) which is
-not required for Buildah as it supports only Linux.
+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**
 
@@ -486,7 +508,6 @@ commands specified by the **RUN** instruction.
 Note: You can also override the default runtime by setting the BUILDAH\_RUNTIME
 environment variable.  `export BUILDAH_RUNTIME=/usr/local/bin/runc`
 
-
 #### **--secret**=**id=id,src=path**
 
 Pass secret information to be used in the Containerfile for building images
@@ -497,7 +518,6 @@ To later use the secret, use the --mount flag in a `RUN` instruction within a `C
 
 `RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret`
 
-
 #### **--security-opt**=*option*
 
 Security Options
@@ -697,7 +717,9 @@ process.
 
 #### **--variant**=""
 
-Set the architecture variant of the image to be pulled.
+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]]*]
 
@@ -858,7 +880,7 @@ $ podman build --layers --force-rm -t imageName .
 $ podman build --no-cache --rm=false -t imageName .
 ```
 
-### Building an multi-architecture image using a --manifest option (Requires emulation software)
+### Building a multi-architecture image using the --manifest option (requires emulation software)
 
 ```
 $ podman build --arch arm --manifest myimage /tmp/mysrc
@@ -866,6 +888,10 @@ $ podman build --arch arm --manifest myimage /tmp/mysrc
 $ podman build --arch amd64 --manifest myimage /tmp/mysrc
 
 $ podman build --arch s390x --manifest myimage /tmp/mysrc
+
+$ podman build --platform linux/s390x,linux/ppc64le,linux/amd64 --manifest myimage /tmp/mysrc
+
+$ podman build --platform linux/arm64 --platform linux/amd64 --manifest myimage /tmp/mysrc
 ```
 
 ### Building an image using a URL, Git repo, or archive
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index c3e2bbfca..f63f5ca9c 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -595,6 +595,8 @@ Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and
 
        type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
 
+       type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true
+
        type=volume,source=vol1,destination=/path/in/container,ro=true
 
        type=tmpfs,tmpfs-size=512M,destination=/path/in/container
@@ -613,6 +615,8 @@ Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and
 
 	      · ro, readonly: true or false (default).
 
+        . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
+
        Options specific to image:
 
 	      · rw, readwrite: true or false (default).
@@ -627,6 +631,8 @@ Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and
 
 	      . relabel: shared, private.
 
+        . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
+
        Options specific to tmpfs:
 
 	      · ro, readonly: true or false (default).
@@ -639,6 +645,7 @@ Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and
 
 	      · notmpcopyup: Disable copying files from the image to the tmpfs.
 
+        . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
 
 #### **--name**=*name*
 
diff --git a/docs/source/markdown/podman-image-prune.1.md b/docs/source/markdown/podman-image-prune.1.md
index bd08d18fc..493332ec0 100644
--- a/docs/source/markdown/podman-image-prune.1.md
+++ b/docs/source/markdown/podman-image-prune.1.md
@@ -17,6 +17,10 @@ The image prune command does not prune cache images that only use layers that ar
 
 Remove dangling images and images that have no associated containers.
 
+#### **--external**
+
+Remove images even when they are used by external containers (e.g., build containers).
+
 #### **--filter**=*filters*
 
 Provide filter values.
diff --git a/docs/source/markdown/podman-machine-init.1.md b/docs/source/markdown/podman-machine-init.1.md
index 1236db602..f1fbd56ee 100644
--- a/docs/source/markdown/podman-machine-init.1.md
+++ b/docs/source/markdown/podman-machine-init.1.md
@@ -40,7 +40,7 @@ do these things manually or handle otherwise.
 #### **--image-path**
 
 Fully qualified path or URL to the VM image.
-Can also be set to `testing` or `stable` to pull down default image.
+Can also be set to `testing`, `next`, or `stable` to pull down default image.
 Defaults to `testing`.
 
 #### **--memory**, **-m**=*number*
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index a369ce5ea..6d68fd62b 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -615,6 +615,8 @@ Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and
 
        type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
 
+       type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true
+
        type=volume,source=vol1,destination=/path/in/container,ro=true
 
        type=tmpfs,tmpfs-size=512M,destination=/path/in/container
@@ -633,6 +635,8 @@ Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and
 
 	      · ro, readonly: true or false (default).
 
+        . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
+
        Options specific to image:
 
 	      · rw, readwrite: true or false (default).
@@ -647,6 +651,8 @@ Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and
 
 	      . relabel: shared, private.
 
+        . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
+
        Options specific to tmpfs:
 
 	      · ro, readonly: true or false (default).
@@ -659,6 +665,8 @@ Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and
 
 	      · notmpcopyup: Disable copying files from the image to the tmpfs.
 
+        . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
+
 #### **--name**=*name*
 
 Assign a name to the container.