10 files changed, 39 insertions, 34 deletions
diff --git a/docs/source/markdown/options/device-read-bps.md b/docs/source/markdown/options/device-read-bps.md
index e0c610061..f6617ab77 100644
--- a/docs/source/markdown/options/device-read-bps.md
+++ b/docs/source/markdown/options/device-read-bps.md
@@ -2,4 +2,8 @@
 
 Limit read rate (in bytes per second) from a device (e.g. **--device-read-bps=/dev/sda:1mb**).
 
+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
+
 This option is not supported on cgroups V1 rootless systems.
diff --git a/docs/source/markdown/options/device-read-iops.md b/docs/source/markdown/options/device-read-iops.md
index 9cd0f9030..944c66441 100644
--- a/docs/source/markdown/options/device-read-iops.md
+++ b/docs/source/markdown/options/device-read-iops.md
@@ -2,4 +2,8 @@
 
 Limit read rate (in IO operations per second) from a device (e.g. **--device-read-iops=/dev/sda:1000**).
 
+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
+
 This option is not supported on cgroups V1 rootless systems.
diff --git a/docs/source/markdown/options/device-write-bps.md b/docs/source/markdown/options/device-write-bps.md
index 3dacc4515..ebcda0181 100644
--- a/docs/source/markdown/options/device-write-bps.md
+++ b/docs/source/markdown/options/device-write-bps.md
@@ -2,4 +2,8 @@
 
 Limit write rate (in bytes per second) to a device (e.g. **--device-write-bps=/dev/sda:1mb**).
 
+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
+
 This option is not supported on cgroups V1 rootless systems.
diff --git a/docs/source/markdown/options/device-write-iops.md b/docs/source/markdown/options/device-write-iops.md
index cf5ce3859..6de273d18 100644
--- a/docs/source/markdown/options/device-write-iops.md
+++ b/docs/source/markdown/options/device-write-iops.md
@@ -2,4 +2,8 @@
 
 Limit write rate (in IO operations per second) to a device (e.g. **--device-write-iops=/dev/sda:1000**).
 
+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
+
 This option is not supported on cgroups V1 rootless systems.
diff --git a/docs/source/markdown/options/digestfile.md b/docs/source/markdown/options/digestfile.md
new file mode 100644
index 000000000..de013e287
--- /dev/null
+++ b/docs/source/markdown/options/digestfile.md
@@ -0,0 +1,4 @@
+#### **--digestfile**=*Digestfile*
+
+After copying the image, write the digest of the resulting image to the file.
+(This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
diff --git a/docs/source/markdown/options/name.container.md b/docs/source/markdown/options/name.container.md
new file mode 100644
index 000000000..0c3df6ef1
--- /dev/null
+++ b/docs/source/markdown/options/name.container.md
@@ -0,0 +1,14 @@
+#### **--name**=*name*
+
+Assign a name to the container.
+
+The operator can identify a container in three ways:
+
+- UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”);
+- UUID short identifier (“f78375b1c487”);
+- Name (“jonah”).
+
+Podman generates a UUID for each container, and if a name is not assigned
+to the container with **--name** then it will generate a random
+string name. The name is useful any place you need to identify a container.
+This works for both background and foreground containers.
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
index 10f0f7f56..4fe50caed 100644
--- a/docs/source/markdown/podman-create.1.md.in
+++ b/docs/source/markdown/podman-create.1.md.in
@@ -144,7 +144,7 @@ device. The devices that podman will load modules when necessary are:
 
 @@option device-cgroup-rule
 
-#### **--device-read-bps**=*path*
+@@option device-read-bps
 
 @@option device-read-iops
 
@@ -299,19 +299,7 @@ This option is currently supported only by the **journald** log driver.
 
 @@option mount
 
-#### **--name**=*name*
-
-Assign a name to the container
-
-The operator can identify a container in three ways:
-UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
-UUID short identifier (“f78375b1c487”)
-Name (“jonah”)
-
-podman generates a UUID for each container, and if a name is not assigned
-to the container with **--name** then it will generate a random
-string name. The name is useful any place you need to identify a container.
-This works for both background and foreground containers.
+@@option name.container
 
 #### **--network**=*mode*, **--net**
 
diff --git a/docs/source/markdown/podman-manifest-push.1.md.in b/docs/source/markdown/podman-manifest-push.1.md.in
index 88d070c3f..b27fbee8d 100644
--- a/docs/source/markdown/podman-manifest-push.1.md.in
+++ b/docs/source/markdown/podman-manifest-push.1.md.in
@@ -29,9 +29,7 @@ Specifies the compression format to use.  Supported values are: `gzip`, `zstd` a
 
 @@option creds
 
-#### **--digestfile**=*Digestfile*
-
-After copying the image, write the digest of the resulting image to the file.
+@@option digestfile
 
 #### **--format**, **-f**=*format*
 
diff --git a/docs/source/markdown/podman-push.1.md.in b/docs/source/markdown/podman-push.1.md.in
index a98964e45..408fdb43c 100644
--- a/docs/source/markdown/podman-push.1.md.in
+++ b/docs/source/markdown/podman-push.1.md.in
@@ -62,9 +62,7 @@ Specifies the compression format to use.  Supported values are: `gzip`, `zstd` a
 
 @@option creds
 
-#### **--digestfile**=*Digestfile*
-
-After copying the image, write the digest of the resulting image to the file.  (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
+@@option digestfile
 
 @@option disable-content-trust
 
diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in
index b63c37e6f..64affa238 100644
--- a/docs/source/markdown/podman-run.1.md.in
+++ b/docs/source/markdown/podman-run.1.md.in
@@ -327,20 +327,7 @@ system's page size (the value would be very large, that's millions of trillions)
 
 @@option mount
 
-#### **--name**=*name*
-
-Assign a name to the container.
-
-The operator can identify a container in three ways:
-
-- UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”);
-- UUID short identifier (“f78375b1c487”);
-- Name (“jonah”).
-
-Podman generates a UUID for each container, and if a name is not assigned
-to the container with **--name** then it will generate a random
-string name. The name is useful any place you need to identify a container.
-This works for both background and foreground containers.
+@@option name.container
 
 #### **--network**=*mode*, **--net**