# class RDoc::Markup::ToHtml

Outputs RDoc markup as HTML.

### Public Class Methods

new(markup = nil) click to toggle source

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

      # 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(((\{.*?\})|\b\S+?)\[\S+?\])/, :TIDYLINK)

      init_tags
    end

## Special Handling

↑ top

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

### Public Instance Methods

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 lib/rdoc/markup/to_html.rb, line 106
    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 lib/rdoc/markup/to_html.rb, line 121
    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) click to toggle source

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

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

CGI escapes `text`

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

Determines the HTML list element for `list_type` and `open_tag`

    # File lib/rdoc/markup/to_html.rb, line 334
    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 lib/rdoc/markup/to_html.rb, line 343
    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 lib/rdoc/markup/to_html.rb, line 367
    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 lib/rdoc/markup/to_html.rb, line 353
    def list_item_start(list_item, list_type)
      case list_type
      when :BULLET, :LALPHA, :NUMBER, :UALPHA then
        "<li>"
      when :LABEL, :NOTE then
        "<dt>#{to_html list_item.label}\n<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 lib/rdoc/markup/to_html.rb, line 381
    def parseable? text
      text =~ %r\b(def|class|module|require)\b|=>|\{\s?\||do \|/ and
        text !~ %r<%|%>/
    end

to_html(item) click to toggle source

Converts `item` to HTML using RDoc::Text#to_html

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

Adds `blank_line` to the output

    # File lib/rdoc/markup/to_html.rb, line 261
    def accept_blank_line(blank_line)
      # @res << annotate("<p />") << "\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 lib/rdoc/markup/to_html.rb, line 269
    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) click to toggle source

Finishes consumption of `list`

    # File lib/rdoc/markup/to_html.rb, line 232
    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 lib/rdoc/markup/to_html.rb, line 254
    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 lib/rdoc/markup/to_html.rb, line 243
    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 lib/rdoc/markup/to_html.rb, line 223
    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 lib/rdoc/markup/to_html.rb, line 182
    def accept_paragraph(paragraph)
      @res << "\n<p>"
      @res << wrap(to_html(paragraph.text))
      @res << "</p>\n"
    end

accept_raw(raw) click to toggle source

Adds `raw` to the output

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

accept_rule(rule) click to toggle source

Adds `rule` to the output

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

Returns the generated output

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

start_accepting() click to toggle source

Prepares the visitor for HTML generation

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