From 011de3f2fd86c5797af3b20ea119faffcf1530e9 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Mon, 29 Jul 2024 08:16:13 -0500
Subject: [PATCH] [DOC] Mods about markup formats (#1143)

---
 doc/rdoc/markup_reference.rb |  3 ++-
 lib/rdoc/markup.rb           | 31 ++++++++++++++++++-------------
 lib/rdoc/options.rb          |  6 +++---
 lib/rdoc/task.rb             |  5 ++---
 lib/rdoc/tom_doc.rb          |  8 +-------
 5 files changed, 26 insertions(+), 27 deletions(-)

diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb
index bfc84abd5a..d1901b86e2 100644
--- a/doc/rdoc/markup_reference.rb
+++ b/doc/rdoc/markup_reference.rb
@@ -532,7 +532,8 @@
 #
 #   - Appears on a line by itself.
 #   - Specifies the format for the \RDoc input;
-#     parameter +type+ is one of +markdown+, +rd+, +rdoc+, +tomdoc+.
+#     parameter +type+ is one of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
+#     See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats].
 #
 # ===== Directives for HTML Output
 #
diff --git a/lib/rdoc/markup.rb b/lib/rdoc/markup.rb
index 6e93030965..3c29870d8a 100644
--- a/lib/rdoc/markup.rb
+++ b/lib/rdoc/markup.rb
@@ -10,19 +10,24 @@
 # RDoc::Markup and other markup formats do no output formatting, this is
 # handled by the RDoc::Markup::Formatter subclasses.
 #
-# = Supported Formats
-#
-# Besides the RDoc::Markup format, the following formats are built in to RDoc:
-#
-# markdown::
-#   The markdown format as described by
-#   http://daringfireball.net/projects/markdown/.  See RDoc::Markdown for
-#   details on the parser and supported extensions.
-# rd::
-#   The rdtool format.  See RDoc::RD for details on the parser and format.
-# tomdoc::
-#   The TomDoc format as described by http://tomdoc.org/.  See RDoc::TomDoc
-#   for details on the parser and supported extensions.
+# = Markup Formats
+#
+# +RDoc+ supports these markup formats:
+#
+# - +rdoc+:
+#   the +RDoc+ markup format;
+#   see RDoc::MarkupReference.
+# - +markdown+:
+#   The +markdown+ markup format as described in
+#   the {Markdown Guide}[https://www.markdownguide.org];
+#   see RDoc::Markdown.
+# - +rd+:
+#   the +rd+ markup format format;
+#   see RDoc::RD.
+# - +tomdoc+:
+#   the TomDoc format as described in
+#   {TomDoc for Ruby}[http://tomdoc.org];
+#   see RDoc::TomDoc.
 #
 # You can choose a markup format using the following methods:
 #
diff --git a/lib/rdoc/options.rb b/lib/rdoc/options.rb
index c8fca4a262..2631d57364 100644
--- a/lib/rdoc/options.rb
+++ b/lib/rdoc/options.rb
@@ -233,9 +233,9 @@ class RDoc::Options
   attr_accessor :main_page
 
   ##
-  # The default markup format.  The default is 'rdoc'.  'markdown', 'tomdoc'
-  # and 'rd' are also built-in.
-
+  # The markup format.
+  # One of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
+  # See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats].
   attr_accessor :markup
 
   ##
diff --git a/lib/rdoc/task.rb b/lib/rdoc/task.rb
index eb584c9d2a..ba697d0a93 100644
--- a/lib/rdoc/task.rb
+++ b/lib/rdoc/task.rb
@@ -104,9 +104,8 @@ class RDoc::Task < Rake::TaskLib
   attr_accessor :name
 
   ##
-  # Comment markup format.  rdoc, rd and tomdoc are supported.  (default is
-  # 'rdoc')
-
+  # The markup format; one of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
+  # See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats].
   attr_accessor :markup
 
   ##
diff --git a/lib/rdoc/tom_doc.rb b/lib/rdoc/tom_doc.rb
index e161fcf42f..d10f024f70 100644
--- a/lib/rdoc/tom_doc.rb
+++ b/lib/rdoc/tom_doc.rb
@@ -3,13 +3,7 @@
 
 # A parser for TomDoc based on TomDoc 1.0.0-rc1 (02adef9b5a)
 #
-# The TomDoc specification can be found at:
-#
-# http://tomdoc.org
-#
-# The latest version of the TomDoc specification can be found at:
-#
-# https://github.com/mojombo/tomdoc/blob/master/tomdoc.md
+# The TomDoc specification can be found at http://tomdoc.org.
 #
 # To choose TomDoc as your only default format see RDoc::Options@Saved+Options
 # for instructions on setting up a <code>.rdoc_options</code> file to store