rdoc 2.0.0

data/lib/rdoc/markup/to_html.rb

@@ -0,0 +1,353 @@
+require 'rdoc/markup/formatter'
+require 'rdoc/markup/fragments'
+require 'rdoc/markup/inline'
+
+require 'cgi'
+
+class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
+
+  LIST_TYPE_TO_HTML = {
+    :BULLET =>     %w[<ul> </ul>],
+    :NUMBER =>     %w[<ol> </ol>],
+    :UPPERALPHA => %w[<ol> </ol>],
+    :LOWERALPHA => %w[<ol> </ol>],
+    :LABELED =>    %w[<dl> </dl>],
+    :NOTE    =>    %w[<table> </table>],
+  }
+
+  InlineTag = Struct.new(:bit, :on, :off)
+
+  def initialize
+    super
+
+    # external hyperlinks
+    @markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK)
+
+    # and links of the form  <text>[<url>]
+    @markup.add_special(/(((\{.*?\})|\b\S+?)\[\S+?\.\S+?\])/, :TIDYLINK)
+
+    init_tags
+  end
+
+  ##
+  # Generate a hyperlink for url, labeled with text. Handle the
+  # special cases for img: and link: described under handle_special_HYPEDLINK
+
+  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
+              HTML.gen_url @from_path, path
+            end
+    end
+
+    if (type == "http" 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
+
+  ##
+  # And we're invoked with a potential external hyperlink mailto:
+  # just gets inserted. 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.  We also
+  # support a special type of hyperlink, link:, which is a reference
+  # to a local file whose path is relative to the --op directory.
+
+  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]
+
+  def handle_special_TIDYLINK(special)
+    text = special.text
+
+    return text unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/
+
+    label = $1
+    url   = $2
+    gen_url url, label
+  end
+
+  ##
+  # Set up the standard mapping of attributes to HTML tags
+
+  def init_tags
+    @attr_tags = [
+      InlineTag.new(RDoc::Markup::Attribute.bitmap_for(:BOLD), "<b>", "</b>"),
+      InlineTag.new(RDoc::Markup::Attribute.bitmap_for(:TT),   "<tt>", "</tt>"),
+      InlineTag.new(RDoc::Markup::Attribute.bitmap_for(:EM),   "<em>", "</em>"),
+    ]
+  end
+
+  ##
+  # Add a new set of HTML tags for an attribute. We allow separate start and
+  # end tags for flexibility.
+
+  def add_tag(name, start, stop)
+    @attr_tags << InlineTag.new(RDoc::Markup::Attribute.bitmap_for(name), start, stop)
+  end
+
+  ##
+  # Given an HTML tag, decorate it with class information and the like if
+  # required. This is a no-op in the base class, but is overridden in HTML
+  # output classes that implement style sheets.
+
+  def annotate(tag)
+    tag
+  end
+
+  ##
+  # Here's the client side of the visitor pattern
+
+  def start_accepting
+    @res = ""
+    @in_list_entry = []
+  end
+
+  def end_accepting
+    @res
+  end
+
+  def accept_paragraph(am, fragment)
+    @res << annotate("<p>") + "\n"
+    @res << wrap(convert_flow(am.flow(fragment.txt)))
+    @res << annotate("</p>") + "\n"
+  end
+
+  def accept_verbatim(am, fragment)
+    @res << annotate("<pre>") + "\n"
+    @res << CGI.escapeHTML(fragment.txt)
+    @res << annotate("</pre>") << "\n"
+  end
+
+  def accept_rule(am, fragment)
+    size = fragment.param
+    size = 10 if size > 10
+    @res << "<hr size=\"#{size}\"></hr>"
+  end
+
+  def accept_list_start(am, fragment)
+    @res << html_list_name(fragment.type, true) << "\n"
+    @in_list_entry.push false
+  end
+
+  def accept_list_end(am, fragment)
+    if tag = @in_list_entry.pop
+      @res << annotate(tag) << "\n"
+    end
+    @res << html_list_name(fragment.type, false) << "\n"
+  end
+
+  def accept_list_item(am, fragment)
+    if tag = @in_list_entry.last
+      @res << annotate(tag) << "\n"
+    end
+
+    @res << list_item_start(am, fragment)
+
+    @res << wrap(convert_flow(am.flow(fragment.txt))) << "\n"
+
+    @in_list_entry[-1] = list_end_for(fragment.type)
+  end
+
+  def accept_blank_line(am, fragment)
+    # @res << annotate("<p />") << "\n"
+  end
+
+  def accept_heading(am, fragment)
+    @res << convert_heading(fragment.head_level, am.flow(fragment.txt))
+  end
+
+  ##
+  # This is a higher speed (if messier) version of wrap
+
+  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
+  end
+
+  private
+
+  def on_tags(res, item)
+    attr_mask = item.turn_on
+    return if attr_mask.zero?
+
+    @attr_tags.each do |tag|
+      if attr_mask & tag.bit != 0
+        res << annotate(tag.on)
+      end
+    end
+  end
+
+  def off_tags(res, item)
+    attr_mask = item.turn_off
+    return if attr_mask.zero?
+
+    @attr_tags.reverse_each do |tag|
+      if attr_mask & tag.bit != 0
+        res << annotate(tag.off)
+      end
+    end
+  end
+
+  def convert_flow(flow)
+    res = ""
+
+    flow.each do |item|
+      case item
+      when String
+        res << convert_string(item)
+      when RDoc::Markup::AttrChanger
+        off_tags(res, item)
+        on_tags(res,  item)
+      when RDoc::Markup::Special
+        res << convert_special(item)
+      else
+        raise "Unknown flow element: #{item.inspect}"
+      end
+    end
+
+    res
+  end
+
+  ##
+  # some of these patterns are taken from SmartyPants...
+
+  def convert_string(item)
+    CGI.escapeHTML(item).
+
+    # convert -- to em-dash, (-- to en-dash)
+      gsub(/---?/, '&#8212;'). #gsub(/--/, '&#8211;').
+
+    # convert ... to elipsis (and make sure .... becomes .<elipsis>)
+      gsub(/\.\.\.\./, '.&#8230;').gsub(/\.\.\./, '&#8230;').
+
+    # convert single closing quote
+      gsub(%r{([^ \t\r\n\[\{\(])\'}, '\1&#8217;').
+      gsub(%r{\'(?=\W|s\b)}, '&#8217;').
+
+    # convert single opening quote
+      gsub(/'/, '&#8216;').
+
+    # convert double closing quote
+      gsub(%r{([^ \t\r\n\[\{\(])\'(?=\W)}, '\1&#8221;').
+
+    # convert double opening quote
+      gsub(/'/, '&#8220;').
+
+    # convert copyright
+      gsub(/\(c\)/, '&#169;').
+
+    # convert and registered trademark
+      gsub(/\(r\)/, '&#174;')
+
+  end
+
+  def convert_special(special)
+    handled = false
+    RDoc::Markup::Attribute.each_name_of(special.type) do |name|
+      method_name = "handle_special_#{name}"
+      if self.respond_to? method_name
+        special.text = send(method_name, special)
+        handled = true
+      end
+    end
+    raise "Unhandled special: #{special}" unless handled
+    special.text
+  end
+
+  def convert_heading(level, flow)
+    res =
+      annotate("<h#{level}>") +
+      convert_flow(flow) +
+      annotate("</h#{level}>\n")
+  end
+
+  def html_list_name(list_type, is_open_tag)
+    tags = LIST_TYPE_TO_HTML[list_type] || raise("Invalid list type: #{list_type.inspect}")
+    annotate(tags[ is_open_tag ? 0 : 1])
+  end
+
+  def list_item_start(am, fragment)
+    case fragment.type
+    when :BULLET, :NUMBER then
+      annotate("<li>")
+
+    when :UPPERALPHA then
+      annotate("<li type=\"A\">")
+
+    when :LOWERALPHA then
+      annotate("<li type=\"a\">")
+
+    when :LABELED then
+      annotate("<dt>") +
+        convert_flow(am.flow(fragment.param)) +
+        annotate("</dt>") +
+        annotate("<dd>")
+
+    when :NOTE then
+      annotate("<tr>") +
+        annotate("<td valign=\"top\">") +
+        convert_flow(am.flow(fragment.param)) +
+        annotate("</td>") +
+        annotate("<td>")
+    else
+      raise "Invalid list type"
+    end
+  end
+
+  def list_end_for(fragment_type)
+    case fragment_type
+    when :BULLET, :NUMBER, :UPPERALPHA, :LOWERALPHA then
+      "</li>"
+    when :LABELED then
+      "</dd>"
+    when :NOTE then
+      "</td></tr>"
+    else
+      raise "Invalid list type"
+    end
+  end
+
+end
+

data/lib/rdoc/markup/to_html_crossref.rb

@@ -0,0 +1,86 @@
+require 'rdoc/markup/to_html'
+
+##
+# Subclass of the RDoc::Markup::ToHtml class that supports looking up words in
+# the AllReferences list. Those that are found (like AllReferences in this
+# comment) will be hyperlinked
+
+class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
+
+  attr_accessor :context
+
+  ##
+  # We need to record the html path of our caller so we can generate
+  # correct relative paths for any hyperlinks that we find
+
+  def initialize(from_path, context, show_hash)
+    super()
+
+    # class names, variable names, or instance variables
+    @markup.add_special(/(
+                           # A::B.meth(**) (for operator in Fortran95)
+                           \w+(::\w+)*[.\#]\w+(\([\.\w+\*\/\+\-\=\<\>]+\))?
+                           # meth(**) (for operator in Fortran95)
+                         | \#\w+(\([.\w\*\/\+\-\=\<\>]+\))?
+                         | \b([A-Z]\w*(::\w+)*[.\#]\w+)  #    A::B.meth
+                         | \b([A-Z]\w+(::\w+)*)          #    A::B
+                         | \#\w+[!?=]?                   #    #meth_name
+                         | \\?\b\w+([_\/\.]+\w+)*[!?=]?  #    meth_name
+                         )/x,
+                        :CROSSREF)
+
+    @from_path = from_path
+    @context = context
+    @show_hash = show_hash
+
+    @seen = {}
+  end
+
+  ##
+  # We're invoked when any text matches the CROSSREF pattern
+  # (defined in MarkUp). If we fine the corresponding reference,
+  # generate a hyperlink. If the name we're looking for contains
+  # no punctuation, we look for it up the module/class chain. For
+  # example, HyperlinkHtml is found, even without the Generator::
+  # prefix, because we look for it in module Generator first.
+
+  def handle_special_CROSSREF(special)
+    name = special.text
+
+    return @seen[name] if @seen.include? name
+
+    if name[0,1] == '#' then
+      lookup = name[1..-1]
+      name = lookup unless @show_hash
+    else
+      lookup = name
+    end
+
+    # Find class, module, or method in class or module.
+    if /([A-Z]\w*)[.\#](\w+[!?=]?)/ =~ lookup then
+      container = $1
+      method = $2
+      ref = @context.find_symbol container, method
+    elsif /([A-Za-z]\w*)[.\#](\w+(\([\.\w+\*\/\+\-\=\<\>]+\))?)/ =~ lookup then
+      container = $1
+      method = $2
+      ref = @context.find_symbol container, method
+    else
+      ref = @context.find_symbol lookup
+    end
+
+    out = if lookup =~ /^\\/ then
+            $'
+          elsif ref and ref.document_self then
+            "<a href=\"#{ref.as_href(@from_path)}\">#{name}</a>"
+          else
+            name
+          end
+
+    @seen[name] = out
+
+    out
+  end
+
+end
+

data/lib/rdoc/markup/to_latex.rb

@@ -0,0 +1,328 @@
+require 'rdoc/markup/formatter'
+require 'rdoc/markup/fragments'
+require 'rdoc/markup/inline'
+
+require 'cgi'
+
+##
+# Convert SimpleMarkup to basic LaTeX report format.
+
+class RDoc::Markup::ToLaTeX < RDoc::Markup::Formatter
+
+  BS = "\020"   # \
+  OB = "\021"   # {
+  CB = "\022"   # }
+  DL = "\023"   # Dollar
+
+  BACKSLASH   = "#{BS}symbol#{OB}92#{CB}"
+  HAT         = "#{BS}symbol#{OB}94#{CB}"
+  BACKQUOTE   = "#{BS}symbol#{OB}0#{CB}"
+  TILDE       = "#{DL}#{BS}sim#{DL}"
+  LESSTHAN    = "#{DL}<#{DL}"
+  GREATERTHAN = "#{DL}>#{DL}"
+
+  def self.l(str)
+    str.tr('\\', BS).tr('{', OB).tr('}', CB).tr('$', DL)
+  end
+
+  def l(arg)
+    RDoc::Markup::ToLaTeX.l(arg)
+  end
+
+  LIST_TYPE_TO_LATEX = {
+    :BULLET =>  [ l("\\begin{itemize}"), l("\\end{itemize}") ],
+    :NUMBER =>  [ l("\\begin{enumerate}"), l("\\end{enumerate}"), "\\arabic" ],
+    :UPPERALPHA =>  [ l("\\begin{enumerate}"), l("\\end{enumerate}"), "\\Alph" ],
+    :LOWERALPHA =>  [ l("\\begin{enumerate}"), l("\\end{enumerate}"), "\\alph" ],
+    :LABELED => [ l("\\begin{description}"), l("\\end{description}") ],
+    :NOTE    => [
+      l("\\begin{tabularx}{\\linewidth}{@{} l X @{}}"),
+      l("\\end{tabularx}") ],
+  }
+
+  InlineTag = Struct.new(:bit, :on, :off)
+
+  def initialize
+    init_tags
+    @list_depth = 0
+    @prev_list_types = []
+  end
+
+  ##
+  # Set up the standard mapping of attributes to LaTeX
+
+  def init_tags
+    @attr_tags = [
+      InlineTag.new(RDoc::Markup::Attribute.bitmap_for(:BOLD), l("\\textbf{"), l("}")),
+      InlineTag.new(RDoc::Markup::Attribute.bitmap_for(:TT),   l("\\texttt{"), l("}")),
+      InlineTag.new(RDoc::Markup::Attribute.bitmap_for(:EM),   l("\\emph{"), l("}")),
+    ]
+  end
+
+  ##
+  # Escape a LaTeX string
+
+  def escape(str)
+    $stderr.print "FE: ", str if $DEBUG_RDOC
+    s = str.
+       sub(/\s+$/, '').
+      gsub(/([_\${}&%#])/, "#{BS}\\1").
+      gsub(/\\/, BACKSLASH).
+      gsub(/\^/, HAT).
+      gsub(/~/,  TILDE).
+      gsub(/</,  LESSTHAN).
+      gsub(/>/,  GREATERTHAN).
+      gsub(/,,/, ",{},").
+      gsub(/\`/,  BACKQUOTE)
+    $stderr.print "-> ", s, "\n" if $DEBUG_RDOC
+    s
+  end
+
+  ##
+  # Add a new set of LaTeX tags for an attribute. We allow
+  # separate start and end tags for flexibility
+
+  def add_tag(name, start, stop)
+    @attr_tags << InlineTag.new(RDoc::Markup::Attribute.bitmap_for(name), start, stop)
+  end
+
+  ##
+  # Here's the client side of the visitor pattern
+
+  def start_accepting
+    @res = ""
+    @in_list_entry = []
+  end
+
+  def end_accepting
+    @res.tr(BS, '\\').tr(OB, '{').tr(CB, '}').tr(DL, '$')
+  end
+
+  def accept_paragraph(am, fragment)
+    @res << wrap(convert_flow(am.flow(fragment.txt)))
+    @res << "\n"
+  end
+
+  def accept_verbatim(am, fragment)
+    @res << "\n\\begin{code}\n"
+    @res << fragment.txt.sub(/[\n\s]+\Z/, '')
+    @res << "\n\\end{code}\n\n"
+  end
+
+  def accept_rule(am, fragment)
+    size = fragment.param
+    size = 10 if size > 10
+    @res << "\n\n\\rule{\\linewidth}{#{size}pt}\n\n"
+  end
+
+  def accept_list_start(am, fragment)
+    @res << list_name(fragment.type, true) << "\n"
+    @in_list_entry.push false
+  end
+
+  def accept_list_end(am, fragment)
+    if tag = @in_list_entry.pop
+      @res << tag << "\n"
+    end
+    @res << list_name(fragment.type, false) << "\n"
+  end
+
+  def accept_list_item(am, fragment)
+    if tag = @in_list_entry.last
+      @res << tag << "\n"
+    end
+    @res << list_item_start(am, fragment)
+    @res << wrap(convert_flow(am.flow(fragment.txt))) << "\n"
+    @in_list_entry[-1] = list_end_for(fragment.type)
+  end
+
+  def accept_blank_line(am, fragment)
+    # @res << "\n"
+  end
+
+  def accept_heading(am, fragment)
+    @res << convert_heading(fragment.head_level, am.flow(fragment.txt))
+  end
+
+  ##
+  # This is a higher speed (if messier) version of wrap
+
+  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
+  end
+
+  private
+
+  def on_tags(res, item)
+    attr_mask = item.turn_on
+    return if attr_mask.zero?
+
+    @attr_tags.each do |tag|
+      if attr_mask & tag.bit != 0
+        res << tag.on
+      end
+    end
+  end
+
+  def off_tags(res, item)
+    attr_mask = item.turn_off
+    return if attr_mask.zero?
+
+    @attr_tags.reverse_each do |tag|
+      if attr_mask & tag.bit != 0
+        res << tag.off
+      end
+    end
+  end
+
+  def convert_flow(flow)
+    res = ""
+    flow.each do |item|
+      case item
+      when String
+        $stderr.puts "Converting '#{item}'" if $DEBUG_RDOC
+        res << convert_string(item)
+      when AttrChanger
+        off_tags(res, item)
+        on_tags(res,  item)
+      when Special
+        res << convert_special(item)
+      else
+        raise "Unknown flow element: #{item.inspect}"
+      end
+    end
+    res
+  end
+
+  ##
+  # some of these patterns are taken from SmartyPants...
+
+  def convert_string(item)
+    escape(item).
+
+    # convert ... to elipsis (and make sure .... becomes .<elipsis>)
+      gsub(/\.\.\.\./, '.\ldots{}').gsub(/\.\.\./, '\ldots{}').
+
+    # convert single closing quote
+      gsub(%r{([^ \t\r\n\[\{\(])\'}, '\1\'').
+      gsub(%r{\'(?=\W|s\b)}, "'" ).
+
+    # convert single opening quote
+      gsub(/'/, '`').
+
+    # convert double closing quote
+      gsub(%r{([^ \t\r\n\[\{\(])\"(?=\W)}, "\\1''").
+
+    # convert double opening quote
+      gsub(/"/, "``").
+
+    # convert copyright
+      gsub(/\(c\)/, '\copyright{}')
+
+  end
+
+  def convert_special(special)
+    handled = false
+    Attribute.each_name_of(special.type) do |name|
+      method_name = "handle_special_#{name}"
+      if self.respond_to? method_name
+        special.text = send(method_name, special)
+        handled = true
+      end
+    end
+    raise "Unhandled special: #{special}" unless handled
+    special.text
+  end
+
+  def convert_heading(level, flow)
+    res =
+      case level
+      when 1 then "\\chapter{"
+      when 2 then "\\section{"
+      when 3 then "\\subsection{"
+      when 4 then "\\subsubsection{"
+      else  "\\paragraph{"
+      end +
+      convert_flow(flow) +
+      "}\n"
+  end
+
+  def list_name(list_type, is_open_tag)
+    tags = LIST_TYPE_TO_LATEX[list_type] || raise("Invalid list type: #{list_type.inspect}")
+    if tags[2] # enumerate
+      if is_open_tag
+        @list_depth += 1
+        if @prev_list_types[@list_depth] != tags[2]
+          case @list_depth
+          when 1
+            roman = "i"
+          when 2
+            roman = "ii"
+          when 3
+            roman = "iii"
+          when 4
+            roman = "iv"
+          else
+            raise("Too deep list: level #{@list_depth}")
+          end
+          @prev_list_types[@list_depth] = tags[2]
+          return l("\\renewcommand{\\labelenum#{roman}}{#{tags[2]}{enum#{roman}}}") + "\n" + tags[0]
+        end
+      else
+        @list_depth -= 1
+      end
+    end
+    tags[ is_open_tag ? 0 : 1]
+  end
+
+  def list_item_start(am, fragment)
+    case fragment.type
+    when :BULLET, :NUMBER, :UPPERALPHA, :LOWERALPHA then
+      "\\item "
+
+    when :LABELED then
+      "\\item[" + convert_flow(am.flow(fragment.param)) + "] "
+
+    when :NOTE then
+        convert_flow(am.flow(fragment.param)) + " & "
+    else
+      raise "Invalid list type"
+    end
+  end
+
+  def list_end_for(fragment_type)
+    case fragment_type
+    when :BULLET, :NUMBER, :UPPERALPHA, :LOWERALPHA, :LABELED then
+      ""
+    when :NOTE
+      "\\\\\n"
+    else
+      raise "Invalid list type"
+    end
+  end
+
+end
+