Merge branch '2.7.x'

* 2.7.x: (40 commits)
  (#7746) Fix bootstrap issues from #7717 fix.
  (#7683) Use ronn, when available, to render the output.
  (#7683) Add a 'man' face and subcommand to Puppet.
  maint: remove obsolete work-around code from help face.
  (#7699) Don't duplicate inherited action names on faces.
  (#7177) Deprecate implicit 'puppet apply' for 2.7.0
  (#7717) Layout cleanup for subcommand extraction.
  #7211: Test unknown options don't shadow unknown actions.
  #7211: nasty logic error with global Face options taking arguments.
  #7211: more helpful error messages in various cases.
  maint: Fix order dependent test failure
  (#5966) Add support for hostname regular expressions in auth.conf
  (#7708) Delete extended documentation from configuration reference
  (#7707) Document signals in puppet agent and puppet master help
  add puppet master polling step for ticket 7117
  (#5318) Always notice changes to manifests when compiling.
  (#5318) Always notice changes to manifests when compiling.
  (#7557) Remove Faces Application
  maint: Fix order dependent spec failure for face indirection
  (#7690) Don't blow up when listing terminuses available for faces
  ...

Conflicts (resolved manually):
	acceptance/tests/ticket_7117_broke_env_criteria_authconf.rb

1 files changed, 27 insertions, 16 deletions

diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb
index be38ad388..d244127a4 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -3,24 +3,35 @@ Puppet::Indirector::Face.define(:node, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
-  summary "View and manage node definitions"
-
-  description <<-EOT
-    This face interacts with node objects, which are what Puppet uses to
+  summary "View and manage node definitions."
+  description <<-'EOT'
+    This face interacts with node objects, which are used by Puppet to
     build a catalog. A node object consists of the node's facts,
-    environment, additional top-scope variables, and classes.
+    environment, node parameters (exposed in the parser as top-scope
+    variables), and classes.
   EOT
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
-    for this face include:
 
-    * `active_record`
-    * `exec`
-    * `ldap`
-    * `memory`
-    * `plain`
-    * `rest`
-    * `yaml`
+  get_action(:destroy).summary "Invalid for this face."
+  get_action(:search).summary "Invalid for this face."
+  get_action(:save).summary "Invalid for this face."
+
+  find = get_action(:find)
+  find.summary "Retrieve a node object."
+  find.arguments "<host>"
+  find.returns <<-'EOT'
+    A Puppet::Node object.
+
+    RENDERING ISSUES: Rendering as string and json are currently broken;
+    node objects can only be rendered as yaml.
+  EOT
+  find.examples <<-'EOT'
+    Retrieve an "empty" (no classes, fact and bulit-in parameters only,
+    and an environment of "production") node:
+
+    $ puppet node find somenode.puppetlabs.lan --terminus plain --render-as yaml
+
+    Retrieve a node using the puppet master's configured ENC:
+
+    $ puppet node find somenode.puppetlabs.lan --terminus exec --mode master --render-as yaml
   EOT
 end