(#7773, 7776, 7764) Several help template tweaks

Per UX review of help output, this commit makes several changes to templates and
shared help text:

* Change "unknown" to "undocumented"
* Remove copyright from short help
* Point readers to the man pages (issue 7773)
* Remove examples from short help (issue 7776)
* Remove summary from short help and make it a fallback for description
* Edit common option summaries to fit on a single 80-col line

4 files changed, 19 insertions, 30 deletions

diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb
index c788f34fd..94b935fed 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 face" %>
 
-<% 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..0122d974c 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 face." %>
 <%= '=' * (_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 -%>
 
diff --git a/lib/puppet/indirector/face.rb b/lib/puppet/indirector/face.rb
index 756306a2f..bb8ce2ceb 100644
--- a/lib/puppet/indirector/face.rb
+++ b/lib/puppet/indirector/face.rb
@@ -2,7 +2,7 @@ require 'puppet/face'
 
 class Puppet::Indirector::Face < Puppet::Face
   option "--terminus TERMINUS" do
-    summary "The indirector terminus to use for this action."
+    summary "The indirector terminus to use."
     description <<-EOT
       Indirector faces expose indirected subsystems of Puppet. These
       subsystems are each able to retrieve and alter a specific type of data