123456789_123456789_123456789_123456789_123456789_

Class: RDoc::Markup

Overview

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.

Markup and other markup formats do no output formatting, this is handled by the 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.

Markup

Markup is extensible at runtime: you can add new markup elements to be recognized in the documents that Markup parses.

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 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 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 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 Options#encoding and defaults to Encoding.default_external.

RDoc Markup Reference

See MarkupReference.

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(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.

[ GitHub ] 

  


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



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


  







Class Method Details



  

    .parse(str)  
  



  

    

Parses str into an Markup::Document.


  



  [ GitHub ]


  

  


# 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 Attribute Details



  

    #attribute_manager   (readonly)
  



  

    

An AttributeManager which handles inline markup.


  



  [ GitHub ]


  

  


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



attr_reader :attribute_manager


  







Instance Method Details



  

    #add_html(tag, name)  
  



  

    

Add to the sequences recognized as general markup.


  



  [ GitHub ]


  

  


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



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


  








  

    #add_regexp_handling(pattern, name)  
  



  

    

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.


  



  [ GitHub ]


  

  


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



  

    

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.


  



  [ GitHub ]


  

  


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



  

    

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


  



  [ GitHub ]


  

  


# 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