3 files changed, 21 insertions, 32 deletions
diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb
index c788f34fd..5242ed218 100644
--- a/lib/puppet/face/help/action.erb
+++ b/lib/puppet/face/help/action.erb
@@ -1,21 +1,16 @@
-<%= action.summary || face.summary || "unknown face..." %>
-
 <% if action.synopsis -%>
 USAGE: <%= action.synopsis %>
 
 <% end -%>
-<% if action.short_description -%>
-<%= action.short_description.strip %>
+<%= action.short_description || action.summary || face.summary || "undocumented subcommand" %>
 
-<% end -%>
 <% if action.returns -%>
 RETURNS: <%= action.returns.strip %>
 
 <% end -%>
 OPTIONS:
 <%# Remove these options once we can introspect them normally. -%>
-  --mode MODE                    - The run mode to use (`user`, `agent`, or
-                                   `master`).
+  --mode MODE                    - The run mode to use (user, agent, or master).
   --render-as FORMAT             - The rendering format to use.
   --verbose                      - Whether to log verbosely.
   --debug                        - Whether to log debug information.
@@ -26,7 +21,7 @@ OPTIONS:
         option = action.get_option name -%>
 <%= "  " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%>
 <%     if !(option.summary) -%>
-unknown option...
+undocumented option
 <%     elsif option.summary.length <= summaryroom -%>
 <%= option.summary %>
 <%
@@ -51,7 +46,4 @@ unknown option...
       end -%>
 <% end -%>
 
-<% if action.examples -%>
-EXAMPLES:
-<%= action.examples %>
-<% end -%>
+See 'puppet man <%= face.name %>' or 'man puppet-<%= face.name %>' for full help.
diff --git a/lib/puppet/face/help/face.erb b/lib/puppet/face/help/face.erb
index 2a0f0181c..870cc547f 100644
--- a/lib/puppet/face/help/face.erb
+++ b/lib/puppet/face/help/face.erb
@@ -1,17 +1,12 @@
-<%= face.summary || "unknown face..." %>
-
 <% if face.synopsis -%>
 USAGE: <%= face.synopsis %>
 
 <% end -%>
-<% if face.short_description -%>
-<%= face.short_description %>
+<%= (face.short_description || face.summary || "undocumented subcommand").strip %>
 
-<% end -%>
 OPTIONS:
 <%# Remove these options once we can introspect them normally. -%>
-  --mode MODE                    - The run mode to use (`user`, `agent`, or
-                                   `master`).
+  --mode MODE                    - The run mode to use (user, agent, or master).
   --render-as FORMAT             - The rendering format to use.
   --verbose                      - Whether to log verbosely.
   --debug                        - Whether to log debug information.
@@ -22,7 +17,7 @@ OPTIONS:
         option = face.get_option name -%>
 <%= "  " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%>
 <%     if !(option.summary) -%>
-unknown option...
+undocumented option
 <%     elsif option.summary.length <= summaryroom -%>
 <%= option.summary %>
 <%
@@ -54,7 +49,7 @@ ACTIONS:
      action = face.get_action(actionname) -%>
   <%= action.name.to_s.ljust(padding) + '  ' -%>
 <% if !(action.summary) -%>
-unknown action...
+undocumented action
 <% elsif action.summary.length <= summaryroom -%>
 <%= action.summary %>
 <% else
@@ -86,6 +81,4 @@ AUTHOR
 <%= face.authors.join("\n").gsub(/^/, ' * ') %>
 
 <% end -%>
-COPYRIGHT AND LICENSE:
-<%= face.copyright.gsub(/^/, '  ') %>
-<%= face.license.gsub(/^/, '  ')   %>
+See 'puppet man <%= face.name %>' or 'man puppet-<%= face.name %>' for full help.
diff --git a/lib/puppet/face/help/man.erb b/lib/puppet/face/help/man.erb
index 6f21fe413..90e27964c 100644
--- a/lib/puppet/face/help/man.erb
+++ b/lib/puppet/face/help/man.erb
@@ -1,4 +1,4 @@
-puppet-<%= face.name %>(8) -- <%= face.summary || "Unknown face." %>
+puppet-<%= face.name %>(8) -- <%= face.summary || "Undocumented subcommand." %>
 <%= '=' * (_erbout.length - 1) %>
 
 <% if face.synopsis -%>
@@ -32,7 +32,7 @@ configuration options can also be generated by running puppet with
   and `master`.
 * --render-as FORMAT:
   The format in which to render output. The most common formats are `json`,
-  `s` (string), and `yaml`, but other options such as `dot` are
+  `s` (string), `yaml`, and `console`, but other options such as `dot` are
   sometimes available.
 * --verbose:
   Whether to log verbosely.
@@ -57,12 +57,15 @@ ACTIONS
   <%= action.synopsis %>
 
 <%   end -%>
-<%   if action.description -%>
   `DESCRIPTION`
 
+<%   if action.description -%>
 <%= action.description.gsub(/^/, '  ') %>
-<%   end
-     unique_options = action.options - face.options
+<% else -%>
+  <%= action.summary || "Undocumented action." %>
+<%   end -%>
+
+<%   unique_options = action.options - face.options
      unless unique_options.empty? -%>
   `OPTIONS`
 
@@ -101,6 +104,7 @@ EXAMPLES
 `<%= action.name.to_s %>`
 
 <%= action.examples.strip %>
+
 <%   end
    end -%>
 
@@ -112,9 +116,9 @@ NOTES
 
 <% end # notes
 if face.respond_to? :indirection -%>
-This is an indirector face, which exposes `find`, `search`, `save`, and
-`destroy` actions for an indirected subsystem of Puppet. Valid termini
-for this face include:
+This subcommand is an indirector face, which exposes `find`, `search`, `save`,
+and `destroy` actions for an indirected subsystem of Puppet. Valid termini for
+this face include:
 
 * `<%= face.class.terminus_classes(face.indirection.name).join("`\n* `") %>`