rdoc 3.1 → 6.3.3

data/lib/rdoc/markup/to_html.rb

@@ -1,25 +1,25 @@
-require 'rdoc/markup/formatter'
-require 'rdoc/markup/inline'
-
+# frozen_string_literal: true
 require 'cgi'
 
 ##
-# Outputs RDoc markup as HTML
+# Outputs RDoc markup as HTML.
 
 class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
   include RDoc::Text
 
+  # :section: Utilities
+
   ##
   # Maps RDoc::Markup::Parser::LIST_TOKENS types to HTML tags
 
   LIST_TYPE_TO_HTML = {
-    :BULLET => ['<ul>', '</ul>'],
-    :LABEL  => ['<dl>', '</dl>'],
-    :LALPHA => ['<ol style="display: lower-alpha">', '</ol>'],
-    :NOTE   => ['<table class="rdoc-list">', '</table>'],
-    :NUMBER => ['<ol>', '</ol>'],
-    :UALPHA => ['<ol style="display: upper-alpha">', '</ol>'],
+    :BULLET => ['<ul>',                                      '</ul>'],
+    :LABEL  => ['<dl class="rdoc-list label-list">',         '</dl>'],
+    :LALPHA => ['<ol style="list-style-type: lower-alpha">', '</ol>'],
+    :NOTE   => ['<dl class="rdoc-list note-list">',          '</dl>'],
+    :NUMBER => ['<ol>',                                      '</ol>'],
+    :UALPHA => ['<ol style="list-style-type: upper-alpha">', '</ol>'],
   }
 
   attr_reader :res # :nodoc:
@@ -27,157 +27,141 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   attr_reader :list # :nodoc:
 
   ##
-  # Path to this document for relative links
+  # The RDoc::CodeObject HTML is being generated for.  This is used to
+  # generate namespaced URI fragments
 
-  attr_accessor :from_path
+  attr_accessor :code_object
 
   ##
-  # Converts a target url to one that is relative to a given path
-
-  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 '.'
+  # Path to this document for relative links
 
-    while from.size > 0 and to.size > 0 and from[0] == to[0] do
-      from.shift
-      to.shift
-    end
+  attr_accessor :from_path
 
-    from.fill ".."
-    from.concat to
-    from << to_file
-    File.join(*from)
-  end
+  # :section:
 
   ##
   # Creates a new formatter that will output HTML
 
-  def initialize
+  def initialize options, markup = nil
     super
 
-    @th = nil
+    @code_object = nil
+    @from_path = ''
     @in_list_entry = nil
     @list = nil
-    @from_path = ''
-
-    # external hyperlinks
-    @markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK)
+    @th = nil
+    @hard_break = "<br>\n"
 
-    # and links of the form  <text>[<url>]
-    @markup.add_special(/(((\{.*?\})|\b\S+?)\[\S+?\.\S+?\])/, :TIDYLINK)
+    init_regexp_handlings
 
     init_tags
   end
 
+  # :section: Regexp Handling
+  #
+  # These methods are used by regexp handling markup added by RDoc::Markup#add_regexp_handling.
+
   ##
-  # Maps attributes to HTML tags
+  # Adds regexp handlings.
 
-  def init_tags
-    add_tag :BOLD, "<b>",  "</b>"
-    add_tag :TT,   "<tt>", "</tt>"
-    add_tag :EM,   "<em>", "</em>"
+  def init_regexp_handlings
+    # external links
+    @markup.add_regexp_handling(/(?:link:|https?:|mailto:|ftp:|irc:|www\.)\S+\w/,
+                                :HYPERLINK)
+    init_link_notation_regexp_handlings
   end
 
   ##
-  # Generate a hyperlink for +url+, labeled with +text+.  Handles the special
-  # cases for img: and link: described under handle_special_HYPERLINK
-
-  def gen_url(url, text)
-    if url =~ /([A-Za-z]+):(.*)/ then
-      type = $1
-      path = $2
-    else
-      type = "http"
-      path = url
-      url  = "http://#{url}"
-    end
+  # Adds regexp handlings about link notations.
 
-    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
+  def init_link_notation_regexp_handlings
+    add_regexp_handling_RDOCLINK
+    add_regexp_handling_TIDYLINK
+  end
 
-    if (type == "http" or type == "link") and
-       url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
-      "<img src=\"#{url}\" />"
+  def handle_RDOCLINK url # :nodoc:
+    case url
+    when /^rdoc-ref:/
+      $'
+    when /^rdoc-label:/
+      text = $'
+
+      text = case text
+             when /\Alabel-/    then $'
+             when /\Afootmark-/ then $'
+             when /\Afoottext-/ then $'
+             else                    text
+             end
+
+      gen_url url, text
+    when /^rdoc-image:/
+      "<img src=\"#{$'}\">"
     else
-      "<a href=\"#{url}\">#{text.sub(%r{^#{type}:/*}, '')}</a>"
+      url =~ /\Ardoc-[a-z]+:/
+
+      $'
     end
   end
 
-  # :section: Special handling
+  ##
+  # +target+ is a <code><br></code>
+
+  def handle_regexp_HARD_BREAK target
+    '<br>'
+  end
 
   ##
-  # And we're invoked with a potential external hyperlink. <tt>mailto:</tt>
-  # just gets inserted. <tt>http:</tt> links are checked to see if they
-  # reference an image. If so, that image gets inserted using an
-  # <tt><img></tt> tag. Otherwise a conventional <tt><a href></tt> is used.
-  # We also support a special type of hyperlink, <tt>link:</tt>, which is a
-  # reference to a local file whose path is relative to the --op directory.
+  # +target+ is a potential link.  The following schemes are handled:
+  #
+  # <tt>mailto:</tt>::
+  #   Inserted as-is.
+  # <tt>http:</tt>::
+  #   Links are checked to see if they reference an image. If so, that image
+  #   gets inserted using an <tt><img></tt> tag. Otherwise a conventional
+  #   <tt><a href></tt> is used.
+  # <tt>link:</tt>::
+  #   Reference to a local file relative to the output directory.
+
+  def handle_regexp_HYPERLINK(target)
+    url = target.text
 
-  def handle_special_HYPERLINK(special)
-    url = special.text
     gen_url url, url
   end
 
   ##
-  # Here's a hypedlink where the label is different to the URL
-  # <label>[url] or {long label}[url]
+  # +target+ 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.
+
+  def handle_regexp_RDOCLINK target
+    handle_RDOCLINK target.text
+  end
+
+  ##
+  # This +target+ is a link where the label is different from the URL
+  # <tt>label[url]</tt> or <tt>{long label}[url]</tt>
 
-  def handle_special_TIDYLINK(special)
-    text = special.text
+  def handle_regexp_TIDYLINK(target)
+    text = target.text
 
-    return text unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/
+    return text unless
+      text =~ /^\{(.*)\}\[(.*?)\]$/ or text =~ /^(\S+)\[(.*?)\]$/
 
     label = $1
     url   = $2
-    gen_url url, label
-  end
 
-  # :section: Utilities
+    label = handle_RDOCLINK label if /^rdoc-image:/ =~ label
 
-  ##
-  # Wraps +txt+ to +line_len+
-
-  def wrap(txt, line_len = 76)
-    res = []
-    sp = 0
-    ep = txt.length
-
-    while sp < ep
-      # scan back for a space
-      p = sp + line_len - 1
-      if p >= ep
-        p = ep
-      else
-        while p > sp and txt[p] != ?\s
-          p -= 1
-        end
-        if p <= sp
-          p = sp + line_len
-          while p < ep and txt[p] != ?\s
-            p += 1
-          end
-        end
-      end
-      res << txt[sp...p] << "\n"
-      sp = p
-      sp += 1 while sp < ep and txt[sp] == ?\s
-    end
-
-    res.join.strip
+    gen_url url, label
   end
 
   # :section: Visitor
+  #
+  # These methods implement the HTML visitor.
 
   ##
   # Prepares the visitor for HTML generation
@@ -195,31 +179,65 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     @res.join
   end
 
+  ##
+  # Adds +block_quote+ to the output
+
+  def accept_block_quote block_quote
+    @res << "\n<blockquote>"
+
+    block_quote.parts.each do |part|
+      part.accept self
+    end
+
+    @res << "</blockquote>\n"
+  end
+
   ##
   # Adds +paragraph+ to the output
 
-  def accept_paragraph(paragraph)
+  def accept_paragraph paragraph
     @res << "\n<p>"
-    @res << wrap(to_html(paragraph.text))
+    text = paragraph.text @hard_break
+    text = text.gsub(/\r?\n/, ' ')
+    @res << to_html(text)
     @res << "</p>\n"
   end
 
   ##
   # Adds +verbatim+ to the output
 
-  def accept_verbatim(verbatim)
-    @res << "\n<pre>"
-    @res << CGI.escapeHTML(verbatim.text.rstrip)
-    @res << "</pre>\n"
+  def accept_verbatim verbatim
+    text = verbatim.text.rstrip
+
+    klass = nil
+
+    content = if verbatim.ruby? or parseable? text then
+                begin
+                  tokens = RDoc::Parser::RipperStateLex.parse text
+                  klass  = ' class="ruby"'
+
+                  result = RDoc::TokenStream.to_html tokens
+                  result = result + "\n" unless "\n" == result[-1]
+                  result
+                rescue
+                  CGI.escapeHTML text
+                end
+              else
+                CGI.escapeHTML text
+              end
+
+    if @options.pipe then
+      @res << "\n<pre><code>#{CGI.escapeHTML text}\n</code></pre>\n"
+    else
+      @res << "\n<pre#{klass}>#{content}</pre>\n"
+    end
   end
 
   ##
   # Adds +rule+ to the output
 
-  def accept_rule(rule)
-    size = rule.weight
-    size = 10 if size > 10
-    @res << "<hr style=\"height: #{size}px\">\n"
+  def accept_rule rule
+    @res << "<hr>\n"
   end
 
   ##
@@ -268,12 +286,25 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   end
 
   ##
-  # Adds +heading+ to the output
+  # Adds +heading+ to the output.  The headings greater than 6 are trimmed to
+  # level 6.
+
+  def accept_heading heading
+    level = [6, heading.level].min
+
+    label = heading.label @code_object
 
-  def accept_heading(heading)
-    @res << "\n<h#{heading.level}>"
+    @res << if @options.output_decoration
+              "\n<h#{level} id=\"#{label}\">"
+            else
+              "\n<h#{level}>"
+            end
     @res << to_html(heading.text)
-    @res << "</h#{heading.level}>\n"
+    unless @options.pipe then
+      @res << "<span><a href=\"##{label}\">&para;</a>"
+      @res << " <a href=\"#top\">&uarr;</a></span>"
+    end
+    @res << "</h#{level}>\n"
   end
 
   ##
@@ -284,12 +315,63 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   end
 
   ##
-  # CGI escapes +text+
+  # Adds +table+ to the output
+
+  def accept_table header, body, aligns
+    @res << "\n<table role=\"table\">\n<thead>\n<tr>\n"
+    header.zip(aligns) do |text, align|
+      @res << '<th'
+      @res << ' align="' << align << '"' if align
+      @res << '>' << CGI.escapeHTML(text) << "</th>\n"
+    end
+    @res << "</tr>\n</thead>\n<tbody>\n"
+    body.each do |row|
+      @res << "<tr>\n"
+      row.zip(aligns) do |text, align|
+        @res << '<td'
+        @res << ' align="' << align << '"' if align
+        @res << '>' << CGI.escapeHTML(text) << "</td>\n"
+      end
+      @res << "</tr>\n"
+    end
+    @res << "</tbody>\n</table>\n"
+  end
+
+  # :section: Utilities
+
+  ##
+  # CGI-escapes +text+
 
   def convert_string(text)
     CGI.escapeHTML text
   end
 
+  ##
+  # Generate a link to +url+ with content +text+.  Handles the special cases
+  # for img: and link: described under handle_regexp_HYPERLINK
+
+  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
+      if scheme != 'link' and /\.(?:rb|rdoc|md)\z/i =~ url
+        url = url.sub(%r%\A([./]*)(.*)\z%) { "#$1#{$2.tr('.', '_')}.html" }
+      end
+
+      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
+
   ##
   # Determines the HTML list element for +list_type+ and +open_tag+
 
@@ -299,6 +381,15 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     tags[open_tag ? 0 : 1]
   end
 
+  ##
+  # Maps attributes to HTML tags
+
+  def init_tags
+    add_tag :BOLD, "<strong>", "</strong>"
+    add_tag :TT,   "<code>",   "</code>"
+    add_tag :EM,   "<em>",     "</em>"
+  end
+
   ##
   # Returns the HTML tag for +list_type+, possible using a label from
   # +list_item+
@@ -307,10 +398,10 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     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>"
+    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
@@ -323,15 +414,25 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     case list_type
     when :BULLET, :LALPHA, :NUMBER, :UALPHA then
       "</li>"
-    when :LABEL then
+    when :LABEL, :NOTE then
       "</dd>"
-    when :NOTE then
-      "</td></tr>"
     else
       raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
     end
   end
 
+  ##
+  # Returns true if text is valid ruby syntax
+
+  def parseable? text
+    verbose, $VERBOSE = $VERBOSE, nil
+    eval("BEGIN {return true}\n#{text}")
+  rescue SyntaxError
+    false
+  ensure
+    $VERBOSE = verbose
+  end
+
   ##
   # Converts +item+ to HTML using RDoc::Text#to_html