Cleanup Documentation and bash completions

Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>

Closes: #159
Approved by: TomSweeneyRedHat

22 files changed, 80 insertions, 70 deletions

diff --git a/README.md b/README.md
index a603db444..d7d63d382 100644
--- a/README.md
+++ b/README.md
@@ -31,16 +31,19 @@ The plan is to use OCI projects and best of breed libraries for different aspect
 libpod is currently in active development.
 
 ## Commands
-| Command                                              | Description                                                               | Demo|
-| ---------------------------------------------------- | --------------------------------------------------------------------------|-----|
+| Command                                                  | Description                                                               | Demo|
+| :------------------------------------------------------- | :------------------------------------------------------------------------ | :----|
 | [podman(1)](/docs/podman.1.md)                           | Simple management tool for pods and images                                ||
-| [podman-attach(1)](/docs/podman-attach.1.md)             | Attach to a running container.
-| [podman-cp(1)](/docs/podman-cp.1.md)                     | Instead of providing a `podman cp` command, the man page `podman-cp` describes how to use the `podman mount` command to have even more flexibility and functionality.||
+| [podman-attach(1)](/docs/podman-attach.1.md)             | Attach to a running container                                             ||
+| [podman-commit(1)](/docs/podman-commit.1.md)             | Create new image based on the changed container                           ||
+| [podman-cp(1)](/docs/podman-cp.1.md)                     | Instead of providing a `podman cp` command, the man page `podman-cp` describes how to use the `podman mount` command to have even more flexibility and functionality||
+| [podman-create(1)](/docs/podman-create.1.md)             | Create a new container                                                    ||
 | [podman-diff(1)](/docs/podman-diff.1.md)                 | Inspect changes on a container or image's filesystem                      |[![...](/docs/play.png)](https://asciinema.org/a/FXfWB9CKYFwYM4EfqW3NSZy1G)|
-| [podman-exec(1)](/docs/podman-exec.1.md)                 | Execute a command in a running container.
+| [podman-exec(1)](/docs/podman-exec.1.md)                 | Execute a command in a running container
 | [podman-export(1)](/docs/podman-export.1.md)             | Export container's filesystem contents as a tar archive                   |[![...](/docs/play.png)](https://asciinema.org/a/913lBIRAg5hK8asyIhhkQVLtV)|
 | [podman-history(1)](/docs/podman-history.1.md)           | Shows the history of an image                                             |[![...](/docs/play.png)](https://asciinema.org/a/bCvUQJ6DkxInMELZdc5DinNSx)|
 | [podman-images(1)](/docs/podman-images.1.md)             | List images in local storage                                              |[![...](/docs/play.png)](https://asciinema.org/a/133649)|
+| [podman-import(1)](/docs/podman-import.1.md)             | Import a tarball and save it as a filesystem image                        ||
 | [podman-info(1)](/docs/podman-info.1.md)                 | Display system information                                                ||
 | [podman-inspect(1)](/docs/podman-inspect.1.md)           | Display the configuration of a container or image                         |[![...](/docs/play.png)](https://asciinema.org/a/133418)|
 | [podman-kill(1)](/docs/podman-kill.1.md)                 | Kill the main process in one or more running containers                   |[![...](/docs/play.png)](https://asciinema.org/a/3jNos0A5yzO4hChu7ddKkUPw7)|
@@ -53,7 +56,6 @@ libpod is currently in active development.
 | [podman-ps(1)](/docs/podman-ps.1.md)                     | Prints out information about containers                                   |[![...](/docs/play.png)](https://asciinema.org/a/bbT41kac6CwZ5giESmZLIaTLR)|
 | [podman-pull(1)](/docs/podman-pull.1.md)                 | Pull an image from a registry                                             |[![...](/docs/play.png)](https://asciinema.org/a/lr4zfoynHJOUNu1KaXa1dwG2X)|
 | [podman-push(1)](/docs/podman-push.1.md)                 | Push an image to a specified destination                                  |[![...](/docs/play.png)](https://asciinema.org/a/133276)|
-| [podman-rename(1)](/docs/podman-rename.1.md)             | Rename a container                                                        ||
 | [podman-rm(1)](/docs/podman-rm.1.md)                     | Removes one or more containers                                            |[![...](/docs/play.png)](https://asciinema.org/a/7EMk22WrfGtKWmgHJX9Nze1Qp)|
 | [podman-rmi(1)](/docs/podman-rmi.1.md)                   | Removes one or more images                                                |[![...](/docs/play.png)](https://asciinema.org/a/133799)|
 | [podman-save(1)](/docs/podman-save.1.md)                 | Saves an image to an archive                                              |[![...](/docs/play.png)](https://asciinema.org/a/kp8kOaexEhEa20P1KLZ3L5X4g)|
diff --git a/completions/bash/podman b/completions/bash/podman
index fd7fa99e2..37f70e24a 100644
--- a/completions/bash/podman
+++ b/completions/bash/podman
@@ -1501,7 +1501,6 @@ _podman_podman() {
     ps
     pull
     push
-    rename
     rm
     rmi
     run
@@ -1510,6 +1509,7 @@ _podman_podman() {
     stats
     stop
     tag
+    top
     umount
     unmount
     unpause
diff --git a/docs/podman-attach.1.md b/docs/podman-attach.1.md
index ddb59e553..4d8b803c8 100644
--- a/docs/podman-attach.1.md
+++ b/docs/podman-attach.1.md
@@ -3,7 +3,7 @@
 # podman-attach "1" "December 2017" "podman"
 
 ## NAME
-podman-attach - Attach to a running container
+podman attach - Attach to a running container
 
 ## SYNOPSIS
 **podman attach [OPTIONS] CONTAINER**
diff --git a/docs/podman-commit.1.md b/docs/podman-commit.1.md
index 10680fcb8..001c37daf 100644
--- a/docs/podman-commit.1.md
+++ b/docs/podman-commit.1.md
@@ -3,7 +3,7 @@
 # podman-commit "1" "December 2017" "podman"
 
 ## NAME
-podman-commit - Create new image based on the changed container
+podman commit - Create new image based on the changed container
 
 ## SYNOPSIS
 **podman commit**
diff --git a/docs/podman-cp.1.md b/docs/podman-cp.1.md
index 0c23d6f10..440a88866 100644
--- a/docs/podman-cp.1.md
+++ b/docs/podman-cp.1.md
@@ -3,7 +3,7 @@
 # podman-cp "1" "August 2017" "podman"
 
 ## NAME
-podman-cp - Copy files/folders between a container and the local filesystem.
+podman cp - Copy files/folders between a container and the local filesystem
 
 ## Description
 We chose not to implement the `cp` feature in `podman` even though the upstream Docker
diff --git a/docs/podman-create.1.md b/docs/podman-create.1.md
index 117a076a6..bf2f8b4c2 100644
--- a/docs/podman-create.1.md
+++ b/docs/podman-create.1.md
@@ -1,11 +1,13 @@
 % podman(1) podman-create - Create a new container
 % Dan Walsh
-podman-create - Create a new container
 
-# SYNOPSIS
+## NAME
+podman create - Create a new container
+
+## SYNOPSIS
 **podman create** [*options* [...]] IMAGE [COMMAND] [ARG...]
 
-# DESCRIPTION
+## DESCRIPTION
 
 Creates a writeable container layer over the specified image and prepares it for
 running the specified command. The container ID is then printed to STDOUT. This
@@ -15,7 +17,7 @@ any point.
 
 The initial status of the container created with **podman create** is 'created'.
 
-# OPTIONS
+## OPTIONS
 **--add-host**=[]
    Add a custom host-to-IP mapping (host:ip)
 
@@ -561,9 +563,9 @@ the `nocopy` flag. The `nocopy` flag can be set on bind mounts and named volumes
 The image developer can set a different default with the WORKDIR instruction. The operator
 can override the working directory by using the **-w** option.
 
-# EXAMPLES
+## EXAMPLES
 
-# HISTORY
+## HISTORY
 August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
 September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
 November 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
diff --git a/docs/podman-exec.1.md b/docs/podman-exec.1.md
index aa8d36a96..a9795002e 100644
--- a/docs/podman-exec.1.md
+++ b/docs/podman-exec.1.md
@@ -3,7 +3,7 @@
 # podman-exec "1" "December 2017" "podman"
 
 ## NAME
-podman-exec - Execute a command in a running container
+podman exec - Execute a command in a running container
 
 ## SYNOPSIS
 **podman exec**
diff --git a/docs/podman-export.1.md b/docs/podman-export.1.md
index 5652c245b..ae6e6024c 100644
--- a/docs/podman-export.1.md
+++ b/docs/podman-export.1.md
@@ -3,7 +3,7 @@
 # podman-export "1" "July 2017" "podman"
 
 ## NAME
-podman-export - Export container's filesystem contents as a tar archive
+podman export - Export container's filesystem contents as a tar archive
 
 ## SYNOPSIS
 **podman export**
diff --git a/docs/podman-history.1.md b/docs/podman-history.1.md
index f4a089b3c..0a07be699 100644
--- a/docs/podman-history.1.md
+++ b/docs/podman-history.1.md
@@ -3,7 +3,7 @@
 % podman-history "1" "JULY 2017" "podman"
 
 ## NAME
-podman-history - Shows the history of an image
+podman history - Shows the history of an image
 
 ## SYNOPSIS
 **podman history**
diff --git a/docs/podman-import.1.md b/docs/podman-import.1.md
index f90b82a89..a789bdbfc 100644
--- a/docs/podman-import.1.md
+++ b/docs/podman-import.1.md
@@ -3,7 +3,7 @@
 # podman-import "1" "November 2017" "podman"
 
 ## NAME
-podman-import - import a tarball and save it as a filesystem image
+podman import - Import a tarball and save it as a filesystem image
 
 ## SYNOPSIS
 **podman import**
diff --git a/docs/podman-info.1.md b/docs/podman-info.1.md
index 09c46d7f9..f3e3bc63f 100644
--- a/docs/podman-info.1.md
+++ b/docs/podman-info.1.md
@@ -3,7 +3,7 @@
 % podman-version "1" "JULY 2017" "podman"
 
 ## NAME
-podman-info - Display system information
+podman info - Display system information
 
 
 ## SYNOPSIS
diff --git a/docs/podman-load.1.md b/docs/podman-load.1.md
index 80210d547..4b0cf4017 100644
--- a/docs/podman-load.1.md
+++ b/docs/podman-load.1.md
@@ -3,7 +3,7 @@
 # podman-load "1" "July 2017" "podman"
 
 ## NAME
-podman-load - Load an image from docker archive
+podman load - Load an image from docker archive
 
 ## SYNOPSIS
 **podman load**
diff --git a/docs/podman-login.1.md b/docs/podman-login.1.md
index 2b136789e..180cdd45e 100644
--- a/docs/podman-login.1.md
+++ b/docs/podman-login.1.md
@@ -3,7 +3,7 @@
 # podman-login "1" "August 2017" "podman"
 
 ## NAME
-podman-login - Login to a container registry
+podman login - Login to a container registry
 
 ## SYNOPSIS
 **podman login**
diff --git a/docs/podman-logout.1.md b/docs/podman-logout.1.md
index 7fa6c728d..d6281500b 100644
--- a/docs/podman-logout.1.md
+++ b/docs/podman-logout.1.md
@@ -3,7 +3,7 @@
 # podman-logout "1" "August 2017" "podman"
 
 ## NAME
-podman-logout - Logout of a container registry
+podman logout - Logout of a container registry
 
 ## SYNOPSIS
 **podman logout**
diff --git a/docs/podman-ps.1.md b/docs/podman-ps.1.md
index 493a11465..11c3aabaf 100644
--- a/docs/podman-ps.1.md
+++ b/docs/podman-ps.1.md
@@ -3,7 +3,7 @@
 % podman-ps "1" "AUGUST 2017" "podman"
 
 ## NAME
-podman-ps - Prints out information about containers
+podman ps - Prints out information about containers
 
 ## SYNOPSIS
 **podman ps**
diff --git a/docs/podman-pull.1.md b/docs/podman-pull.1.md
index ccb2248fb..b1212ee6b 100644
--- a/docs/podman-pull.1.md
+++ b/docs/podman-pull.1.md
@@ -3,7 +3,7 @@
 # podman-pull "1" "July 2017" "podman"
 
 ## NAME
-podman-pull - Pull an image from a registry
+podman pull - Pull an image from a registry
 
 ## SYNOPSIS
 **podman pull**
diff --git a/docs/podman-run.1.md b/docs/podman-run.1.md
index 19e73aea2..0431478e4 100644
--- a/docs/podman-run.1.md
+++ b/docs/podman-run.1.md
@@ -1,11 +1,13 @@
 % podman(1) podman-run - Run a command in a container
 % Dan Walsh
-podman-run - Run a command in a new container
 
-# SYNOPSIS
+## NAME
+podman run - Run a command in a new container
+
+## SYNOPSIS
 **podman run** [*options* [...]] IMAGE [COMMAND] [ARG...]
 
-# DESCRIPTION
+## DESCRIPTION
 
 Run a process in a new container. **podman run** starts a process with its own
 file system, its own networking, and its own isolated process tree. The IMAGE
@@ -19,7 +21,7 @@ If the IMAGE is not already loaded then **podman run** will pull the IMAGE, and
 all image dependencies, from the repository in the same way running **podman
 pull** IMAGE, before it starts the container from that image.
 
-# OPTIONS
+## OPTIONS
 **--add-host**=[]
    Add a custom host-to-IP mapping (host:ip)
 
@@ -598,9 +600,9 @@ the exit codes follow the `chroot` standard, see below:
     $ podman run busybox /bin/sh -c 'exit 3'
     # 3
 
-# EXAMPLES
+## EXAMPLES
 
-## Running container in read-only mode
+### Running container in read-only mode
 
 During container image development, containers often need to write to the image
 content.  Installing packages into /usr, for example.  In production,
@@ -613,7 +615,7 @@ tmpfs directories on /run and /tmp.
 
     # podman run --read-only --tmpfs /run --tmpfs /tmp -i -t fedora /bin/bash
 
-## Exposing log messages from the container to the host's log
+### Exposing log messages from the container to the host's log
 
 If you want messages that are logged in your container to show up in the host's
 syslog/journal then you should bind mount the /dev/log directory as follows.
@@ -632,7 +634,7 @@ Then exit and check the journal.
 
 This should list the message sent to logger.
 
-## Attaching to one or more from STDIN, STDOUT, STDERR
+### Attaching to one or more from STDIN, STDOUT, STDERR
 
 If you do not specify -a then podman will attach everything (stdin,stdout,stderr)
 . You can specify to which of the three standard streams (stdin, stdout, stderr)
@@ -705,7 +707,7 @@ Create a 3rd container using the new --ipc=container:CONTAINERID option, now it
  0x0000162e 0          root       666        27         1
 ```
 
-## Mapping Ports for External Usage
+### Mapping Ports for External Usage
 
 The exposed port of an application can be mapped to a host port using the **-p**
 flag. For example, an httpd port 80 can be mapped to the host port 8080 using the
@@ -713,7 +715,7 @@ following:
 
     # podman run -p 8080:80 -d -i -t fedora/httpd
 
-## Mounting External Volumes
+### Mounting External Volumes
 
 To mount a host directory as a container volume, specify the absolute path to
 the directory and the absolute path for the container directory separated by a
@@ -737,7 +739,7 @@ to the host directory:
 Now, writing to the /data1 volume in the container will be allowed and the
 changes will also be reflected on the host in /var/db.
 
-## Using alternative security labeling
+### Using alternative security labeling
 
 You can override the default labeling scheme for each container by specifying
 the `--security-opt` flag. For example, you can specify the MCS/MLS level, a
@@ -766,7 +768,7 @@ Note:
 
 You would have to write policy defining a `svirt_apache_t` type.
 
-## Setting device weight
+### Setting device weight
 
 If you want to set `/dev/sda` device weight to `200`, you can specify the device
 weight by `--blkio-weight-device` flag. Use the following command:
@@ -777,7 +779,7 @@ weight by `--blkio-weight-device` flag. Use the following command:
 $ podman run -d busybox top
 ```
 
-## Setting Namespaced Kernel Parameters (Sysctls)
+### Setting Namespaced Kernel Parameters (Sysctls)
 
 The `--sysctl` sets namespaced kernel parameters (sysctls) in the
 container. For example, to turn on IP forwarding in the containers
@@ -794,7 +796,7 @@ evolves we expect to see more sysctls become namespaced.
 See the definition of the `--sysctl` option above for the current list of
 supported sysctls.
 
-# HISTORY
+## HISTORY
 April 2014, Originally compiled by William Henry (whenry at redhat dot com)
 based on docker.com source material and internal work.
 June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
diff --git a/docs/podman-save.1.md b/docs/podman-save.1.md
index e55ea1c9b..280073e74 100644
--- a/docs/podman-save.1.md
+++ b/docs/podman-save.1.md
@@ -3,7 +3,7 @@
 # podman-save "1" "July 2017" "podman"
 
 ## NAME
-podman-save - Save an image to docker-archive or oci-archive
+podman save - Save an image to docker-archive or oci-archive
 
 ## SYNOPSIS
 **podman save**
diff --git a/docs/podman-stats.1.md b/docs/podman-stats.1.md
index 80d061cb2..6d050b485 100644
--- a/docs/podman-stats.1.md
+++ b/docs/podman-stats.1.md
@@ -3,7 +3,7 @@
 # podman-stats "1" "July 2017" "podman"
 
 ## NAME
-podman-stats - Display a live stream of 1 or more containers' resource usage statistics
+podman stats - Display a live stream of 1 or more containers' resource usage statistics
 
 ## SYNOPSIS
 **podman** **stats** [*options* [...]] [container]
diff --git a/docs/podman-version.1.md b/docs/podman-version.1.md
index e6dba33fc..8978da630 100644
--- a/docs/podman-version.1.md
+++ b/docs/podman-version.1.md
@@ -3,7 +3,7 @@
 # podman-version "1" "July 2017" "podman"
 
 ## NAME
-podman-version - Display the PODMAN Version Information
+podman version - Display the PODMAN Version Information
 
 ## SYNOPSIS
 **podman version**
diff --git a/docs/podman.1.md b/docs/podman.1.md
index be35c506d..ad9138a1d 100644
--- a/docs/podman.1.md
+++ b/docs/podman.1.md
@@ -55,6 +55,9 @@ has the capability to debug pods/images created by crio.
 ### attach
 Attach to a running container
 
+### commit
+Create new image based on the changed container
+
 ### create
 create a new container
 
@@ -109,9 +112,6 @@ Pull an image from a registry
 ### push
 Push an image from local storage to elsewhere
 
-### rename
-Rename a container
-
 ### rm
 Remove one or more containers
 
diff --git a/transfer.md b/transfer.md
index b72f0a584..1a2820cf3 100644
--- a/transfer.md
+++ b/transfer.md
@@ -23,29 +23,31 @@ For many troubleshooting and information collection steps, there may be an exist
 Following provides equivalent with PODMAN tools for gathering information or jumping into containers, for operational use.
 
 | Existing Step | PODMAN (and friends) |
-| :---: | :---: |
+| :--- | :--- |
+| `docker run`  | [`podman run`](./docs/podman-run.1.md) |
 | `docker exec` | [`podman exec`](./docs/podman-exec.1.md) |
 | `docker info` | [`podman info`](./docs/podman-info.1.md)  |
 | `docker inspect` | [`podman inspect`](./docs/podman-inspect.1.md)       |
 | `docker logs` | [`podman logs`](./docs/podman-logs.1.md)                 |
-| `docker ps` | [`podman ps`](./docs/podman-ps.1.md) |
-| `docker stats` | [`podman stats`](./docs/podman-stats.1.md)|
+| `docker ps`   | [`podman ps`](./docs/podman-ps.1.md) |
+| `docker stats`| [`podman stats`](./docs/podman-stats.1.md)|
 
 ## Development Transfer
 
 There are other equivalents for these tools
 
 | Existing Step | PODMAN (and friends) |
-| :---: | :---: |
-| `docker attach` | [`podman exec`](./docs/podman-attach.1.md) ***|
+| :--- | :--- |
+| `docker attach` | [`podman exec`](./docs/podman-attach.1.md)|
 | `docker build`  | [`buildah bud`](https://github.com/projectatomic/buildah/blob/master/docs/buildah-bud.md) |
-| `docker commit` | [`buildah commit`](https://github.com/projectatomic/buildah/blob/master/docs/buildah-commit.md) |
+| `docker commit` | [`podman commit`](./docs/podman-commit.1.md)|
 | `docker cp`     | [`podman mount`](./docs/podman-cp.1.md) ****   |
 | `docker create` | [`podman create`](./docs/podman-create.1.md)  |
 | `docker diff`   | [`podman diff`](./docs/podman-diff.1.md)      |
 | `docker export` | [`podman export`](./docs/podman-export.1.md)  |
 | `docker history`| [`podman history`](./docs/podman-history.1.md)|
 | `docker images` | [`podman images`](./docs/podman-images.1.md)  |
+| `docker import` | [`podman import`](./docs/podman-import.1.md)  |
 | `docker kill`   | [`podman kill`](./docs/podman-kill.1.md)      |
 | `docker load`   | [`podman load`](./docs/podman-load.1.md)      |
 | `docker login`  | [`podman login`](./docs/podman-login.1.md)    |
@@ -58,36 +60,38 @@ There are other equivalents for these tools
 | `docker rmi`    | [`podman rmi`](./docs/podman-rmi.1.md)        |
 | `docker run`    | [`podman run`](./docs/podman-run.1.md)        |
 | `docker save`   | [`podman save`](./docs/podman-save.1.md)      |
+| `docker start`  | [`podman start`](./docs/podman-start.1.md)    |
 | `docker stop`   | [`podman stop`](./docs/podman-stop.1.md)      |
 | `docker tag`    | [`podman tag`](./docs/podman-tag.1.md)        |
+| `docker top`    | [`podman top`](./docs/podman-top.1.md)        |
 | `docker unpause`| [`podman unpause`](./docs/podman-unpause.1.md)|
 | `docker version`| [`podman version`](./docs/podman-version.1.md)|
 | `docker wait`   | [`podman wait`](./docs/podman-wait.1.md)   |
 
-*** Use `podman exec` to enter a container and `podman logs` to view the output of pid 1 of a container.
 **** Use mount to take advantage of the entire linux tool chain rather then just cp.  Read [`here`](./docs/podman-cp.1.md) for more information.
 
 ## Missing commands in podman
 
 Those Docker commands currently do not have equivalents in `podman`:
 
- * `docker container`
- * `docker events`
- * `docker image`
- * `docker network`
- * `docker node`
- * `docker plugin`
- * `docker port`
- * `docker rename`
- * `docker restart`
- * `docker search`
- * `docker secret`
- * `docker service`
- * `docker stack`
- * `docker swarm`
- * `docker system`
- * `docker top`
- * `docker volume`
+| Missing command | Description|
+| :--- | :--- |
+| `docker container`||
+| `docker events`   ||
+| `docker image`    ||
+| `docker network`  ||
+| `docker node`     ||
+| `docker plugin`   |podman does not support plugins.  We recommend you use alternative OCI Runtimes or OCI Runtime Hooks to alter behaviour of podman.|
+| `docker port`     ||
+| `docker rename`   | podman does not support rename, you need to use `podman rm` and  `podman create` to rename a container.|
+| `docker restart`  | podman does not support restart.  We recommend that you put your podman containers into a systemd unit file and use it for restarting applications.|
+| `docker search`   ||
+| `docker secret`   ||
+| `docker service`  ||
+| `docker stack`    ||
+| `docker swarm`    | podman does not support swarm.  We support Kubernetes for orchestration using [CRI-O](https://github.com/kubernetes-incubator/cri-o).|
+| `docker system`   ||
+| `docker volume`   | podman does not support volumes.  Volumes should be built on the host operating system and then volume mounted into the containers.|
 
 ## Missing commands in Docker