Class: RDoc::Markup

Inherits:
Object
  • Object
show all
Defined in:
lib/rdoc/markup.rb,
lib/rdoc/markup/raw.rb,
lib/rdoc/markup/table.rb,
lib/rdoc/markup/element.rb,
lib/rdoc/markup/heading.rb,
lib/rdoc/markup/blank_line.rb,
lib/rdoc/markup/hard_break.rb

Overview

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 Markup Reference

  • 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 + "</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 Markup Reference

–

Original Author

Dave Thomas, [email protected]

License

Ruby license

Defined Under Namespace

Classes: BlankLine, BlockQuote, Document, Element, Formatter, HardBreak, Heading, Include, IndentedParagraph, InlineParser, LinkLabelToHtml, List, ListItem, Paragraph, Parser, PreProcess, Raw, Rule, Table, ToAnsi, ToBs, ToHtml, ToHtmlCrossref, ToHtmlSnippet, ToJoinedParagraph, ToLabel, ToMarkdown, ToRdoc, ToTableOfContents, ToTest, ToTtOnly, Verbatim

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Markup

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.



151
152
153
154
 
# File 'lib/rdoc/markup.rb', line 151

def initialize
  @regexp_handlings = []
  @output = nil
end

Instance Attribute Details

#regexp_handlings ⇒ Object (readonly)

Array of regexp handling pattern and its name. A regexp handling sequence is something like a WikiWord



116
117
118
 
# File 'lib/rdoc/markup.rb', line 116

def regexp_handlings
  @regexp_handlings
end

Class Method Details

.parse(str) ⇒ Object

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



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# 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

Instance Method Details

#add_regexp_handling(pattern, name) ⇒ Object

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.



164
165
166
 
# File 'lib/rdoc/markup.rb', line 164

def add_regexp_handling(pattern, name)
  @regexp_handlings << [pattern, name]
end

#convert(input, formatter) ⇒ Object

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



172
173
174
175
176
177
178
179
180
181
 
# File 'lib/rdoc/markup.rb', line 172

def convert(input, formatter)
  document = case input
             when RDoc::Markup::Document then
               input
             else
               RDoc::Markup::Parser.parse input
             end

  document.accept formatter
end