Add the rdoc: scheme to allow forward-compatible class and file links. Issue #53

Author: drbrain

History.txt

@@ -2,6 +2,10 @@
 
 * Minor enhancements
   * RDoc::Parser::C now supports :doc: and :nodoc: for class comments
+  * Added the <tt>rdoc:</tt> link scheme which links to a named reference.
+    This can be used to create cross-generator named links unlike the
+    <tt>link:</tt> scheme which is dependent upon the exact file name.  Issue
+    #53 by Simon Chiang
 * Bug fixes
   * `ri []` and other special methods now work properly.  Issue #52 by
     ddebernardy.

lib/rdoc/markup/to_html.rb

@@ -97,6 +97,7 @@ def initialize markup = nil
 
   def handle_special_HYPERLINK(special)
     url = special.text
+
     gen_url url, url
   end
 

lib/rdoc/markup/to_html_crossref.rb

@@ -112,6 +112,7 @@ def initialize(from_path, context, show_hash, hyperlink_all = false,
     crossref_re = hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
 
     @markup.add_special crossref_re, :CROSSREF
+    @markup.add_special /rdoc:\S+\w/, :HYPERLINK
 
     @from_path = from_path
     @context = context
@@ -122,28 +123,18 @@ def initialize(from_path, context, show_hash, hyperlink_all = false,
   end
 
   ##
-  # 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, 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
-
-    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
+  # Creates a link to the reference +name+ if the name exists.  If +text+ is
+  # given it is used as the link text, otherwise +name+ is used.
 
+  def cross_reference name, text = nil
     return @seen[name] if @seen.include? name
 
     lookup = name
 
     name = name[1..-1] unless @show_hash if name[0, 1] == '#'
 
+    text = name unless text
+
     # Find class, module, or method in class or module.
     #
     # Do not, however, use an if/elsif/else chain to do so.  Instead, test
@@ -187,7 +178,7 @@ def handle_special_CROSSREF(special)
             ref ? $' : lookup
           elsif ref then
             if ref.document_self then
-              "<a href=\"#{ref.as_href @from_path}\">#{name}</a>"
+              "<a href=\"#{ref.as_href @from_path}\">#{text}</a>"
             else
               name
             end
@@ -200,5 +191,43 @@ def handle_special_CROSSREF(special)
     out
   end
 
+  ##
+  # 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, 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
+
+    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
+
+    cross_reference name
+  end
+
+  ##
+  # Handles <tt>rdoc:</tt> scheme hyperlinks
+
+  def handle_special_HYPERLINK special
+    return cross_reference $' if special.text =~ /\Ardoc:/
+
+    super
+  end
+
+  ##
+  # Generates links for <tt>rdoc:</tt> scheme URLs
+
+  def gen_url url, text
+    super unless url =~ /\Ardoc:/
+      
+    cross_reference $', text
+  end
+
 end
 

test/test_rdoc_markup_to_html.rb

@@ -306,6 +306,14 @@ def test_gen_url
                  @to.gen_url('link:example', 'example')
   end
 
+  def test_handle_special_HYPERLINK_link
+    special = RDoc::Markup::Special.new 0, 'link:README.txt'
+
+    link = @to.handle_special_HYPERLINK special
+
+    assert_equal '<a href="README.txt">README.txt</a>', link
+  end
+
   def test_list_verbatim_2
     str = "* one\n    verb1\n    verb2\n* two\n"
 

test/test_rdoc_markup_to_html_crossref.rb

@@ -165,5 +165,47 @@ def test_handle_special_CROSSREF_special
                  @xref.convert('C2::C3;method(*)')
   end
 
+  def test_handle_special_HYPERLINK_rdoc
+    RDoc::TopLevel.new 'README.txt'
+    @to = RDoc::Markup::ToHtmlCrossref.new 'C2.html', @c2, true
+
+    link = @to.handle_special_HYPERLINK hyper 'C2::C3'
+
+    assert_equal '<a href="C2/C3.html">C2::C3</a>', link
+
+    link = @to.handle_special_HYPERLINK hyper 'C4'
+
+    assert_equal '<a href="C4.html">C4</a>', link
+
+    link = @to.handle_special_HYPERLINK hyper 'README.txt'
+
+    assert_equal '<a href="README_txt.html">README.txt</a>', link
+  end
+
+  def test_handle_special_TIDYLINK_rdoc
+    RDoc::TopLevel.new 'README.txt'
+    @to = RDoc::Markup::ToHtmlCrossref.new 'C2.html', @c2, true
+
+    link = @to.handle_special_TIDYLINK tidy 'C2::C3'
+
+    assert_equal '<a href="C2/C3.html">tidy</a>', link
+
+    link = @to.handle_special_TIDYLINK tidy 'C4'
+
+    assert_equal '<a href="C4.html">tidy</a>', link
+
+    link = @to.handle_special_TIDYLINK tidy 'README.txt'
+
+    assert_equal '<a href="README_txt.html">tidy</a>', link
+  end
+
+  def hyper reference
+    RDoc::Markup::Special.new 0, "rdoc:#{reference}"
+  end
+
+  def tidy reference
+    RDoc::Markup::Special.new 0, "{tidy}[rdoc:#{reference}]"
+  end
+
 end