Home Classes Methods

In Files

rdoc/markup/to_html.rb

Class/Module Index

RDoc::Markup::ToHtml

Outputs RDoc markup as HTML.

Public Class Methods

new(options, markup = nil) click to toggle source

Creates a new formatter that will output HTML

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

Special Handling ↑ top

Public Instance Methods

handle_special_HARD_BREAK(special) click to toggle source

special is a

 
               # File rdoc/markup/to_html.rb, line 71
def handle_special_HARD_BREAK special
  '<br>'
end

handle_special_HYPERLINK(special) click to toggle source

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 rdoc/markup/to_html.rb, line 87
def handle_special_HYPERLINK(special)
  url = special.text

  gen_url url, url
end

handle_special_RDOCLINK(special) click to toggle source

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 rdoc/markup/to_html.rb, line 102
def handle_special_RDOCLINK special
  url = special.text

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

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

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

    $'
  end
end

handle_special_TIDYLINK(special) click to toggle source

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

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

  return text unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\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 Instance Methods

convert_string(text) click to toggle source

CGI-escapes text

 
               # File rdoc/markup/to_html.rb, line 290
def convert_string(text)
  CGI.escapeHTML text
end

gen_url(url, text) click to toggle source

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

 
               # File rdoc/markup/to_html.rb, line 298
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
    "<a#{id} href=\"#{url}\">#{text.sub(%r{^#{scheme}:/*}i, '')}</a>"
  end
end

html_list_name(list_type, open_tag) click to toggle source

Determines the HTML list element for list_type and open_tag

 
               # File rdoc/markup/to_html.rb, line 312
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() click to toggle source

Maps attributes to HTML tags

 
               # File rdoc/markup/to_html.rb, line 321
def init_tags
  add_tag :BOLD, "<strong>", "</strong>"
  add_tag :TT,   "<code>",   "</code>"
  add_tag :EM,   "<em>",     "</em>"
end

list_end_for(list_type) click to toggle source

Returns the HTML end-tag for list_type

 
               # File rdoc/markup/to_html.rb, line 347
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) click to toggle source

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

 
               # File rdoc/markup/to_html.rb, line 331
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) click to toggle source

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

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

to_html(item) click to toggle source

Converts item to HTML using RDoc::Text#to_html

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

Visitor ↑ top

Public Instance Methods

accept_blank_line(blank_line) click to toggle source

Adds blank_line to the output

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

accept_block_quote(block_quote) click to toggle source

Adds block_quote to the output

 
               # File rdoc/markup/to_html.rb, line 163
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) click to toggle source

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

 
               # File rdoc/markup/to_html.rb, line 262
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)
  unless @options.pipe then
    @res << "<span><a href=\"##{label}\">&para;</a>"
    @res << " <a href=\"#documentation\">&uarr;</a></span>"
  end
  @res << "</h#{level}>\n"
end

accept_list_end(list) click to toggle source

Finishes consumption of list

 
               # File rdoc/markup/to_html.rb, line 225
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) click to toggle source

Finishes consumption of list_item

 
               # File rdoc/markup/to_html.rb, line 247
def accept_list_item_end(list_item)
  @in_list_entry[-1] = list_end_for(@list.last)
end

accept_list_item_start(list_item) click to toggle source

Prepares the visitor for consuming list_item

 
               # File rdoc/markup/to_html.rb, line 236
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) click to toggle source

Prepares the visitor for consuming list

 
               # File rdoc/markup/to_html.rb, line 216
def accept_list_start(list)
  @list << list.type
  @res << html_list_name(list.type, true)
  @in_list_entry.push false
end

accept_paragraph(paragraph) click to toggle source

Adds paragraph to the output

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

accept_raw(raw) click to toggle source

Adds raw to the output

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

accept_rule(rule) click to toggle source

Adds rule to the output

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

accept_verbatim(verbatim) click to toggle source

Adds verbatim to the output

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

  @res << if verbatim.ruby? or parseable? text then
            begin
              tokens = RDoc::RubyLex.tokenize text, @options

              html = RDoc::TokenStream.to_html tokens

              "\n<pre class=\"ruby\">#{html}</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() click to toggle source

Returns the generated output

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

start_accepting() click to toggle source

Prepares the visitor for HTML generation

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

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please see Improve the docs, or visit Documenting-ruby.org.

Home Classes Methods

In Files

Parent

Sections

Methods

Included Modules

Class/Module Index

RDoc::Markup::ToHtml

Public Class Methods

Special Handling ↑ top

Public Instance Methods

Utilities ↑ top

Constants

Attributes

Public Instance Methods

Visitor ↑ top

Public Instance Methods