Class: RDoc::Markup

Inherits:
Object
  • 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.

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.

–

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.



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

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.



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

def attribute_manager
  @attribute_manager
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_html(tag, name) ⇒ Object

Add to the sequences recognized as general markup.



168
169
170
 
# File 'lib/rdoc/markup.rb', line 168

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.



180
181
182
 
# File 'lib/rdoc/markup.rb', line 180

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.



161
162
163
 
# File 'lib/rdoc/markup.rb', line 161

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.



188
189
190
191
192
193
194
195
196
197
 
# 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