Update man pages. Fix formatting in playbook example. Also, YAML documents by definition start with '---', so I have added this to the example and the manpage

docs/man/man1/ansible.1

@@ -105,8 +105,6 @@ Copyright \(co 2012, Michael DeHaan
 Ansible is released under the terms of the MIT license\&.
 .SH "SEE ALSO"
 .sp
-ansible\-modules (5)
+\fBansible\-modules\fR(5), \fBansible\-playbook\fR(5)
-.sp
-ansible\-playbook (5)
 .sp
 Ansible home page: https://github\&.com/mpdehaan/ansible/

docs/man/man5/ansible-modules.5

@@ -158,8 +158,8 @@ To write your own modules, simply follow the convention of those already availab
 Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
 .SH "SEE ALSO"
 .sp
-ansible(1)
+\fBansible\fR(1)
 .sp
-ansible\-playbook(5) \- pending
+\fBansible\-playbook\fR(5) \- pending
 .sp
 Ansible home page: https://github\&.com/mpdehaan/ansible/

docs/man/man5/ansible-playbook.5

@@ -1,7 +1,7 @@
 '\" t
 .\"     Title: ansible-modules
-.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\"    Author: [see the "AUTHOR" section]
-.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
+.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
 .\"      Date: 02/26/2012
 .\"    Manual: System administration commands
 .\"    Source: Ansible-playbook 0.0.1
@@ -9,6 +9,15 @@
 .\"
 .TH "ANSIBLE\-MODULES" "5" "02/26/2012" "Ansible\-playbook 0\&.0\&.1" "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
@@ -28,163 +37,33 @@ Ansible ships with a ansible\-playbook tool for running playbooks\&. Playbooks c
 Playbooks are currently writeable in YAML\&. Other formats (JSON?) may be supported in the future\&.
 .SH "EXAMPLE"
 .sp
+.if n \{\
 .RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
 .\}
-.el \{\
+.nf
-.sp -1
+\-\-\-
-.IP \(bu 2.3
+\- pattern: \*(Aq*\*(Aq
-.\}
+  hosts: \*(Aq/etc/ansible/hosts\*(Aq
-pattern:
+  tasks:
-\fI*\fR
+  \- do:
-hosts:
+    \- configure template & module variables for future template calls
-\fI/etc/ansible/hosts\fR
+    \- setup http_port=80 max_clients=200
-tasks:
+  \- do:
+    \- write the apache config file
+    \- template src=/srv/mytemplates/httpd\&.j2 dest=/etc/httpd/conf
+    notify:
+    \- restart apache
+  \- do
+    \- ensure apache is running
+    \- service name=httpd ensure=started
+  handlers:
+    \- do:
+      \- restart apache
+      \- service name=httpd ensure=restarted
+.fi
+.if n \{\
 .RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
 .\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-do:
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-configure template & module variables for future template calls
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-setup http_port=80 max_clients=200
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-do:
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-write the apache config file
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-template src=/srv/mytemplates/httpd\&.j2 dest=/etc/httpd/conf notify:
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-restart apache
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-do
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-ensure apache is running
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-service name=httpd ensure=started handlers:
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-do:
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-restart apache
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-service name=httpd ensure=restarted
-.RE
 .SH "WHAT THE EXAMPLE MEANS"
 .sp
 Here\(cqs what the above example will do\&.
@@ -212,10 +91,13 @@ Handlers are like tasks, but are conditionally executed\&. If a module reports a
 .SH "FUTURE BEHAVIOR"
 .sp
 What the playbook run does with a host when an error is detected is currently being refined and is subject to change\&.
+.SH "AUTHOR"
+.sp
+Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
 .SH "SEE ALSO"
 .sp
-ansible(1)
+\fBansible\fR(1)
 .sp
-ansible\-playbook(1) \- pending
+\fBansible\-playbook\fR(5) \- pending
 .sp
 Ansible home page: https://github\&.com/mpdehaan/ansible/

docs/man/man5/ansible-playbook.5.asciidoc

@@ -14,19 +14,23 @@ ansible-playbook - format and function of an ansible playbook file
 DESCRIPTION
 -----------
 
-Ansible ships with a ansible-playbook tool for running playbooks.  Playbooks can represent
+Ansible ships with a ansible-playbook tool for running playbooks.
-frequent tasks, desired system configurations, or deployment processes.
+Playbooks can represent frequent tasks, desired system configurations,
+or deployment processes.
 
 
 FORMAT
 ------
 
-Playbooks are currently writeable in YAML.  Other formats (JSON?) may be supported in the future.
+Playbooks are currently writeable in YAML.  Other formats (JSON?) may
+be supported in the future.
 
 
 EXAMPLE
 -------
 
+[literal]
+---
 - pattern: '*'
   hosts: '/etc/ansible/hosts'
   tasks:
@@ -52,48 +56,52 @@ WHAT THE EXAMPLE MEANS
 
 Here's what the above example will do.
 
-For all hosts in /etc/ansible/hosts (one host per line) that are named 'webserver-anything', first
+For all hosts in /etc/ansible/hosts (one host per line) that are named
-write a JSON file into /etc/ansible/setup on each remote system with the values
+'webserver-anything', first write a JSON file into /etc/ansible/setup
-max_clients and http_port.
+on each remote system with the values max_clients and http_port.
 
-Next, use a Jinja2 template locally residing 
+Next, use a Jinja2 template locally residing at
-at /srv/mytemplates/httpd.j2 to write the Apache config file on each host
+/srv/mytemplates/httpd.j2 to write the Apache config file on each host
 to the path /etc/httpd/conf, using the previous values.
 
 Ensure that apache is running if stopped.
 
-If and only if the config file changed, note that we need to restart apache at the end of
+If and only if the config file changed, note that we need to restart
-the run, otherwise, don't bother because we already know it is running.
+apache at the end of the run, otherwise, don't bother because we
+already know it is running.
 
 
 HIGH LEVEL EXPLANATION
 ----------------------
 
-Playbooks are executed top down and can contain multiple references to patterns.
+Playbooks are executed top down and can contain multiple references to
-For instance, a playbook could do something to all webservers, then do something
+patterns.  For instance, a playbook could do something to all
-to all database servers, then do something different to all webservers again.
+webservers, then do something to all database servers, then do
+something different to all webservers again.
 
-For each pattern, the tasks in the 'tasks' list are executed in order for all
+For each pattern, the tasks in the 'tasks' list are executed in order
-hosts in the host file matching the pattern.
+for all hosts in the host file matching the pattern.
 
-For each task, a "do" statement describes what the task is and what ansible
+For each task, a "do" statement describes what the task is and what
-module to use to accomplish the task, along with any arguments.  The first
+ansible module to use to accomplish the task, along with any
-line in the "do" is the name of the task -- this will appear in any log output.
+arguments.  The first line in the "do" is the name of the task -- this
+will appear in any log output.
 
-The second line in each "do" is the module name followed by module arguments.
+The second line in each "do" is the module name followed by module
+arguments.
 
 Most modules accept key=value format arguments.
 
-Handlers are like tasks, but are conditionally executed.  If a module reports
+Handlers are like tasks, but are conditionally executed.  If a module
-a 'change', it can choose to notify a handler by name.  If notified, it will
+reports a 'change', it can choose to notify a handler by name.  If
-run only for hosts that changed.
+notified, it will run only for hosts that changed.
 
 
 FUTURE BEHAVIOR
 ---------------
 
-What the playbook run does with a host when an error is detected is currently being refined
+What the playbook run does with a host when an error is detected is
-and is subject to change. 
+currently being refined and is subject to change.
 
 
 AUTHOR

examples/playbook.yml

@@ -1,3 +1,4 @@
+---
 - pattern: '*'
   hosts: /etc/ansible/hosts
   tasks: