diff --git a/README.md b/README.md
index 090088b9..d424b50d 100644
--- a/README.md
+++ b/README.md
@@ -8,10 +8,10 @@ Note: this package is in alpha.
 
 The buildah package provides a command line tool which can be used to
 * create a working container, either from scratch or using an image as a starting point
-* mount the working container's root filesystem for manipulation
-* unmount the working container's root filesystem
-* use the updated contents of the container's root filesystem as a filesystem layer to create a new image
-* delete a working container
+* mount a working container's root filesystem for manipulation
+* unmount a working container's root filesystem
+* use the updated contents of a container's root filesystem as a filesystem layer to create a new image
+* delete a working container or an image
 
 **Installation notes**
 
diff --git a/docs/buildah-add.md b/docs/buildah-add.md
index 107fea52..e8763eec 100644
--- a/docs/buildah-add.md
+++ b/docs/buildah-add.md
@@ -1,23 +1,31 @@
-## buildah-add "March 2017"
+## buildah-add "1" "March 2017" "buildah"
 
 ## NAME
-buildah add - Add the contents of a file, URL, or a directory to the container. 
-
+buildah add - Add the contents of a file, URL, or a directory to a container.
 
 ## SYNOPSIS
-**buildah** **add** **containerID** **SRC** [**DEST**] 
+**buildah** **add** **containerID** **SRC** [[...] **DEST**]
 
 ## DESCRIPTION
-Adds the contents of a file, URL, or a directory to a container's working directory.  If a local file appears to be an archive, its contents are extracted and added instead of the archive file itself.  If a destination is not specified, the location of the source will be used for the destination.  
+Adds the contents of a file, URL, or a directory to a container's working
+directory or a specified location in the container.  If a local source file
+appears to be an archive, its contents are extracted and added instead of the
+archive file itself.  If a local directory is specified as a source, its
+*contents* are copied to the destination.
 
 ## EXAMPLE
-**buildah add containerID '/myapp/app.conf' '/myapp/app.conf' **
-**buildah add containerID '/home/myuser/myproject.go' **
-**buildah add containerID '/home/myuser/myfiles.tar' '/tmp' **
-**buildah add containerID '/tmp/workingdir' '/tmp/workingdir' **
-**buildah add containerID 'https://github.com/projectatomic/buildah' '/tmp' **
-**buildah add containerID 'passwd' 'certs.d' /etc **
+
+buildah add containerID '/myapp/app.conf' '/myapp/app.conf'
+
+buildah add containerID '/home/myuser/myproject.go'
+
+buildah add containerID '/home/myuser/myfiles.tar' '/tmp'
+
+buildah add containerID '/tmp/workingdir' '/tmp/workingdir'
+
+buildah add containerID 'https://github.com/projectatomic/buildah/blob/master/README.md' '/tmp'
+
+buildah add containerID 'passwd' 'certs.d' /etc
 
 ## SEE ALSO
 buildah(1)
-
diff --git a/docs/buildah-commit.md b/docs/buildah-commit.md
index 99d27ba5..d78cbc89 100644
--- a/docs/buildah-commit.md
+++ b/docs/buildah-commit.md
@@ -1,27 +1,37 @@
-## buildah-commit "March 2017"
+## buildah-commit "1" "March 2017" "buildah"
 
 ## NAME
-buildah commit - Create an image from a working container. 
-
+buildah commit - Create an image from a working container.
 
 ## SYNOPSIS
-**buildah** **commit** **containerID** [*command options* [...]] 
+**buildah** **commit** [*options* [...]] **containerID** [**imageName**]
 
 ## DESCRIPTION
-Writes a new image using the container's read-write layer and if it is based on an image, the layers of that image are written.
+Writes a new image using the specified container's read-write layer and if it
+is based on an image, the layers of that image.  If an image name is not
+specified, an ID is assigned, but no name is assigned to the image.
 
 ## OPTIONS
 
 **--disable-compression**
-Don't compress the layers.
 
-**--signature-policy
-Pathname of the signature policy file to use.  This option is generally not recommended for use. 
+Don't compress filesystem layers when building the image.
+
+**--signature-policy**
+
+Pathname of a signature policy file to use.  It is not recommended that this
+option be used, as the default behavior of using the system-wide default policy
+(frequently */etc/containers/policy.json*) is most often preferred.
 
 ## EXAMPLE
-**buildah commit containerID **
-**buildah commit containerID --disable-compression --signature-policy '/etc/containers/policy.json' **
+
+buildah commit containerID
+
+buildah commit containerID newImageName
+
+buildah commit --disable-compression --signature-policy '/etc/containers/policy.json' containerID
+
+buildah commit --disable-compression --signature-policy '/etc/containers/policy.json' containerID newImageName
 
 ## SEE ALSO
 buildah(1)
-
diff --git a/docs/buildah-config.md b/docs/buildah-config.md
index 3bfb8860..722fa959 100644
--- a/docs/buildah-config.md
+++ b/docs/buildah-config.md
@@ -1,60 +1,91 @@
-## buildah-config "March 2017"
+## buildah-config "1" "March 2017" "buildah"
 
 ## NAME
-buildah config - Update image configuration settings. 
-
+buildah config - Update image configuration settings.
 
 ## SYNOPSIS
-**buildah** **config** **containerID** [*command options* [...]] 
+**buildah** **config** [*options* [...]] **containerID**
 
 ## DESCRIPTION
-Update a number of the image's configuration settings such as the
-name, author, label and more. 
+Updates one or more of the settings kept for a container.
 
 ## OPTIONS
 
-**--annotation *annotation* **
-Image *annotation* e.g. annotation=*annotation*, for the target image
+**--annotation** *annotation*
 
-**--arch *architecture* **
-*architecture* of the target image
+Adds an image *annotation* (e.g. annotation=*annotation*) to the image manifest
+of any images which will be built using the specified container.
 
-**--author *author* **
-Image *author* contact information
+**--arch** *architecture*
 
-**--cmd *command* **
-*command* for containers based on image
+Specify the target *architecture* for any images which will be built using the
+specified container.  By default, if the container was based on an image, that
+image's target architecture is kept, otherwise the host's architecture is
+recorded.
 
-**--created-by *created* **dd
-Description of how the image was *created* (default: "manual edits")
+**--author** *author*
 
-**--entrypoint *entry* **
-*entry* point for containers based on image
+Sets contact information for the *author* for any images which will be built
+using the specified container.
 
-**--env *envar* **
-Environment variable (*envar*) to set when running containers based on image
+**--cmd** *command*
 
-**--label *label* **
-Image configuration *label* e.g. label=*label*
+Sets the default *command* to run for containers based on any images which will
+be built using the specified container.  When used in combination with an
+*entry point*, this specifies the default parameters for the *entry point*.
 
-**--os *operating system* **
-Image target *operating system*
+**--created-by** *created*
 
-**--port *port* **
-*port* to expose when running containers based on image
+Set the description of how the read-write layer *created* (default: "manual
+edits") in any images which will be created using the specified container.
 
-**--user *user* **
-*user* to run containers based on image as
+**--entrypoint** *entry*
 
-**--volume *volume* **
-*volume* to create for containers based on image
+Sets the *entry point* for containers based on any images which will be built
+using the specified container.
 
-**--workingdir *directory* **
-Initial working *directory* for containers based on image
+**--env** *var=value*
+
+Adds a value (e.g. name=*value*) to the environment for containers based on any
+images which will be built using the specified container.
+
+**--label** *label*
+
+Adds an image *label* (e.g. label=*value*) to the image configuration of any
+images which will be built using the specified container.
+
+**--os** *operating system*
+
+Specify the target *operating system* for any images which will be built using
+the specified container.  By default, if the container was based on an image,
+its OS is kept, otherwise the host's OS's name is recorded.
+
+**--port** *port*
+
+Specifies a *port* to expose when running containers based on any images which
+will be built using the specified container.
+
+**--user** *user*
+
+Specify the *user* as whom containers based on images which will be built using
+the specified container should run.  The user can be specified as a user name
+or UID, optionally followed by a group name or GID, separated by a colon (':').
+If names are used, the container should include entries for those names in its
+*/etc/passwd* and */etc/group* files.
+
+**--volume** *volume*
+
+Specifies a location in the directory tree which should be marked as a *volume*
+in any images which will be built using the specified container.
+
+**--workingdir** *directory*
+
+Sets the initial working *directory* for containers based on images which will
+be built using the specified container.
 
 ## EXAMPLE
-**buildah config containerID --author='Jane Austen' --workingdir='/etc/mycontainers' **
+
+buildah config --author='Jane Austen' --workingdir='/etc/mycontainers' containerID
 
 ## SEE ALSO
 buildah(1)
-
diff --git a/docs/buildah-containers.md b/docs/buildah-containers.md
index b3d97689..d6d11d6b 100644
--- a/docs/buildah-containers.md
+++ b/docs/buildah-containers.md
@@ -1,30 +1,36 @@
-## buildah-containers "March 2017"
+## buildah-containers "1" "March 2017" "buildah"
 
 ## NAME
-buildah containers - List the working containers and their base images. 
-
+buildah containers - List the working containers and their base images.
 
 ## SYNOPSIS
-**buildah** **containers** [*options* [...]] 
+**buildah** **containers** [*options* [...]]
 
 ## DESCRIPTION
-Lists containers which appear to be buildah working containers, their names and IDs, and the names and IDs of the images from which they were initialized.
+Lists containers which appear to be buildah working containers, their names and
+IDs, and the names and IDs of the images from which they were initialized.
 
 ## OPTIONS
 
-**--noheading, -n **
+**--noheading, -n**
+
 Omit the table headings from the listing of containers.
 
 **--notruncate**
-Do not truncate output.
 
-**--quiet, -q **
-Displays only the container image id's.
+Do not truncate IDs in output.
+
+**--quiet, -q**
+
+Displays only the container IDs.
 
 ## EXAMPLE
-**buildah containers **
-**buildah containers --quiet **
-**buildah containers -q --noheading --notruncate **
+
+buildah containers
+
+buildah containers --quiet
+
+buildah containers -q --noheading --notruncate
 
 ## SEE ALSO
 buildah(1)
diff --git a/docs/buildah-copy.md b/docs/buildah-copy.md
index c72ac4be..a44925c5 100644
--- a/docs/buildah-copy.md
+++ b/docs/buildah-copy.md
@@ -1,25 +1,29 @@
-## buildah-copy "March 2017"
+## buildah-copy "1" "March 2017" "buildah"
 
 ## NAME
-buildah copy - Copies the contents of a file, URL, or directory into a container's working directory. 
-
+buildah copy - Copies the contents of a file, URL, or directory into a container's working directory.
 
 ## SYNOPSIS
-**buildah** **copy** containerID **SRC** [**DEST**] 
+**buildah** **copy** containerID **SRC** [[...] **DEST**]
 
 ## DESCRIPTION
-Copies the contents of a file, URL, or a directory to a container's working directory.  If a local file appears to be an archive, its contents are extracted and copied instead of the archive file itself.  If a destination is not specified, the location of the source will be used for the destination.  
-
-
+Copies the contents of a file, URL, or a directory to a container's working
+directory or a specified location in the container.  If a local directory is
+specified as a source, its *contents* are copied to the destination.
 
 ## EXAMPLE
-**buildah copy containerID '/myapp/app.conf' '/myapp/app.conf' **
-**buildah copy containerID '/home/myuser/myproject.go' **
-**buildah copy containerID '/home/myuser/myfiles.tar' '/tmp' **
-**buildah copy containerID '/tmp/workingdir' '/tmp/workingdir' **
-**buildah copy containerID 'https://github.com/projectatomic/buildah' '/tmp' **
-**buildah copy containerID 'passwd' 'certs.d' /etc **
+
+buildah copy containerID '/myapp/app.conf' '/myapp/app.conf'
+
+buildah copy containerID '/home/myuser/myproject.go'
+
+buildah copy containerID '/home/myuser/myfiles.tar' '/tmp'
+
+buildah copy containerID '/tmp/workingdir' '/tmp/workingdir'
+
+buildah copy containerID 'https://github.com/projectatomic/buildah' '/tmp'
+
+buildah copy containerID 'passwd' 'certs.d' /etc
 
 ## SEE ALSO
 buildah(1)
-
diff --git a/docs/buildah-from.md b/docs/buildah-from.md
index 2e778b50..b9c767ed 100644
--- a/docs/buildah-from.md
+++ b/docs/buildah-from.md
@@ -1,44 +1,56 @@
-## buildah-from "March 2017"
+## buildah-from "1" "March 2017" "buildah"
 
 ## NAME
-buildah from - Creates a new working container, either from scratch or using a specified image as a starting point. 
-
+buildah from - Creates a new working container, either from scratch or using a specified image as a starting point.
 
 ## SYNOPSIS
-**buildah** **from** *imagename* [*options* [...]] 
+**buildah** **from** [*options* [...]] *imageName*
 
 ## DESCRIPTION
-Creates a working container based upon the supplied image name.  If the supplied image name is "scratch" a new default container will be created.
+Creates a working container based upon the specified image name.  If the
+supplied image name is "scratch" a new empty container is created.
 
 ## RETURN VALUE
-The container id of the container that was created.  On error, -1 is returned and errno is returned. 
+The container ID of the container that was created.  On error, -1 is returned and errno is returned.
 
 ## OPTIONS
 
-**--mount** 
+**--mount**
+
 Mount the working container printing the mount point upon successful completion.
 
 **--name** *name*
+
 A *name* for the working container
 
 **--pull**
-Pull the image if it is not present.  If this flag is not specified,the image will not be pulled regardless.  Defaults to TRUE.
 
-**--pull-always** 
+Pull the image if it is not present.  If this flag is disabled (with
+*--pull=false*) and the image is not present, the image will not be pulled.
+Defaults to *true*.
+
+**--pull-always**
+
 Pull the image even if a version of the image is already present.
 
 **--registry** *registry*
-A prefix to prepend to the image name in order to pull the image.  Default value is "docker://"
+
+A prefix to prepend to the image name in order to pull the image.  Default
+value is "docker://"
 
 **--signature-policy** *signaturepolicy*
-The path of the for the signature policy file.  The default location is */etc/containers/policy.json* and changing to another file is not recommended.
 
+Pathname of a signature policy file to use.  It is not recommended that this
+option be used, as the default behavior of using the system-wide default policy
+(frequently */etc/containers/policy.json*) is most often preferred.
 
 ## EXAMPLE
-**buildah from imagename --pull --registry "myregistry://" --mount **
-**buildah from imagename --signature-policy /etc/containers/policy.json **
-**buildah from imagename --pull-always --registry "myregistry://" --name "mycontainer" **
+
+buildah from imagename --pull --registry "myregistry://" --mount
+
+buildah from imagename --signature-policy /etc/containers/policy.json
+
+buildah from imagename --pull-always --registry "myregistry://" --name "mycontainer"
 
 ## SEE ALSO
 buildah(1)
-
diff --git a/docs/buildah-images.md b/docs/buildah-images.md
index a092e8f8..a7589760 100644
--- a/docs/buildah-images.md
+++ b/docs/buildah-images.md
@@ -1,31 +1,35 @@
-## buildah-images "March 2017"
+## buildah-images "1" "March 2017" "buildah"
 
 ## NAME
-buildah images - List images in local storage. 
-
+buildah images - List images in local storage.
 
 ## SYNOPSIS
-**buildah** **images** [*options* [...]] 
+**buildah** **images** [*options* [...]]
 
 ## DESCRIPTION
-Displays locally stored images, their names and IDs, and the names and IDs of the containers.
+Displays locally stored images, their names, and their IDs.
 
 ## OPTIONS
 
-**--nodheading, -n **
+**--noheading, -n**
+
 Omit the table headings from the listing of images.
 
 **--notruncate**
+
 Do not truncate output.
 
-**--quiet, -q **
-Lists only the container image id's.
+**--quiet, -q**
+
+Lists only the image IDs.
 
 ## EXAMPLE
-**buildah images **
-**buildah images --quiet **
-**buildah images -q --noheading --notruncate **
+
+buildah images
+
+buildah images --quiet
+
+buildah images -q --noheading --notruncate
 
 ## SEE ALSO
 buildah(1)
-
diff --git a/docs/buildah-mount.md b/docs/buildah-mount.md
index 068c0b53..c0616ced 100644
--- a/docs/buildah-mount.md
+++ b/docs/buildah-mount.md
@@ -1,22 +1,22 @@
-## buildah-mount "March 2017"
+## buildah-mount "1" "March 2017" "buildah"
 
 ## NAME
-buildah mount - Mount the working container's root filesystem.
-
+buildah mount - Mount a working container's root filesystem.
 
 ## SYNOPSIS
-**buildah** **mount** **containerID** 
+**buildah** **mount** **containerID**
 
 ## DESCRIPTION
-Mount the container's root file system in a location which can be accessed from the host, and returns the location.
+Mounts the specified container's root file system in a location which can be
+accessed from the host, and returns its location.
 
 ## RETURN VALUE
-The location of the mounted file system.  On error an empty string and errno is returned. 
+The location of the mounted file system.  On error an empty string and errno is
+returned.
 
 ## EXAMPLE
-**buildah mount containerID **
-**mountFS=buildah mount containerID **
+
+buildah mount containerID
 
 ## SEE ALSO
 buildah(1)
-
diff --git a/docs/buildah-rm.md b/docs/buildah-rm.md
index 9fdc2ba6..7ccacf50 100644
--- a/docs/buildah-rm.md
+++ b/docs/buildah-rm.md
@@ -1,19 +1,19 @@
-## buildah-rm "March 2017"
+## buildah-rm "1" "March 2017" "buildah"
 
 ## NAME
-buildah rm - Removes one or more working containers. 
-
+buildah rm - Removes one or more working containers.
 
 ## SYNOPSIS
-**buildah** **rm** **containerID(s)** 
+**buildah** **rm** **containerID [...]**
 
 ## DESCRIPTION
-Removes a working container or containers unmounting them if necessary.  Multiple containers are space separated.  If multiple containers are passed to this command and the removal fails on one, the containers following that container will not be removed. 
+Removes one or more working containers, unmounting them if necessary.
 
 ## EXAMPLE
-**buildah delete containerID **
-**buildah delete containerID1 containerID2 containerID3 **
+
+buildah rm containerID
+
+buildah rm containerID1 containerID2 containerID3
 
 ## SEE ALSO
 buildah(1)
-
diff --git a/docs/buildah-rmi.md b/docs/buildah-rmi.md
index 8e5de245..c75052e4 100644
--- a/docs/buildah-rmi.md
+++ b/docs/buildah-rmi.md
@@ -1,19 +1,19 @@
-## buildah-rmi "March 2017"
+## buildah-rmi "1" "March 2017" "buildah"
 
 ## NAME
-buildah rmi - Removes one or more images. 
-
+buildah rmi - Removes one or more images.
 
 ## SYNOPSIS
-**buildah** **rmi** **imageID(s)** 
+**buildah** **rmi** **imageID [...]**
 
 ## DESCRIPTION
-Removes a locally stored image or images.  Multiple images are space separated.  If multiple images are passed to this command and the removal fails on one, the images following that image will not be removed.   
+Removes one or more locally stored images.
 
 ## EXAMPLE
-**buildah rmi imageID **
-**buildah rmi imageID1 imageID2 imageID3 **
+
+buildah rmi imageID
+
+buildah rmi imageID1 imageID2 imageID3
 
 ## SEE ALSO
 buildah(1)
-
diff --git a/docs/buildah-run.md b/docs/buildah-run.md
index 8f2c8ceb..82cdf7f2 100644
--- a/docs/buildah-run.md
+++ b/docs/buildah-run.md
@@ -1,27 +1,32 @@
-## buildah-run "March 2017"
+## buildah-run "1" "March 2017" "buildah"
 
 ## NAME
-buildah run - Run a command inside of the container. 
-
+buildah run - Run a command inside of the container.
 
 ## SYNOPSIS
-**buildah** **run** **containerID** [*command options* [...]] 
+**buildah** **run** **containerID** [*options* [...] --] **command**
 
 ## DESCRIPTION
-Launches a container and runs the specified command in that container using the container's root filesystem as a root filesystem, using configuration settings inherited from the container's image or as specified using previous calls to the buildah-config command.
+Launches a container and runs the specified command in that container using the
+container's root filesystem as a root filesystem, using configuration settings
+inherited from the container's image or as specified using previous calls to
+the *buildah config* command.
 
 ## OPTIONS
 
-**--runtime**
+**--runtime** *path*
+
 The *path* to an alternate runtime.
 
-**--runtime-flag**
-Adds global flags for the containter rutime.
+**--runtime-flag** *flag*
 
+Adds global flags for the container rutime.
 
 ## EXAMPLE
-**buildah run containerID 'ps -auxw' **
+
+buildah run containerID 'ps -auxw'
+
+buildah run containerID --runtime-flag --no-new-keyring 'ps -auxw'
 
 ## SEE ALSO
 buildah(1)
-
diff --git a/docs/buildah-umount.md b/docs/buildah-umount.md
index 3c815a9c..6e2ea1c6 100644
--- a/docs/buildah-umount.md
+++ b/docs/buildah-umount.md
@@ -1,19 +1,17 @@
-## buildah-umount "March 2017"
+## buildah-umount "1" "March 2017" "buildah"
 
 ## NAME
-buildah umount - Unmount a working container's root file system. 
-
+buildah umount - Unmount a working container's root file system.
 
 ## SYNOPSIS
-**buildah** **umount** **containerID**  
+**buildah** **umount** **containerID**
 
 ## DESCRIPTION
 Unmounts the specified container's root file system.
 
-
 ## EXAMPLE
-**buildah umount containerID **
+
+buildah umount containerID
 
 ## SEE ALSO
 buildah(1)
-
diff --git a/docs/buildah.md b/docs/buildah.md
index b3124dde..cba96bd5 100644
--- a/docs/buildah.md
+++ b/docs/buildah.md
@@ -1,18 +1,17 @@
-## buildah "March 2017"
+## buildah "1" "March 2017" "buildah"
 
 ## NAME
-buildah - A command line tool to facilitate working with containers and their images. 
-
+buildah - A command line tool to facilitate working with containers and using them to build images.
 
 ## DESCRIPTION
 The buildah package provides a command line tool which can be used to:
 
     * Create a working container, either from scratch or using an image as a starting point.
-    * Mount the working container's root filesystem for manipulation.
-    * Unmount the working container's root filesystem.
-    * Use the updated contents of the container's root filesystem as a filesystem layer to create a new image.
-    * Delete a working container or it's image.
- 
+    * Mount a working container's root filesystem for manipulation.
+    * Unmount a working container's root filesystem.
+    * Use the updated contents of a container's root filesystem as a filesystem layer to create a new image.
+    * Delete a working container or an image.
+
 ## SEE ALSO
 | Command               | Description |
 | --------------------- | --------------------------------------------------- |