[DOC] Enhances text about escapes (#917)

doc/rdoc/markup_reference.rb

@@ -820,37 +820,6 @@
 #
 #   ====== +Monofont+ in a 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;
@@ -1074,6 +1043,93 @@
 #
 #     {rdoc-image:https://www.ruby-lang.org/images/[email protected]}[./Alias.html]
 #
+# === Escaping Text
+#
+# Text that would otherwise be interpreted as markup
+# can be "escaped," so that it is not interpreted as markup;
+# the escape character is the backslash (<tt>'\\'</tt>).
+#
+# In a verbatim text block or a code block,
+# the escape character is always preserved:
+#
+# Example input:
+#
+#   This is not verbatim text.
+#
+#     This is verbatim text, with an escape character \.
+#
+#   This is not a code block.
+#
+#     def foo
+#       'String with an escape character.'
+#     end
+#
+# Rendered HTML:
+#
+# >>>
+#   This is not verbatim text.
+#
+#     This is verbatim text, with an escape character \.
+#
+#   This is not a code block.
+#
+#     def foo
+#       'This is a code block with an escape character \.'
+#     end
+#
+# In typeface markup (italic, bold, or monofont),
+# an escape character is preserved unless it is immediately
+# followed by nested typeface markup.
+#
+# Example input:
+#
+#   This list is about escapes; it contains:
+#
+#   - <tt>Monofont text with unescaped nested _italic_</tt>.
+#   - <tt>Monofont text with escaped nested \_italic_</tt>.
+#   - <tt>Monofont text with an escape character \</tt>.
+#
+# Rendered HTML:
+#
+# >>>
+#   This list is about escapes; it contains:
+#
+#   - <tt>Monofont text with unescaped nested _italic_</tt>.
+#   - <tt>Monofont text with escaped nested \_italic_</tt>.
+#   - <tt>Monofont text with an escape character \ </tt>.
+#
+# In other text-bearing blocks
+# (paragraphs, block quotes, list items, headings):
+#
+# - A single escape character immediately followed by markup
+#   escapes the markup.
+# - A single escape character followed by whitespace is preserved.
+# - A single escape character anywhere else is ignored.
+# - A double escape character is rendered as a single backslash.
+#
+#   Example input:
+#
+#     This list is about escapes; it contains:
+#
+#     - An unescaped class name, RDoc, that will become a link.
+#     - An escaped class name, \RDoc, that will not become a link.
+#     - An escape character followed by whitespace \ .
+#     - An escape character \that is ignored.
+#     - A double escape character \\ that is rendered
+#       as a single backslash.
+#
+#   Rendered HTML:
+#
+#   >>>
+#     This list is about escapes; it contains:
+#
+#     - An unescaped class name, RDoc, that will become a link.
+#     - An escaped class name, \RDoc, that will not become a link.
+#     - An escape character followed by whitespace \ .
+#     - An escape character \that is ignored.
+#     - A double escape character \\ that is rendered
+#       as a single backslash.
+#
 # == Documentation Derived from Ruby Code
 #
 # [Class]