[DOC] Add some links in intro; delimit rendered HTML output. (#904)

BurdetteLamar · web-flow · commit c02645364f08 · 2022-07-28T09:50:37.000-05:00
diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb
@@ -9,16 +9,28 @@
 #
 # = \RDoc Markup Reference
 #
-# [Note]
+# Notes:
 #
-#   Examples in this reference are Ruby code and comments.
-#   Certain differences among the sources are noted.
+# - Examples in this reference are Ruby code and comments;
+#   certain differences from other sources
+#   (such as C code and comments) are noted.
+# - An example that shows rendered HTML output
+#   displays that output in a blockquote:
+#
+#   Rendered HTML:
+#   >>>
+#     Some stuff
 #
 # \RDoc-generated documentation is derived from and controlled by:
 #
-# - Single-line or multi-line comments that precede certain definitions.
-# - \RDoc directives in trailing comments (on the same line as code).
-# - The Ruby code itself.
+# - Single-line or multi-line comments that precede certain definitions;
+#   see {Markup in Comments}[rdoc-ref:RDoc::MarkupReference@Markup+in+Comments].
+# - \RDoc directives in trailing comments (on the same line as code);
+#   see <tt>:nodoc:</tt>, <tt>:doc:</tt>, and <tt>:notnew</tt>.
+# - \RDoc directives in single-line comments;
+#   see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives].
+# - The Ruby code itself;
+#   see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code]
 #
 # == Markup in Comments
 #
@@ -76,12 +88,12 @@
 #   # You'll love it.
 #
 # Rendered HTML:
+# >>>
+#   \RDoc produces HTML and command-line documentation for Ruby projects.
+#   \RDoc includes the rdoc and ri tools for generating and displaying
+#   documentation from the command-line.
 #
-# \RDoc produces HTML and command-line documentation for Ruby projects.
-# \RDoc includes the rdoc and ri tools for generating and displaying
-# documentation from the command-line.
-#
-# You'll love it.
+#   You'll love it.
 #
 # A paragraph may contain nested blocks, including:
 #
@@ -113,16 +125,17 @@
 #   # This is not verbatim text.
 #
 # Rendered HTML:
+# >>>
+#   This is not verbatim text.
 #
-# This is not verbatim text.
-#
-#   This is verbatim text.
-#     Whitespace is honored.     # See?
+#     This is verbatim text.
 #       Whitespace is honored.     # See?
+#         Whitespace is honored.     # See?
 #
-#   This is still the same verbatim text block.
+#     This is still the same verbatim text block.
+#
+#   This is not verbatim text.
 #
-# This is not verbatim text.
 # ==== Code Blocks
 #
 # A special case of verbatim text is the <em>code block</em>,
@@ -134,12 +147,24 @@
 # - Has a contrasting background color.
 # - Has syntax highlighting.
 #
-# Example:
+# Example input:
 #
-#   def foo(name = '', value = 0)
-#     @name = name      # Whitespace is still honored.
-#     @value = value
-#   end
+#   Consider this method:
+#
+#     def foo(name = '', value = 0)
+#       @name = name      # Whitespace is still honored.
+#       @value = value
+#     end
+#
+#
+# Rendered HTML:
+# >>>
+#   Consider this method:
+#
+#     def foo(name = '', value = 0)
+#       @name = name      # Whitespace is still honored.
+#       @value = value
+#     end
 #
 # Pro tip:  If your indented Ruby code does not get highlighted,
 # it may contain a syntax error.
@@ -180,14 +205,14 @@
 #   # - Last one.
 #
 # Rendered HTML:
+# >>>
+#   - An item.
+#   - Another.
+#   - An item spanning
+#     multiple lines.
 #
-# - An item.
-# - Another.
-# - An item spanning
-#   multiple lines.
-#
-# * Yet another.
-# - Last one.
+#   * Yet another.
+#   - Last one.
 #
 # ===== Numbered Lists
 #
@@ -206,14 +231,14 @@
 #   # 1000. Last one.
 #
 # Rendered HTML:
+# >>>
+#   100. An item.
+#   10. Another.
+#   1. An item spanning
+#      multiple lines.
 #
-# 100. An item.
-# 10. Another.
-# 1. An item spanning
-#    multiple lines.
-#
-# 1. Yet another.
-# 1000. Last one.
+#   1. Yet another.
+#   1000. Last one.
 #
 # ===== Lettered Lists
 #
@@ -232,12 +257,12 @@
 #   # a. Last one.
 #
 # Rendered HTML:
+# >>>
+#   z. An item.
+#   y. Another.
 #
-# z. An item.
-# y. Another.
-#
-# x. Yet another.
-# a. Last one.
+#   x. Yet another.
+#   a. Last one.
 #
 # ===== Labeled Lists
 #
@@ -257,14 +282,14 @@
 #   # bam:: Last one.
 #
 # Rendered HTML:
+# >>>
+#   [foo] An item.
+#   bat:: Another.
+#   [bag] An item spanning
+#         multiple lines.
 #
-# [foo] An item.
-# bat:: Another.
-# [bag] An item spanning
-#       multiple lines.
-#
-# [bar baz] Yet another.
-# bam:: Last one.
+#   [bar baz] Yet another.
+#   bam:: Last one.
 #
 # ===== Blocks Nested in Lists
 #
@@ -313,15 +338,15 @@
 #   # ---
 #
 # Rendered HTML:
+# >>>
+#   ------
+#   Stuff between.
 #
-# ------
-# Stuff between.
-#
-# \--- Not a horizontal rule.
+#   \--- Not a horizontal rule.
 #
-# -- Also not a horizontal rule.
+#   -- Also not a horizontal rule.
 #
-# ---
+#   ---
 #
 # ==== Directives
 #

Original file line number	Diff line number	Diff line change
`@@ -9,16 +9,28 @@`
`9`	`9`	`#`
`10`	`10`	`# = \RDoc Markup Reference`
`11`	`11`	`#`
`12`		`-# [Note]`
	`12`	`+# Notes:`
`13`	`13`	`#`
`14`		`-# Examples in this reference are Ruby code and comments.`
`15`		`-# Certain differences among the sources are noted.`
	`14`	`+# - Examples in this reference are Ruby code and comments;`
	`15`	`+# certain differences from other sources`
	`16`	`+# (such as C code and comments) are noted.`
	`17`	`+# - An example that shows rendered HTML output`
	`18`	`+# displays that output in a blockquote:`
	`19`	`+#`
	`20`	`+# Rendered HTML:`
	`21`	`+# >>>`
	`22`	`+# Some stuff`
`16`	`23`	`#`
`17`	`24`	`# \RDoc-generated documentation is derived from and controlled by:`
`18`	`25`	`#`
`19`		`-# - Single-line or multi-line comments that precede certain definitions.`
`20`		`-# - \RDoc directives in trailing comments (on the same line as code).`
`21`		`-# - The Ruby code itself.`
	`26`	`+# - Single-line or multi-line comments that precede certain definitions;`
	`27`	`+# see {Markup in Comments}[rdoc-ref:RDoc::MarkupReference@Markup+in+Comments].`
	`28`	`+# - \RDoc directives in trailing comments (on the same line as code);`
	`29`	`+# see <tt>:nodoc:</tt>, <tt>:doc:</tt>, and <tt>:notnew</tt>.`
	`30`	`+# - \RDoc directives in single-line comments;`
	`31`	`+# see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives].`
	`32`	`+# - The Ruby code itself;`
	`33`	`+# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code]`
`22`	`34`	`#`
`23`	`35`	`# == Markup in Comments`
`24`	`36`	`#`
`@@ -76,12 +88,12 @@`
`76`	`88`	`# # You'll love it.`
`77`	`89`	`#`
`78`	`90`	`# Rendered HTML:`
	`91`	`+# >>>`
	`92`	`+# \RDoc produces HTML and command-line documentation for Ruby projects.`
	`93`	`+# \RDoc includes the rdoc and ri tools for generating and displaying`
	`94`	`+# documentation from the command-line.`
`79`	`95`	`#`
`80`		`-# \RDoc produces HTML and command-line documentation for Ruby projects.`
`81`		`-# \RDoc includes the rdoc and ri tools for generating and displaying`
`82`		`-# documentation from the command-line.`
`83`		`-#`
`84`		`-# You'll love it.`
	`96`	`+# You'll love it.`
`85`	`97`	`#`
`86`	`98`	`# A paragraph may contain nested blocks, including:`
`87`	`99`	`#`
`@@ -113,16 +125,17 @@`
`113`	`125`	`# # This is not verbatim text.`
`114`	`126`	`#`
`115`	`127`	`# Rendered HTML:`
	`128`	`+# >>>`
	`129`	`+# This is not verbatim text.`
`116`	`130`	`#`
`117`		`-# This is not verbatim text.`
`118`		`-#`
`119`		`-# This is verbatim text.`
`120`		`-# Whitespace is honored. # See?`
	`131`	`+# This is verbatim text.`
`121`	`132`	`# Whitespace is honored. # See?`
	`133`	`+# Whitespace is honored. # See?`
`122`	`134`	`#`
`123`		`-# This is still the same verbatim text block.`
	`135`	`+# This is still the same verbatim text block.`
	`136`	`+#`
	`137`	`+# This is not verbatim text.`
`124`	`138`	`#`
`125`		`-# This is not verbatim text.`
`126`	`139`	`# ==== Code Blocks`
`127`	`140`	`#`
`128`	`141`	`# A special case of verbatim text is the <em>code block</em>,`
`@@ -134,12 +147,24 @@`
`134`	`147`	`# - Has a contrasting background color.`
`135`	`148`	`# - Has syntax highlighting.`
`136`	`149`	`#`
`137`		`-# Example:`
	`150`	`+# Example input:`
`138`	`151`	`#`
`139`		`-# def foo(name = '', value = 0)`
`140`		`-# @name = name # Whitespace is still honored.`
`141`		`-# @value = value`
`142`		`-# end`
	`152`	`+# Consider this method:`
	`153`	`+#`
	`154`	`+# def foo(name = '', value = 0)`
	`155`	`+# @name = name # Whitespace is still honored.`
	`156`	`+# @value = value`
	`157`	`+# end`
	`158`	`+#`
	`159`	`+#`
	`160`	`+# Rendered HTML:`
	`161`	`+# >>>`
	`162`	`+# Consider this method:`
	`163`	`+#`
	`164`	`+# def foo(name = '', value = 0)`
	`165`	`+# @name = name # Whitespace is still honored.`
	`166`	`+# @value = value`
	`167`	`+# end`
`143`	`168`	`#`
`144`	`169`	`# Pro tip: If your indented Ruby code does not get highlighted,`
`145`	`170`	`# it may contain a syntax error.`
`@@ -180,14 +205,14 @@`
`180`	`205`	`# # - Last one.`
`181`	`206`	`#`
`182`	`207`	`# Rendered HTML:`
	`208`	`+# >>>`
	`209`	`+# - An item.`
	`210`	`+# - Another.`
	`211`	`+# - An item spanning`
	`212`	`+# multiple lines.`
`183`	`213`	`#`
`184`		`-# - An item.`
`185`		`-# - Another.`
`186`		`-# - An item spanning`
`187`		`-# multiple lines.`
`188`		`-#`
`189`		`-# * Yet another.`
`190`		`-# - Last one.`
	`214`	`+# * Yet another.`
	`215`	`+# - Last one.`
`191`	`216`	`#`
`192`	`217`	`# ===== Numbered Lists`
`193`	`218`	`#`
`@@ -206,14 +231,14 @@`
`206`	`231`	`# # 1000. Last one.`
`207`	`232`	`#`
`208`	`233`	`# Rendered HTML:`
	`234`	`+# >>>`
	`235`	`+# 100. An item.`
	`236`	`+# 10. Another.`
	`237`	`+# 1. An item spanning`
	`238`	`+# multiple lines.`
`209`	`239`	`#`
`210`		`-# 100. An item.`
`211`		`-# 10. Another.`
`212`		`-# 1. An item spanning`
`213`		`-# multiple lines.`
`214`		`-#`
`215`		`-# 1. Yet another.`
`216`		`-# 1000. Last one.`
	`240`	`+# 1. Yet another.`
	`241`	`+# 1000. Last one.`
`217`	`242`	`#`
`218`	`243`	`# ===== Lettered Lists`
`219`	`244`	`#`
`@@ -232,12 +257,12 @@`
`232`	`257`	`# # a. Last one.`
`233`	`258`	`#`
`234`	`259`	`# Rendered HTML:`
	`260`	`+# >>>`
	`261`	`+# z. An item.`
	`262`	`+# y. Another.`
`235`	`263`	`#`
`236`		`-# z. An item.`
`237`		`-# y. Another.`
`238`		`-#`
`239`		`-# x. Yet another.`
`240`		`-# a. Last one.`
	`264`	`+# x. Yet another.`
	`265`	`+# a. Last one.`
`241`	`266`	`#`
`242`	`267`	`# ===== Labeled Lists`
`243`	`268`	`#`
`@@ -257,14 +282,14 @@`
`257`	`282`	`# # bam:: Last one.`
`258`	`283`	`#`
`259`	`284`	`# Rendered HTML:`
	`285`	`+# >>>`
	`286`	`+# [foo] An item.`
	`287`	`+# bat:: Another.`
	`288`	`+# [bag] An item spanning`
	`289`	`+# multiple lines.`
`260`	`290`	`#`
`261`		`-# [foo] An item.`
`262`		`-# bat:: Another.`
`263`		`-# [bag] An item spanning`
`264`		`-# multiple lines.`
`265`		`-#`
`266`		`-# [bar baz] Yet another.`
`267`		`-# bam:: Last one.`
	`291`	`+# [bar baz] Yet another.`
	`292`	`+# bam:: Last one.`
`268`	`293`	`#`
`269`	`294`	`# ===== Blocks Nested in Lists`
`270`	`295`	`#`
`@@ -313,15 +338,15 @@`
`313`	`338`	`# # ---`
`314`	`339`	`#`
`315`	`340`	`# Rendered HTML:`
	`341`	`+# >>>`
	`342`	`+# ------`
	`343`	`+# Stuff between.`
`316`	`344`	`#`
`317`		`-# ------`
`318`		`-# Stuff between.`
`319`		`-#`
`320`		`-# \--- Not a horizontal rule.`
	`345`	`+# \--- Not a horizontal rule.`
`321`	`346`	`#`
`322`		`-# -- Also not a horizontal rule.`
	`347`	`+# -- Also not a horizontal rule.`
`323`	`348`	`#`
`324`		`-# ---`
	`349`	`+# ---`
`325`	`350`	`#`
`326`	`351`	`# ==== Directives`
`327`	`352`	`#`