14 files changed, 45 insertions, 108 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/label.md b/docs/source/markdown/options/label.md
new file mode 100644
index 000000000..629aa82e6
--- /dev/null
+++ b/docs/source/markdown/options/label.md
@@ -0,0 +1,3 @@
+#### **--label**, **-l**=*key=value*
+
+Add metadata to a <<container|pod>>.
diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in
index 693e0d3b9..bc1e03e4c 100644
--- a/docs/source/markdown/podman-build.1.md.in
+++ b/docs/source/markdown/podman-build.1.md.in
@@ -156,8 +156,8 @@ more.
 
 When executing RUN instructions, run the command specified in the instruction
 with the specified capability removed from its capability set.
-The CAP\_AUDIT\_WRITE, CAP\_CHOWN, CAP\_DAC\_OVERRIDE, CAP\_FOWNER,
-CAP\_FSETID, CAP\_KILL, CAP\_MKNOD, CAP\_NET\_BIND\_SERVICE, CAP\_SETFCAP,
+The CAP\_CHOWN, CAP\_DAC\_OVERRIDE, CAP\_FOWNER,
+CAP\_FSETID, CAP\_KILL, CAP\_NET\_BIND\_SERVICE, CAP\_SETFCAP,
 CAP\_SETGID, CAP\_SETPCAP, CAP\_SETUID, and CAP\_SYS\_CHROOT capabilities are
 granted by default; this option can be used to remove them.
 
@@ -391,28 +391,9 @@ This option is not supported on the remote client, including Mac and Windows
 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.
 
-#### **--memory**, **-m**=*LIMIT*
+@@option memory
 
-Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes),
-m (mebibytes), or g (gibibytes))
-
-Allows you to constrain the memory available to a container. If the host
-supports swap memory, then the **-m** memory setting can be larger than physical
-RAM. If a limit of 0 is specified (not using **-m**), the container's memory is
-not limited. The actual limit may be rounded up to a multiple of the operating
-system's page size (the value would be very large, that's millions of
-trillions).
-
-#### **--memory-swap**=*LIMIT*
-
-A limit value equal to memory plus swap. Must be used with the  **-m**
-(**--memory**) option. The swap `LIMIT` should always be larger than **-m**
-(**--memory**) value.  By default, the swap `LIMIT` will be set to double
-the value of --memory.
-
-The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes),
-`k` (kibibytes), `m` (mebibytes), or `g` (gibibytes). If you don't specify a
-unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap.
+@@option memory-swap
 
 #### **--network**=*mode*, **--net**
 
diff --git a/docs/source/markdown/podman-container-clone.1.md.in b/docs/source/markdown/podman-container-clone.1.md.in
index 3e31389d2..6e40a9496 100644
--- a/docs/source/markdown/podman-container-clone.1.md.in
+++ b/docs/source/markdown/podman-container-clone.1.md.in
@@ -64,28 +64,15 @@ Force removal of the original container that we are cloning. Can only be used in
 
 If no memory limits are specified, the original container's will be used.
 
-#### **--memory-reservation**=*limit*
+@@option memory-reservation
 
-Memory soft limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes))
+If unspecified, memory reservation will be the same as memory limit from the
+container being cloned.
 
-After setting memory reservation, when the system detects memory contention
-or low memory, containers are forced to restrict their consumption to their
-reservation. So you should always set the value below **--memory**, otherwise the
-hard limit will take precedence. By default, memory reservation will be the same
-as memory limit from the container being cloned.
+@@option memory-swap
 
-#### **--memory-swap**=*limit*
-
-A limit value equal to memory plus swap. Must be used with the  **-m**
-(**--memory**) flag. The swap `LIMIT` should always be larger than **-m**
-(**--memory**) value. By default, the swap `LIMIT` will be set to double
-the value of --memory if specified. Otherwise, the container being cloned will be used to derive the swap value.
-
-The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes),
-`k` (kibibytes), `m` (mebibytes), or `g` (gibibytes). If you don't specify a
-unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap.
-
-This option is not supported on cgroups V1 rootless systems.
+If unspecified, the container being cloned will be used to derive
+the swap value.
 
 @@option memory-swappiness
 
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
index 987f10181..25726af8c 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
 
@@ -260,9 +260,7 @@ To specify multiple static IPv6 addresses per container, set multiple networks u
 
 @@option ipc
 
-#### **--label**, **-l**=*label*
-
-Add metadata to a container (e.g., --label com.example.key=value)
+@@option label
 
 @@option label-file
 
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-pod-clone.1.md.in b/docs/source/markdown/podman-pod-clone.1.md.in
index 24edc44ec..d1e1b3468 100644
--- a/docs/source/markdown/podman-pod-clone.1.md.in
+++ b/docs/source/markdown/podman-pod-clone.1.md.in
@@ -66,32 +66,13 @@ Print usage statement.
 
 @@option infra-name
 
-#### **--label**, **-l**=*label*
-
-Add metadata to a pod (e.g., --label com.example.key=value).
+@@option label
 
 @@option label-file
 
-#### **--memory**, **-m**=*limit*
-
-Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes))
-
-Constrains the memory available to a container. If the host
-supports swap memory, then the **-m** memory setting can be larger than physical
-RAM. If a limit of 0 is specified (not using **-m**), the container's memory is
-not limited. The actual limit may be rounded up to a multiple of the operating
-system's page size (the value would be very large, that's millions of trillions).
-
-#### **--memory-swap**=*limit*
-
-A limit value equal to memory plus swap. Must be used with the  **-m**
-(**--memory**) flag. The swap `LIMIT` should always be larger than **-m**
-(**--memory**) value. By default, the swap `LIMIT` will be set to double
-the value of --memory.
+@@option memory
 
-The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes),
-`k` (kibibytes), `m` (mebibytes), or `g` (gibibytes). If you don't specify a
-unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap.
+@@option memory-swap
 
 #### **--name**, **-n**
 
diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in
index 35d06fa00..bad39b66f 100644
--- a/docs/source/markdown/podman-pod-create.1.md.in
+++ b/docs/source/markdown/podman-pod-create.1.md.in
@@ -130,34 +130,15 @@ The address must be within the network's IPv6 address pool.
 
 To specify multiple static IPv6 addresses per pod, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option.
 
-#### **--label**, **-l**=*label*
-
-Add metadata to a pod (e.g., --label com.example.key=value).
+@@option label
 
 @@option label-file
 
 @@option mac-address
 
-#### **--memory**, **-m**=*limit*
-
-Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes))
-
-Constrains the memory available to a container. If the host
-supports swap memory, then the **-m** memory setting can be larger than physical
-RAM. If a limit of 0 is specified (not using **-m**), the container's memory is
-not limited. The actual limit may be rounded up to a multiple of the operating
-system's page size (the value would be very large, that's millions of trillions).
-
-#### **--memory-swap**=*limit*
-
-A limit value equal to memory plus swap. Must be used with the  **-m**
-(**--memory**) flag. The swap `LIMIT` should always be larger than **-m**
-(**--memory**) value. By default, the swap `LIMIT` will be set to double
-the value of --memory.
+@@option memory
 
-The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes),
-`k` (kibibytes), `m` (mebibytes), or `g` (gibibytes). If you don't specify a
-unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap.
+@@option memory-swap
 
 #### **--name**, **-n**=*name*
 
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 64affa238..3ad338662 100644
--- a/docs/source/markdown/podman-run.1.md.in
+++ b/docs/source/markdown/podman-run.1.md.in
@@ -280,9 +280,7 @@ To specify multiple static IPv6 addresses per container, set multiple networks u
 
 @@option ipc
 
-#### **--label**, **-l**=*key=value*
-
-Add metadata to a container.
+@@option label
 
 @@option label-file
 
@@ -309,15 +307,7 @@ This option is currently supported only by the **journald** log driver.
 
 @@option mac-address
 
-#### **--memory**, **-m**=*number[unit]*
-
-Memory limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes).
-
-Allows you to constrain the memory available to a container. If the host
-supports swap memory, then the **-m** memory setting can be larger than physical
-RAM. If a limit of 0 is specified (not using **-m**), the container's memory is
-not limited. The actual limit may be rounded up to a multiple of the operating
-system's page size (the value would be very large, that's millions of trillions).
+@@option memory
 
 @@option memory-reservation