Link from RDoc::Markup to RDoc::MarkupReference (#906)

Recently new RDoc::MarkupReference replaces Markup Reference in RDoc::Markup (which was always the goal).

Author: BurdetteLamar

lib/rdoc/markup.rb

@@ -97,289 +97,7 @@
 #
 # = \RDoc Markup Reference
 #
-# == Block Markup
-#
-# === Paragraphs and Verbatim
-#
-# The markup engine looks for a document's natural left margin.  This is
-# used as the initial margin for the document.
-#
-# Consecutive lines starting at this margin are considered to be a
-# paragraph. Empty lines separate paragraphs.
-#
-# Any line that starts to the right of the current margin is treated
-# as verbatim text.  This is useful for code listings:
-#
-#   3.times { puts "Ruby" }
-#
-# In verbatim text, two or more blank lines are collapsed into one,
-# and trailing blank lines are removed:
-#
-#   This is the first line
-#
-#
-#   This is the second non-blank line,
-#   after 2 blank lines in the source markup.
-#
-#
-# There were two trailing blank lines right above this paragraph, that
-# have been removed. In addition, the verbatim text has been shifted
-# left, so the amount of indentation of verbatim text is unimportant.
-#
-# For HTML output RDoc makes a small effort to determine if a verbatim section
-# contains Ruby source code.  If so, the verbatim block will be marked up as
-# HTML.  Triggers include "def", "class", "module", "require", the "hash
-# rocket"# (=>) or a block call with a parameter.
-#
-# === Headers
-#
-# A line starting with an equal sign (=) is treated as a
-# heading.  Level one headings have one equals sign, level two headings
-# have two, and so on until level six, which is the maximum
-# (seven hyphens or more result in a level six heading).
-#
-# For example, the above header was obtained with:
-#
-#   === Headers
-#
-# In HTML output headers have an id matching their name.  The above example's
-# HTML is:
-#
-#   <h3 id="label-Headers">Headers</h3>
-#
-# If a heading is inside a method body the id will be prefixed with the
-# method's id.  If the above header where in the documentation for a method
-# such as:
-#
-#   ##
-#   # This method does fun things
-#   #
-#   # = Example
-#   #
-#   #   Example of fun things goes here ...
-#
-#   def do_fun_things
-#   end
-#
-# The header's id would be:
-#
-#   <h1 id="method-i-do_fun_things-label-Example">Example</h1>
-#
-# The label can be linked-to using <tt>SomeClass@Headers</tt>.  See
-# {Links}[rdoc-ref:RDoc::Markup@Links] for further details.
-#
-# === Rules
-#
-# A line starting with three or more hyphens (at the current indent)
-# generates a horizontal rule.
-#
-#   ---
-#
-# produces:
-#
-# ---
-#
-# === Simple Lists
-#
-# If a paragraph starts with a "*", "-", "<digit>." or "<letter>.",
-# then it is taken to be the start of a list.  The margin is increased to be
-# the first non-space following the list start flag.  Subsequent lines
-# should be indented to this new margin until the list ends.  For example:
-#
-#   * this is a list with three paragraphs in
-#     the first item.  This is the first paragraph.
-#
-#     And this is the second paragraph.
-#
-#     1. This is an indented, numbered list.
-#     2. This is the second item in that list
-#
-#     This is the third conventional paragraph in the
-#     first list item.
-#
-#   * This is the second item in the original list
-#
-# produces:
-#
-# * this is a list with three paragraphs in
-#   the first item.  This is the first paragraph.
-#
-#   And this is the second paragraph.
-#
-#   1. This is an indented, numbered list.
-#   2. This is the second item in that list
-#
-#   This is the third conventional paragraph in the
-#   first list item.
-#
-# * This is the second item in the original list
-#
-# === Labeled Lists
-#
-# You can also construct labeled lists, sometimes called description
-# or definition lists.  Do this by putting the label in square brackets
-# and indenting the list body:
-#
-#   [cat]  a small furry mammal
-#          that seems to sleep a lot
-#
-#   [ant]  a little insect that is known
-#          to enjoy picnics
-#
-# produces:
-#
-# [cat]  a small furry mammal
-#        that seems to sleep a lot
-#
-# [ant]  a little insect that is known
-#        to enjoy picnics
-#
-# If you want the list bodies to line up to the left of the labels,
-# use two colons:
-#
-#   cat::  a small furry mammal
-#          that seems to sleep a lot
-#
-#   ant::  a little insect that is known
-#          to enjoy picnics
-#
-# produces:
-#
-# cat::  a small furry mammal
-#        that seems to sleep a lot
-#
-# ant::  a little insect that is known
-#        to enjoy picnics
-#
-# Notice that blank lines right after the label are ignored in labeled lists:
-#
-#   [one]
-#
-#       definition 1
-#
-#   [two]
-#
-#       definition 2
-#
-# produces the same output as
-#
-#   [one]  definition 1
-#   [two]  definition 2
-#
-#
-# === Lists and Verbatim
-#
-# If you want to introduce a verbatim section right after a list, it has to be
-# less indented than the list item bodies, but more indented than the list
-# label, letter, digit or bullet. For instance:
-#
-#   *   point 1
-#
-#   *   point 2, first paragraph
-#
-#       point 2, second paragraph
-#         verbatim text inside point 2
-#       point 2, third paragraph
-#     verbatim text outside of the list (the list is therefore closed)
-#   regular paragraph after the list
-#
-# produces:
-#
-# *   point 1
-#
-# *   point 2, first paragraph
-#
-#     point 2, second paragraph
-#       verbatim text inside point 2
-#     point 2, third paragraph
-#   verbatim text outside of the list (the list is therefore closed)
-# regular paragraph after the list
-#
-# == Text Markup
-#
-# === Bold, Italic, Typewriter Text
-#
-# You can use markup within text (except verbatim) to change the
-# appearance of parts of that text.  Out of the box, RDoc::Markup
-# supports word-based and general markup.
-#
-# Word-based markup uses flag characters around individual words:
-#
-# <tt>\*_word_\*</tt>::  displays _word_ in a *bold* font
-# <tt>\__word_\_</tt>::  displays _word_ in an _emphasized_ font
-# <tt>\+_word_\+</tt>::  displays _word_ in a +code+ font
-#
-# General markup affects text between a start delimiter and an end
-# delimiter.  Not surprisingly, these delimiters look like HTML markup.
-#
-# <tt>\<b>_text_</b></tt>::    displays _text_ in a *bold* font
-# <tt>\<em>_text_</em></tt>::  displays _text_ in an _emphasized_ font
-#                              (alternate tag: <tt>\<i></tt>)
-# <tt>\<tt>_text_\</tt></tt>:: displays _text_ in a +code+ font
-#                              (alternate tag: <tt>\<code></tt>)
-#
-# Unlike conventional Wiki markup, general markup can cross line
-# boundaries.  You can turn off the interpretation of markup by
-# preceding the first character with a backslash (see <i>Escaping
-# Text Markup</i>, below).
-#
-# === Links
-#
-# Links to starting with +http:+, +https:+, +mailto:+, +ftp:+ or +www.+
-# are recognized.  An HTTP url that references an external image is converted
-# into an inline image element.
-#
-# Classes and methods will be automatically linked to their definition.  For
-# example, <tt>RDoc::Markup</tt> will link to this documentation.  By default
-# methods will only be automatically linked if they contain an <tt>_</tt> (all
-# methods can be automatically linked through the <tt>--hyperlink-all</tt>
-# command line option).
-#
-# Single-word methods can be linked by using the <tt>#</tt> character for
-# instance methods or <tt>::</tt> for class methods.  For example,
-# <tt>#convert</tt> links to #convert.  A class or method may be combined like
-# <tt>RDoc::Markup#convert</tt>.
-#
-# A heading inside the documentation can be linked by following the class
-# or method by an <tt>@</tt> then the heading name.
-# <tt>RDoc::Markup@Links</tt> will link to this section like this:
-# RDoc::Markup@Links.  Spaces in headings with multiple words must be escaped
-# with <tt>+</tt> like <tt>RDoc::Markup@Escaping+Text+Markup</tt>.
-# Punctuation and other special characters must be escaped like CGI.escape.
-#
-# The <tt>@</tt> can also be used to link to sections.  If a section and a
-# heading share the same name the section is preferred for the link.
-#
-# 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>.
-# The +url+ may be an +http:+-type link or a cross-reference to a class,
-# module or method with a label.
-#
-# Links with the <code>rdoc-image:</code> scheme will create an image tag for
-# HTML output.  Only fully-qualified URLs are supported.
-#
-# Links with the <tt>rdoc-ref:</tt> scheme will link to the referenced class,
-# module, method, file, etc.  If the referenced item is does not exist
-# no link will be generated and <tt>rdoc-ref:</tt> will be removed from the
-# resulting text.
-#
-# Links starting with <tt>rdoc-label:label_name</tt> will link to the
-# +label_name+.  You can create a label for the current link (for
-# bidirectional links) by supplying a name for the current link like
-# <tt>rdoc-label:label-other:label-mine</tt>.
-#
-# Links starting with +link:+ refer to local files whose path is relative to
-# the <tt>--op</tt> directory.  Use <tt>rdoc-ref:</tt> instead of
-# <tt>link:</tt> to link to files generated by RDoc as the link target may
-# be different across RDoc generators.
-#
-# Example links:
-#
-#   https://github.com/ruby/rdoc
-#   mailto:user@example.com
-#   {RDoc Documentation}[http://rdoc.rubyforge.org]
-#   {RDoc Markup}[rdoc-ref:RDoc::Markup]
+# See RDoc::MarkupReference.
 #
 # === Escaping Text Markup
 #