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

# `Markup` Formats¶ ↑

`RDoc` supports these markup formats:

- `rdoc`: the `RDoc` markup format; see `RDoc::MarkupReference`.

- `markdown`: The `markdown` markup format as described in the Markdown Guide; see `RDoc::Markdown`.

- `rd`: the `rd` markup format format; see `RDoc::RD`.

- `tomdoc`: the TomDoc format as described in TomDoc for Ruby; see `RDoc::TomDoc`.

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)
Source

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

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.

parse (str)
Source

    # File lib/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

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

### Public Instance Methods

add_html (tag, name)
Source

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

Add to the sequences recognized as general markup.

add_regexp_handling (pattern, name)
Source

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

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.

add_word_pair (start, stop, name)
Source

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

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

convert (input, formatter)
Source

    # File lib/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

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