(#1204) Edit content and formatting of puppet resource help

Clarified how to modify the system state with puppet resource,
and reformatted the markdown for compatibility with ronn.

1 files changed, 44 insertions, 45 deletions

diff --git a/lib/puppet/application/resource.rb b/lib/puppet/application/resource.rb
index a0e33408d..f5741b9ee 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 <param>] [-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