class RDoc::Markup

RDoc::Markup 解析纯文本文档，并尝试将其分解为组成部分。其中一些部分是高级别的：段落、逐字文本块、列表条目等。其他部分发生在字符级别：一段粗体文本、代码字体中的一个单词。这种标记在精神上类似于 WikiWiki 网站上使用的标记，人们可以使用一组简单的格式规则创建网页。

RDoc::Markup 和其他标记格式不进行输出格式化，这由 RDoc::Markup::Formatter 子类处理。

Markup 格式 ↑

RDoc 支持以下标记格式

您可以使用以下方法选择标记格式

每个项目

如果您使用 rake 构建文档，请使用 RDoc::Task#markup。

如果您手动构建文档，请运行

rdoc --markup your_favorite_format --write-options

并提交 .rdoc_options 并将其与您打包的 gem 一起发布。

每个文件

在文件顶部使用 :markup: 指令来设置文件其余部分的默认格式。

每个注释

在要以不同格式编写的注释顶部使用 :markup: 指令。

RDoc::Markup ↑

RDoc::Markup 在运行时是可扩展的：您可以添加新的标记元素，以便在 RDoc::Markup 解析的文档中识别。

RDoc::Markup 旨在成为一系列工具的基础，这些工具的共同要求是以各种不同的输出格式和媒体呈现简单的纯文本。可以设想，RDoc::Markup 可以作为格式化 RDoc 样式注释块、Wiki 条目和在线常见问题解答的基础。

概要 ↑

此代码将 input_string 转换为 HTML。转换发生在 convert 方法中，因此您可以使用相同的 RDoc::Markup 转换器来转换多个输入字符串。

require 'rdoc'

h = RDoc::Markup::ToHtml.new(RDoc::Options.new)

puts h.convert(input_string)

您可以扩展 RDoc::Markup 解析器以识别新的标记序列，并添加正则表达式处理。在这里，我们使 WikiWords 对解析器具有意义，并且使序列 {word} 和 <no>text…</no> 表示删除线文本。然后，我们对 HTML 输出类进行子类化以处理这些。

require 'rdoc'

class WikiHtml < RDoc::Markup::ToHtml
  def handle_regexp_WIKIWORD(target)
    "<font color=red>" + target.text + "</font>"
  end
end

markup = RDoc::Markup.new
markup.add_word_pair("{", "}", :STRIKE)
markup.add_html("no", :STRIKE)

markup.add_regexp_handling(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)

wh = WikiHtml.new RDoc::Options.new, markup
wh.add_tag(:STRIKE, "<strike>", "</strike>")

puts "<body>#{wh.convert ARGF.read}</body>"

编码 ↑

在支持编码的情况下，RDoc 会自动将所有文档转换为相同的输出编码。输出编码可以通过 RDoc::Options#encoding 设置，默认值为 Encoding.default_external。

RDoc Markup 参考 ↑

请参阅 RDoc::MarkupReference。

属性

attribute_manager[R]

一个处理内联标记的 AttributeManager。

公共类方法

new(attribute_manager = nil) 点击以切换源代码

获取一段文本，并使用各种启发式方法来确定其结构（段落、列表等）。当我们识别出重要的块时，调用事件处理程序。

# File rdoc/markup.rb, line 151
def initialize attribute_manager = nil
  @attribute_manager = attribute_manager || RDoc::Markup::AttributeManager.new
  @output = nil
end
parse(str) 点击以切换源代码

将 str 解析为 RDoc::Markup::Document。

# File rdoc/markup.rb, line 121
  def self.parse str
    RDoc::Markup::Parser.parse str
  rescue RDoc::Markup::Parser::Error => e
    $stderr.puts <<-EOF
While parsing markup, RDoc encountered a #{e.class}:

#{e}
\tfrom #{e.backtrace.join "\n\tfrom "}

---8<---
#{text}
---8<---

RDoc #{RDoc::VERSION}

Ruby #{RUBY_VERSION}-p#{RUBY_PATCHLEVEL} #{RUBY_RELEASE_DATE}

Please file a bug report with the above information at:

https://github.com/ruby/rdoc/issues

    EOF
    raise
  end

公共实例方法

add_html(tag, name) 点击以切换源代码

添加到被识别为通用标记的序列。

# File rdoc/markup.rb, line 168
def add_html(tag, name)
  @attribute_manager.add_html(tag, name)
end
add_regexp_handling(pattern, name) 点击以切换源代码

添加到其他内联序列。例如，我们可以使用类似这样的方法添加 WikiWords

parser.add_regexp_handling(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)

每个 Wiki 单词都将呈现给输出格式化程序。

# File rdoc/markup.rb, line 180
def add_regexp_handling(pattern, name)
  @attribute_manager.add_regexp_handling(pattern, name)
end
add_word_pair(start, stop, name) 点击以切换源代码

添加到用于向单个单词添加格式的序列（例如 粗体）。匹配的条目将生成输出格式化程序可以通过其 name 识别的属性。

# File rdoc/markup.rb, line 161
def add_word_pair(start, stop, name)
  @attribute_manager.add_word_pair(start, stop, name)
end
convert(input, formatter) 点击以切换源代码

我们获取 input，在必要时进行解析，然后使用访问者调用输出 formatter 以呈现结果。

# File rdoc/markup.rb, line 188
def convert input, formatter
  document = case input
             when RDoc::Markup::Document then
               input
             else
               RDoc::Markup::Parser.parse input
             end

  document.accept formatter
end