(#7564) Finish templates

This is a rebase of the following commits:

* (#7563) Add a template for manpages

In order to generate manpages in a reasonably maintainable way, we need
to format text from the Faces help API for use with Ronn
(https://github.com/rtomayko/ronn/).

This commit adds a man template to the help templates folder; it has
been verified to generate Ronn-friendly input text. It isn't currently
called by any applications, but can be demonstrated by exchanging it for
face.erb.

* (#7634) Change ERB trim mode used in the Faces help API

<%= something -%> tags (note the minus) are unavoidably necessary at at
least one point in the Faces help templates. ERB objects instantiated
with the % trim mode will blow up horribly whenever one of these tags
appears.

This commit changes the trim mode to `-` and refactors all help
templates accordingly.

* (#7563) Refactor short help templates

This commit attempts to bring the short face and action help templates closer to the goals of fitting cleanly on one screen, fitting the prevailing *nix aesthetic, and being useful without overwhelming the user.

5 files changed, 271 insertions, 60 deletions

diff --git a/lib/puppet/face/help.rb b/lib/puppet/face/help.rb
index 7a382b8c9..9376adf04 100644
--- a/lib/puppet/face/help.rb
+++ b/lib/puppet/face/help.rb
@@ -95,7 +95,7 @@ Puppet::Face.define(:help, '0.0.1') do
 
   def erb(name)
     template = (Pathname(__FILE__).dirname + "help" + name)
-    erb = ERB.new(template.read, nil, '%')
+    erb = ERB.new(template.read, nil, '-')
     erb.filename = template.to_s
     return erb
   end
diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb
index aab7f2564..c788f34fd 100644
--- a/lib/puppet/face/help/action.erb
+++ b/lib/puppet/face/help/action.erb
@@ -1,22 +1,57 @@
-puppet <%= face.name %><%= action.default? ? '' : " #{action.name}" %> - <%= action.summary || face.summary %>
+<%= action.summary || face.summary || "unknown face..." %>
 
-% if action.synopsis
-usage: <%= action.synopsis %>
+<% if action.synopsis -%>
+USAGE: <%= action.synopsis %>
 
-% end
-% if action.description or action.short_description
-<%= action.short_description %>
+<% end -%>
+<% if action.short_description -%>
+<%= action.short_description.strip %>
 
-%end
-% unless action.options.empty?
+<% end -%>
+<% if action.returns -%>
+RETURNS: <%= action.returns.strip %>
+
+<% end -%>
 OPTIONS:
-%   action.options.sort.each do |name|
-%     option = action.get_option name
-<%= "  " + option.optparse.join(" |" ) %> - <%= option.summary %>
+<%# Remove these options once we can introspect them normally. -%>
+  --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.
+<% unless action.options.empty?
+     optionroom = 30
+     summaryroom = 80 - 5 - optionroom
+      action.options.sort.each do |name|
+        option = action.get_option name -%>
+<%= "  " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%>
+<%     if !(option.summary) -%>
+unknown option...
+<%     elsif option.summary.length <= summaryroom -%>
+<%= option.summary %>
+<%
+        else
+          words = option.summary.split
+          wrapped = ['']
+          i = 0
+          words.each do |word|
+            if wrapped[i].length + word.length <= summaryroom
+              wrapped[i] << word + ' '
+            else
+              i += 1
+              wrapped[i] = word + ' '
+            end
+          end
+-%>
+<%= wrapped.shift.strip %>
+<%       wrapped.each do |line| -%>
+<%= (' ' * (optionroom + 5) ) + line.strip %>
+<%       end
+        end
+      end -%>
+<% end -%>
 
-%   end
-% end
-% if action.examples
+<% if action.examples -%>
 EXAMPLES:
 <%= action.examples %>
-% end
+<% end -%>
diff --git a/lib/puppet/face/help/face.erb b/lib/puppet/face/help/face.erb
index b249981de..2a0f0181c 100644
--- a/lib/puppet/face/help/face.erb
+++ b/lib/puppet/face/help/face.erb
@@ -1,48 +1,91 @@
-NAME
-  <%= face.name %> -- <%= face.summary || "unknown face..." %>
+<%= face.summary || "unknown face..." %>
 
-% if face.synopsis
-SYNOPSIS
-<%= face.synopsis.gsub(/^/, '  ') %>
+<% if face.synopsis -%>
+USAGE: <%= face.synopsis %>
 
-% end
-% if face.description
-DESCRIPTION
-<%= face.description.chomp.gsub(/^/, '  ') %>
+<% end -%>
+<% if face.short_description -%>
+<%= face.short_description %>
 
-%end
-% unless face.options.empty?
-OPTIONS
-%   face.options.sort.each do |name|
-%     option = face.get_option name
-<%= "  " + option.optparse.join(" |" ) %>
+<% end -%>
+OPTIONS:
+<%# Remove these options once we can introspect them normally. -%>
+  --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.
+<% unless face.options.empty?
+     optionroom = 30
+     summaryroom = 80 - 5 - optionroom
+      face.options.sort.each do |name|
+        option = face.get_option name -%>
+<%= "  " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%>
+<%     if !(option.summary) -%>
+unknown option...
+<%     elsif option.summary.length <= summaryroom -%>
 <%= option.summary %>
-<%= option.description %>
+<%
+       else
+         words = option.summary.split
+         wrapped = ['']
+         i = 0
+         words.each do |word|
+           if wrapped[i].length + word.length <= summaryroom
+             wrapped[i] << word + ' '
+           else
+             i += 1
+             wrapped[i] = word + ' '
+           end
+         end
+-%>
+<%= wrapped.shift.strip %>
+<%       wrapped.each do |line| -%>
+<%= (' ' * (optionroom + 5) ) + line.strip %>
+<%       end
+        end
+      end -%>
+<% end -%>
 
-%   end
-% end
-ACTIONS
-% padding = face.actions.map{|x| x.to_s.length}.max + 2
-% face.actions.each do |actionname|
-%   action = face.get_action(actionname)
-  <%= action.name.to_s.ljust(padding) %>  <%= action.summary %>
-% end
+ACTIONS:
+<% padding = face.actions.map{|x| x.to_s.length}.max + 2
+   summaryroom = 80 - (padding + 4)
+   face.actions.each do |actionname|
+     action = face.get_action(actionname) -%>
+  <%= action.name.to_s.ljust(padding) + '  ' -%>
+<% if !(action.summary) -%>
+unknown action...
+<% elsif action.summary.length <= summaryroom -%>
+<%= action.summary %>
+<% else
+          words = action.summary.split
+          wrapped = ['']
+          i = 0
+          words.each do |word|
+            if wrapped[i].length + word.length <= summaryroom
+              wrapped[i] << word + ' '
+            else
+              i += 1
+              wrapped[i] = word + ' '
+            end
+          end
+-%>
+<%= wrapped.shift.strip %>
+<%       wrapped.each do |line| -%>
+<%= (' ' * (padding + 4) ) + line.strip %>
+<%       end
+        end
+end -%>
 
-% if face.examples
-EXAMPLES
-<%= face.examples %>
-% end
-% if face.notes
-NOTES
-<%= face.notes %>
+<% if face.respond_to? :indirection -%>
+TERMINI: <%= face.class.terminus_classes(face.indirection.name).join(", ") %>
 
-% end
-% unless face.authors.empty?
+<% end
+   unless face.authors.empty? -%>
 AUTHOR
 <%= face.authors.join("\n").gsub(/^/, ' * ') %>
 
-%end
-COPYRIGHT AND LICENSE
+<% end -%>
+COPYRIGHT AND LICENSE:
 <%= face.copyright.gsub(/^/, '  ') %>
 <%= face.license.gsub(/^/, '  ')   %>
-
diff --git a/lib/puppet/face/help/global.erb b/lib/puppet/face/help/global.erb
index 80c77ad26..c5a9ec9e0 100644
--- a/lib/puppet/face/help/global.erb
+++ b/lib/puppet/face/help/global.erb
@@ -1,18 +1,18 @@
 Usage: puppet <subcommand> [options] <action> [options]
 
 Available subcommands, from Puppet Faces:
-% Puppet::Face.faces.sort.each do |name|
-%   face = Puppet::Face[name, :current]
+<% Puppet::Face.faces.sort.each do |name|
+     face = Puppet::Face[name, :current] -%>
   <%= face.name.to_s.ljust(16) %>  <%= face.summary %>
-% end
+<% end -%>
 
-% unless legacy_applications.empty? then # great victory when this is true!
+<% unless legacy_applications.empty? then # great victory when this is true! -%>
 Available applications, soon to be ported to Faces:
-%   legacy_applications.each do |appname|
-%     summary = horribly_extract_summary_from appname
+<%   legacy_applications.each do |appname|
+       summary = horribly_extract_summary_from appname -%>
   <%= appname.to_s.ljust(16) %>  <%= summary %>
-%   end
-% end
+<%   end
+   end -%>
 
 See 'puppet help <subcommand> <action>' for help on a specific subcommand action.
 See 'puppet help <subcommand>' for help on a specific subcommand.
diff --git a/lib/puppet/face/help/man.erb b/lib/puppet/face/help/man.erb
new file mode 100644
index 000000000..899d0166c
--- /dev/null
+++ b/lib/puppet/face/help/man.erb
@@ -0,0 +1,133 @@
+puppet-<%= face.name %>(8) -- <%= face.summary || "Unknown face." %>
+<%= '=' * (_erbout.length - 1) %>
+
+<% if face.synopsis -%>
+SYNOPSIS
+--------
+<%= face.synopsis %>
+
+<% end
+   if face.description -%>
+DESCRIPTION
+-----------
+<%= face.description.strip %>
+
+<% end -%>
+OPTIONS
+-------
+Note that any configuration parameter that's valid in the configuration
+file is also a valid long argument, although it may or may not be
+relevant to the present action. For example, `server` is a valid
+configuration parameter, so you can specify `--server <servername>` as
+an argument.
+
+See the configuration file documentation at
+<http://docs.puppetlabs.com/references/stable/configuration.html> for the
+full list of acceptable parameters. A commented list of all
+configuration options can also be generated by running puppet with
+`--genconfig`.
+
+* --mode MODE:
+  The run mode to use for the current action. Valid modes are `user`, `agent`,
+  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
+  sometimes available.
+* --verbose:
+  Whether to log verbosely.
+* --debug:
+  Whether to log debug information.
+<% unless face.options.empty?
+     face.options.sort.each do |name|
+       option = face.get_option name -%>
+<%= "* " + option.optparse.join(" | " ) %>:
+<%= option.description.gsub(/^/, '  ') || '  ' + option.summary %>
+<%   end
+   end -%>
+
+ACTIONS
+-------
+<% face.actions.each do |actionname|
+     action = face.get_action(actionname) -%>
+* `<%= action.name.to_s %>` - <%= action.summary %>:
+<%   if action.synopsis -%>
+  `SYNOPSIS`
+
+  <%= action.synopsis %>
+
+<%   end -%>
+<%   if action.description -%>
+  `DESCRIPTION`
+
+<%= action.description.gsub(/^/, '  ') %>
+<%   end
+     unique_options = action.options - face.options
+     unless unique_options.empty? -%>
+  `OPTIONS`
+
+<%     unique_options.sort.each do |name|
+         option = action.get_option name
+         text = option.description || option.summary -%>
+  <%= '<' + option.optparse.join("> | <") + '>' %> -
+<%= text.gsub(/^/, '  ') %>
+<%     end -%>
+
+<%   end -%>
+<%   if action.returns -%>
+  `RETURNS`
+
+<%= action.returns.gsub(/^/, '  ') %>
+
+<%   end
+     if action.notes -%>
+  `NOTES`
+
+<%= action.notes.gsub(/^/, '  ') %>
+
+<%   end
+   end
+   if face.examples or face.actions.any? {|actionname| face.get_action(actionname).examples} -%>
+EXAMPLES
+--------
+<% end
+   if face.examples -%>
+<%= face.examples %>
+
+<% end
+   face.actions.each do |actionname|
+     action = face.get_action(actionname)
+     if action.examples -%>
+`<%= action.name.to_s %>`
+
+<%= action.examples.strip %>
+<%   end
+   end -%>
+
+<% if face.notes or face.respond_to? :indirection -%>
+NOTES
+-----
+<% if face.notes -%>
+<%= face.notes.strip %>
+
+<% 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:
+
+* `<%= face.class.terminus_classes(face.indirection.name).join("`\n* `") %>`
+
+<% end # indirection
+   end # notes or indirection
+   unless face.authors.empty? -%>
+AUTHOR
+------
+<%= face.authors.join("\n").gsub(/^/, ' * ') %>
+
+<% end -%>
+COPYRIGHT AND LICENSE
+---------------------
+<%= face.copyright %>
+<%= face.license %>
+