update documentation for knife exec

9 files changed, 120 insertions, 13 deletions

diff --git a/chef/distro/common/html/knife-bootstrap.1.html b/chef/distro/common/html/knife-bootstrap.1.html
index bbc00b24cf..e8c38ec1c5 100644
--- a/chef/distro/common/html/knife-bootstrap.1.html
+++ b/chef/distro/common/html/knife-bootstrap.1.html
@@ -61,6 +61,7 @@
   <div class='man-navigation' style='display:none'>
     <a href="#NAME">NAME</a>
     <a href="#SYNOPSIS">SYNOPSIS</a>
+    <a href="#DESCRIPTION">DESCRIPTION</a>
     <a href="#SEE-ALSO">SEE ALSO</a>
     <a href="#AUTHOR">AUTHOR</a>
     <a href="#DOCUMENTATION">DOCUMENTATION</a>
@@ -97,6 +98,8 @@
 </dl>
 
 
+<h2 id="DESCRIPTION">DESCRIPTION</h2>
+
 <p>Performs a Chef Bootstrap on the target node. The goal of the bootstrap
 is to get Chef installed on the target system so it can run Chef Client
 with a Chef Server. The main assumption is a baseline OS installation
@@ -159,11 +162,11 @@ sub-command looks in the following locations for the template to use:</p>
 
 <h2 id="AUTHOR">AUTHOR</h2>
 
-<p>   Chef was written by Adam Jacob <a href="&#x6d;&#x61;&#x69;&#x6c;&#x74;&#x6f;&#x3a;&#x61;&#x64;&#x61;&#x6d;&#x40;&#111;&#x70;&#x73;&#99;&#x6f;&#x64;&#101;&#x2e;&#99;&#x6f;&#x6d;" data-bare-link="true">&#97;&#100;&#x61;&#109;&#x40;&#111;&#112;&#x73;&#x63;&#x6f;&#100;&#101;&#46;&#x63;&#111;&#x6d;</a> with many contributions from the community.</p>
+<p>   Chef was written by Adam Jacob <a href="&#109;&#x61;&#105;&#108;&#116;&#x6f;&#58;&#97;&#x64;&#x61;&#x6d;&#64;&#x6f;&#112;&#115;&#99;&#x6f;&#100;&#101;&#x2e;&#x63;&#111;&#109;" data-bare-link="true">&#x61;&#x64;&#x61;&#x6d;&#x40;&#111;&#112;&#x73;&#99;&#x6f;&#x64;&#x65;&#x2e;&#99;&#x6f;&#x6d;</a> with many contributions from the community.</p>
 
 <h2 id="DOCUMENTATION">DOCUMENTATION</h2>
 
-<p>   This manual page was written by Joshua Timberman <a href="&#109;&#x61;&#x69;&#x6c;&#x74;&#111;&#58;&#106;&#111;&#115;&#104;&#x75;&#97;&#x40;&#x6f;&#112;&#x73;&#99;&#x6f;&#x64;&#101;&#x2e;&#99;&#111;&#109;" data-bare-link="true">&#106;&#111;&#115;&#x68;&#117;&#97;&#x40;&#x6f;&#x70;&#115;&#x63;&#x6f;&#100;&#x65;&#x2e;&#99;&#x6f;&#x6d;</a>.
+<p>   This manual page was written by Joshua Timberman <a href="&#109;&#x61;&#x69;&#108;&#116;&#x6f;&#x3a;&#106;&#111;&#x73;&#104;&#x75;&#97;&#x40;&#x6f;&#x70;&#115;&#99;&#111;&#x64;&#101;&#46;&#99;&#x6f;&#x6d;" data-bare-link="true">&#106;&#111;&#115;&#104;&#x75;&#97;&#64;&#111;&#x70;&#x73;&#x63;&#111;&#100;&#x65;&#x2e;&#x63;&#111;&#109;</a>.
    Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p>
 
 <h2 id="CHEF">CHEF</h2>
diff --git a/chef/distro/common/html/knife-exec.1.html b/chef/distro/common/html/knife-exec.1.html
index 12dd059054..428eeabc10 100644
--- a/chef/distro/common/html/knife-exec.1.html
+++ b/chef/distro/common/html/knife-exec.1.html
@@ -61,7 +61,12 @@
   <div class='man-navigation' style='display:none'>
     <a href="#NAME">NAME</a>
     <a href="#SYNOPSIS">SYNOPSIS</a>
-    <a href="#EXEC-SUBCOMMAND">EXEC SUBCOMMAND</a>
+    <a href="#DESCRIPTION">DESCRIPTION</a>
+    <a href="#EXAMPLES">EXAMPLES</a>
+    <a href="#SEE-ALSO">SEE ALSO</a>
+    <a href="#AUTHOR">AUTHOR</a>
+    <a href="#DOCUMENTATION">DOCUMENTATION</a>
+    <a href="#CHEF">CHEF</a>
   </div>
 
   <ol class='man-decor man-head man head'>
@@ -79,7 +84,43 @@
 
 <p><strong>knife</strong> <strong>exec</strong> <em>(options)</em></p>
 
-<h2 id="EXEC-SUBCOMMAND">EXEC SUBCOMMAND</h2>
+<dl>
+<dt><code>-E</code>, <code>--exec CODE</code></dt><dd>Provide a snippet of code to evaluate on the command line</dd>
+</dl>
+
+
+<h2 id="DESCRIPTION">DESCRIPTION</h2>
+
+<p><code>knife exec</code> runs arbitrary ruby scripts in a context similar to that of
+the <span class="man-ref">shef<span class="s">(1)</span></span> DSL. See the shef documentation for a description of the
+commands available.</p>
+
+<h2 id="EXAMPLES">EXAMPLES</h2>
+
+<dl>
+<dt>Make an API call against an arbitrary endpoint</dt><dd>knife exec -E 'api.get("nodes/fluke.localdomain/cookbooks")'<br />
+=> list of cookbooks for the node <em>fluke.localdomain</em></dd>
+<dt>Remove the role <em>obsolete</em> from all nodes</dt><dd>knife exec -E 'nodes.transform(:all){|n| n.run_list.delete("role[obsolete]")}'</dd>
+<dt>Generate the expanded run list for hosts in the <code>webserver</code> role</dt><dd>knife exec -E 'nodes.find(:roles => "webserver") {|n| n.expand!; n[:recipes]}'</dd>
+</dl>
+
+
+<h2 id="SEE-ALSO">SEE ALSO</h2>
+
+<p>   <strong><span class="man-ref">shef<span class="s">(1)</span></span></strong></p>
+
+<h2 id="AUTHOR">AUTHOR</h2>
+
+<p>   Chef was written by Adam Jacob <a href="&#x6d;&#97;&#105;&#x6c;&#x74;&#111;&#x3a;&#x61;&#100;&#x61;&#109;&#64;&#111;&#112;&#x73;&#99;&#111;&#x64;&#x65;&#x2e;&#99;&#111;&#x6d;" data-bare-link="true">&#97;&#x64;&#97;&#x6d;&#x40;&#x6f;&#112;&#x73;&#99;&#x6f;&#x64;&#x65;&#46;&#x63;&#111;&#x6d;</a> with many contributions from the community.</p>
+
+<h2 id="DOCUMENTATION">DOCUMENTATION</h2>
+
+<p>   This manual page was written by Joshua Timberman <a href="&#109;&#x61;&#105;&#108;&#116;&#111;&#x3a;&#106;&#111;&#115;&#104;&#x75;&#97;&#64;&#111;&#112;&#115;&#99;&#x6f;&#x64;&#x65;&#46;&#99;&#x6f;&#x6d;" data-bare-link="true">&#x6a;&#111;&#x73;&#x68;&#x75;&#x61;&#x40;&#111;&#x70;&#x73;&#99;&#x6f;&#x64;&#x65;&#x2e;&#x63;&#x6f;&#109;</a>.
+   Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.</p>
+
+<h2 id="CHEF">CHEF</h2>
+
+<p>   Knife is distributed with Chef. <a href="http://wiki.opscode.com/display/chef/Home" data-bare-link="true">http://wiki.opscode.com/display/chef/Home</a></p>
 
 
   <ol class='man-decor man-foot man foot'>
diff --git a/chef/distro/common/html/shef.1.html b/chef/distro/common/html/shef.1.html
index 29f189d82b..3d01e35853 100644
--- a/chef/distro/common/html/shef.1.html
+++ b/chef/distro/common/html/shef.1.html
@@ -230,7 +230,7 @@ chef:recipe > pp ls '/tmp'<br />
 "hello_world"]</p></li>
 <li><p>Search for <em>nodes</em> by role, and print their IP addresses</p>
 
-<p>chef > nodes.find(:roles => 'opscode-chef') {|n| n[:ipaddress] }<br />
+<p>chef > nodes.find(:roles => 'monitoring-server') {|n| n[:ipaddress] }<br />
 => ["10.254.199.5"]</p></li>
 <li><p>Remove the role <em>obsolete</em> from every node in the system</p>
 
@@ -258,12 +258,12 @@ and may become out of sync with the behavior of those libraries.</p>
 
 <h2 id="AUTHOR">AUTHOR</h2>
 
-<p>   Chef was written by Adam Jacob <a href="&#x6d;&#x61;&#105;&#108;&#x74;&#111;&#58;&#x61;&#100;&#97;&#109;&#64;&#111;&#x70;&#x73;&#x63;&#x6f;&#x64;&#x65;&#46;&#x63;&#x6f;&#x6d;" data-bare-link="true">&#x61;&#x64;&#97;&#109;&#64;&#x6f;&#112;&#x73;&#x63;&#x6f;&#100;&#x65;&#x2e;&#99;&#111;&#109;</a> with many
+<p>   Chef was written by Adam Jacob <a href="&#x6d;&#97;&#105;&#x6c;&#x74;&#111;&#x3a;&#x61;&#100;&#x61;&#109;&#64;&#111;&#112;&#x73;&#99;&#111;&#x64;&#x65;&#x2e;&#99;&#111;&#x6d;" data-bare-link="true">&#97;&#x64;&#97;&#x6d;&#x40;&#x6f;&#112;&#x73;&#99;&#x6f;&#x64;&#x65;&#46;&#x63;&#111;&#x6d;</a> with many
    contributions from the community. Shef was written by Daniel DeLeo.</p>
 
 <h2 id="DOCUMENTATION">DOCUMENTATION</h2>
 
-<p>   This manual page was written by Daniel DeLeo <a href="&#109;&#97;&#105;&#x6c;&#x74;&#111;&#58;&#100;&#x61;&#x6e;&#x40;&#111;&#112;&#115;&#x63;&#x6f;&#x64;&#x65;&#46;&#x63;&#111;&#109;" data-bare-link="true">&#x64;&#x61;&#110;&#x40;&#x6f;&#x70;&#x73;&#x63;&#x6f;&#x64;&#x65;&#46;&#99;&#111;&#109;</a>.
+<p>   This manual page was written by Daniel DeLeo <a href="&#109;&#x61;&#105;&#108;&#116;&#111;&#x3a;&#100;&#97;&#110;&#64;&#x6f;&#112;&#115;&#99;&#111;&#100;&#101;&#x2e;&#x63;&#x6f;&#109;" data-bare-link="true">&#100;&#x61;&#x6e;&#x40;&#111;&#x70;&#x73;&#x63;&#x6f;&#x64;&#101;&#x2e;&#x63;&#111;&#x6d;</a>.
    Permission is granted to copy, distribute and / or modify this
    document under the terms of the Apache 2.0 License.</p>
 
diff --git a/chef/distro/common/man/man1/knife-bootstrap.1 b/chef/distro/common/man/man1/knife-bootstrap.1
index 753ae8bfa7..92a2f1b0f9 100644
--- a/chef/distro/common/man/man1/knife-bootstrap.1
+++ b/chef/distro/common/man/man1/knife-bootstrap.1
@@ -53,7 +53,7 @@ Execute the bootstrap via sudo
 \fB\-d\fR, \fB\-\-distro DISTRO\fR
 Bootstrap a distro using a template
 .
-.P
+.SH "DESCRIPTION"
 Performs a Chef Bootstrap on the target node\. The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server\. The main assumption is a baseline OS installation exists\. This sub\-command is used internally by some cloud computing server create commands and the others will be migrated in a future version of Chef\.
 .
 .P
diff --git a/chef/distro/common/man/man1/knife-exec.1 b/chef/distro/common/man/man1/knife-exec.1
index 6c61086a94..db24438f87 100644
--- a/chef/distro/common/man/man1/knife-exec.1
+++ b/chef/distro/common/man/man1/knife-exec.1
@@ -9,5 +9,38 @@
 .SH "SYNOPSIS"
 \fBknife\fR \fBexec\fR \fI(options)\fR
 .
-.SH "EXEC SUBCOMMAND"
-
+.TP
+\fB\-E\fR, \fB\-\-exec CODE\fR
+Provide a snippet of code to evaluate on the command line
+.
+.SH "DESCRIPTION"
+\fBknife exec\fR runs arbitrary ruby scripts in a context similar to that of the shef(1) DSL\. See the shef documentation for a description of the commands available\.
+.
+.SH "EXAMPLES"
+.
+.TP
+Make an API call against an arbitrary endpoint
+knife exec \-E \'api\.get("nodes/fluke\.localdomain/cookbooks")\'
+.
+.br
+=> list of cookbooks for the node \fIfluke\.localdomain\fR
+.
+.TP
+Remove the role \fIobsolete\fR from all nodes
+knife exec \-E \'nodes\.transform(:all){|n| n\.run_list\.delete("role[obsolete]")}\'
+.
+.TP
+Generate the expanded run list for hosts in the \fBwebserver\fR role
+knife exec \-E \'nodes\.find(:roles => "webserver") {|n| n\.expand!; n[:recipes]}\'
+.
+.SH "SEE ALSO"
+\fBshef(1)\fR
+.
+.SH "AUTHOR"
+Chef was written by Adam Jacob \fIadam@opscode\.com\fR with many contributions from the community\.
+.
+.SH "DOCUMENTATION"
+This manual page was written by Joshua Timberman \fIjoshua@opscode\.com\fR\. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2\.0 License\.
+.
+.SH "CHEF"
+Knife is distributed with Chef\. \fIhttp://wiki\.opscode\.com/display/chef/Home\fR
diff --git a/chef/distro/common/man/man1/shef.1 b/chef/distro/common/man/man1/shef.1
index 0c59998fad..99edb84c7b 100644
--- a/chef/distro/common/man/man1/shef.1
+++ b/chef/distro/common/man/man1/shef.1
@@ -218,7 +218,7 @@ chef:recipe > pp ls \'/tmp\'
 Search for \fInodes\fR by role, and print their IP addresses
 .
 .IP
-chef > nodes\.find(:roles => \'opscode\-chef\') {|n| n[:ipaddress] }
+chef > nodes\.find(:roles => \'monitoring\-server\') {|n| n[:ipaddress] }
 .
 .br
 => ["10\.254\.199\.5"]
diff --git a/chef/distro/common/markdown/man1/knife-bootstrap.mkd b/chef/distro/common/markdown/man1/knife-bootstrap.mkd
index dd70f529d0..8fba685804 100644
--- a/chef/distro/common/markdown/man1/knife-bootstrap.mkd
+++ b/chef/distro/common/markdown/man1/knife-bootstrap.mkd
@@ -28,6 +28,8 @@ __knife__ __bootstrap__ _(options)_
   * `-d`, `--distro DISTRO`:
     Bootstrap a distro using a template
 
+## DESCRIPTION
+
 Performs a Chef Bootstrap on the target node. The goal of the bootstrap
 is to get Chef installed on the target system so it can run Chef Client
 with a Chef Server. The main assumption is a baseline OS installation
diff --git a/chef/distro/common/markdown/man1/knife-exec.mkd b/chef/distro/common/markdown/man1/knife-exec.mkd
index b0edfa0cb6..34d9297fb9 100644
--- a/chef/distro/common/markdown/man1/knife-exec.mkd
+++ b/chef/distro/common/markdown/man1/knife-exec.mkd
@@ -5,5 +5,33 @@ knife-exec(1) -- Run user scripts using the Chef API DSL
 
 __knife__ __exec__ _(options)_
 
-## EXEC SUBCOMMAND
+  * `-E`, `--exec CODE`:
+    Provide a snippet of code to evaluate on the command line
+
+## DESCRIPTION
+`knife exec` runs arbitrary ruby scripts in a context similar to that of
+the shef(1) DSL. See the shef documentation for a description of the
+commands available.
+
+## EXAMPLES
+  * Make an API call against an arbitrary endpoint:
+    knife exec -E 'api.get("nodes/fluke.localdomain/cookbooks")'  
+    => list of cookbooks for the node _fluke.localdomain_
+  * Remove the role _obsolete_ from all nodes:
+    knife exec -E 'nodes.transform(:all){|n| n.run\_list.delete("role[obsolete]")}'
+  * Generate the expanded run list for hosts in the `webserver` role:
+    knife exec -E 'nodes.find(:roles => "webserver") {|n| n.expand!; n[:recipes]}'
+
+## SEE ALSO
+   __shef(1)__
+
+## AUTHOR
+   Chef was written by Adam Jacob <adam@opscode.com> with many contributions from the community.
+
+## DOCUMENTATION
+   This manual page was written by Joshua Timberman <joshua@opscode.com>.
+   Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.
+
+## CHEF
+   Knife is distributed with Chef. <http://wiki.opscode.com/display/chef/Home>
 
diff --git a/chef/distro/common/markdown/man1/shef.mkd b/chef/distro/common/markdown/man1/shef.mkd
index 783668818e..a2e0f04814 100644
--- a/chef/distro/common/markdown/man1/shef.mkd
+++ b/chef/distro/common/markdown/man1/shef.mkd
@@ -149,7 +149,7 @@ convergence run via `run_chef`
 
 * Search for _nodes_ by role, and print their IP addresses
 
-  chef > nodes.find(:roles => 'opscode-chef') {|n| n[:ipaddress] }  
+  chef > nodes.find(:roles => 'monitoring-server') {|n| n[:ipaddress] }  
   => ["10.254.199.5"]  
 
 * Remove the role _obsolete_ from every node in the system