Merge branch 'ticket/next/1204' into next

11 files changed, 531 insertions, 444 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/apply.rb b/lib/puppet/application/apply.rb
index 1a5ab2c0c..a1edf6243 100644
--- a/lib/puppet/application/apply.rb
+++ b/lib/puppet/application/apply.rb
@@ -29,30 +29,43 @@ class Puppet::Application::Apply < Puppet::Application
   def help
     <<-HELP
 
-SYNOPSIS
+puppet-apply(8) -- Apply Puppet manifests locally
 ========
-Run a stand-alone 'puppet' manifest.
+
+SYNOPSIS
+--------
+Applies a standalone Puppet manifest to the local system.
 
 
 USAGE
-=====
-  puppet apply [-h|--help] [-V|--version] [-d|--debug] [-v|--verbose] [-e|--execute]
-              [--detailed-exitcodes] [-l|--logdest <file>] <file>
+-----
+puppet apply [-h|--help] [-V|--version] [-d|--debug] [-v|--verbose]
+  [-e|--execute] [--detailed-exitcodes] [-l|--logdest <file>]
+  [--apply <catalog>] <file>
 
 
 DESCRIPTION
-===========
-This is the standalone puppet execution tool; use it to execute
-individual manifests that you write. If you need to execute site-wide
-manifests, use 'puppet agent' and 'puppet master'.
+-----------
+This is the standalone puppet execution tool; use it to apply
+individual manifests.
+
+When provided with a modulepath, via command line or config file, puppet
+apply can effectively mimic the catalog that would be served by puppet
+master with access to the same modules, although there are some subtle
+differences. When combined with scheduling and an automated system for
+pushing manifests, this can be used to implement a serverless Puppet
+site.
+
+Most users should use 'puppet agent' and 'puppet master' for site-wide
+manifests.
 
 
 OPTIONS
-=======
+-------
 Note that any configuration parameter that's valid in the configuration
-file is also a valid long argument. For example, 'ssldir' is a valid
-configuration parameter, so you can specify '--ssldir <directory>' as an
-argument.
+file is also a valid long argument. For example, 'modulepath' is a
+valid configuration parameter, so you can specify '--tags <class>,<tag>'
+as an argument.
 
 See the configuration file documentation at
 http://docs.puppetlabs.com/references/stable/configuration.html for the
@@ -60,42 +73,50 @@ full list of acceptable parameters. A commented list of all
 configuration options can also be generated by running puppet with
 '--genconfig'.
 
-debug:              Enable full debugging.
+* --debug:
+  Enable full debugging.
+
+* --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.
 
-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.
+* --help:
+  Print this help message
 
-help:               Print this help message
+* --loadclasses:
+  Load any stored classes. 'puppet agent' caches configured classes
+  (usually at /etc/puppet/classes.txt), and setting this option causes
+  all of those classes to be set in your puppet manifest.
 
-loadclasses:        Load any stored classes. 'puppet agent' caches
-                    configured classes (usually at
-                    /etc/puppet/classes.txt), and setting this option
-                    causes all of those classes to be set in your puppet
-                    manifest.
+* --logdest:
+  Where to send messages. Choose between syslog, the console, and a log
+  file. Defaults to sending messages to the console.
 
-logdest:            Where to send messages. Choose between syslog, the
-                    console, and a log file. Defaults to sending
-                    messages to the console.
+* --execute:
+  Execute a specific piece of Puppet code
 
-execute:            Execute a specific piece of Puppet code
+* --verbose:
+  Print extra information.
 
-verbose:            Print extra information.
+* --apply:
+  Apply a JSON catalog (such as one generated with 'puppet master --compile'). You can
+  either specify a JSON file or pipe in JSON from standard input.
 
 
 EXAMPLE
-=======
-  puppet -l /tmp/manifest.log manifest.pp
+-------
+    $ puppet apply -l /tmp/manifest.log manifest.pp
+    $ puppet apply --modulepath=/root/dev/modules -e "include ntpd::server"
 
 
 AUTHOR
-======
+------
 Luke Kanies
 
 
 COPYRIGHT
-=========
+---------
 Copyright (c) 2005 Puppet Labs, LLC Licensed under the GNU Public
 License
 
diff --git a/lib/puppet/application/cert.rb b/lib/puppet/application/cert.rb
index 0db968e9e..0808a42da 100644
--- a/lib/puppet/application/cert.rb
+++ b/lib/puppet/application/cert.rb
@@ -48,30 +48,32 @@ class Puppet::Application::Cert < Puppet::Application
   def help
     <<-HELP
 
-SYNOPSIS
+puppet-cert(8) -- Manage certificates and requests
 ========
-Stand-alone certificate authority. Capable of generating certificates
-but mostly meant for signing certificate requests from puppet clients.
+
+SYNOPSIS
+--------
+Standalone certificate authority. Capable of generating certificates,
+but mostly used for signing certificate requests from puppet clients.
 
 
 USAGE
-=====
-  puppet cert [-h|--help] [-V|--version] [-d|--debug] [-v|--verbose]
-              [-g|--generate] [-l|--list] [-s|--sign] [-r|--revoke]
-              [-p|--print] [-c|--clean] [--verify] [--digest DIGEST]
-              [--fingerprint] [host]
+-----
+puppet cert [-h|--help] [-V|--version] [-d|--debug] [-v|--verbose]
+  [-g|--generate] [-l|--list] [-s|--sign] [-r|--revoke] [-p|--print]
+  [-c|--clean] [--verify] [--digest <digest>] [--fingerprint] [host]
 
 
 DESCRIPTION
-===========
-Because the puppetmasterd daemon defaults to not signing client
+-----------
+Because the puppet master service defaults to not signing client
 certificate requests, this script is available for signing outstanding
 requests. It can be used to list outstanding requests and then either
 sign them individually or sign all of them.
 
 
 OPTIONS
-=======
+-------
 Note that any configuration parameter that's valid in the configuration
 file is also a valid long argument. For example, 'ssldir' is a valid
 configuration parameter, so you can specify '--ssldir <directory>' as an
@@ -83,73 +85,82 @@ full list of acceptable parameters. A commented list of all
 configuration options can also be generated by running puppet cert with
 '--genconfig'.
 
-all:         Operate on all items. Currently only makes sense with
-             '--sign', '--clean', or '--list'.
+* --all:
+  Operate on all items. Currently only makes sense with '--sign',
+  '--clean', or '--list'.
 
-digest:      Set the digest for fingerprinting (defaults to md5). Valid
-             values depends on your openssl and openssl ruby extension
-             version, but should contain at least md5, sha1, md2,
-             sha256.
+* --digest:
+  Set the digest for fingerprinting (defaults to md5). Valid values
+  depends on your openssl and openssl ruby extension version, but should
+  contain at least md5, sha1, md2, sha256.
 
-clean:       Remove all files related to a host from puppet cert's
-             storage. This is useful when rebuilding hosts, since new
-             certificate signing requests will only be honored if puppet
-             cert does not have a copy of a signed certificate for that
-             host. The certificate of the host is also revoked. If
-             '--all' is specified then all host certificates, both
-             signed and unsigned, will be removed.
+* --clean:
+  Remove all files related to a host from puppet cert's storage. This is
+  useful when rebuilding hosts, since new certificate signing requests
+  will only be honored if puppet cert does not have a copy of a signed
+  certificate for that host. The certificate of the host is also
+  revoked. If '--all' is specified then all host certificates, both
+  signed and unsigned, will be removed.
 
-debug:       Enable full debugging.
+* --debug:
+  Enable full debugging.
 
-generate:    Generate a certificate for a named client. A
-             certificate/keypair will be generated for each client named
-             on the command line.
+* --generate:
+  Generate a certificate for a named client. A certificate/keypair will
+  be generated for each client named on the command line.
 
-help:        Print this help message
+* --help:
+  Print this help message
 
-list:        List outstanding certificate requests. If '--all' is
-             specified, signed certificates are also listed, prefixed by
-             '+', and revoked or invalid certificates are prefixed by
-             '-' (the verification outcome is printed in parenthesis).
+* --list:
+  List outstanding certificate requests. If '--all' is specified, signed
+  certificates are also listed, prefixed by '+', and revoked or invalid
+  certificates are prefixed by '-' (the verification outcome is printed
+  in parenthesis).
 
-print:       Print the full-text version of a host's certificate.
+* --print:
+  Print the full-text version of a host's certificate.
 
-fingerprint: Print the DIGEST (defaults to md5) fingerprint of a host's
-             certificate.
+* --fingerprint:
+  Print the DIGEST (defaults to md5) fingerprint of a host's
+  certificate.
 
-revoke:      Revoke the certificate of a client. The certificate can be
-             specified either by its serial number, given as a decimal
-             number or a hexadecimal number prefixed by '0x', or by its
-             hostname. The certificate is revoked by adding it to the
-             Certificate Revocation List given by the 'cacrl' config
-             parameter. Note that the puppetmasterd needs to be
-             restarted after revoking certificates.
+* --revoke:
+  Revoke the certificate of a client. The certificate can be specified
+  either by its serial number, given as a decimal number or a
+  hexadecimal number prefixed by '0x', or by its hostname. The
+  certificate is revoked by adding it to the Certificate Revocation List
+  given by the 'cacrl' config parameter. Note that the puppetmasterd
+  needs to be restarted after revoking certificates.
 
-sign:        Sign an outstanding certificate request. Unless '--all' is
-             specified, hosts must be listed after all flags.
+* --sign:
+  Sign an outstanding certificate request. Unless '--all' is specified,
+  hosts must be listed after all flags.
 
-verbose:     Enable verbosity.
+* --verbose:
+  Enable verbosity.
 
-version:     Print the puppet version number and exit.
+* --version:
+  Print the puppet version number and exit.
 
-verify:      Verify the named certificate against the local CA
-             certificate.
+* --verify:
+  Verify the named certificate against the local CA certificate.
 
 
 EXAMPLE
-=======
-  $ puppet cert -l
-  culain.madstop.com
-  $ puppet cert -s culain.madstop.com
+-------
+    $ puppet cert -l
+    culain.madstop.com
+    $ puppet cert -s culain.madstop.com
 
 
 AUTHOR
-======
+------
 Luke Kanies
 
 
 COPYRIGHT
-=========
+---------
 Copyright (c) 2005 Puppet Labs, LLC Licensed under the GNU Public
 License
 
diff --git a/lib/puppet/application/describe.rb b/lib/puppet/application/describe.rb
index 0c7bea96d..79643159e 100644
--- a/lib/puppet/application/describe.rb
+++ b/lib/puppet/application/describe.rb
@@ -183,50 +183,51 @@ class Puppet::Application::Describe < Puppet::Application
   def help
     <<-HELP
 
-SYNOPSIS
+puppet-describe(8) -- Display help about resource types
 ========
-Print help about puppet types on the console. Run with '-h' to get
-detailed help.
-
 
-USAGE
-=====
-  puppet describe [-h|--help] [-s|--short] [-p|--providers] [-l|--list] [-m|--meta]
+SYNOPSIS
+--------
+Prints help about Puppet resource types, providers, and metaparameters.
 
 
-DESCRIPTION
-===========
-Prints details of Puppet types, providers and metaparameters on the
-console.
+USAGE
+-----
+puppet describe [-h|--help] [-s|--short] [-p|--providers] [-l|--list] [-m|--meta]
 
 
 OPTIONS
-=======
-help:      Print this help text
+-------
+* --help:
+  Print this help text
 
-providers: Describe providers in detail for each type
+* --providers:
+  Describe providers in detail for each type
 
-list:      List all types
+* --list:
+  List all types
 
-meta:      List all metaparameters
+* --meta:
+  List all metaparameters
 
-short:     List only parameters without detail
+* --short:
+  List only parameters without detail
 
 
 EXAMPLE
-=======
-  puppet describe --list
-  puppet describe file --providers
-  puppet describe user -s -m
+-------
+    $ puppet describe --list
+    $ puppet describe file --providers
+    $ puppet describe user -s -m
 
 
 AUTHOR
-======
+------
 David Lutterkort
 
 
 COPYRIGHT
-=========
+---------
 Copyright (c) 2005 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
 
diff --git a/lib/puppet/application/filebucket.rb b/lib/puppet/application/filebucket.rb
index 77ebbb843..460115586 100644
--- a/lib/puppet/application/filebucket.rb
+++ b/lib/puppet/application/filebucket.rb
@@ -15,37 +15,41 @@ class Puppet::Application::Filebucket < Puppet::Application
   def help
     <<-HELP
 
-SYNOPSIS
+puppet-filebucket(8) -- Store and retrieve files in a filebucket
 ========
+
+SYNOPSIS
+--------
 A stand-alone Puppet filebucket client.
 
 
 USAGE
-=====
-  puppet filebucket [-h|--help] [-V|--version] [-d|--debug] [-v|--verbose]
-     [-l|--local] [-r|--remote]
-     [-s|--server <server>] [-b|--bucket <directory>] <file> <file> ...
-
+-----
+puppet filebucket <mode> [-h|--help] [-V|--version] [-d|--debug]
+  [-v|--verbose] [-l|--local] [-r|--remote] [-s|--server <server>]
+  [-b|--bucket <directory>] <file> <file> ...
 
-DESCRIPTION
-===========
-This is a stand-alone filebucket client for sending files to a local or
-central filebucket.
+Puppet filebucket can operate in three modes, with only one mode per call:
 
+backup:
+  Send one or more files to the specified file bucket. Each sent file is
+  printed with its resulting md5 sum.
 
-USAGE
-=====
-This client can operate in three modes, with only one mode per call:
+get:
+  Return the text associated with an md5 sum. The text is printed to
+  stdout, and only one file can be retrieved at a time.
 
-backup:  Send one or more files to the specified file bucket. Each sent
-         file is printed with its resulting md5 sum.
+restore:
+  Given a file path and an md5 sum, store the content associated with
+  the sum into the specified file path. You can specify an entirely new
+  path to this argument; you are not restricted to restoring the content
+  to its original location.
 
-get:     Return the text associated with an md5 sum. The text is printed
-         to stdout, and only one file can be retrieved at a time.
 
-restore: Given a file path and an md5 sum, store the content associated
-         with the sum into the specified file path. You can specify an
-         entirely new path to this argument; you are not restricted to
+DESCRIPTION
+-----------
+This is a stand-alone filebucket client for sending files to a local or
+central filebucket.
 
 Note that 'filebucket' defaults to using a network-based filebucket
 available on the server named 'puppet'. To use this, you'll have to be
@@ -53,16 +57,8 @@ running as a user with valid Puppet certificates. Alternatively, you can
 use your local file bucket by specifying '--local'.
 
 
-EXAMPLE
-=======
-  $ puppet filebucket backup /etc/passwd
-  /etc/passwd: 429b225650b912a2ee067b0a4cf1e949
-  $ puppet filebucket restore /tmp/passwd 429b225650b912a2ee067b0a4cf1e949
-  $
-
-
 OPTIONS
-=======
+-------
 Note that any configuration parameter that's valid in the configuration
 file is also a valid long argument. For example, 'ssldir' is a valid
 configuration parameter, so you can specify '--ssldir <directory>' as an
@@ -74,35 +70,44 @@ full list of acceptable parameters. A commented list of all
 configuration options can also be generated by running puppet with
 '--genconfig'.
 
-debug:   Enable full debugging.
+* --debug:
+  Enable full debugging.
 
-help:    Print this help message
+* --help:
+  Print this help message
 
-local:   Use the local filebucket. This will use the default
-         configuration information.
+* --local:
+  Use the local filebucket. This will use the default configuration
+  information.
 
-remote:  Use a remote filebucket. This will use the default
-         configuration information.
+* --remote:
+  Use a remote filebucket. This will use the default configuration
+  information.
 
-server:  The server to send the file to, instead of locally.
+* --server:
+  The server to send the file to, instead of locally.
 
-verbose: Print extra information.
+* --verbose:
+  Print extra information.
 
-version: Print version information.
+* --version:
+  Print version information.
 
 
 EXAMPLE
-=======
-  puppet filebucket -b /tmp/filebucket /my/file
+-------
+    $ puppet filebucket backup /etc/passwd
+    /etc/passwd: 429b225650b912a2ee067b0a4cf1e949
+    $ puppet filebucket restore /tmp/passwd 429b225650b912a2ee067b0a4cf1e949
 
 
 AUTHOR
-======
+------
 Luke Kanies
 
 
 COPYRIGHT
-=========
+---------
 Copyright (c) 2005 Puppet Labs, LLC Licensed under the GNU Public
 License
 
diff --git a/lib/puppet/application/inspect.rb b/lib/puppet/application/inspect.rb
index 599898a07..578588144 100644
--- a/lib/puppet/application/inspect.rb
+++ b/lib/puppet/application/inspect.rb
@@ -22,20 +22,22 @@ class Puppet::Application::Inspect < Puppet::Application
   def help
     <<-HELP
 
-SYNOPSIS
+puppet-inspect(8) -- Send an inspection report
 ========
 
-Prepare and submit an inspection report to the puppet master.
+SYNOPSIS
+--------
+
+Prepares and submits an inspection report to the puppet master.
 
 
 USAGE
-=====
-
-  puppet inspect
+-----
+puppet inspect
 
 
 DESCRIPTION
-===========
+-----------
 
 This command uses the cached catalog from the previous run of 'puppet
 agent' to determine which attributes of which resources have been
@@ -44,11 +46,12 @@ the current state of the system, writes the state of the specified
 resource attributes to a report, and submits the report to the puppet
 master.
 
-Puppet inspect does not run as a daemon, and must be run manually or from cron.
+Puppet inspect does not run as a daemon, and must be run manually or
+from cron.
 
 
 OPTIONS
-=======
+-------
 
 Any configuration setting which is valid in the configuration file is
 also a valid long argument, e.g. '--server=master.domain.com'. See the
@@ -58,13 +61,13 @@ the full list of acceptable settings.
 
 
 AUTHOR
-======
+------
 
 Puppet Labs
 
 
 COPYRIGHT
-=========
+---------
 
 Copyright (c) 2011 Puppet Labs, LLC
 Licensed under the GNU General Public License version 2
diff --git a/lib/puppet/application/kick.rb b/lib/puppet/application/kick.rb
index 4cf06036f..9612a72aa 100644
--- a/lib/puppet/application/kick.rb
+++ b/lib/puppet/application/kick.rb
@@ -40,20 +40,23 @@ class Puppet::Application::Kick < Puppet::Application
   def help
     <<-HELP
 
-SYNOPSIS
+puppet-kick(8) -- Remotely control puppet agent
 ========
+
+SYNOPSIS
+--------
 Trigger a puppet agent run on a set of hosts.
 
 
 USAGE
-=====
-  puppet kick [-a|--all] [-c|--class <class>] [-d|--debug] [-f|--foreground]
-      [-h|--help] [--host <host>] [--no-fqdn] [--ignoreschedules]
-      [-t|--tag <tag>] [--test] [-p|--ping] <host> [<host> [...]]
+-----
+puppet kick [-a|--all] [-c|--class <class>] [-d|--debug] [-f|--foreground]
+  [-h|--help] [--host <host>] [--no-fqdn] [--ignoreschedules]
+  [-t|--tag <tag>] [--test] [-p|--ping] <host> [<host> [...]]
 
 
 DESCRIPTION
-===========
+-----------
 This script can be used to connect to a set of machines running 'puppet
 agent' and trigger them to run their configurations. The most common
 usage would be to specify a class of hosts and a set of tags, and
@@ -72,11 +75,11 @@ copy things like LDAP settings.
 
 
 USAGE NOTES
-===========
+-----------
 'puppet kick' is useless unless 'puppet agent' is listening. See its
 documentation for more information, but the gist is that you must enable
 'listen' on the 'puppet agent' daemon, either using '--listen' on the
-command line or adding 'listen: true' in its config file. In addition,
+command line or adding 'listen = true' in its config file. In addition,
 you need to set the daemons up to specifically allow connections by
 creating the 'namespaceauth' file, normally at
 '/etc/puppet/namespaceauth.conf'. This file specifies who has access to
@@ -84,7 +87,7 @@ each namespace; if you create the file you must add every namespace you
 want any Puppet daemon to allow -- it is currently global to all Puppet
 daemons.
 
-An example file looks like this::
+An example file looks like this:
 
     [fileserver]
         allow *.madstop.com
@@ -100,68 +103,75 @@ could leave off the 'fileserver' and 'puppetmaster' namespaces.
 
 
 OPTIONS
-=======
+-------
 Note that any configuration parameter that's valid in the configuration
 file is also a valid long argument. For example, 'ssldir' is a valid
 configuration parameter, so you can specify '--ssldir <directory>' as an
 argument.
 
 See the configuration file documentation at
-http://reductivelabs.com/projects/puppet/reference/configref.html for
+http://docs.puppetlabs.com/references/latest/configuration.html for
 the full list of acceptable parameters. A commented list of all
 configuration options can also be generated by running puppet master
 with '--genconfig'.
 
-all:             Connect to all available hosts. Requires LDAP support
-                 at this point.
-
-class:           Specify a class of machines to which to connect. This
-                 only works if you have LDAP configured, at the moment.
+* --all:
+  Connect to all available hosts. Requires LDAP support at this point.
 
-debug:           Enable full debugging.
+* --class:
+  Specify a class of machines to which to connect. This only works if
+  you have LDAP configured, at the moment.
 
-foreground:      Run each configuration in the foreground; that is, when
-                 connecting to a host, do not return until the host has
-                 finished its run. The default is false.
+* --debug:
+  Enable full debugging.
 
-help:            Print this help message
+* --foreground:
+  Run each configuration in the foreground; that is, when connecting to
+  a host, do not return until the host has finished its run. The default
+  is false.
 
-host:            A specific host to which to connect. This flag can be
-                 specified more than once.
+* --help:
+  Print this help message
 
-ignoreschedules: Whether the client should ignore schedules when running
-                 its configuration. This can be used to force the client
-                 to perform work it would not normally perform so soon.
-                 The default is false.
+* --host:
+  A specific host to which to connect. This flag can be specified more
+  than once.
 
-parallel:        How parallel to make the connections. Parallelization
-                 is provided by forking for each client to which to
-                 connect. The default is 1, meaning serial execution.
+* --ignoreschedules:
+  Whether the client should ignore schedules when running its
+  configuration. This can be used to force the client to perform work it
+  would not normally perform so soon. The default is false.
 
-tag:             Specify a tag for selecting the objects to apply. Does
-                 not work with the --test option.
+* --parallel:
+  How parallel to make the connections. Parallelization is provided by
+  forking for each client to which to connect. The default is 1, meaning
+  serial execution.
 
-test:            Print the hosts you would connect to but do not
-                 actually connect. This option requires LDAP support at
-                 this point.
+* --tag:
+  Specify a tag for selecting the objects to apply. Does not work with
+  the --test option.
 
-ping::
+* --test:
+  Print the hosts you would connect to but do not actually connect. This
+  option requires LDAP support at this point.
 
-  Do a ICMP echo against the target host. Skip hosts that don't respond to ping.
+* --ping:
+  Do a ICMP echo against the target host. Skip hosts that don't respond
+  to ping.
 
 
 EXAMPLE
-=======
-  sudo puppet kick -p 10 -t remotefile -t webserver host1 host2
+-------
+    $ sudo puppet kick -p 10 -t remotefile -t webserver host1 host2
 
 
 AUTHOR
-======
+------
 Luke Kanies
 
 
 COPYRIGHT
-=========
+---------
 Copyright (c) 2005 Puppet Labs, LLC Licensed under the GNU Public
 License
 
diff --git a/lib/puppet/application/master.rb b/lib/puppet/application/master.rb
index b2b77f870..f689b9e01 100644
--- a/lib/puppet/application/master.rb
+++ b/lib/puppet/application/master.rb
@@ -28,25 +28,32 @@ class Puppet::Application::Master < Puppet::Application
   def help
     <<-HELP
 
-SYNOPSIS
+puppet-master(8) -- The puppet master daemon
 ========
+
+SYNOPSIS
+--------
 The central puppet server. Functions as a certificate authority by
 default.
 
 
 USAGE
-=====
-  puppet master [-D|--daemonize|--no-daemonize] [-d|--debug] [-h|--help]
-      [-l|--logdest <file>|console|syslog] [-v|--verbose] [-V|--version]
-      [--compile <nodename>] [--apply <catalog>]
+-----
+puppet master [-D|--daemonize|--no-daemonize] [-d|--debug] [-h|--help]
+  [-l|--logdest <file>|console|syslog] [-v|--verbose] [-V|--version]
+  [--compile <node-name>]
+
 
 DESCRIPTION
-===========
-This is the puppet central daemon.
+-----------
+This command starts an instance of puppet master, running as a daemon
+and using Ruby's built-in Webrick webserver. Puppet master can also be
+managed by other application servers; when this is the case, this
+executable is not used.
 
 
 OPTIONS
-=======
+-------
 Note that any configuration parameter that's valid in the configuration
 file is also a valid long argument. For example, 'ssldir' is a valid
 configuration parameter, so you can specify '--ssldir <directory>' as an
@@ -55,47 +62,49 @@ argument.
 See the configuration file documentation at
 http://docs.puppetlabs.com/references/stable/configuration.html for the
 full list of acceptable parameters. A commented list of all
-configuration options can also be generated by running puppetmasterdd
+configuration options can also be generated by running puppet master
 with '--genconfig'.
 
-daemonize:    Send the process into the background. This is the default.
-
-no-daemonize: Do not send the process into the background.
+* --daemonize:
+  Send the process into the background. This is the default.
 
-debug:        Enable full debugging.
+* --no-daemonize:
+  Do not send the process into the background.
 
-help:         Print this help message.
+* --debug:
+  Enable full debugging.
 
-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.
+* --help:
+  Print this help message.
 
-verbose:      Enable verbosity.
+* --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.
 
-version:      Print the puppet version number and exit.
+* --verbose:
+  Enable verbosity.
 
-compile:      Capability to compile a catalogue and output it in JSON
-              from the Puppet master. Uses facts contained in the
-              $vardir/yaml/ directory to compile the catalog.
+* --version:
+  Print the puppet version number and exit.
 
-apply:        Capability to apply JSON catalog (such as one generated
-              with --compile). You can either specify a JSON file or
-              pipe in JSON from standard input.
+* --compile:
+  Compile a catalogue and output it in JSON from the puppet master. Uses
+  facts contained in the $vardir/yaml/ directory to compile the catalog.
 
 
 EXAMPLE
-=======
+-------
   puppet master
 
 
 AUTHOR
-======
+------
 Luke Kanies
 
 
 COPYRIGHT
-=========
+---------
 Copyright (c) 2005 Puppet Labs, LLC Licensed under the GNU Public
 License
 
diff --git a/lib/puppet/application/queue.rb b/lib/puppet/application/queue.rb
index d32ec9a6f..00ace37fa 100644
--- a/lib/puppet/application/queue.rb
+++ b/lib/puppet/application/queue.rb
@@ -40,24 +40,34 @@ class Puppet::Application::Queue < Puppet::Application
   def help
     <<-HELP
 
-SYNOPSIS
+puppet-queue(8) -- Queuing daemon for asynchronous storeconfigs
 ========
-Retrieve serialized records from a queue and process them in order.
+
+SYNOPSIS
+--------
+Retrieves serialized storeconfigs records from a queue and processes
+them in order.
 
 
 USAGE
-=====
-  puppet queue [-d|--debug] [-v|--verbose]
+-----
+puppet queue [-d|--debug] [-v|--verbose]
 
 
 DESCRIPTION
-===========
-This is a simple application that just processes entities in a queue as
-they are recieved.
+-----------
+This application runs as a daemon and processes storeconfigs data,
+retrieving the data from a stomp server message queue and writing it to
+a database.
+
+For more information, including instructions for properly setting up
+your puppet master and message queue, see the documentation on setting
+up asynchronous storeconfigs at:
+http://projects.puppetlabs.com/projects/1/wiki/Using_Stored_Configuration
 
 
 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
@@ -66,30 +76,34 @@ an argument.
 See the configuration file documentation at
 http://docs.puppetlabs.com/references/stable/configuration.html for the
 full list of acceptable parameters. A commented list of all
-configuration options can also be generated by running puppetd with
+configuration options can also be generated by running puppet queue with
 '--genconfig'.
 
-debug:   Enable full debugging.
+* --debug:
+  Enable full debugging.
 
-help:    Print this help message
+* --help:
+  Print this help message
 
-verbose: Turn on verbose reporting.
+* --verbose:
+  Turn on verbose reporting.
 
-version: Print the puppet version number and exit.
+* --version:
+  Print the puppet version number and exit.
 
 
 EXAMPLE
-=======
-  puppet queue
+-------
+    $ puppet queue
 
 
 AUTHOR
-======
+------
 Luke Kanies
 
 
 COPYRIGHT
-=========
+---------
 Copyright (c) 2009 Puppet Labs, LLC Licensed under the GNU Public
 License
 
diff --git a/lib/puppet/application/resource.rb b/lib/puppet/application/resource.rb
index a0e33408d..3995c285b 100644
--- a/lib/puppet/application/resource.rb
+++ b/lib/puppet/application/resource.rb
@@ -38,37 +38,41 @@ class Puppet::Application::Resource < Puppet::Application
   def help
     <<-HELP
 
-SYNOPSIS
+puppet-resource(8) -- The resource abstraction layer shell
 ========
-Use the Puppet RAL to directly interact with the system.
+
+SYNOPSIS
+--------
+Uses the Puppet RAL to directly interact with the system.
 
 
 USAGE
-=====
-  puppet resource [-h|--help] [-d|--debug] [-v|--verbose] [-e|--edit]
-                  [-H|--host <host>] [-p|--param <param>] [-t|--types]
-                  type <name>
+-----
+puppet resource [-h|--help] [-d|--debug] [-v|--verbose] [-e|--edit]
+  [-H|--host <host>] [-p|--param <parameter>] [-t|--types] <type>
+  [<name>] [<attribute>=<value> ...]
 
 
 DESCRIPTION
-===========
+-----------
 This command provides simple facilities for converting current system
-state into Puppet code, along with some ability to use Puppet to affect
-the current state.
+state into Puppet code, along with some ability to modify the current
+state using Puppet's RAL.
 
-By default, you must at least provide a type to list, which case puppet
-resource will tell you everything it knows about all instances of that
-type. You can optionally specify an instance name, and puppet resource
-will only describe that single instance.
+By default, you must at least provide a type to list, in which case
+puppet resource will tell you everything it knows about all resources of
+that type. You can optionally specify an instance name, and puppet
+resource will only describe that single instance.
 
-You can also add '--edit' as an argument, and puppet resource will write
-its output to a file, open that file in an editor, and then apply the
-file as a Puppet transaction. You can easily use this to use Puppet to
-make simple changes to a system.
+If given a type, a name, and a series of <attribute>=<value> pairs,
+puppet resource will modify the state of the specified resource.
+Alternately, if given a type, a name, and the '--edit' flag, puppet
+resource will write its output to a file, open that file in an editor,
+and then apply the saved file as a Puppet transaction.
 
 
 OPTIONS
-=======
+-------
 Note that any configuration parameter that's valid in the configuration
 file is also a valid long argument. For example, 'ssldir' is a valid
 configuration parameter, so you can specify '--ssldir <directory>' as an
@@ -80,59 +84,54 @@ full list of acceptable parameters. A commented list of all
 configuration options can also be generated by running puppet with
 '--genconfig'.
 
-debug: Enable full debugging.
-
-edit:
+* --debug:
+  Enable full debugging.
 
+* --edit:
   Write the results of the query to a file, open the file in an editor,
   and read the file back in as an executable Puppet manifest.
 
-host:
-
+* --host:
   When specified, connect to the resource server on the named host
   and retrieve the list of resouces of the type specified.
 
-help:
-
+* --help:
   Print this help message.
 
-param:
-
+* --param:
   Add more parameters to be outputted from queries.
 
-types:
-
+* --types:
   List all available types.
 
-verbose:
-
+* --verbose:
   Print extra information.
 
 
 EXAMPLE
-=======
-This example uses `puppet resource` to return Puppet configuration for
+-------
+This example uses `puppet resource` to return a Puppet configuration for
 the user `luke`:
 
-     $ puppet resource user luke
-     user { 'luke':
-       home => '/home/luke',
-       uid => '100',
-       ensure => 'present',
-       comment => 'Luke Kanies,,,',
-       gid => '1000',
-       shell => '/bin/bash',
-       groups => ['sysadmin','audio','video','puppet']
-     }
+    $ puppet resource user luke
+    user { 'luke':
+     home => '/home/luke',
+     uid => '100',
+     ensure => 'present',
+     comment => 'Luke Kanies,,,',
+     gid => '1000',
+     shell => '/bin/bash',
+     groups => ['sysadmin','audio','video','puppet']
+    }
 
 
 AUTHOR
-======
+------
 Luke Kanies
 
 
 COPYRIGHT
-=========
+---------
 Copyright (c) 2005-2007 Puppet Labs, LLC Licensed under the GNU Public
 License