7 files changed, 27 insertions, 17 deletions
diff --git a/docs/source/markdown/options/README.md b/docs/source/markdown/options/README.md
index b737fabf7..92f3d374e 100644
--- a/docs/source/markdown/options/README.md
+++ b/docs/source/markdown/options/README.md
@@ -42,3 +42,5 @@ This allows the shared use of examples in the option file:
 ```
     Example: podman <<subcommand>> --foo --bar
 ```
+As a special case, `podman-pod-X` becomes just `X` (the "pod" is removed).
+This makes the `pod-id-file` man page more useful.
diff --git a/docs/source/markdown/options/arch.md b/docs/source/markdown/options/arch.md
new file mode 100644
index 000000000..005197707
--- /dev/null
+++ b/docs/source/markdown/options/arch.md
@@ -0,0 +1,2 @@
+#### **--arch**=*ARCH*
+Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`.
diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in
index 626a9db3b..c0cf08f3c 100644
--- a/docs/source/markdown/podman-build.1.md.in
+++ b/docs/source/markdown/podman-build.1.md.in
@@ -988,9 +988,11 @@ use it as the context. The Containerfile at the root of the repository will be
 used and it only works if the GitHub repository is a dedicated repository.
 
 ```
-$ podman build git://github.com/scollier/purpletest
+$ podman build https://github.com/scollier/purpletest
 ```
 
+  Note: Github does not support using `git://` for performing `clone` operation due to recent changes in their security guidance (https://github.blog/2021-09-01-improving-git-protocol-security-github/). Use an `https://` URL if the source repository is hosted on Github.
+
 #### Building an image using a URL to an archive
 
   Podman will fetch the archive file, decompress it, and use its contents as the
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
index 5bb1dceca..45dfe304c 100644
--- a/docs/source/markdown/podman-create.1.md.in
+++ b/docs/source/markdown/podman-create.1.md.in
@@ -73,8 +73,7 @@ and specified with a _tag_.
 Add an annotation to the container. The format is key=value.
 The **--annotation** option can be set multiple times.
 
-#### **--arch**=*ARCH*
-Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`.
+@@option arch
 
 #### **--attach**, **-a**=*location*
 
diff --git a/docs/source/markdown/podman-images.1.md b/docs/source/markdown/podman-images.1.md
index 923b22f1b..d005db23d 100644
--- a/docs/source/markdown/podman-images.1.md
+++ b/docs/source/markdown/podman-images.1.md
@@ -4,11 +4,11 @@
 podman\-images - List images in local storage
 
 ## SYNOPSIS
-**podman images** [*options*]
+**podman images** [*options*] [image]
 
-**podman image list** [*options*]
+**podman image list** [*options*] [image]
 
-**podman image ls** [*options*]
+**podman image ls** [*options*] [image]
 
 ## DESCRIPTION
 Displays locally stored images, their names, and their IDs.
@@ -107,15 +107,22 @@ Sort by *created*, *id*, *repository*, *size* or *tag* (default: **created**)
 ## EXAMPLE
 
 ```
-# podman images
-REPOSITORY                                   TAG      IMAGE ID       CREATED       SIZE
-docker.io/kubernetes/pause                   latest   e3d42bcaf643   3 years ago   251 kB
-<none>                                       <none>   ebb91b73692b   4 weeks ago   27.2 MB
-docker.io/library/ubuntu                     latest   4526339ae51c   6 weeks ago   126 MB
+$ podman images
+REPOSITORY                         TAG         IMAGE ID      CREATED       SIZE
+quay.io/podman/stable              latest      e0b7dabc3352  22 hours ago  331 MB
+docker.io/library/alpine           latest      9c6f07244728  5 days ago    5.83 MB
+registry.fedoraproject.org/fedora  latest      2ecb6df95994  3 weeks ago   169 MB
+quay.io/libpod/testimage           20220615    f26aa69bb3f3  2 months ago  8.4 MB
+```
+
+```
+$ podman images stable
+REPOSITORY             TAG         IMAGE ID      CREATED       SIZE
+quay.io/podman/stable  latest      e0b7dabc3352  22 hours ago  331 MB
 ```
 
 ```
-# podman images --quiet
+# podman image ls --quiet
 e3d42bcaf643
 ebb91b73692b
 4526339ae51c
@@ -129,7 +136,7 @@ docker.io/library/ubuntu                     latest   4526339ae51c   6 weeks ago
 ```
 
 ```
-# podman images --no-trunc
+# podman image list --no-trunc
 REPOSITORY                                   TAG      IMAGE ID                                                                  CREATED       SIZE
 docker.io/kubernetes/pause                   latest   sha256:e3d42bcaf643097dd1bb0385658ae8cbe100a80f773555c44690d22c25d16b27   3 years ago   251 kB
 <none>                                       <none>   sha256:ebb91b73692bd27890685846412ae338d13552165eacf7fcd5f139bfa9c2d6d9   4 weeks ago   27.2 MB
diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in
index 4321cb364..29c4f865d 100644
--- a/docs/source/markdown/podman-pull.1.md.in
+++ b/docs/source/markdown/podman-pull.1.md.in
@@ -49,8 +49,7 @@ All tagged images in the repository will be pulled.
 
 *IMPORTANT: When using the all-tags flag, Podman will not iterate over the search registries in the **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** but will always use docker.io for unqualified image names.*
 
-#### **--arch**=*ARCH*
-Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`.
+@@option arch
 
 #### **--authfile**=*path*
 
diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in
index 21ce566ce..df9f1c28a 100644
--- a/docs/source/markdown/podman-run.1.md.in
+++ b/docs/source/markdown/podman-run.1.md.in
@@ -90,8 +90,7 @@ and specified with a _tag_.
 Add an annotation to the container.
 This option can be set multiple times.
 
-#### **--arch**=*ARCH*
-Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`.
+@@option arch
 
 #### **--attach**, **-a**=*stdin* | *stdout* | *stderr*