Outputs RDoc markup as HTML
Creates a new formatter that will output HTML
# File rdoc/markup/to_html.rb, line 65
def initialize markup = nil
super
@th = nil
@in_list_entry = nil
@list = nil
@from_path = ''
# external links
@markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK)
# and links of the form <text>[<url>]
@markup.add_special(/(((\{.*?\})|\b\S+?)\[\S+?\])/, :TIDYLINK)
init_tags
end
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 98
def handle_special_HYPERLINK(special)
url = special.text
gen_url url, url
end
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 108
def handle_special_TIDYLINK(special)
text = special.text
return text unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/
label = $1
url = $2
gen_url url, label
end
Maps RDoc::Markup::Parser::LIST_TOKENS types to HTML tags
Converts a target url to one that is relative to a given path
# File rdoc/markup/to_html.rb, line 39
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
CGI escapes text
# File rdoc/markup/to_html.rb, line 231
def convert_string(text)
CGI.escapeHTML text
end
Generate a link for url, labeled with text.
Handles the special cases for img: and link: described under #handle_special_HYPERLINK
# File rdoc/markup/to_html.rb, line 239
def gen_url(url, text)
if url =~ /([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 =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
"<img src=\"#{url}\" />"
else
"<a href=\"#{url}\">#{text.sub(%r{^#{type}:/*}, '')}</a>"
end
end
Determines the HTML list element for list_type and
open_tag
# File rdoc/markup/to_html.rb, line 268
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
Returns the HTML end-tag for list_type
# File rdoc/markup/to_html.rb, line 303
def list_end_for(list_type)
case list_type
when :BULLET, :LALPHA, :NUMBER, :UALPHA then
"</li>"
when :LABEL then
"</dd>"
when :NOTE then
"</td></tr>"
else
raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
end
end
Returns the HTML tag for list_type, possible using a label
from list_item
# File rdoc/markup/to_html.rb, line 287
def list_item_start(list_item, list_type)
case list_type
when :BULLET, :LALPHA, :NUMBER, :UALPHA then
"<li>"
when :LABEL then
"<dt>#{to_html list_item.label}</dt>\n<dd>"
when :NOTE then
"<tr><td class=\"rdoc-term\"><p>#{to_html list_item.label}</p></td>\n<td>"
else
raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
end
end
Converts item to HTML using RDoc::Text#to_html
# File rdoc/markup/to_html.rb, line 319
def to_html item
super convert_flow @am.flow item
end
Adds blank_line to the output
# File rdoc/markup/to_html.rb, line 206
def accept_blank_line(blank_line)
# @res << annotate("<p />") << "\n"
end
Adds heading to the output
# File rdoc/markup/to_html.rb, line 213
def accept_heading(heading)
@res << "\n<h#{heading.level}>"
@res << to_html(heading.text)
@res << "</h#{heading.level}>\n"
end
Finishes consumption of list
# File rdoc/markup/to_html.rb, line 177
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
Finishes consumption of list_item
# File rdoc/markup/to_html.rb, line 199
def accept_list_item_end(list_item)
@in_list_entry[-1] = list_end_for(@list.last)
end
Prepares the visitor for consuming list_item
# File rdoc/markup/to_html.rb, line 188
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
Prepares the visitor for consuming list
# File rdoc/markup/to_html.rb, line 168
def accept_list_start(list)
@list << list.type
@res << html_list_name(list.type, true)
@in_list_entry.push false
end
Adds paragraph to the output
# File rdoc/markup/to_html.rb, line 141
def accept_paragraph(paragraph)
@res << "\n<p>"
@res << wrap(to_html(paragraph.text))
@res << "</p>\n"
end
Adds raw to the output
# File rdoc/markup/to_html.rb, line 222
def accept_raw raw
@res << raw.parts.join("\n")
end
Adds rule to the output
# File rdoc/markup/to_html.rb, line 159
def accept_rule(rule)
size = rule.weight
size = 10 if size > 10
@res << "<hr style=\"height: #{size}px\">\n"
end
Adds verbatim to the output
# File rdoc/markup/to_html.rb, line 150
def accept_verbatim(verbatim)
@res << "\n<pre>"
@res << CGI.escapeHTML(verbatim.text.rstrip)
@res << "</pre>\n"
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.