rdoc 2.5.11 → 3.0

data/lib/rdoc/markup/to_html_crossref.rb

@@ -9,10 +9,10 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   ##
   # Regular expression to match class references
   #
-  # 1) There can be a '\' in front of text to suppress any cross-references
-  # 2) There can be a '::' in front of class names to reference from the
+  # 1. There can be a '\\' in front of text to suppress the cross-reference
+  # 2. There can be a '::' in front of class names to reference from the
   #    top-level namespace.
-  # 3) The method can be followed by parenthesis
+  # 3. The method can be followed by parenthesis (not recommended)
 
   CLASS_REGEXP_STR = '\\\\?((?:\:{2})?[A-Z]\w*(?:\:\:\w+)*)'
 
@@ -34,10 +34,10 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
                       # A::B::C.meth
                       #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
 
-                      # Stand-alone method (proceeded by a #)
+                      # Stand-alone method (preceeded by a #)
                       | \\?\##{METHOD_REGEXP_STR}
 
-                      # Stand-alone method (proceeded by ::)
+                      # Stand-alone method (preceeded by ::)
                       | ::#{METHOD_REGEXP_STR}
 
                       # A::B::C
@@ -51,9 +51,10 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
                       # In order that words like "can't" not
                       # be flagged as potential cross-references, only
                       # flag potential class cross-references if the character
-                      # after the cross-referece is a space or sentence
-                      # punctuation.
-                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;]|\z)
+                      # after the cross-referece is a space, sentence
+                      # punctuation, tag start character, or attribute
+                      # marker.
+                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;<\000]|\z)
 
                       # Things that look like filenames
                       # The key thing is that there must be at least
@@ -62,7 +63,29 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
                       | (?:\.\.\/)*[-\/\w]+[_\/\.][-\w\/\.]+
 
                       # Things that have markup suppressed
-                      | \\[^\s]
+                      # Don't process things like '\<' in \<tt>, though.
+                      # TODO: including < is a hack, not very satisfying.
+                      | \\[^\s<]
+                      )/x
+
+  ##
+  # Version of CROSSREF_REGEXP used when <tt>--hyperlink-all</tt> is specified.
+
+  ALL_CROSSREF_REGEXP = /(
+                      # A::B::C.meth
+                      #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
+
+                      # Stand-alone method
+                      | \\?#{METHOD_REGEXP_STR}
+
+                      # A::B::C
+                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;<\000]|\z)
+
+                      # Things that look like filenames
+                      | (?:\.\.\/)*[-\/\w]+[_\/\.][-\w\/\.]+
+
+                      # Things that have markup suppressed
+                      | \\[^\s<]
                       )/x
 
   ##
@@ -78,17 +101,21 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   ##
   # Creates a new crossref resolver that generates links relative to +context+
   # which lives at +from_path+ in the generated files.  '#' characters on
-  # references are removed unless +show_hash+ is true.
+  # references are removed unless +show_hash+ is true.  Only method names
+  # preceded by '#' or '::' are hyperlinked, unless +hyperlink_all+ is true.
 
-  def initialize(from_path, context, show_hash)
+  def initialize(from_path, context, show_hash, hyperlink_all = false)
     raise ArgumentError, 'from_path cannot be nil' if from_path.nil?
     super()
 
-    @markup.add_special(CROSSREF_REGEXP, :CROSSREF)
+    crossref_re = hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
+
+    @markup.add_special crossref_re, :CROSSREF
 
     @from_path = from_path
     @context = context
     @show_hash = show_hash
+    @hyperlink_all = hyperlink_all
 
     @seen = {}
   end
@@ -97,18 +124,21 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # We're invoked when any text matches the CROSSREF pattern.  If we find 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.
+  # For example, ToHtml is found, even without the <tt>RDoc::Markup::</tt>
+  # prefix, because we look for it in module Markup first.
 
   def handle_special_CROSSREF(special)
     name = special.text
 
-    # This ensures that words consisting of only lowercase letters will not
-    # have cross-references generated (to suppress lots of erroneous
-    # cross-references to "new" in text, for instance)
-    return name if name =~ /\A[a-z]*\z/
+    unless @hyperlink_all then
+      # This ensures that words entirely consisting of lowercase letters will
+      # not have cross-references generated (to suppress lots of erroneous
+      # cross-references to "new" in text, for instance)
+      return name if name =~ /\A[a-z]*\z/
+    end
 
     return @seen[name] if @seen.include? name
+
     lookup = name
 
     name = name[1..-1] unless @show_hash if name[0, 1] == '#'
@@ -124,26 +154,47 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
     # whether the string as a whole is a known symbol).
 
     if /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/ =~ lookup then
-      container = $1
       type = $2
-      type = '#' if type == '.'
+      type = '' if type == '.'  # will find either #method or ::method
       method = "#{type}#{$3}"
-      ref = @context.find_symbol container, method
+      container = @context.find_symbol_module($1)
+    elsif /^([.#]|::)#{METHOD_REGEXP_STR}/ =~ lookup then
+      type = $1
+      type = '' if type == '.'
+      method = "#{type}#{$2}"
+      container = @context
+    else
+      container = nil
+    end
+
+    if container then
+      ref = container.find_local_symbol method
+
+      unless ref || RDoc::TopLevel === container then
+        ref = container.find_ancestor_local_symbol method
+      end
     end
 
     ref = @context.find_symbol lookup unless ref
+    ref = nil if RDoc::Alias === ref # external alias: can't link to it
 
     out = if lookup == '\\' then
             lookup
           elsif lookup =~ /^\\/ then
-            $'
-          elsif ref and ref.document_self then
-            "<a href=\"#{ref.as_href @from_path}\">#{name}</a>"
+            # we remove the \ only in front of what we know:
+            # other backslashes are treated later, only outside of <tt>
+            ref ? $' : lookup
+          elsif ref then
+            if ref.document_self then
+              "<a href=\"#{ref.as_href @from_path}\">#{name}</a>"
+            else
+              name
+            end
           else
-            name
+            lookup
           end
 
-    @seen[name] = out
+    @seen[lookup] = out
 
     out
   end

data/lib/rdoc/markup/to_rdoc.rb

@@ -1,3 +1,4 @@
+require 'rdoc/markup/formatter'
 require 'rdoc/markup/inline'
 
 ##
@@ -5,21 +6,49 @@ require 'rdoc/markup/inline'
 
 class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
 
+  ##
+  # Current indent amount for output in characters
+
   attr_accessor :indent
+
+  ##
+  # Output width in characters
+
+  attr_accessor :width
+
+  ##
+  # Stack of current list indexes for alphabetic and numeric lists
+
   attr_reader :list_index
+
+  ##
+  # Stack of list types
+
   attr_reader :list_type
+
+  ##
+  # Stack of list widths for indentation
+
   attr_reader :list_width
+
+  ##
+  # Prefix for the next list item.  See #use_prefix
+
   attr_reader :prefix
+
+  ##
+  # Output accumulator
+
   attr_reader :res
 
+  ##
+  # Creates a new formatter that will output (mostly) \RDoc markup
+
   def initialize
     super
 
-    @markup.add_special(/\\[^\s]/, :SUPPRESSED_CROSSREF)
-
+    @markup.add_special(/\\\S/, :SUPPRESSED_CROSSREF)
     @width = 78
-    @prefix = ''
-
     init_tags
 
     @headings = {}
@@ -34,7 +63,7 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
   end
 
   ##
-  # Maps attributes to ANSI sequences
+  # Maps attributes to HTML sequences
 
   def init_tags
     add_tag :BOLD, "<b>", "</b>"
@@ -42,10 +71,16 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     add_tag :EM,   "<em>", "</em>"
   end
 
+  ##
+  # Adds +blank_line+ to the output
+
   def accept_blank_line blank_line
     @res << "\n"
   end
 
+  ##
+  # Adds +heading+ to the output
+
   def accept_heading heading
     use_prefix or @res << ' ' * @indent
     @res << @headings[heading.level][0]
@@ -54,12 +89,18 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     @res << "\n"
   end
 
+  ##
+  # Finishes consumption of +list+
+
   def accept_list_end list
     @list_index.pop
     @list_type.pop
     @list_width.pop
   end
 
+  ##
+  # Finishes consumption of +list_item+
+
   def accept_list_item_end list_item
     width = case @list_type.last
             when :BULLET then
@@ -76,29 +117,29 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     @indent -= width
   end
 
+  ##
+  # Prepares the visitor for consuming +list_item+
+
   def accept_list_item_start list_item
-    bullet = case @list_type.last
-             when :BULLET then
-               '*'
-             when :NOTE, :LABEL then
-               attributes(list_item.label) + ":\n"
-             else
-               @list_index.last.to_s + '.'
-             end
-
-    case @list_type.last
+    type = @list_type.last
+
+    case type
     when :NOTE, :LABEL then
+      bullet = attributes(list_item.label) + ":\n"
+      @prefix = ' ' * @indent
       @indent += 2
-      @prefix = bullet + (' ' * @indent)
+      @prefix << bullet + (' ' * @indent)
     else
+      bullet = type == :BULLET ? '*' :  @list_index.last.to_s + '.'
       @prefix = (' ' * @indent) + bullet.ljust(bullet.length + 1)
-
       width = bullet.length + 1
-
       @indent += width
     end
   end
 
+  ##
+  # Prepares the visitor for consuming +list+
+
   def accept_list_start list
     case list.type
     when :BULLET then
@@ -123,14 +164,23 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     @list_type << list.type
   end
 
+  ##
+  # Adds +paragraph+ to the output
+
   def accept_paragraph paragraph
     wrap attributes(paragraph.text)
   end
 
+  ##
+  # Adds +raw+ to the output
+
   def accept_raw raw
     @res << raw.parts.join("\n")
   end
 
+  ##
+  # Adds +rule+ to the output
+
   def accept_rule rule
     use_prefix or @res << ' ' * @indent
     @res << '-' * (@width - @indent)
@@ -138,58 +188,46 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
   end
 
   ##
-  # Outputs +verbatim+ flush left and indented 2 columns
+  # Outputs +verbatim+ indented 2 columns
 
   def accept_verbatim verbatim
     indent = ' ' * (@indent + 2)
 
-    lines = []
-    current_line = []
-
-    # split into lines
     verbatim.parts.each do |part|
-      current_line << part
-
-      if part == "\n" then
-        lines << current_line
-        current_line = []
-      end
+      @res << indent unless part == "\n"
+      @res << part
     end
 
-    lines << current_line unless current_line.empty?
-
-    # calculate margin
-    indented = lines.select { |line| line != ["\n"] }
-    margin = indented.map { |line| line.first.length }.min
-
-    # flush left
-    indented.each { |line| line[0][0...margin] = '' }
-
-    # output
-    use_prefix or @res << indent # verbatim is unlikely to have prefix
-    @res << lines.shift.join
-
-    lines.each do |line|
-      @res << indent unless line == ["\n"]
-      @res << line.join
-    end
-
-    @res << "\n"
+    @res << "\n" unless @res =~ /\n\z/
   end
 
+  ##
+  # Applies attribute-specific markup to +text+ using RDoc::AttributeManager
+
   def attributes text
     flow = @am.flow text.dup
     convert_flow flow
   end
 
+  ##
+  # Returns the generated output
+
   def end_accepting
     @res.join
   end
 
+  ##
+  # Removes preceeding \\ from the suppressed crossref +special+
+
   def handle_special_SUPPRESSED_CROSSREF special
-    special.text.sub(/\\/, '')
+    text = special.text
+    text = text.sub('\\', '') unless in_tt?
+    text
   end
 
+  ##
+  # Prepares the visitor for text generation
+
   def start_accepting
     @res = [""]
     @indent = 0
@@ -200,6 +238,10 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     @list_width = []
   end
 
+  ##
+  # Adds the stored #prefix to the output and clears it.  Lists generate a
+  # prefix for later consumption.
+
   def use_prefix
     prefix = @prefix
     @prefix = nil
@@ -208,6 +250,9 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     prefix
   end
 
+  ##
+  # Wraps +text+ to #width
+
   def wrap text
     return unless text && !text.empty?
 

data/lib/rdoc/markup/to_test.rb

@@ -6,6 +6,8 @@ require 'rdoc/markup/formatter'
 
 class RDoc::Markup::ToTest < RDoc::Markup::Formatter
 
+  # :stopdoc:
+
   ##
   # :section: Visitor
 
@@ -22,8 +24,12 @@ class RDoc::Markup::ToTest < RDoc::Markup::Formatter
     @res << paragraph.text
   end
 
+  def accept_raw raw
+    @res << raw.parts.join
+  end
+
   def accept_verbatim(verbatim)
-    @res << verbatim.text
+    @res << verbatim.text.gsub(/^(\S)/, '  \1')
   end
 
   def accept_list_start(list)
@@ -60,5 +66,7 @@ class RDoc::Markup::ToTest < RDoc::Markup::Formatter
     @res << '-' * rule.weight
   end
 
+  # :startdoc:
+
 end