From 446ba1795a47ee8ecd74a649ace95db6c5df2f69 Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Fri, 23 Mar 2012 22:29:51 -0400 Subject: [PATCH] Show when options require arguments in the man pages. --- docs/man/man1/ansible-playbook.1 | 40 ++++++++---- docs/man/man1/ansible-playbook.1.asciidoc | 21 +++--- docs/man/man1/ansible.1 | 79 ++++++++++++++++------- docs/man/man1/ansible.1.asciidoc | 46 ++++++------- 4 files changed, 118 insertions(+), 68 deletions(-) diff --git a/docs/man/man1/ansible-playbook.1 b/docs/man/man1/ansible-playbook.1 index 5d7160d57e..b9bef5cdcf 100644 --- a/docs/man/man1/ansible-playbook.1 +++ b/docs/man/man1/ansible-playbook.1 @@ -1,13 +1,22 @@ '\" t .\" Title: ansible-playbook .\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/31/2012 +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" Date: 03/23/2012 .\" Manual: System administration commands .\" Source: Ansible 0.0.1 .\" Language: English .\" -.TH "ANSIBLE\-PLAYBOOK" "1" "03/31/2012" "Ansible 0\&.0\&.1" "System administration commands" +.TH "ANSIBLE\-PLAYBOOK" "1" "03/23/2012" "Ansible 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 .\" ----------------------------------------------------------------- @@ -34,19 +43,27 @@ The names of one or more YAML format files to run as ansible playbooks\&. .RE .SH "OPTIONS" .PP -\fB\-i\fR, \fB\-\-inventory\fR +\fB\-i\fR \fIPATH\fR, \fB\-\-inventory=\fR\fIPATH\fR .RS 4 -Path to the inventory hosts file, which defaults to /etc/ansible/hosts\&. +The +\fIPATH\fR +to the inventory hosts file, which defaults to +\fI/etc/ansible/hosts\fR\&. .RE .PP -\fB\-M\fR, \fB\-\-module\-path\fR +\fB\-M\fR \fIDIRECTORY\fR, \fB\-\-module\-path=\fR\fIDIRECTORY\fR .RS 4 -Where to load modules from\&. The default is /usr/share/ansible +The +\fIDIRECTORY\fR +to load modules from\&. The default is +\fI/usr/share/ansible\fR\&. .RE .PP -\fB\-f\fR, \fB\-\-forks\fR +\fB\-f\fR \fINUM\fR, \fB\-\-forks=\fR\fINUM\fR .RS 4 -Desired level of parallelism\&. Default 5\&. +Level of parallelism\&. +\fINUM\fR +is specified as an integer, the default is 5\&. .RE .PP \fB\-k\fR, \fB\-\-ask\-pass\fR @@ -54,9 +71,10 @@ Desired level of parallelism\&. Default 5\&. Prompt for the SSH password instead of assuming key\-based authentication with ssh\-agent\&. .RE .PP -\fB\-T\fR, \fB\-\-timeout\fR +\fB\-T\fR \fISECONDS\fR, \fB\-\-timeout=\fR\fISECONDS\fR .RS 4 -Connection timeout to use when trying to talk to hosts, in seconds\&. +Connection timeout to use when trying to talk to hosts, in +\fISECONDS\fR\&. .RE .SH "ENVIRONMENT" .sp diff --git a/docs/man/man1/ansible-playbook.1.asciidoc b/docs/man/man1/ansible-playbook.1.asciidoc index aa400120af..6a54b4353e 100644 --- a/docs/man/man1/ansible-playbook.1.asciidoc +++ b/docs/man/man1/ansible-playbook.1.asciidoc @@ -18,8 +18,9 @@ ansible-playbook ... [options] DESCRIPTION ----------- -*Ansible playbooks* 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. +*Ansible playbooks* 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. ARGUMENTS @@ -34,19 +35,19 @@ OPTIONS ------- -*-i*, *--inventory*:: +*-i* 'PATH', *--inventory=*'PATH':: -Path to the inventory hosts file, which defaults to /etc/ansible/hosts. +The 'PATH' to the inventory hosts file, which defaults to '/etc/ansible/hosts'. -*-M*, *--module-path*:: +*-M* 'DIRECTORY', *--module-path=*'DIRECTORY':: -Where to load modules from. The default is /usr/share/ansible +The 'DIRECTORY' to load modules from. The default is '/usr/share/ansible'. -*-f*, *--forks*:: +*-f* 'NUM', *--forks=*'NUM':: -Desired level of parallelism. Default 5. +Level of parallelism. 'NUM' is specified as an integer, the default is 5. *-k*, *--ask-pass*:: @@ -54,9 +55,9 @@ Desired level of parallelism. Default 5. Prompt for the SSH password instead of assuming key-based authentication with ssh-agent. -*-T*, *--timeout*:: +*-T* 'SECONDS', *--timeout=*'SECONDS':: -Connection timeout to use when trying to talk to hosts, in seconds. +Connection timeout to use when trying to talk to hosts, in 'SECONDS'. ENVIRONMENT diff --git a/docs/man/man1/ansible.1 b/docs/man/man1/ansible.1 index abeaabe4b5..b0273fa0da 100644 --- a/docs/man/man1/ansible.1 +++ b/docs/man/man1/ansible.1 @@ -1,13 +1,22 @@ '\" t .\" Title: ansible .\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 03/31/2012 +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" Date: 03/23/2012 .\" Manual: System administration commands .\" Source: Ansible 0.0.1 .\" Language: English .\" -.TH "ANSIBLE" "1" "03/31/2012" "Ansible 0\&.0\&.1" "System administration commands" +.TH "ANSIBLE" "1" "03/23/2012" "Ansible 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 .\" ----------------------------------------------------------------- @@ -25,38 +34,49 @@ ansible \- run a command somewhere else ansible [\-f forks] [\-m module_name] [\-a args] .SH "DESCRIPTION" .sp -\fBAnsible\fR is an extra\-simple tool/framework/API for doing \'remote things\' over SSH\&. +\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 seperated by semicolons\&. +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\-i\fR, \fB\-\-inventory\fR +\fB\-i\fR \fIPATH\fR, \fB\-\-inventory=\fR\fIPATH\fR .RS 4 -Path to the inventory hosts file, which defaults to /etc/ansible/hosts\&. +The +\fIPATH\fR +to the inventory hosts file, which defaults to +\fI/etc/ansible/hosts\fR\&. .RE .PP -\fB\-f\fR, \fB\-\-forks\fR +\fB\-f\fR \fINUM\fR, \fB\-\-forks=\fR\fINUM\fR .RS 4 -Level of parallelism\&. Specify as an integer, the default is 5\&. +Level of parallelism\&. +\fINUM\fR +is specified as an integer, the default is 5\&. .RE .PP -\fB\-m\fR, \fB\-\-module\-name\fR +\fB\-m\fR \fINAME\fR, \fB\-\-module\-name=\fR\fINAME\fR .RS 4 -Module name to execute\&. +Execute the module called +\fINAME\fR\&. .RE .PP -\fB\-M\fR, \fB\-\-module\-path\fR +\fB\-M\fR \fIDIRECTORY\fR, \fB\-\-module\-path=\fR\fIDIRECTORY\fR .RS 4 -Where to load modules from\&. The default is /usr/share/ansible +The +\fIDIRECTORY\fR +to load modules from\&. The default is +\fI/usr/share/ansible\fR\&. .RE .PP -\fB\-a\fR, \fB\-\-args\fR +\fB\-a\fR \*(Aq\fIARGUMENTS\fR\*(Aq, \fB\-\-args=\fR\*(Aq\fIARGUMENTS\fR\*(Aq .RS 4 -Arguments to pass to the module +The +\fIARGUMENTS\fR +to pass to the module\&. .RE .PP \fB\-k\fR, \fB\-\-ask\-pass\fR @@ -69,29 +89,38 @@ Prompt for the SSH password instead of assuming key\-based authentication with s Try to output everything on one line\&. .RE .PP -\fB\-t\fR, \fB\-\-tree\fR +\fB\-t\fR \fIDIRECTORY\fR, \fB\-\-tree=\fR\fIDIRECTORY\fR .RS 4 -Save contents in this output directory, with the results named in a file named after each host\&. +Save contents in this output +\fIDIRECTORY\fR, with the results saved in a file named after each host\&. .RE .PP -\fB\-T\fR, \fB\-\-timeout\fR +\fB\-T\fR \fISECONDS\fR, \fB\-\-timeout=\fR\fISECONDS\fR .RS 4 -Connection timeout to use when trying to talk to hosts, in seconds\&. +Connection timeout to use when trying to talk to hosts, in +\fISECONDS\fR\&. .RE .PP -\fB\-B\fR, \fB\-\-background\fR +\fB\-B\fR \fINUM\fR, \fB\-\-background=\fR\fINUM\fR .RS 4 -Runs commands in the background, killing the task after N seconds\&. +Run commands in the background, killing the task after +\fINUM\fR +seconds\&. .RE .PP -\fB\-P\fR, \fB\-\-poll\fR +\fB\-P\fR \fINUM\fR, \fB\-\-poll=\fR\fINUM\fR .RS 4 -Poll a background job every (this many) seconds\&. Requires \-B\&. +Poll a background job every +\fINUM\fR +seconds\&. Requires +\fB\-B\fR\&. .RE .PP -\fB\-u\fR, \fB\-\-remote\-user\fR +\fB\-u\fR \fIUSERNAME\fR, \fB\-\-remote\-user=\fR\fIUSERNAME\fR .RS 4 -Use this remote username instead of root +Use this remote +\fIUSERNAME\fR +instead of root\&. .RE .SH "INVENTORY" .sp diff --git a/docs/man/man1/ansible.1.asciidoc b/docs/man/man1/ansible.1.asciidoc index 1228926cd7..c7604cd328 100644 --- a/docs/man/man1/ansible.1.asciidoc +++ b/docs/man/man1/ansible.1.asciidoc @@ -27,37 +27,38 @@ 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 seperated by semicolons. +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. OPTIONS ------- -*-i*, *--inventory*:: +*-i* 'PATH', *--inventory=*'PATH':: -Path to the inventory hosts file, which defaults to /etc/ansible/hosts. +The 'PATH' to the inventory hosts file, which defaults to '/etc/ansible/hosts'. -*-f*, *--forks*:: +*-f* 'NUM', *--forks=*'NUM':: -Level of parallelism. Specify as an integer, the default is 5. +Level of parallelism. 'NUM' is specified as an integer, the default is 5. -*-m*, *--module-name*:: +*-m* 'NAME', *--module-name=*'NAME':: -Module name to execute. +Execute the module called 'NAME'. -*-M*, *--module-path*:: +*-M* 'DIRECTORY', *--module-path=*'DIRECTORY':: -Where to load modules from. The default is /usr/share/ansible +The 'DIRECTORY' to load modules from. The default is '/usr/share/ansible'. -*-a*, *--args*:: +*-a* \'_ARGUMENTS_', *--args=*\'_ARGUMENTS_':: -Arguments to pass to the module +The 'ARGUMENTS' to pass to the module. *-k*, *--ask-pass*:: @@ -70,29 +71,30 @@ Prompt for the SSH password instead of assuming key-based authentication with ss Try to output everything on one line. -*-t*, *--tree*:: +*-t* 'DIRECTORY', *--tree=*'DIRECTORY':: -Save contents in this output directory, with the results named in a file named after each host. +Save contents in this output 'DIRECTORY', with the results saved in a +file named after each host. -*-T*, *--timeout*:: +*-T* 'SECONDS', *--timeout=*'SECONDS':: -Connection timeout to use when trying to talk to hosts, in seconds. +Connection timeout to use when trying to talk to hosts, in 'SECONDS'. -*-B*, *--background*:: +*-B* 'NUM', *--background=*'NUM':: -Runs commands in the background, killing the task after N seconds. +Run commands in the background, killing the task after 'NUM' seconds. -*-P*, *--poll*:: +*-P* 'NUM', *--poll=*'NUM':: -Poll a background job every (this many) seconds. Requires -B. +Poll a background job every 'NUM' seconds. Requires *-B*. -*-u*, *--remote-user*:: +*-u* 'USERNAME', *--remote-user=*'USERNAME':: -Use this remote username instead of root +Use this remote 'USERNAME' instead of root. INVENTORY