11 files changed, 73 insertions, 89 deletions
diff --git a/docs/source/markdown/options/dns-opt.container.md b/docs/source/markdown/options/dns-opt.container.md
new file mode 100644
index 000000000..ea26fd013
--- /dev/null
+++ b/docs/source/markdown/options/dns-opt.container.md
@@ -0,0 +1,3 @@
+#### **--dns-opt**=*option*
+
+Set custom DNS options. Invalid if using **--dns-opt** with **--network** that is set to **none** or **container:**_id_.
diff --git a/docs/source/markdown/options/dns-search.container.md b/docs/source/markdown/options/dns-search.container.md
new file mode 100644
index 000000000..5a803ba39
--- /dev/null
+++ b/docs/source/markdown/options/dns-search.container.md
@@ -0,0 +1,4 @@
+#### **--dns-search**=*domain*
+
+Set custom DNS search domains. Invalid if using **--dns-search** with **--network** that is set to **none** or **container:**_id_.
+Use **--dns-search=.** if you don't wish to set the search domain.
diff --git a/docs/source/markdown/options/systemd.md b/docs/source/markdown/options/systemd.md
new file mode 100644
index 000000000..a341edbc2
--- /dev/null
+++ b/docs/source/markdown/options/systemd.md
@@ -0,0 +1,29 @@
+#### **--systemd**=*true* | *false* | *always*
+
+Run container in systemd mode. The default is **true**.
+
+The value *always* enforces the systemd mode is enforced without
+looking at the executable name. Otherwise, if set to true and the
+command you are running inside the container is **systemd**, **/usr/sbin/init**,
+**/sbin/init** or **/usr/local/sbin/init**.
+
+Running the container in systemd mode causes the following changes:
+
+* Podman mounts tmpfs file systems on the following directories
+  * _/run_
+  * _/run/lock_
+  * _/tmp_
+  * _/sys/fs/cgroup/systemd_
+  * _/var/lib/journal_
+* Podman sets the default stop signal to **SIGRTMIN+3**.
+* Podman sets **container_uuid** environment variable in the container to the
+first 32 characters of the container id.
+
+This allows systemd to run in a confined container without any modifications.
+
+Note that on **SELinux** systems, systemd attempts to write to the cgroup
+file system. Containers writing to the cgroup file system are denied by default.
+The **container_manage_cgroup** boolean must be enabled for this to be allowed on an SELinux separated system.
+```
+setsebool -P container_manage_cgroup true
+```
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
index 4dbc75551..0a880951d 100644
--- a/docs/source/markdown/podman-create.1.md.in
+++ b/docs/source/markdown/podman-create.1.md.in
@@ -184,13 +184,9 @@ is the case the **--dns** flag is necessary for every run.
 The special value **none** can be specified to disable creation of **/etc/resolv.conf** in the container by Podman.
 The **/etc/resolv.conf** file in the image will be used without changes.
 
-#### **--dns-opt**=*option*
+@@option dns-opt.container
 
-Set custom DNS options. Invalid if using **--dns-opt** and **--network** that is set to 'none' or `container:<name|id>`.
-
-#### **--dns-search**=*domain*
-
-Set custom DNS search domains. Invalid if using **--dns-search** and **--network** that is set to 'none' or `container:<name|id>`. (Use --dns-search=. if you don't wish to set the search domain)
+@@option dns-search.container
 
 @@option entrypoint
 
@@ -632,34 +628,7 @@ Network Namespace - current sysctls allowed:
 
 Note: if you use the --network=host option these sysctls will not be allowed.
 
-#### **--systemd**=*true* | *false* | *always*
-
-Run container in systemd mode. The default is *true*.
-
-The value *always* enforces the systemd mode is enforced without
-looking at the executable name. Otherwise, if set to true and the
-command you are running inside the container is **systemd**, **/usr/sbin/init**,
-**/sbin/init** or **/usr/local/sbin/init**.
-
-Running the container in systemd mode causes the following changes:
-
-* Podman mounts tmpfs file systems on the following directories
-  * _/run_
-  * _/run/lock_
-  * _/tmp_
-  * _/sys/fs/cgroup/systemd_
-  * _/var/lib/journal_
-* Podman sets the default stop signal to **SIGRTMIN+3**.
-* Podman sets **container_uuid** environment variable in the container to the
-first 32 characters of the container id.
-
-This allows systemd to run in a confined container without any modifications.
-
-Note: On `SELinux` systems, systemd attempts to write to the cgroup
-file system. Containers writing to the cgroup file system are denied by default.
-The `container_manage_cgroup` boolean must be enabled for this to be allowed on an SELinux separated system.
-
-`setsebool -P container_manage_cgroup true`
+@@option systemd
 
 @@option timeout
 
diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md
index fc2ce171e..88dff2a45 100644
--- a/docs/source/markdown/podman-generate-systemd.1.md
+++ b/docs/source/markdown/podman-generate-systemd.1.md
@@ -26,7 +26,7 @@ therefore the overridden default value._
 A Kubernetes YAML can be executed in systemd via the `podman-kube@.service` systemd template.  The template's argument is the path to the YAML file.  Given a `workload.yaml` file in the home directory, it can be executed as follows:
 
 ```
-$ escaped=$(systemd-escape ~/sysadmin.yaml)
+$ escaped=$(systemd-escape ~/workload.yaml)
 $ systemctl --user start podman-kube@$escaped.service
 $ systemctl --user is-active podman-kube@$escaped.service
 active
diff --git a/docs/source/markdown/podman-image-trust.1.md b/docs/source/markdown/podman-image-trust.1.md
index 4e80bdcf5..2a7da82cc 100644
--- a/docs/source/markdown/podman-image-trust.1.md
+++ b/docs/source/markdown/podman-image-trust.1.md
@@ -32,7 +32,8 @@ Trust **type** provides a way to:
 
 Allowlist ("accept") or
 Denylist ("reject") registries or
-Require signature (“signedBy”).
+Require a simple signing signature (“signedBy”),
+Require a sigstore signature ("sigstoreSigned").
 
 Trust may be updated using the command **podman image trust set** for an existing trust scope.
 
@@ -45,12 +46,14 @@ Trust may be updated using the command **podman image trust set** for an existin
 #### **--pubkeysfile**, **-f**=*KEY1*
   A path to an exported public key on the local system. Key paths
   will be referenced in policy.json. Any path to a file may be used but locating the file in **/etc/pki/containers** is recommended. Options may be used multiple times to
-  require an image be signed by multiple keys.  The **--pubkeysfile** option is required for the **signedBy** type.
+  require an image be signed by multiple keys.  The **--pubkeysfile** option is required for the **signedBy** and **sigstoreSigned** types.
 
 #### **--type**, **-t**=*value*
   The trust type for this policy entry.
   Accepted values:
-    **signedBy** (default): Require signatures with corresponding list of
+    **signedBy** (default): Require simple signing signatures with corresponding list of
+                        public keys
+    **sigstoreSigned**: Require sigstore signatures with corresponding list of
                         public keys
     **accept**: do not require any signatures for this
             registry scope
diff --git a/docs/source/markdown/podman-pod-restart.1.md b/docs/source/markdown/podman-pod-restart.1.md
index 677eca3a3..51f13dbf8 100644
--- a/docs/source/markdown/podman-pod-restart.1.md
+++ b/docs/source/markdown/podman-pod-restart.1.md
@@ -24,17 +24,27 @@ Instead of providing the pod name or ID, restart the last created pod. (This opt
 
 ## EXAMPLE
 
+Restart pod with a given name
 ```
 podman pod restart mywebserverpod
 cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907
+```
 
+Restart multiple pods with given IDs
+```
 podman pod restart 490eb 3557fb
 490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5
 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab
+```
 
+Restart the last created pod
+```
 podman pod restart --latest
 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab
+```
 
+Restart all pods
+```
 podman pod restart --all
 19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818
 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab
@@ -42,7 +52,6 @@ podman pod restart --all
 70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9
 cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907
 ```
-
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-restart(1)](podman-restart.1.md)**
 
diff --git a/docs/source/markdown/podman-pod-stop.1.md.in b/docs/source/markdown/podman-pod-stop.1.md.in
index 3655c3938..abcc69e9e 100644
--- a/docs/source/markdown/podman-pod-stop.1.md.in
+++ b/docs/source/markdown/podman-pod-stop.1.md.in
@@ -29,20 +29,20 @@ Seconds to wait before forcibly stopping the containers in the pod.
 
 ## EXAMPLE
 
-Stop a pod called *mywebserverpod*
+Stop pod with a given name
 ```
 $ podman pod stop mywebserverpod
 cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907
 ```
 
-Stop two pods by their short IDs.
+Stop multiple pods with given IDs.
 ```
 $ podman pod stop 490eb 3557fb
 490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5
 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab
 ```
 
-Stop the most recent pod
+Stop the last created pod
 ```
 $ podman pod stop --latest
 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab
@@ -65,7 +65,7 @@ $ podman pod stop --pod-id-file file1 --pod-id-file file2
 cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907
 ```
 
-Stop all pods with a timeout of 1 second.
+Stop all pods with a timeout of 1 second
 ```
 $ podman pod stop -a -t 1
 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab
diff --git a/docs/source/markdown/podman-rename.1.md b/docs/source/markdown/podman-rename.1.md
index 4017db505..0a807e6de 100644
--- a/docs/source/markdown/podman-rename.1.md
+++ b/docs/source/markdown/podman-rename.1.md
@@ -19,18 +19,18 @@ At present, only containers are supported; pods and volumes cannot be renamed.
 
 ## EXAMPLES
 
+Rename container with a given name
 ```
-# Rename a container by name
 $ podman rename oldContainer aNewName
 ```
 
+Rename container with a given ID
 ```
-# Rename a container by ID
 $ podman rename 717716c00a6b testcontainer
 ```
 
+Create an alias for container with a given ID
 ```
-# Use the container rename alias
 $ podman container rename 6e7514b47180 databaseCtr
 ```
 
diff --git a/docs/source/markdown/podman-rm.1.md.in b/docs/source/markdown/podman-rm.1.md.in
index c0fa94d82..9eb44dcc1 100644
--- a/docs/source/markdown/podman-rm.1.md.in
+++ b/docs/source/markdown/podman-rm.1.md.in
@@ -73,37 +73,37 @@ Remove anonymous volumes associated with the container. This does not include na
 created with **podman volume create**, or the **--volume** option of **podman run** and **podman create**.
 
 ## EXAMPLE
-Remove a container by its name *mywebserver*
+Remove container with a given name
 ```
 $ podman rm mywebserver
 ```
 
-Remove a *mywebserver* container and all of the containers that depend on it
+Remove container with a given name and all of the containers that depend on it
 ```
 $ podman rm --depend mywebserver
 ```
 
-Remove several containers by name and container id.
+Remove multiple containers with given names or IDs
 ```
 $ podman rm mywebserver myflaskserver 860a4b23
 ```
 
-Remove several containers reading their IDs from files.
+Remove multiple containers with IDs read from files
 ```
 $ podman rm --cidfile ./cidfile-1 --cidfile /home/user/cidfile-2
 ```
 
-Forcibly remove a container by container ID.
+Forcibly remove container with a given ID
 ```
 $ podman rm -f 860a4b23
 ```
 
-Remove all containers regardless of its run state.
+Remove all containers regardless of the run state
 ```
 $ podman rm -f -a
 ```
 
-Forcibly remove the latest container created.
+Forcibly remove the last created container
 ```
 $ podman rm -f --latest
 ```
diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in
index c7985d7e1..6798c65da 100644
--- a/docs/source/markdown/podman-run.1.md.in
+++ b/docs/source/markdown/podman-run.1.md.in
@@ -218,14 +218,9 @@ is the case the **--dns** flag is necessary for every run.
 The special value **none** can be specified to disable creation of _/etc/resolv.conf_ in the container by Podman.
 The _/etc/resolv.conf_ file in the image will be used without changes.
 
-#### **--dns-opt**=*option*
+@@option dns-opt.container
 
-Set custom DNS options. Invalid if using **--dns-opt** with **--network** that is set to **none** or **container:**_id_.
-
-#### **--dns-search**=*domain*
-
-Set custom DNS search domains. Invalid if using **--dns-search** and **--network** that is set to **none** or **container:**_id_.
-Use **--dns-search=.** if you don't wish to set the search domain.
+@@option dns-search.container
 
 @@option entrypoint
 
@@ -682,35 +677,7 @@ For the network namespace, the following sysctls are allowed:
 
 Note: if you use the **--network=host** option, these sysctls will not be allowed.
 
-#### **--systemd**=*true* | *false* | *always*
-
-Run container in systemd mode. The default is **true**.
-
-The value *always* enforces the systemd mode is enforced without
-looking at the executable name. Otherwise, if set to true and the
-command you are running inside the container is **systemd**, **/usr/sbin/init**,
-**/sbin/init** or **/usr/local/sbin/init**.
-
-Running the container in systemd mode causes the following changes:
-
-* Podman mounts tmpfs file systems on the following directories
-  * _/run_
-  * _/run/lock_
-  * _/tmp_
-  * _/sys/fs/cgroup/systemd_
-  * _/var/lib/journal_
-* Podman sets the default stop signal to **SIGRTMIN+3**.
-* Podman sets **container_uuid** environment variable in the container to the
-first 32 characters of the container id.
-
-This allows systemd to run in a confined container without any modifications.
-
-Note that on **SELinux** systems, systemd attempts to write to the cgroup
-file system. Containers writing to the cgroup file system are denied by default.
-The **container_manage_cgroup** boolean must be enabled for this to be allowed on an SELinux separated system.
-```
-setsebool -P container_manage_cgroup true
-```
+@@option systemd
 
 @@option timeout