diff --git a/docs/man/man1/ansible.1 b/docs/man/man1/ansible.1
index 2b22c0aa775..f5bb1a3be86 100644
--- a/docs/man/man1/ansible.1
+++ b/docs/man/man1/ansible.1
@@ -22,30 +22,32 @@
 ansible \- run a command somewhere else
 .SH "SYNOPSIS"
 .sp
-ansible [\-H hosts_path] [\-L library_path] [\-f forks] [\-n module_name] [\-a [args1 [args2 \&...]]] [\-p host_pattern] [\-u remote_user]
+ansible [\-f forks] [\-p pattern ] [\-u remote_user] [\-n module_name] [\-a [args1 [args2 \&...]]]
 .SH "DESCRIPTION"
 .sp
-\fBAnsible\fR is an extra\-simple Python API for doing \'remote things\' over SSH\&.
+\fBAnsible\fR is an extra\-simple tool/framework/API for doing \'remote things\' over SSH\&.
 .SH "OPTIONS"
 .PP
-\fB\-P\fR, \fB\-\-askpass\fR
+\fB\-k\fR, \fB\-\-ask\-pass\fR
 .RS 4
-Ask the user to input the ssh password for connecting\&.
+Ask the user to input the ssh password for connecting\&. Generally using ssh\-agent instead is preferred\&.
 .RE
 .PP
-\fB\-H\fR, \fB\-\-host\-list\fR
+\fB\-l\fR, \fB\-\-host\-list\fR
 .RS 4
-Path to hosts list\&.
+Path to hosts list, which defaults to /etc/ansible/hosts\&. Users can use multiple files to emulate groups of systems\&.
 .RE
 .PP
-\fB\-L\fR, \fB\-\-library\fR
+\fB\-m\fR, \fB\-\-module\-path\fR
 .RS 4
-Path to module library\&.
+Override the path to module library, which defaults to /usr/share/ansible\&. The module library contains runnable modules that do
+\fIthings\fR
+to remote hosts\&. See ansible\-modules(5) for a list of those that bundled with Ansible\&.
 .RE
 .PP
 \fB\-f\fR, \fB\-\-forks\fR
 .RS 4
-Level of parallelism\&. Specify as an integer\&.
+Level of parallelism\&. Specify as an integer, the default is 3\&. If set to "1" debugging for certain classes of internal errors may become easier\&.
 .RE
 .PP
 \fB\-n\fR, \fB\-\-name\fR
@@ -55,21 +57,12 @@ Module name to execute\&.
 .PP
 \fB\-a\fR, \fB\-\-args\fR
 .RS 4
-Arguments to module\&.
+Arguments to module, as a single string\&. Be sure to observe proper shell quoting rules\&. How these are handled are up to the module, but most modules take "key=value" pairs delimited by spaces\&.
 .RE
 .PP
 \fB\-p\fR, \fB\-\-pattern\fR
 .RS 4
-Hostname pattern\&. Accepts shell\-like globs\&.
-.RE
-.PP
-\fB\-r\fR, \fB\-\-run\-playbook\fR
-.RS 4
-Playbook file to run\&. Replaces the
-\fB\-n\fR
-and
-\fB\-a\fR
-options\&.
+Hostname pattern\&. Accepts shell\-like globs which can be seperated with ";" The default is "*" which matches all hosts in the ansible hosts file\&.
 .RE
 .PP
 \fB\-u\fR, \fB\-\-remote\-user\fR
@@ -96,6 +89,8 @@ Copyright \(co 2012, Michael DeHaan
 Ansible is released under the terms of the GPLv3 License\&.
 .SH "SEE ALSO"
 .sp
-\fBansible\-modules\fR(5), \fBansible\-playbook\fR(5)
+\fBansible\-modules\fR(5),
+.sp
+\fBansible\-playbook\fR(5),
 .sp
 Ansible home page: https://github\&.com/mpdehaan/ansible/
diff --git a/docs/man/man5/ansible-playbook.5 b/docs/man/man5/ansible-playbook.5
index 3e265507581..3f0a02a6107 100644
--- a/docs/man/man5/ansible-playbook.5
+++ b/docs/man/man5/ansible-playbook.5
@@ -2,12 +2,12 @@
 .\"     Title: ansible-modules
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
-.\"      Date: 02/27/2012
+.\"      Date: 02/28/2012
 .\"    Manual: System administration commands
 .\"    Source: Ansible-playbook 0.0.1
 .\"  Language: English
 .\"
-.TH "ANSIBLE\-MODULES" "5" "02/27/2012" "Ansible\-playbook 0\&.0\&.1" "System administration commands"
+.TH "ANSIBLE\-MODULES" "5" "02/28/2012" "Ansible\-playbook 0\&.0\&.1" "System administration commands"
 .\" -----------------------------------------------------------------
 .\" * set default formatting
 .\" -----------------------------------------------------------------
@@ -22,10 +22,10 @@
 ansible-playbook \- format and function of an ansible playbook file
 .SH "DESCRIPTION"
 .sp
-Ansible ships with a ansible\-playbook tool for running playbooks\&. Playbooks can represent frequent tasks, desired system configurations, or deployment processes\&.
+Ansible ships with \fIansible\-playbook\fR, a tool for running playbooks\&. Playbooks can represent frequent tasks, desired system configurations, or deployment processes\&.
 .SH "FORMAT"
 .sp
-Playbooks are currently writeable in YAML\&. Other formats (JSON?) may be supported in the future\&.
+Playbooks are written in YAML\&.
 .SH "EXAMPLE"
 .sp
 see https://github\&.com/mpdehaan/ansible/blob/master/examples/playbook\&.yml
@@ -35,7 +35,7 @@ Here\(cqs what the above example will do\&.
 .sp
 For all hosts in /etc/ansible/hosts (one host per line) that are named \fIwebserver\-anything\fR, first write a JSON file into /etc/ansible/setup on each remote system with the values max_clients and http_port\&.
 .sp
-Next, use a Jinja2 template locally residing at /srv/templates/httpd\&.j2 to write the Apache config file on each host to the path /etc/httpd/conf, using the previous values\&.
+Next, use a Jinja2 template locally residing at /srv/templates/httpd\&.j2 to write the Apache config file on each host to the path /etc/httpd\&.conf, using the previous values\&.
 .sp
 We\(cqll ensure that apache is running if stopped\&.
 .sp