7 files changed, 77 insertions, 8 deletions
diff --git a/docs/Readme.md b/docs/README.md
index e0918cd54..83f5c79a3 100644
--- a/docs/Readme.md
+++ b/docs/README.md
@@ -52,3 +52,19 @@ likely caused by broken metadata needed to protect clients from cross-site-scrip
 style attacks.  Please [notify a maintainer](https://github.com/containers/podman#communications)
 so they may investigate how/why the `swagger.yaml` file's CORS-metadata is
 incorrect, or the file isn't accessible for some other reason.
+
+## Local Testing
+
+Assuming that you have the [dependencies](https://podman.io/getting-started/installation#build-and-run-dependencies)
+installed, then also install (showing Fedora in the example):
+
+```
+# dnf install python3-sphinx python3-recommonmark
+# pip install sphinx-markdown-tables
+```
+After that completes, cd to the `docs` directory in your Podman sandbox and then do `make html`.
+
+You can then preview the html files in `docs/build/html` with:
+```
+python -m http.server 8000 --directory build/html
+```
diff --git a/docs/source/machine.rst b/docs/source/machine.rst
index be9ef1e95..16c042173 100644
--- a/docs/source/machine.rst
+++ b/docs/source/machine.rst
@@ -3,6 +3,7 @@ Machine
 
 
 :doc:`init <markdown/podman-machine-init.1>` Initialize a new virtual machine
+:doc:`list <markdown/podman-machine-list.1>` List virtual machines
 :doc:`rm <markdown/podman-machine-rm.1>` Remove a virtual machine
 :doc:`ssh <markdown/podman-machine-ssh.1>` SSH into a virtual machine
 :doc:`start <markdown/podman-machine-start.1>` Start a virtual machine
diff --git a/docs/source/markdown/links/podman-machine-ls.1 b/docs/source/markdown/links/podman-machine-ls.1
new file mode 100644
index 000000000..f6acb7f74
--- /dev/null
+++ b/docs/source/markdown/links/podman-machine-ls.1
@@ -0,0 +1 @@
+.so man1/podman-machine-list.1
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index 9ae4ab207..f56319cf3 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -1029,7 +1029,7 @@ Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman
 bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman
 container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the volume
 in the host to the container. If no such named volume exists, Podman will
-create one. The `OPTIONS` are a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup>
+create one. The `OPTIONS` are a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup>  (Note when using the remote client, the volumes will be mounted from the remote server, not necessarly the client machine.)
 
 The _options_ is a comma delimited list and can be:
 
diff --git a/docs/source/markdown/podman-machine-list.1.md b/docs/source/markdown/podman-machine-list.1.md
new file mode 100644
index 000000000..bd5608258
--- /dev/null
+++ b/docs/source/markdown/podman-machine-list.1.md
@@ -0,0 +1,50 @@
+% podman-machine-ls(1)
+
+## NAME
+podman\-machine\-list - List virtual machines
+
+## SYNOPSIS
+**podman machine list** [*options*]
+
+**podman machine ls** [*options*]
+
+## DESCRIPTION
+
+List Podman managed virtual machines.
+
+Podman on macOS requires a virtual machine. This is because containers are Linux -
+containers do not run on any other OS because containers' core functionality is
+tied to the Linux kernel.
+
+## OPTIONS
+
+#### **\-\-format**=*format*
+
+Format list output using a Go template.
+
+Valid placeholders for the Go template are listed below:
+
+| **Placeholder** | **Description**                 |
+| --------------- | ------------------------------- |
+| .Name           | VM name                         |
+| .Created        | Time since VM creation          |
+| .LastUp         | Time since the VM was last run  |
+| .VMType         | VM type                      	|
+
+#### **\-\-help**
+
+Print usage statement.
+
+## EXAMPLES
+
+```
+$ podman machine list
+
+$ podman machine ls --format {{.Name}}\t{{.VMType}}\t{{.Created}}\t{{.LastUp}}\n
+```
+
+## SEE ALSO
+podman-machine(1)
+
+## HISTORY
+March 2021, Originally compiled by Ashley Cui <acui@redhat.com>
diff --git a/docs/source/markdown/podman-machine.1.md b/docs/source/markdown/podman-machine.1.md
index a5d3b78df..693f42fe3 100644
--- a/docs/source/markdown/podman-machine.1.md
+++ b/docs/source/markdown/podman-machine.1.md
@@ -14,13 +14,14 @@ podman\-machine - Manage Podman's virtual machine
 | Command | Man Page                                                | Description                       |
 | ------- | ------------------------------------------------------- | --------------------------------- |
 | init    | [podman-machine-init(1)](podman-machine-init.1.md)      | Initialize a new virtual machine  |
-| rm | [podman-machine-rm(1)](podman-machine-rm.1.md)| Remove a virtual machine     |
-| ssh     | [podman-machine-ssh(1)](podman-machine-ssh.1.md)   | SSH into a virtual machine    |
-| start   | [podman-machine-start(1)](podman-machine-start.1.md)    | Start a virtual machine       |
-| stop    | [podman-machine-stop(1)](podman-machine-stop.1.md)      | Stop a virtual machine        |
+| list    | [podman-machine-list(1)](podman-machine-list.1.md)      | List virtual machines             |
+| rm      | [podman-machine-rm(1)](podman-machine-rm.1.md)          | Remove a virtual machine          |
+| ssh     | [podman-machine-ssh(1)](podman-machine-ssh.1.md)        | SSH into a virtual machine        |
+| start   | [podman-machine-start(1)](podman-machine-start.1.md)    | Start a virtual machine           |
+| stop    | [podman-machine-stop(1)](podman-machine-stop.1.md)      | Stop a virtual machine            |
 
 ## SEE ALSO
-podman(1)
+podman(1), podman-machine-init(1), podman-machine-list(1), podman-machine-rm(1), podman-machine-ssh(1), podman-machine-start(1), podman-machine-stop(1)
 
 ## HISTORY
 March 2021, Originally compiled by Ashley Cui <acui@redhat.com>
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index 6d9d5ba28..fcb5a13ec 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -744,7 +744,7 @@ If a container is run within a pod, and the pod has an infra-container, the infr
 #### **\-\-preserve-fds**=*N*
 
 Pass down to the process N additional file descriptors (in addition to 0, 1, 2).
-The total FDs will be 3+N.
+The total FDs will be 3+N. (This option is not available with the remote Podman client)
 
 #### **\-\-privileged**=**true**|**false**
 
@@ -1104,7 +1104,7 @@ Create a bind mount. If you specify _/HOST-DIR_:_/CONTAINER-DIR_, Podman
 bind mounts _host-dir_ in the host to _CONTAINER-DIR_ in the Podman
 container. Similarly, _SOURCE-VOLUME_:_/CONTAINER-DIR_ will mount the volume
 in the host to the container. If no such named volume exists, Podman will
-create one.
+create one. (Note when using the remote client, the volumes will be mounted from the remote server, not necessarly the client machine.)
 
 The _options_ is a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup>