%a{annotate:rdoc:skip}
module RDoc
#
# RDoc::Markup parses plain text documents and attempts to decompose them into
# their constituent parts. Some of these parts are high-level: paragraphs,
# chunks of verbatim text, list entries and the like. Other parts happen at the
# character level: a piece of bold text, a word in code font. This markup is
# similar in spirit to that used on WikiWiki webs, where folks create web pages
# using a simple set of formatting rules.
#
# RDoc::Markup and other markup formats do no output formatting, this is handled
# by the RDoc::Markup::Formatter subclasses.
#
# # Supported Formats
#
# Besides the RDoc::Markup format, the following formats are built in to RDoc:
#
# markdown
# : The markdown format as described by
# http://daringfireball.net/projects/markdown/. See RDoc::Markdown for
# details on the parser and supported extensions.
# rd
# : The rdtool format. See RDoc::RD for details on the parser and format.
# tomdoc
# : The TomDoc format as described by http://tomdoc.org/. See RDoc::TomDoc
# for details on the parser and supported extensions.
#
#
# You can choose a markup format using the following methods:
#
# per project
# : If you build your documentation with rake use RDoc::Task#markup.
#
# If you build your documentation by hand run:
#
# rdoc --markup your_favorite_format --write-options
#
# and commit `.rdoc_options` and ship it with your packaged gem.
# per file
# : At the top of the file use the `:markup:` directive to set the default
# format for the rest of the file.
# per comment
# : Use the `:markup:` directive at the top of a comment you want to write in
# a different format.
#
#
# # RDoc::Markup
#
# RDoc::Markup is extensible at runtime: you can add new markup elements to be
# recognized in the documents that RDoc::Markup parses.
#
# RDoc::Markup is intended to be the basis for a family of tools which share the
# common requirement that simple, plain-text should be rendered in a variety of
# different output formats and media. It is envisaged that RDoc::Markup could
# be the basis for formatting RDoc style comment blocks, Wiki entries, and
# online FAQs.
#
# ## Synopsis
#
# This code converts `input_string` to HTML. The conversion takes place in the
# `convert` method, so you can use the same RDoc::Markup converter to convert
# multiple input strings.
#
# require 'rdoc'
#
# h = RDoc::Markup::ToHtml.new(RDoc::Options.new)
#
# puts h.convert(input_string)
#
# You can extend the RDoc::Markup parser to recognize new markup sequences, and
# to add regexp handling. Here we make WikiWords significant to the parser, and
# also make the sequences {word} and text... signify strike-through
# text. We then subclass the HTML output class to deal with these:
#
# require 'rdoc'
#
# class WikiHtml < RDoc::Markup::ToHtml
# def handle_regexp_WIKIWORD(target)
# "" + target.text + ""
# 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, "", "")
#
# puts "#{wh.convert ARGF.read}"
#
# ## Encoding
#
# Where Encoding support is available, RDoc will automatically convert all
# documents to the same output encoding. The output encoding can be set via
# RDoc::Options#encoding and defaults to Encoding.default_external.
#
# # RDoc Markup Reference
#
# See RDoc::MarkupReference.
#
class Markup
class Document
include Enumerable[Document]
def each: () { (Document) -> void } -> void
| () -> Enumerator[Document, void]
def file: () -> String?
def accept: (untyped) -> String
end
class ToMarkdown
end
end
end