Extended maintenance of Ruby 1.9.3 ended on February 23, 2015. Read more
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 visit Documenting-ruby.org.