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 16

{
  :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
#in_list_entry readonly Internal use only
#init_tags

Maps attributes to HTML tags.
#list readonly Internal use only
#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.
#res readonly Internal use only
#to_html(item)

Converts item to HTML using Text#to_html

Special Handling

#handle_RDOCLINK(url) Internal use only

These methods handle special markup added by #add_special.
#handle_special_HARD_BREAK(special)

special is a <br>.
#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 45


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 33


attr_accessor :code_object

#from_path (rw)

Path to this document for relative links

[ GitHub ]

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


attr_accessor :from_path

#in_list_entry (readonly)

This method is for internal use only.

[ GitHub ]

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


attr_reader :in_list_entry # :nodoc:

#list (readonly)

This method is for internal use only.

[ GitHub ]

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


attr_reader :list # :nodoc:

#res (readonly)

This method is for internal use only.

[ GitHub ]

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


attr_reader :res # :nodoc:

Instance Method Details

#accept_blank_line(blank_line)

Adds blank_line to the output

[ GitHub ]

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


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 172


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 279


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 242


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 264


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 253


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 233


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 185


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 300


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 226


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 196


def accept_verbatim verbatim
  text = verbatim.text.rstrip

  klass = nil

  content = if verbatim.ruby? or parseable? text then
              begin
                tokens = RDoc::RipperStateLex.parse text
                klass  = ' class="ruby"'

                result = RDoc::TokenStream.to_html tokens
                result = result + "\n" unless "\n" == result[-1]
                result
              rescue
                CGI.escapeHTML text
              end
            else
              CGI.escapeHTML text
            end

  if @options.pipe then
    @res << "\n<pre><code>#{CGI.escapeHTML text}\n</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 309


def convert_string(text)
  CGI.escapeHTML text
end

#end_accepting

Returns the generated output

[ GitHub ]

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


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 317


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_RDOCLINK(url)

This method is for internal use only.

These methods handle special markup added by RDoc::Markup#add_special.

[ GitHub ]

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


def handle_RDOCLINK url # :nodoc:
  case url
  when /^rdoc-ref:/
    $'
  when /^rdoc-label:/
    text = $'

    text = case text
           when /\Alabel-/    then $'
           when /\Afootmark-/ then $'
           when /\Afoottext-/ then $'
           else                    text
           end

    gen_url url, text
  when /^rdoc-image:/
    "<img src=\"#{$'}\">"
  else
    url =~ /\Ardoc-[a-z]+:/

    $'
  end
end

#handle_special_HARD_BREAK(special)

special is a <br>

[ GitHub ]

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


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 112


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 127


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 135


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 338


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 347


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 373


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 357


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 387


def parseable? text
  verbose, $VERBOSE = $VERBOSE, nil
  eval("BEGIN {return true}\n#{text}")
rescue SyntaxError
  false
ensure
  $VERBOSE = verbose
end

#start_accepting

Prepares the visitor for HTML generation

[ GitHub ]

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


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 399


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)

#in_list_entry (readonly)

#list (readonly)

#res (readonly)

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_RDOCLINK(url)

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