Skip to content

Commit

Permalink
[DOC] Enhances text about escapes (#917)
Browse files Browse the repository at this point in the history
  • Loading branch information
BurdetteLamar authored Aug 13, 2022
1 parent 5506d4d commit c40bac8
Showing 1 changed file with 87 additions and 31 deletions.
118 changes: 87 additions & 31 deletions doc/rdoc/markup_reference.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -1074,6 +1043,93 @@
#
# {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./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]
Expand Down

0 comments on commit c40bac8

Please sign in to comment.