# class RDoc::Markup

`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 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 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 <no>text…</no> 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)
        "<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>"

## `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`.

### Attributes

attribute_manager[R]

An AttributeManager which handles inline markup.

### Public Class Methods

new(attribute_manager = nil) click to toggle source

Take a block of text and use various heuristics to determine its structure (paragraphs, lists, and so on). Invoke an event handler as we identify significant chunks.

    # File lib/rdoc/markup.rb, line 146
    def initialize attribute_manager = nil
      @attribute_manager = attribute_manager || RDoc::Markup::AttributeManager.new
      @output = nil
    end

parse(str) click to toggle source

Parses `str` into an RDoc::Markup::Document.

    # File lib/rdoc/markup.rb, line 116
      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

### Public Instance Methods

add_html(tag, name) click to toggle source

Add to the sequences recognized as general markup.

    # File lib/rdoc/markup.rb, line 163
    def add_html(tag, name)
      @attribute_manager.add_html(tag, name)
    end

add_regexp_handling(pattern, name) click to toggle source

Add to other inline sequences. For example, we could add WikiWords using something like:

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

Each wiki word will be presented to the output formatter.

    # File lib/rdoc/markup.rb, line 175
    def add_regexp_handling(pattern, name)
      @attribute_manager.add_regexp_handling(pattern, name)
    end

add_word_pair(start, stop, name) click to toggle source

Add to the sequences used to add formatting to an individual word (such as bold). Matching entries will generate attributes that the output formatters can recognize by their `name`.

    # File lib/rdoc/markup.rb, line 156
    def add_word_pair(start, stop, name)
      @attribute_manager.add_word_pair(start, stop, name)
    end

convert(input, formatter) click to toggle source

We take `input`, parse it if necessary, then invoke the output `formatter` using a Visitor to render the result.

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

      document.accept formatter
    end