normalized descriptions for most man pages

also removed the intermediate man page
added intermidieate manpages to gitignore

13 files changed, 227 insertions, 1221 deletions

diff --git a/.gitignore b/.gitignore
index 5d3970a168..01a802805e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,6 +19,12 @@ rpm-build
 # Mac OS X stuff...
 .DS_Store
 # manpage build stuff...
+docs/man/man1/ansible.1
+docs/man/man1/ansible-doc.1
+docs/man/man1/ansible-galaxy.1
+docs/man/man1/ansible-playbook.1
+docs/man/man1/ansible-pull.1
+docs/man/man1/ansible-vault.1
 docs/man/man3/*
 # Sublime stuff
 *.sublime-project
diff --git a/docs/man/man1/ansible-doc.1 b/docs/man/man1/ansible-doc.1
deleted file mode 100644
index 2d5068d0d3..0000000000
--- a/docs/man/man1/ansible-doc.1
+++ /dev/null
@@ -1,66 +0,0 @@
-'\" t
-.\"     Title: ansible-doc
-.\"    Author: :doctype:manpage
-.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 12/09/2014
-.\"    Manual: System administration commands
-.\"    Source: Ansible 1.9
-.\"  Language: English
-.\"
-.TH "ANSIBLE\-DOC" "1" "12/09/2014" "Ansible 1\&.9" "System administration commands"
-.\" -----------------------------------------------------------------
-.\" * Define some portability stuff
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" http://bugs.debian.org/507673
-.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.ie \n(.g .ds Aq \(aq
-.el       .ds Aq '
-.\" -----------------------------------------------------------------
-.\" * set default formatting
-.\" -----------------------------------------------------------------
-.\" disable hyphenation
-.nh
-.\" disable justification (adjust text to left margin only)
-.ad l
-.\" -----------------------------------------------------------------
-.\" * MAIN CONTENT STARTS HERE *
-.\" -----------------------------------------------------------------
-.SH "NAME"
-ansible-doc \- show documentation on Ansible modules
-.SH "SYNOPSIS"
-.sp
-ansible\-doc [\-M module_path] [\-l] [\-s] [module\&...]
-.SH "DESCRIPTION"
-.sp
-\fBansible\-doc\fR displays information on modules installed in Ansible libraries\&. It displays a terse listing of modules and their short descriptions, provides a printout of their DOCUMENTATION strings, and it can create a short "snippet" which can be pasted into a playbook\&.
-.SH "OPTIONS"
-.PP
-\fB\-M\fR \fIdirectory\fR, \fB\-\-module\-path=\fR\fIdirectory\fR
-.RS 4
-Add an additional directory to the default path for finding module libraries\&.
-.RE
-.PP
-\fB\-s\fR, \fB\-\-snippet=\fR
-.RS 4
-Produce a snippet which can be copied into a playbook for modification, like a kind of task template\&.
-.RE
-.PP
-\fB\-l\fR, \fB\-\-list=\fR
-.RS 4
-Produce a terse listing of modules and a short description of each\&.
-.RE
-.SH "AUTHOR"
-.sp
-ansible\-doc was originally written by Jan\-Piet Mens\&. See the AUTHORS file for a complete list of contributors\&.
-.SH "COPYRIGHT"
-.sp
-Copyright \(co 2012, Jan\-Piet Mens
-.sp
-Ansible is released under the terms of the GPLv3 License\&.
-.SH "SEE ALSO"
-.sp
-\fBansible\-playbook\fR(1), \fBansible\fR(1), \fBansible\-pull\fR(1)
-.sp
-Extensive documentation is available in the documentation site: http://docs\&.ansible\&.com\&. IRC and mailing list info can be found in file CONTRIBUTING\&.md, available in: https://github\&.com/ansible/ansible
diff --git a/docs/man/man1/ansible-doc.1.asciidoc.in b/docs/man/man1/ansible-doc.1.asciidoc.in
index 46d4c2fd26..f46db17b60 100644
--- a/docs/man/man1/ansible-doc.1.asciidoc.in
+++ b/docs/man/man1/ansible-doc.1.asciidoc.in
@@ -28,9 +28,11 @@ playbook.
 OPTIONS
 -------
 
-*-M* 'directory', *--module-path=*'directory'::
+*-M* 'DIRECTORY', *--module-path=*'DIRECTORY'::
 
-Add an additional directory to the default path for finding module libraries.
+the 'DIRECTORY' search path to load modules from. The default is
+'/usr/share/ansible'. This can also be set with the ANSIBLE_LIBRARY
+environment variable.
 
 *-s*, *--snippet=*::
 
@@ -41,6 +43,24 @@ a kind of task template.
 
 Produce a terse listing of modules and a short description of each.
 
+
+ENVIRONMENT
+-----------
+
+ANSIBLE_LIBRARY -- Override the default ansible module library path
+
+
+FILES
+-----
+
+/usr/share/ansible/ -- Default module library
+
+/etc/ansible/ansible.cfg -- Config file, used if present
+
+~/.ansible.cfg -- User config file, overrides the default config if present
+
+
+
 AUTHOR
 ------
 
@@ -59,7 +79,7 @@ Ansible is released under the terms of the GPLv3 License.
 SEE ALSO
 --------
 
-*ansible-playbook*(1), *ansible*(1), *ansible-pull*(1)
+*ansible-playbook*(1), *ansible*(1), *ansible-pull*(1), *ansible-vault*(1), *ansible-galaxy*(1)
 
 Extensive documentation is available in the documentation site:
 <http://docs.ansible.com>. IRC and mailing list info can be found
diff --git a/docs/man/man1/ansible-galaxy.1 b/docs/man/man1/ansible-galaxy.1
deleted file mode 100644
index f8486c75f4..0000000000
--- a/docs/man/man1/ansible-galaxy.1
+++ /dev/null
@@ -1,185 +0,0 @@
-'\" t
-.\"     Title: ansible-galaxy
-.\"    Author: [see the "AUTHOR" section]
-.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 05/05/2015
-.\"    Manual: System administration commands
-.\"    Source: Ansible 2.0.0
-.\"  Language: English
-.\"
-.TH "ANSIBLE\-GALAXY" "1" "05/05/2015" "Ansible 2\&.0\&.0" "System administration commands"
-.\" -----------------------------------------------------------------
-.\" * Define some portability stuff
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" http://bugs.debian.org/507673
-.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.ie \n(.g .ds Aq \(aq
-.el       .ds Aq '
-.\" -----------------------------------------------------------------
-.\" * set default formatting
-.\" -----------------------------------------------------------------
-.\" disable hyphenation
-.nh
-.\" disable justification (adjust text to left margin only)
-.ad l
-.\" -----------------------------------------------------------------
-.\" * MAIN CONTENT STARTS HERE *
-.\" -----------------------------------------------------------------
-.SH "NAME"
-ansible-galaxy \- manage roles using galaxy\&.ansible\&.com
-.SH "SYNOPSIS"
-.sp
-ansible\-galaxy [init|info|install|list|remove] [\-\-help] [options] \&...
-.SH "DESCRIPTION"
-.sp
-\fBAnsible Galaxy\fR is a shared repository for Ansible roles (added in ansible version 1\&.2)\&. The ansible\-galaxy command can be used to manage these roles, or by creating a skeleton framework for roles you\(cqd like to upload to Galaxy\&.
-.SH "COMMON OPTIONS"
-.PP
-\fB\-h\fR, \fB\-\-help\fR
-.RS 4
-Show a help message related to the given sub\-command\&.
-.RE
-.SH "INSTALL"
-.sp
-The \fBinstall\fR sub\-command is used to install roles\&.
-.SS "USAGE"
-.sp
-$ ansible\-galaxy install [options] [\-r FILE | role_name(s)[,version] | tar_file(s)]
-.sp
-Roles can be installed in several different ways:
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-A username\&.rolename[,version] \- this will install a single role\&. The Galaxy API will be contacted to provide the information about the role, and the corresponding \&.tar\&.gz will be downloaded from
-\fBgithub\&.com\fR\&. If the version is omitted, the most recent version available will be installed\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-A file name, using
-\fB\-r\fR
-\- this will install multiple roles listed one per line\&. The format of each line is the same as above: username\&.rolename[,version]
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-A \&.tar\&.gz of a valid role you\(cqve downloaded directly from
-\fBgithub\&.com\fR\&. This is mainly useful when the system running Ansible does not have access to the Galaxy API, for instance when behind a firewall or proxy\&.
-.RE
-.SS "OPTIONS"
-.PP
-\fB\-f\fR, \fB\-\-force\fR
-.RS 4
-Force overwriting an existing role\&.
-.RE
-.PP
-\fB\-i\fR, \fB\-\-ignore\-errors\fR
-.RS 4
-Ignore errors and continue with the next specified role\&.
-.RE
-.PP
-\fB\-n\fR, \fB\-\-no\-deps\fR
-.RS 4
-Don\(cqt download roles listed as dependencies\&.
-.RE
-.PP
-\fB\-p\fR \fIROLES_PATH\fR, \fB\-\-roles\-path=\fR\fIROLES_PATH\fR
-.RS 4
-The path to the directory containing your roles\&. The default is the
-\fBroles_path\fR
-configured in your
-\fBansible\&.cfg\fR
-file (/etc/ansible/roles if not configured)
-.RE
-.PP
-\fB\-r\fR \fIROLE_FILE\fR, \fB\-\-role\-file=\fR\fIROLE_FILE\fR
-.RS 4
-A file containing a list of roles to be imported, as specified above\&. This option cannot be used if a rolename or \&.tar\&.gz have been specified\&.
-.RE
-.SH "REMOVE"
-.sp
-The \fBremove\fR sub\-command is used to remove one or more roles\&.
-.SS "USAGE"
-.sp
-$ ansible\-galaxy remove role1 role2 \&...
-.SS "OPTIONS"
-.PP
-\fB\-p\fR \fIROLES_PATH\fR, \fB\-\-roles\-path=\fR\fIROLES_PATH\fR
-.RS 4
-The path to the directory containing your roles\&. The default is the
-\fBroles_path\fR
-configured in your
-\fBansible\&.cfg\fR
-file (/etc/ansible/roles if not configured)
-.RE
-.SH "INIT"
-.sp
-The \fBinit\fR command is used to create an empty role suitable for uploading to https://galaxy\&.ansible\&.com (or for roles in general)\&.
-.SS "USAGE"
-.sp
-$ ansible\-galaxy init [options] role_name
-.SS "OPTIONS"
-.PP
-\fB\-f\fR, \fB\-\-force\fR
-.RS 4
-Force overwriting an existing role\&.
-.RE
-.PP
-\fB\-p\fR \fIINIT_PATH\fR, \fB\-\-init\-path=\fR\fIINIT_PATH\fR
-.RS 4
-The path in which the skeleton role will be created\&.The default is the current working directory\&.
-.RE
-.PP
-\fB\-\-offline\fR
-.RS 4
-Don\(cqt query the galaxy API when creating roles
-.RE
-.SH "LIST"
-.sp
-The \fBlist\fR sub\-command is used to show what roles are currently instaled\&. You can specify a role name, and if installed only that role will be shown\&.
-.SS "USAGE"
-.sp
-$ ansible\-galaxy list [role_name]
-.SS "OPTIONS"
-.PP
-\fB\-p\fR \fIROLES_PATH\fR, \fB\-\-roles\-path=\fR\fIROLES_PATH\fR
-.RS 4
-The path to the directory containing your roles\&. The default is the
-\fBroles_path\fR
-configured in your
-\fBansible\&.cfg\fR
-file (/etc/ansible/roles if not configured)
-.RE
-.SH "AUTHOR"
-.sp
-Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
-.SH "COPYRIGHT"
-.sp
-Copyright \(co 2014, Michael DeHaan
-.sp
-Ansible is released under the terms of the GPLv3 License\&.
-.SH "SEE ALSO"
-.sp
-\fBansible\fR(1), \fBansible\-pull\fR(1), \fBansible\-doc\fR(1)
-.sp
-Extensive documentation is available in the documentation site: http://docs\&.ansible\&.com\&. IRC and mailing list info can be found in file CONTRIBUTING\&.md, available in: https://github\&.com/ansible/ansible
diff --git a/docs/man/man1/ansible-galaxy.1.asciidoc.in b/docs/man/man1/ansible-galaxy.1.asciidoc.in
index 3d59e31706..e6f2d0b456 100644
--- a/docs/man/man1/ansible-galaxy.1.asciidoc.in
+++ b/docs/man/man1/ansible-galaxy.1.asciidoc.in
@@ -18,10 +18,9 @@ ansible-galaxy [init|info|install|list|remove] [--help] [options] ...
 DESCRIPTION
 -----------
 
-*Ansible Galaxy* is a shared repository for Ansible roles (added in
-ansible version 1.2). The ansible-galaxy command can be used to manage
-these roles, or by creating a skeleton framework for roles you'd like
-to upload to Galaxy.
+*Ansible Galaxy* is a shared repository for Ansible roles.
+The ansible-galaxy command can be used to manage these roles,
+or by creating a skeleton framework for roles you'd like to upload to Galaxy.
 
 COMMON OPTIONS
 --------------
@@ -43,16 +42,16 @@ $ ansible-galaxy install [options] [-r FILE | role_name(s)[,version] | tar_file(
 
 Roles can be installed in several different ways:
 
-* A username.rolename[,version] - this will install a single role. The Galaxy 
-  API will be contacted to provide the information about the role, and the 
-  corresponding .tar.gz will be downloaded from *github.com*. If the version 
+* A username.rolename[,version] - this will install a single role. The Galaxy
+  API will be contacted to provide the information about the role, and the
+  corresponding .tar.gz will be downloaded from *github.com*. If the version
   is omitted, the most recent version available will be installed.
 
 * A file name, using *-r* - this will install multiple roles listed one per
   line. The format of each line is the same as above: username.rolename[,version]
 
 * A .tar.gz of a valid role you've downloaded directly from *github.com*. This
-  is mainly useful when the system running Ansible does not have access to 
+  is mainly useful when the system running Ansible does not have access to
   the Galaxy API, for instance when behind a firewall or proxy.
 
 
@@ -164,7 +163,7 @@ Ansible is released under the terms of the GPLv3 License.
 SEE ALSO
 --------
 
-*ansible*(1), *ansible-pull*(1), *ansible-doc*(1)
+*ansible*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-playbook*(1), *ansible-vault*(1)
 
 Extensive documentation is available in the documentation site:
 <http://docs.ansible.com>. IRC and mailing list info can be found
diff --git a/docs/man/man1/ansible-playbook.1 b/docs/man/man1/ansible-playbook.1
deleted file mode 100644
index cfc33d1744..0000000000
--- a/docs/man/man1/ansible-playbook.1
+++ /dev/null
@@ -1,269 +0,0 @@
-'\" t
-.\"     Title: ansible-playbook
-.\"    Author: :doctype:manpage
-.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 07/23/2015
-.\"    Manual: System administration commands
-.\"    Source: Ansible %VERSION%
-.\"  Language: English
-.\"
-.TH "ANSIBLE\-PLAYBOOK" "1" "07/23/2015" "Ansible %VERSION%" "System administration commands"
-.\" -----------------------------------------------------------------
-.\" * Define some portability stuff
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" http://bugs.debian.org/507673
-.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.ie \n(.g .ds Aq \(aq
-.el       .ds Aq '
-.\" -----------------------------------------------------------------
-.\" * set default formatting
-.\" -----------------------------------------------------------------
-.\" disable hyphenation
-.nh
-.\" disable justification (adjust text to left margin only)
-.ad l
-.\" -----------------------------------------------------------------
-.\" * MAIN CONTENT STARTS HERE *
-.\" -----------------------------------------------------------------
-.SH "NAME"
-ansible-playbook \- run an ansible playbook
-.SH "SYNOPSIS"
-.sp
-ansible\-playbook <filename\&.yml> \&... [options]
-.SH "DESCRIPTION"
-.sp
-\fBAnsible playbooks\fR are a configuration and multinode deployment system\&. Ansible\-playbook is the tool used to run them\&. See the project home page (link below) for more information\&.
-.SH "ARGUMENTS"
-.PP
-\fBfilename\&.yml\fR
-.RS 4
-The names of one or more YAML format files to run as ansible playbooks\&.
-.RE
-.SH "OPTIONS"
-.PP
-\fB\-k\fR, \fB\-\-ask\-pass\fR
-.RS 4
-Prompt for the SSH password instead of assuming key\-based authentication with ssh\-agent\&.
-.RE
-.PP
-\fB\-K\fR, \fB\-\-ask\-sudo\-pass\fR
-.RS 4
-Prompt for the password to use for playbook plays that request sudo access, if any\&.
-.RE
-.PP
-\fB\-b\fR, \fB\-\-become\fR
-.RS 4
-Run operations with become (nopasswd implied)
-.RE
-.PP
-\fB\-\-become\-method=BECOME_METHOD\fR
-.RS 4
-Privilege escalation method to use (default=sudo), valid choices: [ sudo | su | pbrun | pfexec | runas | doas ]
-.RE
-.PP
-\fB\-\-become\-user=BECOME_USER\fR
-.RS 4
-Run operations as this user (default=None)\&.
-.RE
-.PP
-\fB\-C\fR, \fB\-\-check\fR
-.RS 4
-Do not make any changes on the remote system, but test resources to see what might have changed\&. Note this can not scan all possible resource types and is only a simulation\&.
-.RE
-.PP
-\fB\-c\fR \fICONNECTION\fR, \fB\-\-connection=\fR\fICONNECTION\fR
-.RS 4
-Connection type to use\&. Possible options are
-\fIparamiko\fR
-(SSH),
-\fIssh\fR, and
-\fIlocal\fR\&.
-\fIlocal\fR
-is mostly useful for crontab or kickstarts\&.
-.RE
-.PP
-\fB\-D\fR, \fB\-\-diff\fR
-.RS 4
-When changing any templated files, show the unified diffs of how they changed\&. When used with \-\-check, shows how the files would have changed if \-\-check were not used\&.
-.RE
-.PP
-\fB\-e\fR \fIVARS\fR, \fB\-\-extra\-vars=\fR\fIVARS\fR
-.RS 4
-Extra variables to inject into a playbook, in key=value key=value format or as quoted JSON (hashes and arrays)\&. To load variables from a file, specify the file preceded by @ (e\&.g\&. @vars\&.yml)\&.
-.RE
-.PP
-\fB\-\-flush\-cache\fR
-.RS 4
-Clear the fact cache\&.
-.RE
-.PP
-\fB\-\-force\-handlers\fR
-.RS 4
-Run handlers even if a task fails\&.
-.RE
-.PP
-\fB\-f\fR \fINUM\fR, \fB\-\-forks=\fR\fINUM\fR
-.RS 4
-Level of parallelism\&.
-\fINUM\fR
-is specified as an integer, the default is 5\&.
-.RE
-.PP
-\fB\-h\fR, \fB\-\-help\fR
-.RS 4
-Show help page and exit
-.RE
-.PP
-\fB\-i\fR \fIPATH\fR, \fB\-\-inventory=\fR\fIPATH\fR
-.RS 4
-The
-\fIPATH\fR
-to the inventory hosts file, which defaults to
-\fI/etc/ansible/hosts\fR\&.
-.RE
-.PP
-\fB\-l\fR \fISUBSET\fR, \fB\-\-limit=\fR\fISUBSET\fR
-.RS 4
-Further limits the selected host/group patterns\&.
-.RE
-.PP
-\fB\-\-list\-hosts\fR
-.RS 4
-Outputs a list of matching hosts; does not execute anything else\&.
-.RE
-.PP
-\fB\-\-list\-tags\fR
-.RS 4
-List all available tags\&.
-.RE
-.PP
-\fB\-\-list\-tasks\fR
-.RS 4
-List all tasks that would be executed
-.RE
-.PP
-\fB\-M\fR \fIDIRECTORY\fR, \fB\-\-module\-path=\fR\fIDIRECTORY\fR
-.RS 4
-The
-\fIDIRECTORY\fR
-search path to load modules from\&. The default is
-\fI/usr/share/ansible\fR\&. This can also be set with the ANSIBLE_LIBRARY environment variable\&.
-.RE
-.PP
-\fB\-\-private\-key=\fR\fIPRIVATE_KEY_FILE\fR
-.RS 4
-Use this file to authenticate the connection
-.RE
-.PP
-\fB\-\-skip\-tages=\fR\fISKIP_TAGS\fR
-.RS 4
-Only run plays and tasks whose tags do not match these values\&.
-.RE
-.PP
-\fB\-\-start\-at\-task=\fR\fISTART_AT\fR
-.RS 4
-Start the playbook at the task matching this name\&.
-.RE
-.PP
-\fB\-\-step\fR
-.RS 4
-One\-step\-at\-a\-time: confirm each task before running\&.
-.RE
-.PP
-\fB\-S\fR, \-\-su*
-.RS 4
-Run operations with su (deprecated, use become)
-.RE
-.PP
-\fB\-R SU\-USER\fR, \fB\-\-su\-user=\fR\fISU_USER\fR
-.RS 4
-run operations with su as this user (default=root) (deprecated, use become)
-.RE
-.PP
-\fB\-s\fR, \fB\-\-sudo\fR
-.RS 4
-Run operations with sudo (nopasswd) (deprecated, use become)
-.RE
-.PP
-\fB\-U\fR, \fISUDO_USER\fR, \fB\-\-sudo\-user=\fR\fISUDO_USER\fR
-.RS 4
-Desired sudo user (default=root) (deprecated, use become)\&.
-.RE
-.PP
-\fB\-\-skip\-tags=\fR\fISKIP_TAGS\fR
-.RS 4
-Only run plays and tasks whose tags do not match these values\&.
-.RE
-.PP
-\fB\-\-syntax\-check\fR
-.RS 4
-Look for syntax errors in the playbook, but don\(cqt run anything
-.RE
-.PP
-\fB\-t\fR, \fITAGS\fR, \fB\-\-tags=\fR\fITAGS\fR
-.RS 4
-Only run plays and tasks tagged with these values\&.
-.RE
-.PP
-\fB\-T\fR \fISECONDS\fR, \fB\-\-timeout=\fR\fISECONDS\fR
-.RS 4
-Connection timeout to use when trying to talk to hosts, in
-\fISECONDS\fR\&.
-.RE
-.PP
-\fB\-u\fR \fIUSERNAME\fR, \fB\-\-user=\fR\fIUSERNAME\fR
-.RS 4
-Use this remote user name on playbook steps that do not indicate a user name to run as\&.
-.RE
-.PP
-\fB\-\-vault\-password\-file=\fR\fIVAULT_PASSWORD_FILE\fR
-.RS 4
-Vault password file\&.
-.RE
-.PP
-\fB\-v\fR, \fB\-\-verbose\fR
-.RS 4
-Verbose mode, more output from successful actions will be shown\&. Give up to three times for more output\&.
-.RE
-.PP
-\fB\-\-version\fR
-.RS 4
-Show program\(cqs version number and exit\&.
-.RE
-.SH "ENVIRONMENT"
-.sp
-The following environment variables may be specified\&.
-.sp
-ANSIBLE_INVENTORY  \(em Override the default ansible inventory file
-.sp
-ANSIBLE_LIBRARY \(em Override the default ansible module library path
-.SH "FILES"
-.sp
-/etc/ansible/hosts \(em Default inventory file
-.sp
-/usr/share/ansible/ \(em Default module library
-.sp
-/etc/ansible/ansible\&.cfg \(em Config file, used if present
-.sp
-~/\&.ansible\&.cfg \(em User config file, overrides the default config if present
-.SH "AUTHOR"
-.sp
-Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
-.SH "COPYRIGHT"
-.sp
-Copyright \(co 2012, Michael DeHaan
-.sp
-Ansible is released under the terms of the GPLv3 License\&.
-.SH "SEE ALSO"
-.sp
-\fBansible\fR(1), \fBansible\-pull\fR(1), \fBansible\-doc\fR(1)
-.sp
-Extensive documentation is available in the documentation site: http://docs\&.ansible\&.com\&. IRC and mailing list info can be found in file CONTRIBUTING\&.md, available in: https://github\&.com/ansible/ansible
-.SH "AUTHOR"
-.PP
-\fB:doctype:manpage\fR
-.RS 4
-Author.
-.RE
diff --git a/docs/man/man1/ansible-playbook.1.asciidoc.in b/docs/man/man1/ansible-playbook.1.asciidoc.in
index 356ad545e6..66b5b69174 100644
--- a/docs/man/man1/ansible-playbook.1.asciidoc.in
+++ b/docs/man/man1/ansible-playbook.1.asciidoc.in
@@ -34,28 +34,26 @@ The names of one or more YAML format files to run as ansible playbooks.
 OPTIONS
 -------
 
-*-k*, *--ask-pass*::
+*--ask-become-pass*::
 
-Prompt for the SSH password instead of assuming key-based
-authentication with ssh-agent.
+Ask for privilege escalation password.
 
-*-K*, *--ask-sudo-pass*::
+*-k*, *--ask-pass*::
 
-Prompt for the password to use for playbook plays that request sudo
-access, if any.
+Prompt for the connection password, if it is needed for the transport used.
+For example, using ssh and not having  a key-based authentication with ssh-agent.
 
-*-b*, *--become*::
+*--ask-su-pass*::
 
-Run operations with become (nopasswd implied)
+Prompt for su password, used with --su (deprecated, use become).
 
-*--become-method=BECOME_METHOD*::
+*-K*, *--ask-sudo-pass*::
 
-Privilege escalation method to use (default=sudo),
-valid choices: [ sudo | su | pbrun | pfexec | runas | doas ]
+Prompt for the password to use with --sudo, if any (deprecated, use become).
 
-*--become-user=BECOME_USER*::
+*--ask-vault-pass*::
 
-Run operations as this user (default=None).
+Prompt for vault password.
 
 *-C*, *--check*::
 
@@ -65,7 +63,7 @@ a simulation.
 
 *-c* 'CONNECTION', *--connection=*'CONNECTION'::
 
-Connection type to use.  Possible options are 'paramiko' (SSH), 'ssh',
+Connection type to use.  Most common options are 'paramiko' (SSH), 'ssh', 'winrm'
 and 'local'.  'local' is mostly useful for crontab or kickstarts.
 
 *-D*, *--diff*::
@@ -73,10 +71,10 @@ and 'local'.  'local' is mostly useful for crontab or kickstarts.
 When changing any templated files, show the unified diffs of how they changed.  When
 used with --check, shows how the files would have changed if --check were not used.
 
-*-e* 'VARS', *--extra-vars=*'VARS'::
+*-e* 'EXTRA_VARS', *--extra-vars=*'EXTRA_VARS'::
 
 Extra variables to inject into a playbook, in key=value key=value format or
-as quoted JSON (hashes and arrays). To load variables from a file, specify
+as quoted YAML/JSON (hashes and arrays). To load variables from a file, specify
 the file preceded by @ (e.g. @vars.yml).
 
 *--flush-cache*::
@@ -97,12 +95,13 @@ Show help page and exit
 
 *-i* 'PATH', *--inventory=*'PATH'::
 
-The 'PATH' to the inventory hosts file, which defaults to
-'/etc/ansible/hosts'.
+The 'PATH' to the inventory, which defaults to '/etc/ansible/hosts'.
+Alternatively you can use a comma separated list of hosts or single host with traling comma 'host,'.
 
 *-l* 'SUBSET', *--limit=*'SUBSET'::
 
 Further limits the selected host/group patterns.
+You can prefix it with '~' to indicate that the patter in a regex.
 
 *--list-hosts*::
 
@@ -110,11 +109,11 @@ Outputs a list of matching hosts; does not execute anything else.
 
 *--list-tags*::
 
-List all available tags.
+List all available tags; does not execute anything else.
 
 *--list-tasks*::
 
-List all tasks that would be executed
+List all tasks that would be executed; does not execute anything else.
 
 *-M* 'DIRECTORY', *--module-path=*'DIRECTORY'::
 
@@ -144,12 +143,11 @@ Run operations with su (deprecated, use become)
 
 *-R SU-USER*, *--su-user=*'SU_USER'::
 
-run operations with su as this user (default=root)
-(deprecated, use become)
+run operations with su as this user (default=root) (deprecated, use become)
 
 *-s*, *--sudo*::
 
-Run operations with sudo (nopasswd) (deprecated, use become)
+Run the command as the user given by -u and sudo to root (deprecated, use become).
 
 *--ssh-common-args=*''-o ProxyCommand="ssh -W %h:%p ..." ...''::
 
@@ -169,9 +167,9 @@ Add the specified arguments to any scp command-line.
 
 Add the specified arguments to any ssh command-line.
 
-*-U*, 'SUDO_USER', *--sudo-user=*'SUDO_USER'::
+*-U* 'SUDO_USERNAME', *--sudo-user=*'SUDO_USERNAME'::
 
-Desired sudo user (default=root) (deprecated, use become).
+Sudo to 'SUDO_USERNAME' deafult is root. (deprecated, use become).
 
 *--skip-tags=*'SKIP_TAGS'::
 
@@ -191,8 +189,7 @@ Connection timeout to use when trying to talk to hosts, in 'SECONDS'.
 
 *-u* 'USERNAME', *--user=*'USERNAME'::
 
-Use this remote user name on playbook steps that do not indicate a
-user name to run as.
+Use this 'USERNAME' to login to the target host, instead of the current user.
 
 *--vault-password-file=*'VAULT_PASSWORD_FILE'::
 
@@ -207,6 +204,7 @@ up to three times for more output.
 
 Show program's version number and exit.
 
+
 ENVIRONMENT
 -----------
 
@@ -216,6 +214,11 @@ ANSIBLE_INVENTORY  -- Override the default ansible inventory file
 
 ANSIBLE_LIBRARY -- Override the default ansible module library path
 
+ANSIBLE_CONFIG -- Override the default ansible config file
+
+Many more are available for most options in ansible.cfg
+
+
 FILES
 -----
 
@@ -227,6 +230,7 @@ FILES
 
 ~/.ansible.cfg -- User config file, overrides the default config if present
 
+
 AUTHOR
 ------
 
@@ -245,7 +249,7 @@ Ansible is released under the terms of the GPLv3 License.
 SEE ALSO
 --------
 
-*ansible*(1), *ansible-pull*(1), *ansible-doc*(1)
+*ansible*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-vault*(1), *ansible-galaxy*(1)
 
 Extensive documentation is available in the documentation site:
 <http://docs.ansible.com>. IRC and mailing list info can be found
diff --git a/docs/man/man1/ansible-pull.1 b/docs/man/man1/ansible-pull.1
deleted file mode 100644
index 8e9bc6a8f5..0000000000
--- a/docs/man/man1/ansible-pull.1
+++ /dev/null
@@ -1,159 +0,0 @@
-'\" t
-.\"     Title: ansible
-.\"    Author: :doctype:manpage
-.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 07/22/2015
-.\"    Manual: System administration commands
-.\"    Source: Ansible %VERSION%
-.\"  Language: English
-.\"
-.TH "ANSIBLE" "1" "07/22/2015" "Ansible %VERSION%" "System administration commands"
-.\" -----------------------------------------------------------------
-.\" * Define some portability stuff
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" http://bugs.debian.org/507673
-.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.ie \n(.g .ds Aq \(aq
-.el       .ds Aq '
-.\" -----------------------------------------------------------------
-.\" * set default formatting
-.\" -----------------------------------------------------------------
-.\" disable hyphenation
-.nh
-.\" disable justification (adjust text to left margin only)
-.ad l
-.\" -----------------------------------------------------------------
-.\" * MAIN CONTENT STARTS HERE *
-.\" -----------------------------------------------------------------
-.SH "NAME"
-ansible-pull \- set up a remote copy of ansible on each managed node
-.SH "SYNOPSIS"
-.sp
-ansible\-pull \-d DEST \-U URL [options] [ <filename\&.yml> ]
-.SH "DESCRIPTION"
-.sp
-\fBAnsible\fR is an extra\-simple tool/framework/API for doing \*(Aqremote things\*(Aq over SSH\&.
-.sp
-Use ansible\-pull to set up a remote copy of ansible on each managed node, each set to run via cron and update playbook source via a source repository\&. This inverts the default \fBpush\fR architecture of ansible into a \fBpull\fR architecture, which has near\-limitless scaling potential\&.
-.sp
-The setup playbook can be tuned to change the cron frequency, logging locations, and parameters to ansible\-pull\&.
-.sp
-This is useful both for extreme scale\-out as well as periodic remediation\&. Usage of the \fIfetch\fR module to retrieve logs from ansible\-pull runs would be an excellent way to gather and analyze remote logs from ansible\-pull\&.
-.SH "OPTIONAL ARGUMENT"
-.PP
-\fBfilename\&.yml\fR
-.RS 4
-The name of one the YAML format files to run as an ansible playbook\&. This can be a relative path within the checkout\&. If not provided, ansible\-pull will look for a playbook based on the host\(cqs fully\-qualified domain name, on the host hostname and finally a playbook named
-\fBlocal\&.yml\fR\&.
-.RE
-.SH "OPTIONS"
-.PP
-\fB\-\-accept\-host\-key\fR
-.RS 4
-Adds the hostkey for the repo URL if not already added\&.
-.RE
-.PP
-\fB\-K\fR, \fB\-\-ask\-sudo\-pass\fR
-.RS 4
-Ask for sudo password\&.
-.RE
-.PP
-\fB\-C\fR \fICHECKOUT\fR, \fB\-\-checkout=\fR\fICHECKOUT\fR
-.RS 4
-Branch/Tag/Commit to checkout\&. If not provided, uses default behavior of module used to check out playbook repository\&.
-.RE
-.PP
-\fB\-d\fR \fIDEST\fR, \fB\-\-directory=\fR\fIDEST\fR
-.RS 4
-Directory to checkout repository into\&. If not provided, a subdirectory of ~/\&.ansible/pull/ will be used\&.
-.RE
-.PP
-\fB\-e\fR \fIEXTRA_VARS\fR, \fB\-\-extra\-vars=\fR\*(AqEXTRA_VARS*
-.RS 4
-Set additional variables as key=value or YAML/JSON
-.RE
-.PP
-\fB\-f\fR, \fB\-\-force\fR
-.RS 4
-Force running of playbook even if unable to update playbook repository\&. This can be useful, for example, to enforce run\-time state when a network connection may not always be up or possible\&.
-.RE
-.PP
-\fB\-h\fR, \fB\-\-help\fR
-.RS 4
-Show the help message and exit\&.
-.RE
-.PP
-\fB\-i\fR \fIPATH\fR, \fB\-\-inventory=\fR\fIPATH\fR
-.RS 4
-The
-\fIPATH\fR
-to the inventory hosts file\&. This can be a relative path within the checkout\&.
-.RE
-.PP
-\fB\-\-key\-file=\fR\fIKEYFILE\fR
-.RS 4
-Pass
-\fI\-i <key_file>\fR
-to the SSH arguments used by git\&.
-.RE
-.PP
-\fB\-m\fR \fINAME\fR, \fB\-\-module\-name=\fR\fINAME\fR
-.RS 4
-Module used to checkout playbook repository\&. Defaults to git\&.
-.RE
-.PP
-\fB\-o\fR, \fB\-\-only\-if\-changed\fR
-.RS 4
-Only run the playbook if the repository has been updated\&.
-.RE
-.PP
-\fB\-\-purge\fR
-.RS 4
-Purge the checkout after the playbook is run\&.
-.RE
-.PP
-\fB\-s\fR \fISLEEP\fR, \fB\-\-sleep=\fR\fISLEEP\fR
-.RS 4
-Sleep for random interval (between 0 and SLEEP number of seconds) before starting\&. This is a useful way ot disperse git requests\&.
-.RE
-.PP
-\fB\-t\fR \fITAGS\fR, \fB\-\-tags=\fR\fITAGS\fR
-.RS 4
-Only run plays and tasks tagged with these values\&.
-.RE
-.PP
-\fB\-U\fR \fIURL\fR, \fB\-\-url=\fR\fIURL\fR
-.RS 4
-URL of the playbook repository to checkout\&.
-.RE
-.PP
-\fB\-\-vault\-password\-file=\fR\fIVAULT_PASSWORD_FILE\fR
-.RS 4
-Vault password file\&.
-.RE
-.PP
-\fB\-v\fR, \fB\-\-verbose\fR
-.RS 4
-Pass \-vvv to ansible\-playbook\&.
-.RE
-.SH "AUTHOR"
-.sp
-Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
-.SH "COPYRIGHT"
-.sp
-Copyright \(co 2012, Michael DeHaan
-.sp
-Ansible is released under the terms of the GPLv3 License\&.
-.SH "SEE ALSO"
-.sp
-\fBansible\fR(1), \fBansible\-playbook\fR(1), \fBansible\-doc\fR(1)
-.sp
-Extensive documentation is available in the documentation site: http://docs\&.ansible\&.com\&. IRC and mailing list info can be found in file CONTRIBUTING\&.md, available in: https://github\&.com/ansible/ansible
-.SH "AUTHOR"
-.PP
-\fB:doctype:manpage\fR
-.RS 4
-Author.
-.RE
diff --git a/docs/man/man1/ansible-pull.1.asciidoc.in b/docs/man/man1/ansible-pull.1.asciidoc.in
index c0a5ab9ed2..bc7de64ada 100644
--- a/docs/man/man1/ansible-pull.1.asciidoc.in
+++ b/docs/man/man1/ansible-pull.1.asciidoc.in
@@ -5,9 +5,10 @@ ansible(1)
 :man version:  %VERSION%
 :man manual:   System administration commands
 
+
 NAME
 ----
-ansible-pull - set up a remote copy of ansible on each managed node
+ansible-pull - pull playbooks from VCS server and run them using this machine as the target.
 
 
 SYNOPSIS
@@ -18,8 +19,7 @@ ansible-pull -d DEST -U URL [options] [ <filename.yml> ]
 DESCRIPTION
 -----------
 
-*Ansible* is an extra-simple tool/framework/API for doing \'remote things' over
-SSH.
+*Ansible* is an extra-simple tool/framework/API for doing \'remote things'.
 
 Use ansible-pull to set up a remote copy of ansible on each managed
 node, each set to run via cron and update playbook source via
@@ -54,22 +54,40 @@ OPTIONS
 
 Adds the hostkey for the repo URL if not already added.
 
+*--ask-become-pass*::
+
+Ask for privilege escalation password.
+
+*-k*, *--ask-pass*::
+
+Prompt for the connection password, if it is needed for the transport used.
+For example, using ssh and not having  a key-based authentication with ssh-agent.
+
+*--ask-su-pass*::
+
+Prompt for su password, used with --su (deprecated, use become).
+
 *-K*, *--ask-sudo-pass*::
 
-Ask for sudo password.
- 
+Prompt for the password to use with --sudo, if any (deprecated, use become).
+
+*--ask-vault-pass*::
+
+Prompt for vault password.
+
 *-C* 'CHECKOUT', *--checkout=*'CHECKOUT'::
 
 Branch/Tag/Commit to checkout.  If not provided, uses default behavior of module used to check out playbook repository.
 
 *-d* 'DEST', *--directory=*'DEST'::
 
-Directory to checkout repository into. If not provided, a subdirectory of
-~/.ansible/pull/ will be used.
+Directory to checkout repository into. If not provided, a subdirectory of ~/.ansible/pull/ will be used.
 
-*-e* 'EXTRA_VARS', *--extra-vars=*'EXTRA_VARS*::
+*-e* 'EXTRA_VARS', *--extra-vars=*'EXTRA_VARS::
 
-Set additional variables as key=value or YAML/JSON
+Extra variables to inject into a playbook, in key=value key=value format or
+as quoted YAML/JSON (hashes and arrays). To load variables from a file, specify
+the file preceded by @ (e.g. @vars.yml).
 
 *-f*, *--force*::
 
@@ -83,11 +101,12 @@ Show the help message and exit.
 
 *-i* 'PATH', *--inventory=*'PATH'::
 
-The 'PATH' to the inventory hosts file.  This can be a relative path within the checkout.
+The 'PATH' to the inventory, which defaults to '/etc/ansible/hosts'.
+Alternatively you can use a comma separated list of hosts or single host with traling comma 'host,'.
 
-*--key-file=*'KEYFILE'::
+*--private-key=*'PRIVATE_KEY_FILE'::
 
-Pass '-i <key_file>' to the SSH arguments used by git.
+Use this file to authenticate the connection.
 
 *-m* 'NAME', *--module-name=*'NAME'::
 
@@ -140,25 +159,62 @@ Vault password file.
 Pass -vvv to ansible-playbook.
 
 
+INVENTORY
+---------
+
+Ansible stores the hosts it can potentially operate on in an inventory.
+This can be an ini-like file, a script, directory or a list.
+The ini syntax is one host per line.  Groups headers are allowed and
+are included on their own line, enclosed in square brackets that start the line.
+
+Ranges of hosts are also supported.  For more information and
+additional options, see the documentation on http://docs.ansible.com/.
+
+
+ENVIRONMENT
+-----------
+
+The following environment variables may be specified.
+
+ANSIBLE_INVENTORY  -- Override the default ansible inventory file
+
+ANSIBLE_LIBRARY -- Override the default ansible module library path
+
+ANSIBLE_CONFIG -- Override the default ansible config file
+
+Many more are available for most options in ansible.cfg
+
+
+FILES
+-----
+
+/etc/ansible/hosts -- Default inventory file
+
+/usr/share/ansible/ -- Default module library
+
+/etc/ansible/ansible.cfg -- Config file, used if present
+
+~/.ansible.cfg -- User config file, overrides the default config if present
+
+
 AUTHOR
 ------
 
-Ansible was originally written by Michael DeHaan. See the AUTHORS file
-for a complete list of contributors.
+Ansible was originally written by Michael DeHaan.
+See the AUTHORS file for a complete list of contributors.
 
 
 COPYRIGHT
 ---------
 
 Copyright © 2012, Michael DeHaan
-
 Ansible is released under the terms of the GPLv3 License.
 
 
 SEE ALSO
 --------
 
-*ansible*(1), *ansible-playbook*(1), *ansible-doc*(1)
+*ansible*(1) *ansible-playbook*(1), *ansible-doc*(1), *ansible-vault*(1), *ansible-galaxy*(1)
 
 Extensive documentation is available in the documentation site:
 <http://docs.ansible.com>. IRC and mailing list info can be found
diff --git a/docs/man/man1/ansible-vault.1 b/docs/man/man1/ansible-vault.1
deleted file mode 100644
index e448d031b9..0000000000
--- a/docs/man/man1/ansible-vault.1
+++ /dev/null
@@ -1,124 +0,0 @@
-'\" t
-.\"     Title: ansible-vault
-.\"    Author: [see the "AUTHOR" section]
-.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\"      Date: 08/27/2015
-.\"    Manual: System administration commands
-.\"    Source: Ansible 2.0.0
-.\"  Language: English
-.\"
-.TH "ANSIBLE\-VAULT" "1" "08/27/2015" "Ansible 2\&.0\&.0" "System administration commands"
-.\" -----------------------------------------------------------------
-.\" * Define some portability stuff
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" http://bugs.debian.org/507673
-.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.ie \n(.g .ds Aq \(aq
-.el       .ds Aq '
-.\" -----------------------------------------------------------------
-.\" * set default formatting
-.\" -----------------------------------------------------------------
-.\" disable hyphenation
-.nh
-.\" disable justification (adjust text to left margin only)
-.ad l
-.\" -----------------------------------------------------------------
-.\" * MAIN CONTENT STARTS HERE *
-.\" -----------------------------------------------------------------
-.SH "NAME"
-ansible-vault \- manage encrypted YAML data\&.
-.SH "SYNOPSIS"
-.sp
-ansible\-vault [create|decrypt|edit|encrypt|rekey] [\-\-help] [options] file_name
-.SH "DESCRIPTION"
-.sp
-\fBansible\-vault\fR can encrypt any structured data file used by Ansible\&. This can include \fBgroup_vars/\fR or \fBhost_vars/\fR inventory variables, variables loaded by \fBinclude_vars\fR or \fBvars_files\fR, or variable files passed on the ansible\-playbook command line with \fB\-e @file\&.yml\fR or \fB\-e @file\&.json\fR\&. Role variables and defaults are also included!
-.sp
-Because Ansible tasks, handlers, and so on are also data, these can also be encrypted with vault\&. If you\(cqd like to not betray what variables you are even using, you can go as far to keep an individual task file entirely encrypted\&.
-.SH "COMMON OPTIONS"
-.sp
-The following options are available to all sub\-commands:
-.PP
-\fB\-\-vault\-password\-file=\fR\fIFILE\fR
-.RS 4
-A file containing the vault password to be used during the encryption/decryption steps\&. Be sure to keep this file secured if it is used\&. If the file is executable, it will be run and its standard output will be used as the password\&.
-.RE
-.PP
-\fB\-\-new\-vault\-password\-file=\fR\fIFILE\fR
-.RS 4
-A file containing the new vault password to be used when rekeying a file\&. Be sure to keep this file secured if it is used\&. If the file is executable, it will be run and its standard output will be used as the password\&.
-.RE
-.PP
-\fB\-h\fR, \fB\-\-help\fR
-.RS 4
-Show a help message related to the given sub\-command\&.
-.RE
-.PP
-\fB\-\-debug\fR
-.RS 4
-Enable debugging output for troubleshooting\&.
-.RE
-.SH "CREATE"
-.sp
-\fB$ ansible\-vault create [options] FILE\fR
-.sp
-The \fBcreate\fR sub\-command is used to initialize a new encrypted file\&.
-.sp
-First you will be prompted for a password\&. The password used with vault currently must be the same for all files you wish to use together at the same time\&.
-.sp
-After providing a password, the tool will launch whatever editor you have defined with $EDITOR, and defaults to vim\&. Once you are done with the editor session, the file will be saved as encrypted data\&.
-.sp
-The default cipher is AES (which is shared\-secret based)\&.
-.SH "EDIT"
-.sp
-\fB$ ansible\-vault edit [options] FILE\fR
-.sp
-The \fBedit\fR sub\-command is used to modify a file which was previously encrypted using ansible\-vault\&.
-.sp
-This command will decrypt the file to a temporary file and allow you to edit the file, saving it back when done and removing the temporary file\&.
-.SH "REKEY"
-.sp
-\fB$ ansible\-vault rekey [options] FILE_1 [FILE_2, \&..., FILE_N]\fR
-.sp
-The \fBrekey\fR command is used to change the password on a vault\-encrypted files\&. This command can update multiple files at once, and will prompt for both the old and new passwords before modifying any data\&.
-.SH "ENCRYPT"
-.sp
-\fB$ ansible\-vault encrypt [options] FILE_1 [FILE_2, \&..., FILE_N]\fR
-.sp
-The \fBencrypt\fR sub\-command is used to encrypt pre\-existing data files\&. As with the \fBrekey\fR command, you can specify multiple files in one command\&.
-.sp
-Starting with version 2\&.0, the \fBencrypt\fR command accepts an \fB\-\-output FILENAME\fR option to determine where encrypted output is stored\&. With this option, input is read from the (at most one) filename given on the command line; if no input file is given, input is read from stdin\&. Either the input or the output file may be given as \fI\-\fR for stdin and stdout respectively\&. If neither input nor output file is given, the command acts as a filter, reading plaintext from stdin and writing it to stdout\&.
-.sp
-Thus any of the following invocations can be used:
-.sp
-\fB$ ansible\-vault encrypt\fR
-.sp
-\fB$ ansible\-vault encrypt \-\-output OUTFILE\fR
-.sp
-\fB$ ansible\-vault encrypt INFILE \-\-output OUTFILE\fR
-.sp
-\fB$ echo secret|ansible\-vault encrypt \-\-output OUTFILE\fR
-.sp
-Reading from stdin and writing only encrypted output is a good way to prevent sensitive data from ever hitting disk (either interactively or from a script)\&.
-.SH "DECRYPT"
-.sp
-\fB$ ansible\-vault decrypt [options] FILE_1 [FILE_2, \&..., FILE_N]\fR
-.sp
-The \fBdecrypt\fR sub\-command is used to remove all encryption from data files\&. The files will be stored as plain\-text YAML once again, so be sure that you do not run this command on data files with active passwords or other sensitive data\&. In most cases, users will want to use the \fBedit\fR sub\-command to modify the files securely\&.
-.sp
-As with \fBencrypt\fR, the \fBdecrypt\fR subcommand also accepts the \fB\-\-output FILENAME\fR option to specify where plaintext output is stored, and stdin/stdout is handled as described above\&.
-.SH "AUTHOR"
-.sp
-Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
-.SH "COPYRIGHT"
-.sp
-Copyright \(co 2014, Michael DeHaan
-.sp
-Ansible is released under the terms of the GPLv3 License\&.
-.SH "SEE ALSO"
-.sp
-\fBansible\fR(1), \fBansible\-pull\fR(1), \fBansible\-doc\fR(1)
-.sp
-Extensive documentation is available in the documentation site: http://docs\&.ansible\&.com\&. IRC and mailing list info can be found in file CONTRIBUTING\&.md, available in: https://github\&.com/ansible/ansible
diff --git a/docs/man/man1/ansible-vault.1.asciidoc.in b/docs/man/man1/ansible-vault.1.asciidoc.in
index 5db71e09e3..3db033b3f7 100644
--- a/docs/man/man1/ansible-vault.1.asciidoc.in
+++ b/docs/man/man1/ansible-vault.1.asciidoc.in
@@ -7,7 +7,7 @@ ansible-vault(1)
 
 NAME
 ----
-ansible-vault - manage encrypted YAML data.
+ansible-vault - manage encrypted ansible vars files (YAML).
 
 
 SYNOPSIS
@@ -18,15 +18,16 @@ ansible-vault [create|decrypt|edit|encrypt|rekey] [--help] [options] file_name
 DESCRIPTION
 -----------
 
-*ansible-vault* can encrypt any structured data file used by Ansible. This can include 
-*group_vars/* or *host_vars/* inventory variables, variables loaded by *include_vars* or 
-*vars_files*, or variable files passed on the ansible-playbook command line with 
-*-e @file.yml* or *-e @file.json*. Role variables and defaults are also included!
+*ansible-vault* can encrypt any structured data file used by Ansible.
+This can include *group_vars/* or *host_vars/* inventory variables,
+variables loaded by *include_vars* or *vars_files*, or variable files
+passed on the ansible-playbook command line with *-e @file.yml* or *-e @file.json*.
+Role variables and defaults are also included!
 
-Because Ansible tasks, handlers, and so on are also data, these can also be encrypted with 
-vault. If you’d like to not betray what variables you are even using, you can go as far to 
-keep an individual task file entirely encrypted.
+Because Ansible tasks, handlers, and so on are also data, these can also be encrypted with vault.
+If you’d like to not betray what variables you are even using, you can go as far to keep an individual task file entirely encrypted.
 
+The password used with vault currently must be the same for all files you wish to use together at the same time.
 
 COMMON OPTIONS
 --------------
@@ -50,22 +51,19 @@ the password.
 
 Show a help message related to the given sub-command.
 
-*--debug*::
 
-Enable debugging output for troubleshooting.
+If '--valut-password-file' is not supplied ansib-vault will automatically prompt for passwords as required.
+
 
 CREATE
 ------
 
 *$ ansible-vault create [options] FILE*
 
-The *create* sub-command is used to initialize a new encrypted file. 
-
-First you will be prompted for a password. The password used with vault currently 
-must be the same for all files you wish to use together at the same time.
+The *create* sub-command is used to initialize a new encrypted file.
 
-After providing a password, the tool will launch whatever editor you have defined 
-with $EDITOR, and defaults to vim. Once you are done with the editor session, the 
+After providing a password, the tool will launch whatever editor you have defined
+with $EDITOR, and defaults to vim. Once you are done with the editor session, the
 file will be saved as encrypted data.
 
 The default cipher is AES (which is shared-secret based).
@@ -75,11 +73,11 @@ EDIT
 
 *$ ansible-vault edit [options] FILE*
 
-The *edit* sub-command is used to modify a file which was previously encrypted
-using ansible-vault.
+The *edit* sub-command is used to modify a file which was previously encrypted using ansible-vault.
+
+This command will decrypt the file to a temporary file and allow you to edit the file,
+saving it back when done and removing the temporary file.
 
-This command will decrypt the file to a temporary file and allow you to edit the 
-file, saving it back when done and removing the temporary file.
 
 REKEY
 -----
@@ -87,24 +85,23 @@ REKEY
 *$ ansible-vault rekey [options] FILE_1 [FILE_2, ..., FILE_N]*
 
 The *rekey* command is used to change the password on a vault-encrypted files.
-This command can update multiple files at once, and will prompt for both the
-old and new passwords before modifying any data.
+This command can update multiple files at once.
+
 
 ENCRYPT
 -------
 
 *$ ansible-vault encrypt [options] FILE_1 [FILE_2, ..., FILE_N]*
 
-The *encrypt* sub-command is used to encrypt pre-existing data files. As with the
-*rekey* command, you can specify multiple files in one command.
+The *encrypt* sub-command is used to encrypt pre-existing data files.
+As with the *rekey* command, you can specify multiple files in one command.
 
-Starting with version 2.0, the *encrypt* command accepts an *--output FILENAME*
-option to determine where encrypted output is stored. With this option, input is
-read from the (at most one) filename given on the command line; if no input file
-is given, input is read from stdin. Either the input or the output file may be
-given as '-' for stdin and stdout respectively. If neither input nor output file
-is given, the command acts as a filter, reading plaintext from stdin and writing
-it to stdout.
+The *encrypt* command accepts an *--output FILENAME* option to determine where
+encrypted output is stored. With this option, input is read from the (at most one)
+filename given on the command line; if no input file is given, input is read from stdin.
+Either the input or the output file may be given as '-' for stdin and stdout respectively.
+If neither input nor output file is given, the command acts as a filter,
+reading plaintext from stdin and writing it to stdout.
 
 Thus any of the following invocations can be used:
 
@@ -124,10 +121,10 @@ DECRYPT
 
 *$ ansible-vault decrypt [options] FILE_1 [FILE_2, ..., FILE_N]*
 
-The *decrypt* sub-command is used to remove all encryption from data files. The files
-will be stored as plain-text YAML once again, so be sure that you do not run this
-command on data files with active passwords or other sensitive data. In most cases, 
-users will want to use the *edit* sub-command to modify the files securely.
+The *decrypt* sub-command is used to remove all encryption from data files.
+The files will be stored as plain-text YAML once again, so be sure that you do not run this
+command on data files with active passwords or other sensitive data.
+In most cases, users will want to use the *edit* sub-command to modify the files securely.
 
 As with *encrypt*, the *decrypt* subcommand also accepts the *--output FILENAME*
 option to specify where plaintext output is stored, and stdin/stdout is handled
@@ -151,7 +148,7 @@ Ansible is released under the terms of the GPLv3 License.
 SEE ALSO
 --------
 
-*ansible*(1), *ansible-pull*(1), *ansible-doc*(1)
+*ansible*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-playbook*(1), *ansible-galaxy*(1)
 
 Extensive documentation is available in the documentation site:
 <http://docs.ansible.com>. IRC and mailing list info can be found
diff --git a/docs/man/man1/ansible.1 b/docs/man/man1/ansible.1
deleted file mode 100644
index 7c6e79da8d..0000000000
--- a/docs/man/man1/ansible.1
+++ /dev/null
@@ -1,279 +0,0 @@
-'\" t
-.\"     Title: ansible
-.\"    Author: :doctype:manpage
-.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 07/15/2015
-.\"    Manual: System administration commands
-.\"    Source: Ansible %VERSION%
-.\"  Language: English
-.\"
-.TH "ANSIBLE" "1" "07/15/2015" "Ansible %VERSION%" "System administration commands"
-.\" -----------------------------------------------------------------
-.\" * Define some portability stuff
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" http://bugs.debian.org/507673
-.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.ie \n(.g .ds Aq \(aq
-.el       .ds Aq '
-.\" -----------------------------------------------------------------
-.\" * set default formatting
-.\" -----------------------------------------------------------------
-.\" disable hyphenation
-.nh
-.\" disable justification (adjust text to left margin only)
-.ad l
-.\" -----------------------------------------------------------------
-.\" * MAIN CONTENT STARTS HERE *
-.\" -----------------------------------------------------------------
-.SH "NAME"
-ansible \- run a command somewhere else
-.SH "SYNOPSIS"
-.sp
-ansible <host\-pattern> [\-f forks] [\-m module_name] [\-a args]
-.SH "DESCRIPTION"
-.sp
-\fBAnsible\fR is an extra\-simple tool/framework/API for doing \*(Aqremote things\*(Aq over SSH\&.
-.SH "ARGUMENTS"
-.PP
-\fBhost\-pattern\fR
-.RS 4
-A name of a group in the inventory file, a shell\-like glob selecting hosts in inventory file, or any combination of the two separated by semicolons\&.
-.RE
-.SH "OPTIONS"
-.PP
-\fB\-a\fR \*(Aq\fIARGUMENTS\fR\*(Aq, \fB\-\-args=\fR\*(Aq\fIARGUMENTS\fR\*(Aq
-.RS 4
-The
-\fIARGUMENTS\fR
-to pass to the module\&.
-.RE
-.PP
-\fB\-\-ask\-become\-pass\fR
-.RS 4
-Ask for privilege escalation password\&.
-.RE
-.PP
-\fB\-k\fR, \fB\-\-ask\-pass\fR
-.RS 4
-Prompt for the SSH password instead of assuming key\-based authentication with ssh\-agent\&.
-.RE
-.PP
-\fB\-\-ask\-su\-pass\fR
-.RS 4
-Prompt for su password (deprecated, use become)\&.
-.RE
-.PP
-\fB\-K\fR, \fB\-\-ask\-sudo\-pass\fR
-.RS 4
-Prompt for the password to use with \-\-sudo, if any\&.
-.RE
-.PP
-\fB\-\-ask\-vault\-pass\fR
-.RS 4
-Prompt for vault password\&.
-.RE
-.PP
-\fB\-B\fR \fINUM\fR, \fB\-\-background=\fR\fINUM\fR
-.RS 4
-Run commands in the background, killing the task after
-\fINUM\fR
-seconds\&.
-.RE
-.PP
-\fB\-\-become\-method=\fR\fIBECOME_METHOD\fR
-.RS 4
-Privilege escalation method to use (default=sudo), valid choices: [ sudo | su | pbrun | pfexec | runas | doas ]
-.RE
-.PP
-\fB\-\-become\-user=\fR\fIBECOME_USER\fR
-.RS 4
-Run operations as this user (default=None)\&.
-.RE
-.PP
-\fB\-C\fR, \fB\-\-check\fR
-.RS 4
-Don\(cqt make any changes; instead try to predict some of the changes that may occur\&.
-.RE
-.PP
-\fB\-c\fR \fICONNECTION\fR, \fB\-\-connection=\fR\fICONNECTION\fR
-.RS 4
-Connection type to use\&. Possible options are
-\fIparamiko\fR
-(SSH),
-\fIssh\fR, and
-\fIlocal\fR\&.
-\fIlocal\fR
-is mostly useful for crontab or kickstarts\&.
-.RE
-.PP
-\fB\-e\fR \fIEXTRA_VARS*, \fR\fI\fB\-\-extra\-vars=\fR\fR\fI\*(AqEXTRA_VARS\fR
-.RS 4
-Set additional variables as key=value or YAML/JSON\&.
-.RE
-.PP
-\fB\-f\fR \fINUM\fR, \fB\-\-forks=\fR\fINUM\fR
-.RS 4
-Level of parallelism\&.
-\fINUM\fR
-is specified as an integer, the default is 5\&.
-.RE
-.PP
-\fB\-h\fR, \fB\-\-help\fR
-.RS 4
-Show help message and exit\&.
-.RE
-.PP
-\fB\-i\fR \fIPATH\fR, \fB\-\-inventory=\fR\fIPATH\fR
-.RS 4
-The
-\fIPATH\fR
-to the inventory hosts file, which defaults to
-\fI/etc/ansible/hosts\fR\&.
-.RE
-.PP
-\fB\-l\fR \fISUBSET\fR, \fB\-\-limit=\fR\fISUBSET\fR
-.RS 4
-Further limits the selected host/group patterns\&.
-.RE
-.PP
-\fB\-l\fR \fI~REGEX\fR, \fB\-\-limit=\fR\fI~REGEX\fR
-.RS 4
-Further limits hosts with a regex pattern\&.
-.RE
-.PP
-\fB\-\-list\-hosts\fR
-.RS 4
-Outputs a list of matching hosts; does not execute anything else\&.
-.RE
-.PP
-\fB\-m\fR \fINAME\fR, \fB\-\-module\-name=\fR\fINAME\fR
-.RS 4
-Execute the module called
-\fINAME\fR\&.
-.RE
-.PP
-\fB\-M\fR \fIDIRECTORY\fR, \fB\-\-module\-path=\fR\fIDIRECTORY\fR
-.RS 4
-The
-\fIDIRECTORY\fR
-search path to load modules from\&. The default is
-\fI/usr/share/ansible\fR\&. This can also be set with the ANSIBLE_LIBRARY environment variable\&.
-.RE
-.PP
-\fB\-o\fR, \fB\-\-one\-line\fR
-.RS 4
-Try to output everything on one line\&.
-.RE
-.PP
-\fB\-P\fR \fINUM\fR, \fB\-\-poll=\fR\fINUM\fR
-.RS 4
-Poll a background job every
-\fINUM\fR
-seconds\&. Requires
-\fB\-B\fR\&.
-.RE
-.PP
-\fB\-\-private\-key=\fR\fIPRIVATE_KEY_FILE\fR
-.RS 4
-Use this file to authenticate the connection\&.
-.RE
-.PP
-\fB\-S\fR, \fB\-\-su\fR
-.RS 4
-Run operations with su (deprecated, use become)\&.
-.RE
-.PP
-\fB\-R\fR \fISU_USER\fR, \fB\-\-se\-user=\fR\fISUDO_USER\fR
-.RS 4
-Run operations with su as this user (default=root) (deprecated, use become)
-.RE
-.PP
-\fB\-s\fR, \fB\-\-sudo\fR
-.RS 4
-Run the command as the user given by \-u and sudo to root\&.
-.RE
-.PP
-\fB\-U\fR \fISUDO_USERNAME\fR, \fB\-\-sudo\-user=\fR\fISUDO_USERNAME\fR
-.RS 4
-Sudo to
-\fISUDO_USERNAME\fR
-instead of root\&. Implies \-\-sudo\&.
-.RE
-.PP
-\fB\-t\fR \fIDIRECTORY\fR, \fB\-\-tree=\fR\fIDIRECTORY\fR
-.RS 4
-Save contents in this output
-\fIDIRECTORY\fR, with the results saved in a file named after each host\&.
-.RE
-.PP
-\fB\-T\fR \fISECONDS\fR, \fB\-\-timeout=\fR\fISECONDS\fR
-.RS 4
-Connection timeout to use when trying to talk to hosts, in
-\fISECONDS\fR\&.
-.RE
-.PP
-\fB\-u\fR \fIUSERNAME\fR, \fB\-\-user=\fR\fIUSERNAME\fR
-.RS 4
-Use this remote
-\fIUSERNAME\fR
-instead of the current user\&.
-.RE
-.PP
-\fB\-\-vault\-password\-file=\fR\fIVAULT_PASSWORD_FILE\fR
-.RS 4
-Vault password file\&.
-.RE
-.PP
-\fB\-v\fR, \fB\-\-verbose\fR
-.RS 4
-Verbose mode, more output from successful actions will be shown\&. Give up to three times for more output\&.
-.RE
-.PP
-\fB\-\-version\fR
-.RS 4
-Show program version number and exit\&.
-.RE
-.SH "INVENTORY"
-.sp
-Ansible stores the hosts it can potentially operate on in an inventory file\&. The syntax is one host per line\&. Groups headers are allowed and are included on their own line, enclosed in square brackets that start the line\&.
-.sp
-Ranges of hosts are also supported\&. For more information and additional options, see the documentation on http://docs\&.ansible\&.com/\&.
-.SH "FILES"
-.sp
-/etc/ansible/hosts \(em Default inventory file
-.sp
-/usr/share/ansible/ \(em Default module library
-.sp
-/etc/ansible/ansible\&.cfg \(em Config file, used if present
-.sp
-~/\&.ansible\&.cfg \(em User config file, overrides the default config if present
-.SH "ENVIRONMENT"
-.sp
-The following environment variables may be specified\&.
-.sp
-ANSIBLE_INVENTORY  \(em Override the default ansible inventory file
-.sp
-ANSIBLE_LIBRARY \(em Override the default ansible module library path
-.sp
-ANSIBLE_CONFIG \(em Override the default ansible config file
-.SH "AUTHOR"
-.sp
-Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
-.SH "COPYRIGHT"
-.sp
-Copyright \(co 2012, Michael DeHaan
-.sp
-Ansible is released under the terms of the GPLv3 License\&.
-.SH "SEE ALSO"
-.sp
-\fBansible\-playbook\fR(1), \fBansible\-pull\fR(1), \fBansible\-doc\fR(1)
-.sp
-Extensive documentation is available in the documentation site: http://docs\&.ansible\&.com\&. IRC and mailing list info can be found in file CONTRIBUTING\&.md, available in: https://github\&.com/ansible/ansible
-.SH "AUTHOR"
-.PP
-\fB:doctype:manpage\fR
-.RS 4
-Author.
-.RE
diff --git a/docs/man/man1/ansible.1.asciidoc.in b/docs/man/man1/ansible.1.asciidoc.in
index 07172ffd9b..4cabe6c1dc 100644
--- a/docs/man/man1/ansible.1.asciidoc.in
+++ b/docs/man/man1/ansible.1.asciidoc.in
@@ -7,19 +7,19 @@ ansible(1)
 
 NAME
 ----
-ansible - run a command somewhere else
+ansible - run a task on a target host(s)
 
 
 SYNOPSIS
 --------
-ansible <host-pattern> [-f forks] [-m module_name] [-a args]
+ansible <host-pattern> [-m module_name] [-a args] [options]
 
 
 DESCRIPTION
 -----------
 
-*Ansible* is an extra-simple tool/framework/API for doing \'remote things' over
-SSH.
+*Ansible* is an extra-simple tool/framework/API for doing \'remote things'.
+This is the adhoc command that allows for a \'single task playbook' run.
 
 
 ARGUMENTS
@@ -27,9 +27,8 @@ ARGUMENTS
 
 *host-pattern*::
 
-A name of a group in the inventory file, a shell-like glob selecting
-hosts in inventory file, or any combination of the two separated by
-semicolons.
+A name of a group in the inventory, a shell-like glob selecting
+hosts in inventory or any combination of the two separated by commas.
 
 OPTIONS
 -------
@@ -40,19 +39,20 @@ The 'ARGUMENTS' to pass to the module.
 
 *--ask-become-pass*::
 
-Ask for privilege  escalation password.
+Ask for privilege escalation password.
 
 *-k*, *--ask-pass*::
 
-Prompt for the SSH password instead of assuming key-based authentication with ssh-agent.
+Prompt for the connection password, if it is needed for the transport used.
+For example, using ssh and not having  a key-based authentication with ssh-agent.
 
 *--ask-su-pass*::
 
-Prompt for su password (deprecated, use become).
+Prompt for su password, used with --su (deprecated, use become).
 
 *-K*, *--ask-sudo-pass*::
 
-Prompt for the password to use with --sudo, if any.
+Prompt for the password to use with --sudo, if any (deprecated, use become).
 
 *--ask-vault-pass*::
 
@@ -69,20 +69,24 @@ valid choices: [ sudo | su | pbrun | pfexec | runas | doas ]
 
 *--become-user=*'BECOME_USER'::
 
-Run operations as this user (default=None).
+Run operations as this user (default=root).
 
 *-C*, *--check*::
 
-Don't make any changes; instead try to predict some of the changes that may occur.
+Do not make any changes on the remote system, but test resources to see what might
+have changed.  Note this can not scan all possible resource types and is only
+a simulation.
 
 *-c* 'CONNECTION', *--connection=*'CONNECTION'::
 
-Connection type to use.  Possible options are 'paramiko' (SSH), 'ssh',
+Connection type to use.  Most common options are 'paramiko' (SSH), 'ssh', 'winrm'
 and 'local'.  'local' is mostly useful for crontab or kickstarts.
 
-*-e* 'EXTRA_VARS*, *--extra-vars=*'EXTRA_VARS'::
+*-e* 'EXTRA_VARS, *--extra-vars=*'EXTRA_VARS'::
 
-Set additional variables as key=value or YAML/JSON.
+Extra variables to inject into a playbook, in key=value key=value format or
+as quoted YAML/JSON (hashes and arrays). To load variables from a file, specify
+the file preceded by @ (e.g. @vars.yml).
 
 *-f* 'NUM', *--forks=*'NUM'::
 
@@ -94,15 +98,13 @@ Show help message and exit.
 
 *-i* 'PATH', *--inventory=*'PATH'::
 
-The 'PATH' to the inventory hosts file, which defaults to '/etc/ansible/hosts'.
+The 'PATH' to the inventory, which defaults to '/etc/ansible/hosts'.
+Alternatively you can use a comma separated list of hosts or single host with traling comma 'host,'.
 
 *-l* 'SUBSET', *--limit=*'SUBSET'::
 
 Further limits the selected host/group patterns.
-
-*-l* '\~REGEX', *--limit=*'~REGEX'::
-
-Further limits hosts with a regex pattern.
+You can prefix it with '~' to indicate that the patter in a regex.
 
 *--list-hosts*::
 
@@ -136,12 +138,11 @@ Run operations with su (deprecated, use become).
 
 *-R* 'SU_USER', *--se-user=*'SUDO_USER'::
 
-Run operations with su as this user (default=root)
-(deprecated, use become)
+Run operations with su as this user (default=root) (deprecated, use become).
 
 *-s*, *--sudo*::
 
-Run the command as the user given by -u and sudo to root.
+Run the command as the user given by -u and sudo to root (deprecated, use become).
 
 *--ssh-common-args=*''-o ProxyCommand="ssh -W %h:%p ..." ...''::
 
@@ -163,7 +164,7 @@ Add the specified arguments to any ssh command-line.
 
 *-U* 'SUDO_USERNAME', *--sudo-user=*'SUDO_USERNAME'::
 
-Sudo to 'SUDO_USERNAME' instead of root.  Implies --sudo.
+Sudo to 'SUDO_USERNAME' default is root. (deprecated, use become).
 
 *-t* 'DIRECTORY', *--tree=*'DIRECTORY'::
 
@@ -176,16 +177,18 @@ Connection timeout to use when trying to talk to hosts, in 'SECONDS'.
 
 *-u* 'USERNAME', *--user=*'USERNAME'::
 
-Use this remote 'USERNAME' instead of the current user.
+Use this 'USERNAME' to login to the target host, instead of the current user.
 
 *--vault-password-file=*'VAULT_PASSWORD_FILE'::
 
-Vault password file.
+A file containing the vault password to be used during the decryption of vault encrypted files.
+Be sure to keep this file secured if it is used. If the file is executable,
+it will be run and its standard output will be used as the password.
 
 *-v*, *--verbose*::
 
-Verbose mode, more output from successful actions will be shown. Give
-up to three times for more output.
+Verbose mode, more output from successful actions will be shown.
+Give up to three times for more output.
 
 *--version*::
 
@@ -194,24 +197,14 @@ Show program version number and exit.
 INVENTORY
 ---------
 
-Ansible stores the hosts it can potentially operate on in an inventory
-file. The syntax is one host per line.  Groups headers are allowed and
-are included on their own line, enclosed in square brackets that
-start the line.
+Ansible stores the hosts it can potentially operate on in an inventory.
+This can be an ini-like file, a script, directory or a list.
+The ini syntax is one host per line.  Groups headers are allowed and
+are included on their own line, enclosed in square brackets that start the line.
 
 Ranges of hosts are also supported.  For more information and
 additional options, see the documentation on http://docs.ansible.com/.
 
-FILES
------
-
-/etc/ansible/hosts -- Default inventory file
-
-/usr/share/ansible/ -- Default module library
-
-/etc/ansible/ansible.cfg -- Config file, used if present
-
-~/.ansible.cfg -- User config file, overrides the default config if present
 
 ENVIRONMENT
 -----------
@@ -224,26 +217,39 @@ ANSIBLE_LIBRARY -- Override the default ansible module library path
 
 ANSIBLE_CONFIG -- Override the default ansible config file
 
+Many more are available for most options in ansible.cfg
+
+
+FILES
+-----
+
+/etc/ansible/hosts -- Default inventory file
+
+/usr/share/ansible/ -- Default module library
+
+/etc/ansible/ansible.cfg -- Config file, used if present
+
+~/.ansible.cfg -- User config file, overrides the default config if present
+
 
 AUTHOR
 ------
 
-Ansible was originally written by Michael DeHaan. See the AUTHORS file
-for a complete list of contributors.
+Ansible was originally written by Michael DeHaan.
+See the AUTHORS file for a complete list of contributors.
 
 
 COPYRIGHT
 ---------
 
 Copyright © 2012, Michael DeHaan
-
 Ansible is released under the terms of the GPLv3 License.
 
 
 SEE ALSO
 --------
 
-*ansible-playbook*(1), *ansible-pull*(1), *ansible-doc*(1)
+*ansible-playbook*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-vault*(1), *ansible-galaxy*(1)
 
 Extensive documentation is available in the documentation site:
 <http://docs.ansible.com>. IRC and mailing list info can be found