如何为 RDoc::usage() 定义没有 === 标题的部分？答案

【问题标题】：How can I define sections without === Headings for RDoc::usage()?如何为 RDoc::usage() 定义没有 === 标题的部分？
【发布时间】：2010-10-12 12:11:31
【问题描述】：

我喜欢通过 help2man 和 txt2man 使用“--help”输出来生成手册页。 Ruby 的 RDoc 系统非常方便，但我似乎无法完全按照我想要的方式配置 RDoc::usage。这是一个示例脚本：

#!/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')

脚本的输出如下所示：

Name
    foobar - Example command for StackOverflow question

Synopsis
    Usage: foobar [--help]

Options
    --help      This help message

但我真的很想为我的用法输出隐藏“名称”和“概要”标题，但仍将它们标记为输出到手册页的部分。

使用 ':section:' 标记适用于 RDoc::Rdoc，但不适用于 RDoc::usage。有没有明显的方法来标记 usage.rb 的部分而不打印标题？

【问题讨论】：

标签： ruby comments markup rdoc manpage

【解决方案1】：

查看RDoc::usage_no_exit的源码；你有两种方法可以抓住它的胆量来实现你的愿望：

设置 ENV['RI'] 以强制执行不同的格式化选项（包括指定自定义格式化程序类），或

重新定义默认 RI::TextFormatter 的 display_heading（和/或其他方法）以（不）显示标题或其他任何内容

require 'rdoc/usage'
require 'rdoc/ri/ri_formatter'

module RI
  class TextFormatter
    def display_heading
      # nop
    end
  end
end

RDoc::usage('name')

【讨论】：