(#7683) Use ronn, when available, to render the output.

We now look for ronn(1), and if it is available ask it to generate the *roff
output, delegate that to man(1) directly, and show the result to the user in
their pager.

If ronn(1) isn't available we delegate to $MANPAGER, $PAGER, less, most, or
more, in that order, to paginate the raw markdown.  Not nearly so nice, but
better than doing nothing.

Finally, if none of those pagers are available we fall through to the default
behaviour of puppet rendering the output, which more or less results in a
direct dump to the console.  Nice.

Reviewed-By: Nick Fagerlund <nick.fagerlund@puppetlabs.com>

1 files changed, 48 insertions, 0 deletions

diff --git a/lib/puppet/face/man.rb b/lib/puppet/face/man.rb
index 44a339490..38b9202eb 100644
--- a/lib/puppet/face/man.rb
+++ b/lib/puppet/face/man.rb
@@ -1,4 +1,5 @@
 require 'puppet/face'
+require 'puppet/util'
 require 'pathname'
 require 'erb'
 
@@ -8,6 +9,26 @@ Puppet::Face.define(:man, '0.0.1') do
 
   summary "Display Puppet subcommand manual pages."
 
+  description <<-EOT
+    The man face, when invoked from the command line, tries very hard to
+    behave nicely for interactive use.  If possible, it delegates to the
+    ronn(1) command to format the output as a real manual page.
+
+    If ronn(1) is not available, it will use the first of `$MANPAGER`,
+    `$PAGER`, `less`, `most`, or `more` to paginate the (human-readable)
+    input text for the manual page.
+
+    We do try hard to ensure that this behaves correctly when used as
+    part of a pipeline.  (Well, we delegate to tools that do the right
+    thing, which is more or less the same.)
+  EOT
+
+  notes <<-EOT
+    We strongly encourage you to install the `ronn` gem on your system,
+    or otherwise make it available, so that we can display well structured
+    output from this face.
+  EOT
+
   action(:man) do
     summary "Display the manual page for a face."
     arguments "<face>"
@@ -34,6 +55,33 @@ Puppet::Face.define(:man, '0.0.1') do
       # variables we established just above. --daniel 2011-04-11
       return erb.result(binding)
     end
+
+
+    when_rendering :console do |text|
+      # OK, if we have Ronn on the path we can delegate to it and override the
+      # normal output process.  Otherwise delegate to a pager on the raw text,
+      # otherwise we finally just delegate to our parent.  Oh, well.
+      ENV['LESS'] ||= 'FRSX'    # emulate git...
+
+      ronn  = Puppet::Util.which('ronn')
+      pager = [ENV['MANPAGER'], ENV['PAGER'], 'less', 'most', 'more'].
+        detect {|x| x and x.length > 0 and Puppet::Util.which(x) }
+
+      if ronn then
+        # ronn is a stupid about pager selection, we can be smarter. :)
+        if pager then ENV['PAGER'] = pager end
+
+        args  = "--man --manual='Puppet Manual' --organization='Puppet Labs, LLC'"
+        IO.popen("#{ronn} #{args}", 'w') do |fh| fh.write text end
+
+        ''                      # suppress local output, neh?
+      elsif pager then
+        IO.popen(pager, 'w') do |fh| fh.write text end
+        ''
+      else
+        text
+      end
+    end
   end
 
   def legacy_applications