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 95
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 111
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 126
def handle_special_RDOCLINK special
  handle_RDOCLINK special.text
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 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

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 306
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 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

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 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() click to toggle source

Maps attributes to HTML tags

 
               # File 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) click to toggle source

Returns the HTML end-tag for list_type

 
               # File 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) 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 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) click to toggle source

Returns true if text is valid ruby syntax

 
               # File rdoc/markup/to_html.rb, line 384
def parseable? text
  eval("BEGIN {return true}\n#{text}")
rescue SyntaxError
  false
end

to_html(item) click to toggle source

Converts item to HTML using RDoc::Text#to_html

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

Finishes consumption of list

 
               # File 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) click to toggle source

Finishes consumption of list_item

 
               # File 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) click to toggle source

Prepares the visitor for consuming list_item

 
               # File 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) click to toggle source

Prepares the visitor for consuming list

 
               # File 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) click to toggle source

Adds paragraph to the output

 
               # File 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) click to toggle source

Adds raw to the output

 
               # File rdoc/markup/to_html.rb, line 297
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 223
def accept_rule rule
  @res << "<hr>\n"
end

accept_verbatim(verbatim) click to toggle source

Adds verbatim to the output

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

end_accepting() click to toggle source

Returns the generated output

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