1 files changed, 30 insertions, 12 deletions
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index 9ebf6649b..aad179957 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -57,7 +57,7 @@ each of **stdin**, **stdout**, and **stderr**.
 
 **--authfile**[=*path*]
 
-Path to the authentication file. Default is *${XDG_RUNTIME_DIR}/containers/auth.json*. (Not available for remote commands)
+Path to the authentication file. Default is *${XDG_RUNTIME_DIR}/containers/auth.json*.
 
 Note: You can also override the default path of the authentication file by setting the **REGISTRY_AUTH_FILE**
 environment variable.
@@ -118,15 +118,27 @@ Write the pid of the **conmon** process to a file. As **conmon** runs in a separ
 
 **--cpu-period**=*limit*
 
-Limit the container's CPU usage by setting CPU CFS (Completely Fair Scheduler) period.
+Set the CPU period for the Completely Fair Scheduler (CFS), which is a
+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
+users. For more details, see
+https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
 
 **--cpu-quota**=*limit*
 
-Limit the CPU CFS (Completely Fair Scheduler) quota.
+Limit the CPU Completely Fair Scheduler (CFS) quota.
 
 Limit the container's CPU usage. By default, containers run with the full
-CPU resource. This flag tell the kernel to restrict the container's CPU usage
-to the quota you specify.
+CPU resource. The limit is a number in microseconds. If you provide a number,
+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
+users. For more details, see
+https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
 
 **--cpu-rt-period**=*microseconds*
 
@@ -180,7 +192,13 @@ division of CPU shares:
 
 **--cpus**=*number*
 
-Number of CPUs. The default is *0.0* which means no limit.
+Number of CPUs. The default is *0.0* which means no limit. This is shorthand
+for **--cpu-period** and **--cpu-quota**, so you may only set either
+**--cpus** or **--cpu-period** and **--cpu-quota**.
+
+On some systems, changing the CPU limits may not be allowed for non-root
+users. For more details, see
+https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
 
 **--cpuset-cpus**=*number*
 
@@ -197,20 +215,20 @@ to only use memory from the first two memory nodes.
 
 **--detach**, **-d**=**true**|**false**
 
-Detached mode: run the container in the background and print the new container ID. The default is **false**.
+Detached mode: run the container in the background and print the new container ID. The default is *false*.
 
 At any time you can run **podman ps** in
 the other shell to view a list of the running containers. You can reattach to a
 detached container with **podman attach**.
 
 When attached in the tty mode, you can detach from the container (and leave it
-running) using a configurable key sequence.
+running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`.
+Configure the keys sequence using the **--detach-keys** option, or specifying
+it in the **containers.conf** file: see **containers.conf(5)** for more information.
 
-**--detach-keys**=_sequence_
+**--detach-keys**=*sequence*
 
-Specify the key sequence for detaching a container; _sequence_ is a comma-delimited set
-in which each item can be a single character from the [a-Z] range,
-or **ctrl**-_value_, where _value_ is one of: **a-z** or **@^[,_**.
+Specify the key sequence for detaching a container. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is *ctrl-p,ctrl-q*.
 
 This option can also be set in **containers.conf**(5) file.