13 files changed, 34 insertions, 12 deletions
diff --git a/docs/source/markdown/options/arch.md b/docs/source/markdown/options/arch.md
index 005197707..76fb349a0 100644
--- a/docs/source/markdown/options/arch.md
+++ b/docs/source/markdown/options/arch.md
@@ -1,2 +1,3 @@
 #### **--arch**=*ARCH*
 Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`.
+Unless overridden, subsequent lookups of the same image in the local storage will match this architecture, regardless of the host.
diff --git a/docs/source/markdown/options/cpu-period.md b/docs/source/markdown/options/cpu-period.md
index 8df6445e9..efbe6c2ab 100644
--- a/docs/source/markdown/options/cpu-period.md
+++ b/docs/source/markdown/options/cpu-period.md
@@ -5,6 +5,6 @@ duration in microseconds. Once the container's CPU quota is used up, it will
 not be scheduled to run until the current period ends. Defaults to 100000
 microseconds.
 
-On some systems, changing the CPU limits may not be allowed for non-root
+On some systems, changing the resource limits may not be allowed for non-root
 users. For more details, see
-https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
+https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error
diff --git a/docs/source/markdown/options/cpu-quota.md b/docs/source/markdown/options/cpu-quota.md
index 67b9dee8c..753797bad 100644
--- a/docs/source/markdown/options/cpu-quota.md
+++ b/docs/source/markdown/options/cpu-quota.md
@@ -7,6 +7,6 @@ CPU resource. The limit is a number in microseconds. If a number is provided,
 the container will be allowed to use that much CPU time until the CPU period
 ends (controllable via **--cpu-period**).
 
-On some systems, changing the CPU limits may not be allowed for non-root
+On some systems, changing the resource limits may not be allowed for non-root
 users. For more details, see
-https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
+https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error
diff --git a/docs/source/markdown/options/cpu-shares.md b/docs/source/markdown/options/cpu-shares.md
index a5aacd2ca..c2115c1bf 100644
--- a/docs/source/markdown/options/cpu-shares.md
+++ b/docs/source/markdown/options/cpu-shares.md
@@ -33,3 +33,7 @@ this can result in the following division of CPU shares:
 | 100  |  C0         | 0       | 100% of CPU0 |
 | 101  |  C1         | 1       | 100% of CPU1 |
 | 102  |  C1         | 2       | 100% of CPU2 |
+
+On some systems, changing the resource limits may not be allowed for non-root
+users. For more details, see
+https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error
diff --git a/docs/source/markdown/options/cpuset-cpus.md b/docs/source/markdown/options/cpuset-cpus.md
index d717516a0..a67766897 100644
--- a/docs/source/markdown/options/cpuset-cpus.md
+++ b/docs/source/markdown/options/cpuset-cpus.md
@@ -3,3 +3,7 @@
 CPUs in which to allow execution. Can be specified as a comma-separated list
 (e.g. **0,1**), as a range (e.g. **0-3**), or any combination thereof
 (e.g. **0-3,7,11-15**).
+
+On some systems, changing the resource limits may not be allowed for non-root
+users. For more details, see
+https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error
diff --git a/docs/source/markdown/options/cpuset-mems.md b/docs/source/markdown/options/cpuset-mems.md
index d2d13eb54..1eeab7b13 100644
--- a/docs/source/markdown/options/cpuset-mems.md
+++ b/docs/source/markdown/options/cpuset-mems.md
@@ -6,3 +6,7 @@ NUMA systems.
 If there are four memory nodes on the system (0-3), use **--cpuset-mems=0,1**
 then processes in the container will only use memory from the first
 two memory nodes.
+
+On some systems, changing the resource limits may not be allowed for non-root
+users. For more details, see
+https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error
diff --git a/docs/source/markdown/options/platform.md b/docs/source/markdown/options/platform.md
index edfa428ff..b66efdfb2 100644
--- a/docs/source/markdown/options/platform.md
+++ b/docs/source/markdown/options/platform.md
@@ -2,3 +2,4 @@
 
 Specify the platform for selecting the image.  (Conflicts with --arch and --os)
 The `--platform` option can be used to override the current architecture and operating system.
+Unless overridden, subsequent lookups of the same image in the local storage will match this platform, regardless of the host.
diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in
index 772567e53..dab705f94 100644
--- a/docs/source/markdown/podman-build.1.md.in
+++ b/docs/source/markdown/podman-build.1.md.in
@@ -65,8 +65,9 @@ discarded when writing images in Docker formats.
 
 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)
+architecture of the build host. Unless overridden, subsequent lookups of the
+same image in the local storage will match this architecture, regardless of the
+host. (Examples: arm, arm64, 386, amd64, ppc64le, s390x)
 
 @@option authfile
 
@@ -447,7 +448,8 @@ do not include `History` information in their images.
 
 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.
+build host. Unless overridden, subsequent lookups of the same image in the
+local storage will match this OS, regardless of the host.
 
 #### **--os-feature**=*feature*
 
@@ -499,9 +501,12 @@ process.
 
 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.
+architecture of the host (for example `linux/arm`).  Unless overridden,
+subsequent lookups of the same image in the local storage will match this
+platform, regardless of the host.
+
+If `--platform` is set, then the values of the `--arch`, `--os`, and
+`--variant` options will be overridden.
 
 The `--platform` option can be specified more than once, or given a
 comma-separated list of values as its argument.  When more than one platform is
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
index 3e6b07225..7ec4fc66f 100644
--- a/docs/source/markdown/podman-create.1.md.in
+++ b/docs/source/markdown/podman-create.1.md.in
@@ -452,6 +452,7 @@ This option conflicts with **--add-host**.
 
 #### **--os**=*OS*
 Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`.
+Unless overridden, subsequent lookups of the same image in the local storage will match this OS, regardless of the host.
 
 @@option passwd-entry
 
diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in
index 5d875590f..db041298e 100644
--- a/docs/source/markdown/podman-pull.1.md.in
+++ b/docs/source/markdown/podman-pull.1.md.in
@@ -70,6 +70,7 @@ Print the usage statement.
 #### **--os**=*OS*
 
 Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`.
+Unless overridden, subsequent lookups of the same image in the local storage will match this OS, regardless of the host.
 
 @@option platform
 
diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in
index 1c02eafe9..d10520e35 100644
--- a/docs/source/markdown/podman-run.1.md.in
+++ b/docs/source/markdown/podman-run.1.md.in
@@ -465,6 +465,7 @@ This option conflicts with **--add-host**.
 
 #### **--os**=*OS*
 Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`.
+Unless overridden, subsequent lookups of the same image in the local storage will match this OS, regardless of the host.
 
 #### **--passwd**
 
diff --git a/docs/source/markdown/podman-secret-create.1.md b/docs/source/markdown/podman-secret-create.1.md
index e08afb388..39e0c6843 100644
--- a/docs/source/markdown/podman-secret-create.1.md
+++ b/docs/source/markdown/podman-secret-create.1.md
@@ -20,7 +20,7 @@ Secrets will not be committed to an image with `podman commit`, and will not be
 
 ## OPTIONS
 
-#### **--driver**=*driver*
+#### **--driver**, **-d**=*driver*
 
 Specify the secret driver (default **file**, which is unencrypted).
 
diff --git a/docs/source/markdown/podman-secret-inspect.1.md b/docs/source/markdown/podman-secret-inspect.1.md
index df16ba6fa..1a7115f63 100644
--- a/docs/source/markdown/podman-secret-inspect.1.md
+++ b/docs/source/markdown/podman-secret-inspect.1.md
@@ -15,7 +15,7 @@ Secrets can be queried individually by providing their full name or a unique par
 
 ## OPTIONS
 
-#### **--format**=*format*
+#### **--format**, **-f**=*format*
 
 Format secret output using Go template.