Class: RDoc::Markup

Inherits:
Object show all
Defined in:
lib/rdoc/markup.rb,
lib/rdoc/markup/attr_changer.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.

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.

–

Original Author

Dave Thomas, [email protected]

License

Ruby license

Defined Under Namespace

Classes: AttrChanger, AttrSpan, AttributeManager, Attributes, BlankLine, BlockQuote, Document, Formatter, HardBreak, Include, IndentedParagraph, List, ListItem, Paragraph, Parser, PreProcess, Raw, RegexpHandling, 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(attribute_manager = nil) ⇒ 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.



146
147
148
149
 
# File 'lib/rdoc/markup.rb', line 146

def initialize attribute_manager = nil
  @attribute_manager = attribute_manager || RDoc::Markup::AttributeManager.new
  @output = nil
end

Instance Attribute Details

#attribute_manager ⇒ Object (readonly)

An AttributeManager which handles inline markup.



111
112
113
 
# File 'lib/rdoc/markup.rb', line 111

def attribute_manager
  @attribute_manager
end

Class Method Details

.parse(str) ⇒ Object

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



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# 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

Instance Method Details

#add_html(tag, name) ⇒ Object

Add to the sequences recognized as general markup.



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

def add_html(tag, name)
  @attribute_manager.add_html(tag, name)
end

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



175
176
177
 
# 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) ⇒ Object

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.



156
157
158
 
# 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) ⇒ Object

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



183
184
185
186
187
188
189
190
191
192
 
# 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