Merge pull request #32 from tbielawa/DocsFixin

Docs fixin

Makefile

@@ -2,7 +2,7 @@
 
 ASCII2MAN = a2x -D $(dir $@) -d manpage -f manpage $<
 ASCII2HTMLMAN = a2x -D docs/html/man/ -d manpage -f xhtml
-MANPAGES := docs/man/man1/ansible.1 docs/man/man5/ansible-modules.1 docs/man/man5/ansible-playbook.1
+MANPAGES := docs/man/man1/ansible.1 docs/man/man5/ansible-modules.5 docs/man/man5/ansible-playbook.5
 SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")
 
 docs: manuals

docs/man/man1/ansible.1

@@ -2,12 +2,12 @@
 .\"     Title: ansible
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\"      Date: 02/24/2012
+.\"      Date: 02/26/2012
 .\"    Manual: System administration commands
 .\"    Source: Ansible 0.0.1
 .\"  Language: English
 .\"
-.TH "ANSIBLE" "1" "02/24/2012" "Ansible 0\&.0\&.1" "System administration commands"
+.TH "ANSIBLE" "1" "02/26/2012" "Ansible 0\&.0\&.1" "System administration commands"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -105,4 +105,6 @@ Copyright \(co 2012, Michael DeHaan
 Ansible is released under the terms of the MIT license\&.
 .SH "SEE ALSO"
 .sp
+\fBansible\-modules\fR(5), \fBansible\-playbook\fR(5)
+.sp
 Ansible home page: https://github\&.com/mpdehaan/ansible/

docs/man/man1/ansible.1.asciidoc

@@ -106,8 +106,6 @@ Ansible is released under the terms of the MIT license.
 SEE ALSO
 --------
 
-ansible-modules (5)
+*ansible-modules*(5), *ansible-playbook*(5)
-
-ansible-playbook (5)
 
 Ansible home page: <https://github.com/mpdehaan/ansible/>

docs/man/man5/ansible-modules.5

@@ -1,7 +1,7 @@
 '\" t
 .\"     Title: ansible-modules
 .\"    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-modules 0.0.1
@@ -9,6 +9,15 @@
 .\"
 .TH "ANSIBLE\-MODULES" "5" "02/26/2012" "Ansible\-modules 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
@@ -29,10 +38,11 @@ Most modules other than command are idempotent, meaning they will seek to avoid
 .SH "COMMAND"
 .sp
 The command module takes the command name followed by a list of arguments, space delimited\&. This is the only module that does not use key=value style parameters\&.
-.sp
+.PP
-Example usage:
+Example usage
-.sp
+.RS 4
-"/sbin/shutdown \-t now"
+/sbin/shutdown \-t now
+.RE
 .sp
 This module does not support change hooks\&.
 .sp
@@ -60,7 +70,7 @@ Runs the discovery program \fIfacter\fR on the remote system, returning JSON dat
 .sp
 Requires that \fIfacter\fR and \fIruby\-json\fR be installed on the remote end\&.
 .sp
-This module is information only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&.
+This module is informative only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&.
 .SH "FILE"
 .sp
 Ensures the ownership and permissions of files are as desired\&.
@@ -86,7 +96,7 @@ A trivial test module, this module always returns the integer \fI1\fR on success
 .sp
 This module does not support change hooks\&.
 .sp
-This module is information only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&.
+This module is informative only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&.
 .SH "SERVICE"
 .sp
 Controls services on remote machines\&.
@@ -148,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(1) \- pending
+\fBansible\-playbook\fR(5) \- pending
 .sp
 Ansible home page: https://github\&.com/mpdehaan/ansible/

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

@@ -32,9 +32,9 @@ command
 The command module takes the command name followed by a list of arguments, space delimited.
 This is the only module that does not use key=value style parameters.
 
-Example usage:
+Example usage::
 
-"/sbin/shutdown -t now"
+/sbin/shutdown -t now
 
 This module does not support change hooks.
 
@@ -70,7 +70,7 @@ JSON data that can be useful for inventory purposes.
 
 Requires that 'facter' and 'ruby-json' be installed on the remote end.
 
-This module is information only - it takes no parameters & does not support change hooks,
+This module is informative only - it takes no parameters & does not support change hooks,
 nor does it make any changes on the system.
 
 
@@ -95,13 +95,13 @@ This module is in plan.
 ohai
 ----
 
-Similar to the facter module, this returns JSON inventory data.  Ohai data
+Similar to the facter module, this returns JSON inventory data.  Ohai
-is a bit more verbose and nested than facter.
+data is a bit more verbose and nested than facter.
 
 Requires that 'ohai' be installed on the remote end.
 
-This module is information only - it takes no parameters & does not support change hooks,
+This module is information only - it takes no parameters & does not
-nor does it make any changes on the system.
+support change hooks, nor does it make any changes on the system.
 
 
 ping
@@ -112,8 +112,8 @@ successful contact.
 
 This module does not support change hooks.
 
-This module is information only - it takes no parameters & does not support change hooks,
+This module is informative only - it takes no parameters & does not
-nor does it make any changes on the system.
+support change hooks, nor does it make any changes on the system.
 
 
 service
@@ -202,8 +202,8 @@ for a complete list of contributors.
 SEE ALSO
 --------
 
-ansible(1)
+*ansible*(1)
 
-ansible-playbook(1) - pending
+*ansible-playbook*(5) - pending
 
 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 \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-pattern:
-\fI*\fR
-hosts:
-\fI/etc/ansible/hosts\fR
-tasks:
-.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:
+.nf
+\-\-\-
+\- pattern: \*(Aq*\*(Aq
+  hosts: \*(Aq/etc/ansible/hosts\*(Aq
+  tasks:
+  \- do:
+    \- configure template & module variables for future template calls
+    \- setup http_port=80 max_clients=200
+  \- 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
-.\}
-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
@@ -106,8 +114,8 @@ for a complete list of contributors.
 SEE ALSO
 --------
 
-ansible(1)
+*ansible*(1)
 
-ansible-playbook(1) - pending
+*ansible-playbook*(5) - pending
 
 Ansible home page: <https://github.com/mpdehaan/ansible/>

examples/playbook.yml

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

setup.py

@@ -22,6 +22,10 @@ setup(name='ansible',
          ]),
          ('man/man1', [
                 'docs/man/man1/ansible.1'
+         ]),
+         ('man/man5', [
+                'docs/man/man5/ansible-modules.5',
+                'docs/man/man5/ansible-playbook.5'
          ])
       ],
       scripts=[