Change rdoc: to rdoc-ref: and update documetation. Issue #53

Author: drbrain

History.txt

@@ -2,10 +2,11 @@
 
 * 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
+  * Added the <tt>rdoc-ref:</tt> link scheme which links to a named reference.
+    <tt>rdoc-ref:</tt> can resolve references to classes, modules, methods,
+    files, etc.  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.rb

@@ -269,57 +269,59 @@
 # preceding the first character with a backslash (see <i>Escaping
 # Text Markup</i>, below).
 #
-# === Hyperlinks
+# === Links
 #
-# Hyperlinks to the web starting with +http:+, +mailto:+, +ftp:+ or +www.+
+# Links to starting with +http:+, +https:+, +mailto:+, +ftp:+ or +www.+
 # are recognized.  An HTTP url that references an external image file is
-# converted into an inline <img...>.  Hyperlinks starting with +link:+ are
-# assumed to refer to local files whose path is relative to the <tt>--op</tt>
-# directory.
+# converted into an inline image element.
 #
-# Hyperlinks can also be of the form _label_[_url_], in which
-# case _label_ is used in the displayed text, and _url_ is
-# used as the target.  If _label_ contains multiple words,
-# put it in braces: {<em>multi word label</em>}[url].
+# Links starting with <tt>rdoc-ref:</tt> will link to the referenced class,
+# module, method, file, etc.
 #
-# Example hyperlinks:
+# Links starting with +link:+ refer to local files whose path is relative to
+# the <tt>--op</tt> directory.
 #
-#   link:RDoc.html
-#   http://rdoc.rubyforge.org
+# Links can also be of the form <tt>label[url]</tt>, in which case +label+ is
+# used in the displayed text, and +url+ is used as the target.  If +label+
+# contains multiple words, put it in braces: <tt>{multi word label}[url]<tt>.
+#
+# Example links:
+#
+#   https://github.com/rdoc/rdoc
 #   mailto:[email protected]
 #   {RDoc Documentation}[http://rdoc.rubyforge.org]
-#   {RDoc Markup}[link:RDoc/Markup.html]
+#   {RDoc Markup}[rdoc-ref:RDoc::Markup]
 #
 # === Escaping Text Markup
 #
 # Text markup can be escaped with a backslash, as in \<tt>, which was obtained
-# with "<tt>\\<tt></tt>". Except in verbatim sections and between \<tt> tags,
-# to produce a backslash, you have to double it unless it is followed by a
+# with <tt>\\<tt></tt>.  Except in verbatim sections and between \<tt> tags,
+# to produce a backslash you have to double it unless it is followed by a
 # space, tab or newline. Otherwise, the HTML formatter will discard it, as it
-# is used to escape potential hyperlinks:
+# is used to escape potential links:
 #
 #   * The \ must be doubled if not followed by white space: \\.
 #   * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space.
 #   * This is a link to {ruby-lang}[www.ruby-lang.org].
 #   * This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org].
-#   * This will not be hyperlinked to \RDoc::RDoc#document
+#   * This will not be linked to \RDoc::RDoc#document
 #
 # generates:
 #
 # * The \ must be doubled if not followed by white space: \\.
 # * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space.
 # * This is a link to {ruby-lang}[www.ruby-lang.org]
 # * This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org]
-# * This will not be hyperlinked to \RDoc::RDoc#document
+# * This will not be linked to \RDoc::RDoc#document
 #
-# Inside \<tt> tags, more precisely, leading backslashes are removed
-# only if followed by a markup character (<tt><*_+</tt>), a backslash,
-# or a known hyperlink reference (a known class or method). So in the
-# example above, the backslash of <tt>\S</tt> would be removed
-# if there was a class or module named +S+ in the current context.
+# Inside \<tt> tags, more precisely, leading backslashes are removed only if
+# followed by a markup character (<tt><*_+</tt>), a backslash, or a known link
+# reference (a known class or method). So in the example above, the backslash
+# of <tt>\S</tt> would be removed if there was a class or module named +S+ in
+# the current context.
 #
-# This behavior is inherited from RDoc version 1, and has been kept
-# for compatibility with existing RDoc documentation.
+# This behavior is inherited from RDoc version 1, and has been kept for
+# compatibility with existing RDoc documentation.
 #
 # === Conversion of characters
 #
@@ -378,11 +380,10 @@
 #     # ...
 #   end
 #
-# Names of classes, files, and any method names containing an
-# underscore or preceded by a hash character are automatically hyperlinked
-# from comment text to their description. This hyperlinking works inside
-# the current class or module, and with ancestor methods (in included modules
-# or in the superclass).
+# Names of classes, files, and any method names containing an underscore or
+# preceded by a hash character are automatically linked from comment text to
+# their description. This linking works inside the current class or module,
+# and with ancestor methods (in included modules or in the superclass).
 #
 # Method parameter lists are extracted and displayed with the method
 # description.  If a method calls +yield+, then the parameters passed to yield

lib/rdoc/markup/to_html.rb

@@ -70,7 +70,7 @@ def initialize markup = nil
     @list = nil
     @from_path = ''
 
-    # external hyperlinks
+    # external links
     @markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK)
 
     # and links of the form  <text>[<url>]
@@ -84,7 +84,7 @@ def initialize markup = nil
   # These methods handle special markup added by RDoc::Markup#add_special.
 
   ##
-  # +special+ is a potential hyperlink.  The following schemes are handled:
+  # +special+ is a potential link.  The following schemes are handled:
   #
   # <tt>mailto:</tt>::
   #   Inserted as-is.
@@ -102,8 +102,8 @@ def handle_special_HYPERLINK(special)
   end
 
   ##
-  # This +special+ is a hyperlink where the label is different from the URL
-  # label[url] or {long label}[url]
+  # This +special+ 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
@@ -233,8 +233,8 @@ def convert_string(text)
   end
 
   ##
-  # Generate a hyperlink for +url+, labeled with +text+.  Handles the special
-  # cases for img: and link: described under handle_special_HYPERLINK
+  # Generate a link 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

lib/rdoc/markup/to_html_crossref.rb

@@ -2,7 +2,7 @@
 
 ##
 # Subclass of the RDoc::Markup::ToHtml class that supports looking up words
-# from a context.  Those that are found will be hyperlinked.
+# from a context.  Those that are found will be linked.
 
 class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
@@ -102,7 +102,7 @@ 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.  Only method names
-  # preceded by '#' or '::' are hyperlinked, unless +hyperlink_all+ is true.
+  # preceded by '#' or '::' are linked, unless +hyperlink_all+ is true.
 
   def initialize(from_path, context, show_hash, hyperlink_all = false,
                  markup = nil)
@@ -193,10 +193,10 @@ def cross_reference name, text = nil
 
   ##
   # 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.
+  # corresponding reference, generate a link.  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
@@ -212,20 +212,22 @@ def handle_special_CROSSREF(special)
   end
 
   ##
-  # Handles <tt>rdoc:</tt> scheme hyperlinks
+  # Handles <tt>rdoc-ref:</tt> scheme links and allows RDoc::Markup::ToHtml to
+  # handle other schemes.
 
   def handle_special_HYPERLINK special
-    return cross_reference $' if special.text =~ /\Ardoc:/
+    return cross_reference $' if special.text =~ /\Ardoc-ref:/
 
     super
   end
 
   ##
-  # Generates links for <tt>rdoc:</tt> scheme URLs
+  # Generates links for <tt>rdoc-ref:</tt> scheme URLs and allows
+  # RDoc::Markup::ToHtml to handle other schemes.
 
   def gen_url url, text
-    super unless url =~ /\Ardoc:/
-      
+    super unless url =~ /\Ardoc-ref:/
+
     cross_reference $', text
   end
 

test/test_rdoc_markup_to_html_crossref.rb

@@ -200,11 +200,11 @@ def test_handle_special_TIDYLINK_rdoc
   end
 
   def hyper reference
-    RDoc::Markup::Special.new 0, "rdoc:#{reference}"
+    RDoc::Markup::Special.new 0, "rdoc-ref:#{reference}"
   end
 
   def tidy reference
-    RDoc::Markup::Special.new 0, "{tidy}[rdoc:#{reference}]"
+    RDoc::Markup::Special.new 0, "{tidy}[rdoc-ref:#{reference}]"
   end
 
 end