Class: RDoc::Markup::ToHtml

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses: ToHtmlCrossref, ToHtmlSnippet
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, Formatter
Instance Chain: self, ::RDoc::Text, Formatter
Inherits:	RDoc::Markup::Formatter Object RDoc::Markup::Formatter RDoc::Markup::ToHtml
Defined in:	lib/rdoc/markup/to_html.rb

Overview

Outputs RDoc markup as HTML.

Constant Summary

LIST_TYPE_TO_HTML =

Maps Parser::LIST_TOKENS types to HTML tags

# File 'lib/rdoc/markup/to_html.rb', line 15

{
  :BULLET => ['<ul>',                                      '</ul>'],
  :LABEL  => ['<dl class="rdoc-list label-list">',         '</dl>'],
  :LALPHA => ['<ol style="list-style-type: lower-alpha">', '</ol>'],
  :NOTE   => ['<dl class="rdoc-list note-list">',          '</dl>'],
  :NUMBER => ['<ol>',                                      '</ol>'],
  :UALPHA => ['<ol style="list-style-type: upper-alpha">', '</ol>'],
}

::RDoc::Text - Included

MARKUP_FORMAT, TO_HTML_CHARACTERS

Utilities

#code_object rw

The ::RDoc::CodeObject HTML is being generated for.
#convert_string(text)

CGI-escapes text
#from_path rw

Path to this document for relative links.
#gen_url(url, text)

Generate a link to url with content text.
#html_list_name(list_type, open_tag)

Determines the HTML list element for list_type and open_tag
#init_tags

Maps attributes to HTML tags.
#list_end_for(list_type)

Returns the HTML end-tag for list_type
#list_item_start(list_item, list_type)

Returns the HTML tag for list_type, possible using a label from list_item
#parseable?(text) ⇒ Boolean

Returns true if text is valid ruby syntax.
#to_html(item)

Converts item to HTML using Text#to_html

Special Handling

#handle_special_HARD_BREAK(special)

special is a .
#handle_special_HYPERLINK(special)

special is a potential link.
#handle_special_RDOCLINK(special)

special is an rdoc-schemed link that will be converted into a hyperlink.
#handle_special_TIDYLINK(special)

This special is a link where the label is different from the URL label[url] or {url long label}.

Visitor

#accept_blank_line(blank_line)

Adds blank_line to the output.
#accept_block_quote(block_quote)

Adds block_quote to the output.
#accept_heading(heading)

Adds heading to the output.
#accept_list_end(list)

Finishes consumption of #list
#accept_list_item_end(list_item)

Finishes consumption of list_item
#accept_list_item_start(list_item)

Prepares the visitor for consuming list_item
#accept_list_start(list)

Prepares the visitor for consuming #list
#accept_paragraph(paragraph)

Adds paragraph to the output.
#accept_raw(raw)

Adds raw to the output.
#accept_rule(rule)

Adds rule to the output.
#accept_verbatim(verbatim)

Adds verbatim to the output.
#end_accepting

Returns the generated output.
#start_accepting

Prepares the visitor for HTML generation.

Class Method Summary

.new(options, markup = nil) ⇒ ToHtml constructor

Creates a new formatter that will output HTML.

Formatter - Inherited

.gen_relative_url	Converts a target url to one that is relative to a given path.
.new	Creates a new Formatter.

Instance Attribute Summary

Formatter - Inherited

#in_tt?

Are we currently inside tt tags?

Instance Method Summary

::RDoc::Text - Included

#expand_tabs	Expands tab characters in `text` to eight spaces.
#flush_left	Flush `text` left based on the shortest line.
#markup	Convert a string in markup format into HTML.
#normalize_comment	Strips hashes, expands tabs then flushes `text` to the left.
#parse	Normalizes `text` then builds a Document from it.
#snippet	The first `limit` characters of `text` as HTML.
#strip_hashes	Strips leading # characters from `text`
#strip_newlines	Strips leading and trailing n characters from `text`
#strip_stars	Strips /* */ style comments.
#to_html	Converts ampersand, dashes, ellipsis, quotes, copyright and registered trademark symbols in `text` to properly encoded characters.
#wrap	Wraps `txt` to `line_len`

Formatter - Inherited

#accept_document	Adds `document` to the output.
#add_special_RDOCLINK	Adds a special for links of the form rdoc-…:
#add_special_TIDYLINK	Adds a special for links of the form `<text>` and <#add_tag	Add a new set of tags for an attribute.
#annotate	Allows `tag` to be decorated with additional information.
#convert	Marks up `content`
#convert_flow	Converts flow items `flow`
#convert_special	Converts added specials.
#convert_string	Converts a string to be fancier if desired.
#ignore	Use ignore in your subclass to ignore the content of a node.
#off_tags	Turns off tags for `item` on #res
#on_tags	Turns on tags for `item` on #res
#parse_url	Extracts and a scheme, url and an anchor id from `url` and returns them.
#tt?	Is `tag` a tt tag?

Constructor Details

.new(options, markup = nil) ⇒ `ToHtml`

Creates a new formatter that will output HTML

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 44


def initialize options, markup = nil
  super

  @code_object = nil
  @from_path = ''
  @in_list_entry = nil
  @list = nil
  @th = nil
  @hard_break = "<br>\n"

  # external links
  @markup.add_special(/(?:link:|https?:|mailto:|ftp:|irc:|www\.)\S+\w/,
                      :HYPERLINK)

  add_special_RDOCLINK
  add_special_TIDYLINK

  init_tags
end

Instance Attribute Details

#code_object (rw)

The ::RDoc::CodeObject HTML is being generated for. This is used to generate namespaced URI fragments

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 32


attr_accessor :code_object

#from_path (rw)

Path to this document for relative links

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 37


attr_accessor :from_path

Instance Method Details

#accept_blank_line(blank_line)

Adds blank_line to the output

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 268


def accept_blank_line(blank_line)
  # @res << annotate("<p />") << "\n"
end

#accept_block_quote(block_quote)

Adds block_quote to the output

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 171


def accept_block_quote block_quote
  @res << "\n<blockquote>"

  block_quote.parts.each do |part|
    part.accept self
  end

  @res << "</blockquote>\n"
end

#accept_heading(heading)

Adds heading to the output. The headings greater than 6 are trimmed to level 6.

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 276


def accept_heading heading
  level = [6, heading.level].min

  label = heading.label @code_object

  @res << if @options.output_decoration
            "\n<h#{level} id=\"#{label}\">"
          else
            "\n<h#{level}>"
          end
  @res << to_html(heading.text)
  unless @options.pipe then
    @res << "<span><a href=\"##{label}\">&para;</a>"
    @res << " <a href=\"#top\">&uarr;</a></span>"
  end
  @res << "</h#{level}>\n"
end

#accept_list_end(list)

Finishes consumption of #list

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 239


def accept_list_end(list)
  @list.pop
  if tag = @in_list_entry.pop
    @res << tag
  end
  @res << html_list_name(list.type, false) << "\n"
end

#accept_list_item_end(list_item)

Finishes consumption of list_item

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 261


def accept_list_item_end(list_item)
  @in_list_entry[-1] = list_end_for(@list.last)
end

#accept_list_item_start(list_item)

Prepares the visitor for consuming list_item

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 250


def accept_list_item_start(list_item)
  if tag = @in_list_entry.last
    @res << tag
  end

  @res << list_item_start(list_item, @list.last)
end

#accept_list_start(list)

Prepares the visitor for consuming #list

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 230


def accept_list_start(list)
  @list << list.type
  @res << html_list_name(list.type, true)
  @in_list_entry.push false
end

#accept_paragraph(paragraph)

Adds paragraph to the output

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 184


def accept_paragraph paragraph
  @res << "\n<p>"
  text = paragraph.text @hard_break
  text = text.gsub(/\r?\n/, ' ')
  @res << wrap(to_html(text))
  @res << "</p>\n"
end

#accept_raw(raw)

Adds raw to the output

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 297


def accept_raw raw
  @res << raw.parts.join("\n")
end

#accept_rule(rule)

Adds rule to the output

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 223


def accept_rule rule
  @res << "<hr>\n"
end

#accept_verbatim(verbatim)

Adds verbatim to the output

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 195


def accept_verbatim verbatim
  text = verbatim.text.rstrip

  klass = nil

  content = if verbatim.ruby? or parseable? text then
              begin
                tokens = RDoc::RubyLex.tokenize text, @options
                klass  = ' class="ruby"'

                RDoc::TokenStream.to_html tokens
              rescue RDoc::RubyLex::Error
                CGI.escapeHTML text
              end
            else
              CGI.escapeHTML text
            end

  if @options.pipe then
    @res << "\n<pre><code>#{CGI.escapeHTML text}</code></pre>\n"
  else
    @res << "\n<pre#{klass}>#{content}</pre>\n"
  end
end

#convert_string(text)

CGI-escapes text

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 306


def convert_string(text)
  CGI.escapeHTML text
end

#end_accepting

Returns the generated output

[ GitHub ]

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


def end_accepting
  @res.join
end

#gen_url(url, text)

Generate a link to url with content text. Handles the special cases for img: and link: described under handle_special_HYPERLINK

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 314


def gen_url url, text
  scheme, url, id = parse_url url

  if %w[http https link].include?(scheme) and
     url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
    "<img src=\"#{url}\" />"
  else
    text = text.sub %r%^#{scheme}:/*%i, ''
    text = text.sub %r%^[*\^](\d+)$%,   '\1'

    link = "<a#{id} href=\"#{url}\">#{text}</a>"

    link = "<sup>#{link}</sup>" if /"foot/ =~ id

    link
  end
end

#handle_special_HARD_BREAK(special)

special is a

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 95


def handle_special_HARD_BREAK special
  '<br>'
end

#handle_special_HYPERLINK(special)

special is a potential link. The following schemes are handled:

mailto:: Inserted as-is.
http:: Links are checked to see if they reference an image. If so, that image gets inserted using an <img> tag. Otherwise a conventional <a href> is used.
link:: Reference to a local file relative to the output directory.

[ GitHub ]

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


def handle_special_HYPERLINK(special)
  url = special.text

  gen_url url, url
end

#handle_special_RDOCLINK(special)

special is an rdoc-schemed link that will be converted into a hyperlink.

For the rdoc-ref scheme the named reference will be returned without creating a link.

For the rdoc-label scheme the footnote and label prefixes are stripped when creating a link. All other contents will be linked verbatim.

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 126


def handle_special_RDOCLINK special
  handle_RDOCLINK special.text
end

#handle_special_TIDYLINK(special)

This special is a link where the label is different from the URL label[url] or {url long label}

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 134


def handle_special_TIDYLINK(special)
  text = special.text

  return text unless
    text =~ /^\{(.*)\}\[(.*?)\]$/ or text =~ /^(\S+)\[(.*?)\]$/

  label = $1
  url   = $2

  label = handle_RDOCLINK label if /^rdoc-image:/ =~ label

  gen_url url, label
end

#html_list_name(list_type, open_tag)

Determines the HTML list element for list_type and open_tag

Raises:

(RDoc::Error)

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 335


def html_list_name(list_type, open_tag)
  tags = LIST_TYPE_TO_HTML[list_type]
  raise RDoc::Error, "Invalid list type: #{list_type.inspect}" unless tags
  tags[open_tag ? 0 : 1]
end

#init_tags

Maps attributes to HTML tags

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 344


def init_tags
  add_tag :BOLD, "<strong>", "</strong>"
  add_tag :TT,   "<code>",   "</code>"
  add_tag :EM,   "<em>",     "</em>"
end

#list_end_for(list_type)

Returns the HTML end-tag for list_type

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 370


def list_end_for(list_type)
  case list_type
  when :BULLET, :LALPHA, :NUMBER, :UALPHA then
    "</li>"
  when :LABEL, :NOTE then
    "</dd>"
  else
    raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
  end
end

#list_item_start(list_item, list_type)

Returns the HTML tag for list_type, possible using a label from list_item

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 354


def list_item_start(list_item, list_type)
  case list_type
  when :BULLET, :LALPHA, :NUMBER, :UALPHA then
    "<li>"
  when :LABEL, :NOTE then
    Array(list_item.label).map do |label|
      "<dt>#{to_html label}\n"
    end.join << "<dd>"
  else
    raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
  end
end

#parseable?(text) ⇒ `Boolean`

Returns true if text is valid ruby syntax

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 384


def parseable? text
  eval("BEGIN {return true}\n#{text}")
rescue SyntaxError
  false
end

#start_accepting

Prepares the visitor for HTML generation

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 155


def start_accepting
  @res = []
  @in_list_entry = []
  @list = []
end

#to_html(item)

Converts item to HTML using Text#to_html

[ GitHub ]

# File 'lib/rdoc/markup/to_html.rb', line 393


def to_html item
  super convert_flow @am.flow item
end

Class: RDoc::Markup::ToHtml

Overview

Constant Summary

::RDoc::Text - Included

Utilities

Special Handling

Visitor

Class Method Summary

Formatter - Inherited

Instance Attribute Summary

Formatter - Inherited

Instance Method Summary

::RDoc::Text - Included

Formatter - Inherited

Constructor Details

.new(options, markup = nil) ⇒ ToHtml

Instance Attribute Details

#code_object (rw)

#from_path (rw)

Instance Method Details

#accept_blank_line(blank_line)

#accept_block_quote(block_quote)

#accept_heading(heading)

#accept_list_end(list)

#accept_list_item_end(list_item)

#accept_list_item_start(list_item)

#accept_list_start(list)

#accept_paragraph(paragraph)

#accept_raw(raw)

#accept_rule(rule)

#accept_verbatim(verbatim)

#convert_string(text)

#end_accepting

#gen_url(url, text)

#handle_special_HARD_BREAK(special)

#handle_special_HYPERLINK(special)

#handle_special_RDOCLINK(special)

#handle_special_TIDYLINK(special)

#html_list_name(list_type, open_tag)

#init_tags

#list_end_for(list_type)

#list_item_start(list_item, list_type)

#parseable?(text) ⇒ Boolean

#start_accepting

#to_html(item)

.new(options, markup = nil) ⇒ `ToHtml`

#parseable?(text) ⇒ `Boolean`