[ruby/rdoc] [DOC] Removes remaining old Markup Reference (https://github.com/ruby/rdoc/pull/910)

https://github.com/ruby/rdoc/commit/4e44c9c6cf

2 files changed, 31 insertions, 349 deletions

diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb
index 49ad996c2d..c59f12cfe3 100644
--- a/doc/rdoc/markup_reference.rb
+++ b/doc/rdoc/markup_reference.rb
@@ -662,6 +662,37 @@ require 'rdoc'
 #   # [<tt>Two words</tt>] <tt>Two words</tt> in labeled list item.
 #   # ====== <tt>Two words</tt> in heading
 #
+# ==== 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
+# space, tab or newline. Otherwise, the HTML formatter will discard it, as it
+# 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}[https://www.ruby-lang.org].
+#   * This is not a link, however: \{ruby-lang.org}[https://www.ruby-lang.org].
+#   * 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}[https://www.ruby-lang.org]
+# * This is not a link, however: \{ruby-lang.org}[https://www.ruby-lang.org]
+# * 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 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.
+#
 # ==== Character Conversions
 #
 # Certain combinations of characters may be converted to special characters;
diff --git a/lib/rdoc/markup.rb b/lib/rdoc/markup.rb
index 7fec1c6869..6e93030965 100644
--- a/lib/rdoc/markup.rb
+++ b/lib/rdoc/markup.rb
@@ -99,355 +99,6 @@
 #
 # See RDoc::MarkupReference.
 #
-# === 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
-# space, tab or newline. Otherwise, the HTML formatter will discard it, as it
-# 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}[https://www.ruby-lang.org].
-#   * This is not a link, however: \{ruby-lang.org}[https://www.ruby-lang.org].
-#   * 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}[https://www.ruby-lang.org]
-# * This is not a link, however: \{ruby-lang.org}[https://www.ruby-lang.org]
-# * 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 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.
-#
-# === Conversion of characters
-#
-# HTML will convert two/three dashes to an em-dash. Other common characters are
-# converted as well:
-#
-#   em-dash::  -- or ---
-#   ellipsis:: ...
-#
-#   single quotes:: 'text' or `text'
-#   double quotes:: "text" or ``text''
-#
-#   copyright:: (c)
-#   registered trademark:: (r)
-#
-# produces:
-#
-# em-dash::  -- or ---
-# ellipsis:: ...
-#
-# single quotes:: 'text' or `text'
-# double quotes:: "text" or ``text''
-#
-# copyright:: (c)
-# registered trademark:: (r)
-#
-#
-# == Documenting Source Code
-#
-# Comment blocks can be written fairly naturally, either using <tt>#</tt> on
-# successive lines of the comment, or by including the comment in
-# a <tt>=begin</tt>/<tt>=end</tt> block.  If you use the latter form,
-# the <tt>=begin</tt> line _must_ be flagged with an +rdoc+ tag:
-#
-#   =begin rdoc
-#   Documentation to be processed by RDoc.
-#
-#   ...
-#   =end
-#
-# RDoc stops processing comments if it finds a comment line starting
-# with <tt>--</tt> right after the <tt>#</tt> character (otherwise,
-# it will be treated as a rule if it has three dashes or more).
-# This can be used to separate external from internal comments,
-# or to stop a comment being associated with a method, class, or module.
-# Commenting can be turned back on with a line that starts with <tt>++</tt>.
-#
-#   ##
-#   # Extract the age and calculate the date-of-birth.
-#   #--
-#   # FIXME: fails if the birthday falls on February 29th
-#   #++
-#   # The DOB is returned as a Time object.
-#
-#   def get_dob(person)
-#     # ...
-#   end
-#
-# 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
-# will also be displayed:
-#
-#   def fred
-#     ...
-#     yield line, address
-#
-# This will get documented as:
-#
-#   fred() { |line, address| ... }
-#
-# You can override this using a comment containing ':yields: ...' immediately
-# after the method definition
-#
-#   def fred # :yields: index, position
-#     # ...
-#
-#     yield line, address
-#
-# which will get documented as
-#
-#    fred() { |index, position| ... }
-#
-# +:yields:+ is an example of a documentation directive.  These appear
-# immediately after the start of the document element they are modifying.
-#
-# RDoc automatically cross-references words with underscores or camel-case.
-# To suppress cross-references, prefix the word with a \ character.  To
-# include special characters like "<tt>\n</tt>", you'll need to use
-# two \ characters in normal text, but only one in \<tt> text:
-#
-#   "\\n" or "<tt>\n</tt>"
-#
-# produces:
-#
-# "\\n" or "<tt>\n</tt>"
-#
-# == Directives
-#
-# Directives are keywords surrounded by ":" characters.
-#
-# === Controlling what is documented
-#
-# [+:nodoc:+ / <tt>:nodoc: all</tt>]
-#   This directive prevents documentation for the element from
-#   being generated.  For classes and modules, methods, aliases,
-#   constants, and attributes directly within the affected class or
-#   module also will be omitted.  By default, though, modules and
-#   classes within that class or module _will_ be documented.  This is
-#   turned off by adding the +all+ modifier.
-#
-#     module MyModule # :nodoc:
-#       class Input
-#       end
-#     end
-#
-#     module OtherModule # :nodoc: all
-#       class Output
-#       end
-#     end
-#
-#   In the above code, only class <tt>MyModule::Input</tt> will be documented.
-#
-#   The +:nodoc:+ directive, like +:enddoc:+, +:stopdoc:+ and +:startdoc:+
-#   presented below, is local to the current file: if you do not want to
-#   document a module that appears in several files, specify +:nodoc:+ on each
-#   appearance, at least once per file.
-#
-# [+:stopdoc:+ / +:startdoc:+]
-#   Stop and start adding new documentation elements to the current container.
-#   For example, if a class has a number of constants that you don't want to
-#   document, put a +:stopdoc:+ before the first, and a +:startdoc:+ after the
-#   last.  If you don't specify a +:startdoc:+ by the end of the container,
-#   disables documentation for the rest of the current file.
-#
-# [+:doc:+]
-#   Forces a method or attribute to be documented even if it wouldn't be
-#   otherwise.  Useful if, for example, you want to include documentation of a
-#   particular private method.
-#
-# [+:enddoc:+]
-#   Document nothing further at the current level: directives +:startdoc:+ and
-#   +:doc:+ that appear after this will not be honored for the current container
-#   (file, class or module), in the current file.
-#
-# [+:notnew:+ / +:not_new:+ / +:not-new:+ ]
-#   Only applicable to the +initialize+ instance method.  Normally RDoc
-#   assumes that the documentation and parameters for +initialize+ are
-#   actually for the +new+ method, and so fakes out a +new+ for the class.
-#   The +:notnew:+ directive stops this.  Remember that +initialize+ is private,
-#   so you won't see the documentation unless you use the +-a+ command line
-#   option.
-#
-# === Method arguments
-#
-# [+:arg:+ or +:args:+ _parameters_]
-#   Overrides the default argument handling with exactly these parameters.
-#
-#     ##
-#     #  :args: a, b
-#
-#     def some_method(*a)
-#     end
-#
-# [+:yield:+ or +:yields:+ _parameters_]
-#   Overrides the default yield discovery with these parameters.
-#
-#     ##
-#     # :yields: key, value
-#
-#     def each_thing &block
-#       @things.each(&block)
-#     end
-#
-# [+:call-seq:+]
-#   Lines up to the next blank line or lines with a common prefix in the
-#   comment are treated as the method's calling sequence, overriding the
-#   default parsing of method parameters and yield arguments.
-#
-#   Multiple lines may be used.
-#
-#     # :call-seq:
-#     #   ARGF.readlines(sep=$/)     -> array
-#     #   ARGF.readlines(limit)      -> array
-#     #   ARGF.readlines(sep, limit) -> array
-#     #
-#     #   ARGF.to_a(sep=$/)     -> array
-#     #   ARGF.to_a(limit)      -> array
-#     #   ARGF.to_a(sep, limit) -> array
-#     #
-#     # The remaining lines are documentation ...
-#
-# === Sections
-#
-# Sections allow you to group methods in a class into sensible containers.  If
-# you use the sections 'Public', 'Internal' and 'Deprecated' (the three
-# allowed method statuses from TomDoc) the sections will be displayed in that
-# order placing the most useful methods at the top.  Otherwise, sections will
-# be displayed in alphabetical order.
-#
-# [+:category:+ _section_]
-#   Adds this item to the named +section+ overriding the current section.  Use
-#   this to group methods by section in RDoc output while maintaining a
-#   sensible ordering (like alphabetical).
-#
-#     # :category: Utility Methods
-#     #
-#     # CGI escapes +text+
-#
-#     def convert_string text
-#       CGI.escapeHTML text
-#     end
-#
-#   An empty category will place the item in the default category:
-#
-#     # :category:
-#     #
-#     # This method is in the default category
-#
-#     def some_method
-#       # ...
-#     end
-#
-#   Unlike the :section: directive, :category: is not sticky.  The category
-#   only applies to the item immediately following the comment.
-#
-#   Use the :section: directive to provide introductory text for a section of
-#   documentation.
-#
-# [+:section:+ _title_]
-#   Provides section introductory text in RDoc output.  The title following
-#   +:section:+ is used as the section name and the remainder of the comment
-#   containing the section is used as introductory text.  A section's comment
-#   block must be separated from following comment blocks.  Use an empty title
-#   to switch to the default section.
-#
-#   The :section: directive is sticky, so subsequent methods, aliases,
-#   attributes, and classes will be contained in this section until the
-#   section is changed.  The :category: directive will override the :section:
-#   directive.
-#
-#   A :section: comment block may have one or more lines before the :section:
-#   directive.  These will be removed, and any identical lines at the end of
-#   the block are also removed.  This allows you to add visual cues to the
-#   section.
-#
-#   Example:
-#
-#     # ----------------------------------------
-#     # :section: My Section
-#     # This is the section that I wrote.
-#     # See it glisten in the noon-day sun.
-#     # ----------------------------------------
-#
-#     ##
-#     # Comment for some_method
-#
-#     def some_method
-#       # ...
-#     end
-#
-# === Other directives
-#
-# [+:markup:+ _type_]
-#   Overrides the default markup type for this comment with the specified
-#   markup type.  For Ruby files, if the first comment contains this directive
-#   it is applied automatically to all comments in the file.
-#
-#   Unless you are converting between markup formats you should use a
-#   <code>.rdoc_options</code> file to specify the default documentation
-#   format for your entire project.  See RDoc::Options@Saved+Options for
-#   instructions.
-#
-#   At the top of a file the +:markup:+ directive applies to the entire file:
-#
-#     # coding: UTF-8
-#     # :markup: TomDoc
-#
-#     # TomDoc comment here ...
-#
-#     class MyClass
-#       # ...
-#
-#   For just one comment:
-#
-#       # ...
-#     end
-#
-#     # :markup: RDoc
-#     #
-#     # This is a comment in RDoc markup format ...
-#
-#     def some_method
-#       # ...
-#
-#   See Markup@CONTRIBUTING for instructions on adding a new markup format.
-#
-# [+:include:+ _filename_]
-#   Include the contents of the named file at this point. This directive
-#   must appear alone on one line, possibly preceded by spaces. In this
-#   position, it can be escaped with a \ in front of the first colon.
-#
-#   The file will be searched for in the directories listed by the +--include+
-#   option, or in the current directory by default.  The contents of the file
-#   will be shifted to have the same indentation as the ':' at the start of
-#   the +:include:+ directive.
-#
-# [+:title:+ _text_]
-#   Sets the title for the document.  Equivalent to the <tt>--title</tt>
-#   command line parameter.  (The command line parameter overrides any :title:
-#   directive in the source).
-#
-# [+:main:+ _name_]
-#   Equivalent to the <tt>--main</tt> command line parameter.
-#
 #--
 # Original Author:: Dave Thomas,  dave@pragmaticprogrammer.com
 # License:: Ruby license