How can I define sections without === Headings for RDoc::usage()?

Question

I like to generate man pages using '--help' output via help2man and txt2man. Ruby's RDoc system is very convenient, but I can't seem to configure RDoc::usage in exactly the way that I want. Here's a sample script:

#!/usr/bin/env ruby
#
# === Name
#
#   foobar - Example command for StackOverflow question
#
# === Synopsis
# 
#   Usage: foobar [--help]
#
# === Options
#
#   --help     This help message

require 'rdoc/usage'

RDoc::usage('name', 'synopsis', 'options')

The output of the script looks like this:

Name
 foobar - Example command for StackOverflow question

Synopsis
 Usage: foobar [--help]

Options
 --help     This help message

But I would really like to suppress the "Name" and "Synopsis" headers for my usage output, but still mark them as sections for output to a man page.

Using the ':section:' markup works for RDoc::Rdoc, but not RDoc::usage. Is there an obvious way to mark sections for usage.rb without printing headers?

Answer 1

Look at the source code for RDoc::usage_no_exit; you have two ways of hooking to its guts to achieve what yyou desire:

1. Set ENV['RI'] to enforce different formatting options (including specifying a custom formatter class), or

2. Redefine the default RI::TextFormatter's display_heading (and/or other methods) to (not) display the headings or whatever else

   require 'rdoc/usage'
   require 'rdoc/ri/ri_formatter'
   
   
   module RI
     class TextFormatter
       def display_heading
         # nop
       end
     end
   end
   
   
   RDoc::usage('name')