(#1204) Reformat help text for puppet doc and puppet agent.

Markdown changes for compatibility with Ronn, in the interest of
better manpages.

2 files changed, 163 insertions, 149 deletions

diff --git a/lib/puppet/application/agent.rb b/lib/puppet/application/agent.rb
index fa1ec58a5..fa06aae36 100644
--- a/lib/puppet/application/agent.rb
+++ b/lib/puppet/application/agent.rb
@@ -86,26 +86,30 @@ class Puppet::Application::Agent < Puppet::Application
   def help
     <<-HELP
 
-SYNOPSIS
+puppet-agent(8) -- The puppet agent daemon
 ========
-Retrieve the client configuration from the puppet master and apply it to
+
+SYNOPSIS
+--------
+Retrieves the client configuration from the puppet master and applies it to
 the local host.
 
-Currently must be run out periodically, using cron or something similar.
+This service may be run as a daemon, run periodically using cron (or something
+similar), or run interactively for testing purposes.
 
 
 USAGE
-=====
-  puppet agent  [-D|--daemonize|--no-daemonize] [-d|--debug]
-      [--detailed-exitcodes] [--disable] [--enable]
-      [-h|--help] [--certname <host name>] [-l|--logdest syslog|<file>|console]
-      [-o|--onetime] [--serve <handler>] [-t|--test] [--noop]
-      [--digest <digest>] [--fingerprint] [-V|--version]
-      [-v|--verbose] [-w|--waitforcert <seconds>]
+-----
+puppet agent  [-D|--daemonize|--no-daemonize] [-d|--debug]
+  [--detailed-exitcodes] [--disable] [--enable] [-h|--help]
+  [--certname <host name>] [-l|--logdest syslog|<file>|console]
+  [-o|--onetime] [--serve <handler>] [-t|--test] [--noop]
+  [--digest <digest>] [--fingerprint] [-V|--version]
+  [-v|--verbose] [-w|--waitforcert <seconds>]
 
 
 DESCRIPTION
-===========
+-----------
 This is the main puppet client. Its job is to retrieve the local
 machine's configuration from a remote server and apply it. In order to
 successfully communicate with the remote server, the client must have a
@@ -120,10 +124,10 @@ configuration and apply it.
 
 
 USAGE NOTES
-===========
+-----------
 'puppet agent' does its best to find a compromise between interactive
 use and daemon use. Run with no arguments and no configuration, it will
-go into the backgroun, attempt to get a signed certificate, and retrieve
+go into the background, attempt to get a signed certificate, and retrieve
 and apply its configuration every 30 minutes.
 
 Some flags are meant specifically for interactive use -- in particular,
@@ -156,7 +160,7 @@ when signing certificates).
 
 
 OPTIONS
-=======
+-------
 Note that any configuration parameter that's valid in the configuration
 file is also a valid long argument. For example, 'server' is a valid
 configuration parameter, so you can specify '--server <servername>' as
@@ -168,121 +172,122 @@ full list of acceptable parameters. A commented list of all
 configuration options can also be generated by running puppet agent with
 '--genconfig'.
 
-daemonize:          Send the process into the background. This is the
-                    default.
-
-no-daemonize:       Do not send the process into the background.
-
-debug:              Enable full debugging.
-
-digest:             Change the certificate fingerprinting digest
-                    algorithm. The default is MD5. Valid values depends
-                    on the version of OpenSSL installed, but should
-                    always at least contain MD5, MD2, SHA1 and SHA256.
-
-detailed-exitcodes: Provide transaction information via exit codes. If
-                    this is enabled, an exit code of '2' means there
-                    were changes, and an exit code of '4' means that
-                    there were failures during the transaction. This
-                    option only makes sense in conjunction with
-                    --onetime.
-
-disable:            Disable working on the local system. This puts a
-                    lock file in place, causing 'puppet agent' not to
-                    work on the system until the lock file is removed.
-                    This is useful if you are testing a configuration
-                    and do not want the central configuration to
-                    override the local state until everything is tested
-                    and committed.
-
-'puppet agent' uses the same lock file while it is running, so no more
-than one 'puppet agent' process is working at a time.
-
-'puppet agent' exits after executing this.
-
-enable:             Enable working on the local system. This removes any
-                    lock file, causing 'puppet agent' to start managing
-                    the local system again (although it will continue to
-                    use its normal scheduling, so it might not start for
-                    another half hour).
-
-'puppet agent' exits after executing this.
-
-certname:           Set the certname (unique ID) of the client. The
-                    master reads this unique identifying string, which
-                    is usually set to the node's fully-qualified domain
-                    name, to determine which configurations the node
-                    will receive. Use this option to debug setup
-                    problems or implement unusual node identification
-                    schemes.
-
-help:               Print this help message
-
-logdest:            Where to send messages. Choose between syslog, the
-                    console, and a log file. Defaults to sending
-                    messages to syslog, or the console if debugging or
-                    verbosity is enabled.
-
-no-client:          Do not create a config client. This will cause the
-                    daemon to run without ever checking for its
-                    configuration automatically, and only makes sense
-
-onetime:            Run the configuration once. Runs a single (normally
-                    daemonized) Puppet run. Useful for interactively
-                    running puppet agent when used in conjunction with
-                    the --no-daemonize option.
-
-fingerprint:        Display the current certificate or certificate
-                    signing request fingerprint and then exit. Use the
-                    '--digest' option to change the digest algorithm
-                    used.
-
-serve:              Start another type of server. By default, 'puppet
-                    agent' will start a service handler that allows
-                    authenticated and authorized remote nodes to trigger
-                    the configuration to be pulled down and applied. You
-                    can specify any handler here that does not require
-                    configuration, e.g., filebucket, ca, or resource.
-                    The handlers are in 'lib/puppet/network/handler',
-                    and the names must match exactly, both in the call
-                    to 'serve' and in 'namespaceauth.conf'.
-
-test:               Enable the most common options used for testing.
-                    These are 'onetime', 'verbose', 'ignorecache',
-                    'no-daemonize', 'no-usecacheonfailure',
-                    'detailed-exit-codes', 'no-splay', and 'show_diff'.
-
-noop:               Use 'noop' mode where the daemon runs in a no-op or
-                    dry-run mode. This is useful for seeing what changes
-                    Puppet will make without actually executing the
-                    changes.
-
-verbose:            Turn on verbose reporting.
-
-version:            Print the puppet version number and exit.
-
-waitforcert:        This option only matters for daemons that do not yet
-                    have certificates and it is enabled by default, with
-                    a value of 120 (seconds). This causes 'puppet agent'
-                    to connect to the server every 2 minutes and ask it
-                    to sign a certificate request. This is useful for
-                    the initial setup of a puppet client. You can turn
-                    off waiting for certificates by specifying a time of
-                    0.
+* --daemonize:
+  Send the process into the background. This is the default.
+
+* --no-daemonize:
+  Do not send the process into the background.
+
+* --debug:
+  Enable full debugging.
+
+* --digest:
+  Change the certificate fingerprinting digest algorithm. The default is
+  MD5. Valid values depends on the version of OpenSSL installed, but
+  should always at least contain MD5, MD2, SHA1 and SHA256.
+
+* --detailed-exitcodes:
+  Provide transaction information via exit codes. If this is enabled, an
+  exit code of '2' means there were changes, and an exit code of '4'
+  means that there were failures during the transaction. This option
+  only makes sense in conjunction with --onetime.
+
+* --disable:
+  Disable working on the local system. This puts a lock file in place,
+  causing 'puppet agent' not to work on the system until the lock file
+  is removed. This is useful if you are testing a configuration and do
+  not want the central configuration to override the local state until
+  everything is tested and committed.
+
+  'puppet agent' uses the same lock file while it is running, so no more
+  than one 'puppet agent' process is working at a time.
+
+  'puppet agent' exits after executing this.
+
+* --enable:
+  Enable working on the local system. This removes any lock file,
+  causing 'puppet agent' to start managing the local system again
+  (although it will continue to use its normal scheduling, so it might
+  not start for another half hour).
+
+  'puppet agent' exits after executing this.
+
+* --certname:
+  Set the certname (unique ID) of the client. The master reads this
+  unique identifying string, which is usually set to the node's
+  fully-qualified domain name, to determine which configurations the
+  node will receive. Use this option to debug setup problems or
+  implement unusual node identification schemes.
+
+* --help:
+  Print this help message
+
+* --logdest:
+  Where to send messages. Choose between syslog, the console, and a log
+  file. Defaults to sending messages to syslog, or the console if
+  debugging or verbosity is enabled.
+
+* --no-client:
+  Do not create a config client. This will cause the daemon to run
+  without ever checking for its configuration automatically, and only
+  makes sense
+
+* --onetime:
+  Run the configuration once. Runs a single (normally daemonized) Puppet
+  run. Useful for interactively running puppet agent when used in
+  conjunction with the --no-daemonize option.
+
+* --fingerprint:
+  Display the current certificate or certificate signing request
+  fingerprint and then exit. Use the '--digest' option to change the
+  digest algorithm used.
+
+* --serve:
+  Start another type of server. By default, 'puppet agent' will start a
+  service handler that allows authenticated and authorized remote nodes
+  to trigger the configuration to be pulled down and applied. You can
+  specify any handler here that does not require configuration, e.g.,
+  filebucket, ca, or resource. The handlers are in
+  'lib/puppet/network/handler', and the names must match exactly, both
+  in the call to 'serve' and in 'namespaceauth.conf'.
+
+* --test:
+  Enable the most common options used for testing. These are 'onetime',
+  'verbose', 'ignorecache', 'no-daemonize', 'no-usecacheonfailure',
+  'detailed-exit-codes', 'no-splay', and 'show_diff'.
+
+* --noop:
+  Use 'noop' mode where the daemon runs in a no-op or dry-run mode. This
+  is useful for seeing what changes Puppet will make without actually
+  executing the changes.
+
+* --verbose:
+  Turn on verbose reporting.
+
+* --version:
+  Print the puppet version number and exit.
+
+* --waitforcert:
+  This option only matters for daemons that do not yet have certificates
+  and it is enabled by default, with a value of 120 (seconds). This
+  causes 'puppet agent' to connect to the server every 2 minutes and ask
+  it to sign a certificate request. This is useful for the initial setup
+  of a puppet client. You can turn off waiting for certificates by
+  specifying a time of 0.
 
 
 EXAMPLE
-=======
-  puppet agent --server puppet.domain.com
+-------
+    $ puppet agent --server puppet.domain.com
 
 
 AUTHOR
-======
+------
 Luke Kanies
 
 
 COPYRIGHT
-=========
+---------
 Copyright (c) 2005, 2006 Puppet Labs, LLC Licensed under the GNU Public
 License
 
diff --git a/lib/puppet/application/doc.rb b/lib/puppet/application/doc.rb
index c7f270c8d..3bfe41653 100644
--- a/lib/puppet/application/doc.rb
+++ b/lib/puppet/application/doc.rb
@@ -53,20 +53,24 @@ class Puppet::Application::Doc < Puppet::Application
   def help
     <<-HELP
 
-SYNOPSIS
+puppet-doc(8) -- Generate Puppet documentation and references
 ========
-Generate a reference for all Puppet types. Largely meant for internal
+
+SYNOPSIS
+--------
+Generates a reference for all Puppet types. Largely meant for internal
 Puppet Labs use.
 
 
 USAGE
-=====
-  puppet doc [-a|--all] [-h|--help] [-o|--outputdir <rdoc outputdir>] [-m|--mode <text|pdf|rdoc>]
-             [-r|--reference <[type]|configuration|..>] [--charset CHARSET] [manifest-file]
+-----
+puppet doc [-a|--all] [-h|--help] [-o|--outputdir <rdoc-outputdir>]
+  [-m|--mode text|pdf|rdoc] [-r|--reference <reference-name>]
+  [--charset <charset>] [<manifest-file>]
 
 
 DESCRIPTION
-===========
+-----------
 If mode is not 'rdoc', then this command generates a Markdown document
 describing all installed Puppet types or all allowable arguments to
 puppet executables. It is largely meant for internal use and is used to
@@ -77,57 +81,62 @@ the manifests that are in 'manifestdir' and 'modulepath' configuration
 directives. The generated documentation directory is doc by default but
 can be changed with the 'outputdir' option.
 
-If the command is started with 'manifest-file' command-line arguments,
-puppet doc generate a single manifest documentation that is output on
-stdout.
+If the command is run with the name of a manifest file as an argument,
+puppet doc will output a single manifest's documentation on stdout.
 
 
 OPTIONS
-=======
-all:       Output the docs for all of the reference types. In 'rdoc'
-           modes, this also outputs documentation for all resources
+-------
+* --all:
+  Output the docs for all of the reference types. In 'rdoc'
+  modes, this also outputs documentation for all resources
 
-help:      Print this help message
+* --help:
+  Print this help message
 
-outputdir: Specifies the directory where to output the rdoc
-           documentation in 'rdoc' mode.
+* --outputdir:
+  Specifies the directory where to output the rdoc
+  documentation in 'rdoc' mode.
 
-mode:      Determine the output mode. Valid modes are 'text', 'pdf' and
-           'rdoc'. The 'pdf' mode creates PDF formatted files in the
-           /tmp directory. The default mode is 'text'. In 'rdoc' mode
-           you must provide 'manifests-path'
+* --mode:
+  Determine the output mode. Valid modes are 'text', 'pdf' and
+  'rdoc'. The 'pdf' mode creates PDF formatted files in the
+  /tmp directory. The default mode is 'text'. In 'rdoc' mode
+  you must provide 'manifests-path'
 
-reference: Build a particular reference. Get a list of references by
-           running 'puppet doc --list'.
+* --reference:
+  Build a particular reference. Get a list of references by
+  running 'puppet doc --list'.
 
-charset:   Used only in 'rdoc' mode. It sets the charset used in the
-           html files produced.
+* --charset:
+  Used only in 'rdoc' mode. It sets the charset used in the
+  html files produced.
 
 
 EXAMPLE
-=======
-  $ puppet doc -r type > /tmp/type_reference.markdown
+-------
+    $ puppet doc -r type > /tmp/type_reference.markdown
 
 or
 
-  $ puppet doc --outputdir /tmp/rdoc --mode rdoc /path/to/manifests
+    $ puppet doc --outputdir /tmp/rdoc --mode rdoc /path/to/manifests
 
 or
 
-  $ puppet doc /etc/puppet/manifests/site.pp
+    $ puppet doc /etc/puppet/manifests/site.pp
 
 or
 
-  $ puppet doc -m pdf -r configuration
+    $ puppet doc -m pdf -r configuration
 
 
 AUTHOR
-======
+------
 Luke Kanies
 
 
 COPYRIGHT
-=========
+---------
 Copyright (c) 2005-2007 Puppet Labs, LLC Licensed under the GNU Public
 License