RDoc::Markup::

ToHtml

class

Outputs RDoc markup as HTML.

Public Class Methods

new(markup = nil)

Creates a new formatter that will output HTML

# File lib/rdoc/markup/to_html.rb, line 68
def initialize 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(%r(?:link:|https?:|mailto:|ftp:|irc:|www\.)\S+\w/,
                      :HYPERLINK)

  # internal links
  @markup.add_special(%rrdoc-[a-z]+:\S+/, :RDOCLINK)

  # and links of the form  <text>[<url>]
  @markup.add_special(%r(?:
                        \{.*?\} |   # multi-word label
                        \b[^\s{}]+? # single-word label
                       )

                       \[\S+?\]     # link target
                      /, :TIDYLINK)

  init_tags
end

Special Handling

↑ top

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

Public Instance Methods

handle_special_HARD_BREAK(special)

special is a <br> that is not converted.

# File lib/rdoc/markup/to_html.rb, line 104
def handle_special_HARD_BREAK special
  special.text
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.

# File lib/rdoc/markup/to_html.rb, line 120
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.

# File lib/rdoc/markup/to_html.rb, line 135
def handle_special_RDOCLINK special
  url = special.text

  case url
  when %r\Ardoc-ref:/
    $'
  when %r\Ardoc-label:/
    text = $'

    text = case text
           when %r\Alabel-/    then $'
           when %r\Afootmark-/ then "^#{$'}"
           when %r\Afoottext-/ then "*#{$'}"
           else                    text
           end

    gen_url url, text
  else
    url =~ %r\Ardoc-[a-z]+:/

    $'
  end
end

handle_special_TIDYLINK(special)

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

# File lib/rdoc/markup/to_html.rb, line 163
def handle_special_TIDYLINK(special)
  text = special.text

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

  label = $1
  url   = $2
  gen_url url, label
end

Utilities

↑ top

Constants

LIST_TYPE_TO_HTML: Maps RDoc::Markup::Parser::LIST_TOKENS types to HTML tags

Attributes

code_object[RW]: The RDoc::CodeObject HTML is being generated for. This is used to generate namespaced URI fragments
from_path[RW]: Path to this document for relative links

Public Class Methods

gen_relative_url(path, target)

Converts a target url to one that is relative to a given path

# File lib/rdoc/markup/to_html.rb, line 42
def self.gen_relative_url(path, target)
  from        = File.dirname path
  to, to_file = File.split target

  from = from.split "/"
  to   = to.split "/"

  from.delete '.'
  to.delete '.'

  while from.size > 0 and to.size > 0 and from[0] == to[0] do
    from.shift
    to.shift
  end

  from.fill ".."
  from.concat to
  from << to_file
  File.join(*from)
end

Public Instance Methods

convert_string(text)

CGI-escapes text

# File lib/rdoc/markup/to_html.rb, line 308
def convert_string(text)
  CGI.escapeHTML text
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

# File lib/rdoc/markup/to_html.rb, line 316
def gen_url url, text
  if url =~ %r^rdoc-label:([^:]*)(?::(.*))?/ then
    type = "link"
    path = "##{$1}"
    id   = " id=\"#{$2}\"" if $2
  elsif url =~ %r([A-Za-z]+):(.*)/ then
    type = $1
    path = $2
  else
    type = "http"
    path = url
    url  = "http://#{url}"
  end

  if type == "link" then
    url = if path[0, 1] == '#' then # is this meaningful?
            path
          else
            self.class.gen_relative_url @from_path, path
          end
  end

  if (type == "http" or type == "https" or type == "link") and
     url =~ %r\.(gif|png|jpg|jpeg|bmp)$/ then
    "<img src=\"#{url}\" />"
  else
    "<a#{id} href=\"#{url}\">#{text.sub(%r{^#{type}:/*}, '')}</a>"
  end
end

html_list_name(list_type, open_tag)

Determines the HTML list element for list_type and open_tag

# File lib/rdoc/markup/to_html.rb, line 349
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

# File lib/rdoc/markup/to_html.rb, line 358
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

# File lib/rdoc/markup/to_html.rb, line 384
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

# File lib/rdoc/markup/to_html.rb, line 368
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)

Returns true if Ripper is available it can create a sexp from text

# File lib/rdoc/markup/to_html.rb, line 398
def parseable? text
  text =~ %r\b(def|class|module|require)\b|=>|\{\s?\||do \|/ and
    text !~ %r<%|%>/
end

to_html(item)

Converts item to HTML using RDoc::Text#to_html

# File lib/rdoc/markup/to_html.rb, line 406
def to_html item
  super convert_flow @am.flow item
end

Visitor

↑ top

These methods implement the HTML visitor.

Public Instance Methods

accept_blank_line(blank_line)

Adds blank_line to the output

# File lib/rdoc/markup/to_html.rb, line 276
def accept_blank_line(blank_line)
  # @res << annotate("<p />") << "\n"
end

accept_heading(heading)

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

# File lib/rdoc/markup/to_html.rb, line 284
def accept_heading heading
  level = [6, heading.level].min

  label = heading.aref
  label = [@code_object.aref, label].compact.join '-' if
    @code_object and @code_object.respond_to? :aref

  @res << "\n<h#{level} id=\"#{label}\">"
  @res << to_html(heading.text)
  @res << "</h#{level}>\n"
end

accept_list_end(list)

Finishes consumption of list

# File lib/rdoc/markup/to_html.rb, line 247
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

# File lib/rdoc/markup/to_html.rb, line 269
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

# File lib/rdoc/markup/to_html.rb, line 258
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

# File lib/rdoc/markup/to_html.rb, line 238
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

# File lib/rdoc/markup/to_html.rb, line 196
def accept_paragraph paragraph
  @res << "\n<p>"
  text = paragraph.text @hard_break
  @res << wrap(to_html(text))
  @res << "</p>\n"
end

accept_raw(raw)

Adds raw to the output

# File lib/rdoc/markup/to_html.rb, line 299
def accept_raw raw
  @res << raw.parts.join("\n")
end

accept_rule(rule)

Adds rule to the output

# File lib/rdoc/markup/to_html.rb, line 229
def accept_rule(rule)
  size = rule.weight
  size = 10 if size > 10
  @res << "<hr style=\"height: #{size}px\">\n"
end

accept_verbatim(verbatim)

Adds verbatim to the output

# File lib/rdoc/markup/to_html.rb, line 206
def accept_verbatim verbatim
  text = verbatim.text.rstrip

  @res << if verbatim.ruby? or parseable? text then
            options = RDoc::RDoc.current.options if RDoc::RDoc.current

            begin
              tokens = RDoc::RubyLex.tokenize text, options

              "\n<pre class=\"ruby\">"                  "#{RDoc::TokenStream.to_html tokens}"                  "</pre>\n"
            rescue RDoc::RubyLex::Error
              "\n<pre>#{CGI.escapeHTML text}</pre>\n"
            end
          else
            "\n<pre>#{CGI.escapeHTML text}</pre>\n"
          end
end

end_accepting()

Returns the generated output

# File lib/rdoc/markup/to_html.rb, line 189
def end_accepting
  @res.join
end

start_accepting()

Prepares the visitor for HTML generation

# File lib/rdoc/markup/to_html.rb, line 180
def start_accepting
  @res = []
  @in_list_entry = []
  @list = []
end

/	Search
?	Show this help

Keyboard Shortcuts