From 5e3e4bc9840160f2a6f85cba2e05279d7668b014 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Thu, 11 Aug 2022 15:08:57 -0500
Subject: [PATCH] [ruby/rdoc] Mods to section Text Markup
 (https://github.com/ruby/rdoc/pull/916)

https://github.com/ruby/rdoc/commit/5506d4d67e
---
 doc/rdoc/markup_reference.rb | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb
index c7578f3581..04e90aad23 100644
--- a/doc/rdoc/markup_reference.rb
+++ b/doc/rdoc/markup_reference.rb
@@ -94,7 +94,7 @@ require 'rdoc'
 # - {Directive}[rdoc-ref:RDoc::MarkupReference@Directives]:
 #   various special directions for the rendering.
 # - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup]:
-#   text to be rendered in italic, bold, or monofont.
+#   text to be rendered in a special way.
 #
 # About the blocks:
 #
@@ -632,18 +632,24 @@ require 'rdoc'
 #
 # ==== Text Markup
 #
-# Text markup is metatext that marks text as:
+# Text markup is metatext that affects HTML rendering:
 #
-# - Italic.
-# - Bold.
-# - Monofont.
+# - Typeface: italic, bold, monofont.
+# - Character conversions: copyright, trademark, certain punctuation.
+# - Links.
+# - Escapes: marking text as "not markup."
 #
-# Text markup may contain only one type of nested block:
+# ===== Typeface Markup
 #
-# - More text markup:
+# Typeface markup can specify that text is to be rendered
+# as italic, bold, or monofont.
+#
+# Typeface markup may contain only one type of nested block:
+#
+# - More typeface markup:
 #   italic, bold, monofont.
 #
-# ===== Italic
+# ====== Italic
 #
 # Text may be marked as italic via HTML tag <tt><i></tt> or <tt><em></tt>.
 #
@@ -698,7 +704,7 @@ require 'rdoc'
 #
 #   ====== _Italic_ in a Heading
 #
-# ===== Bold
+# ====== Bold
 #
 # Text may be marked as bold via HTML tag <tt><b></tt>.
 #
@@ -755,7 +761,7 @@ require 'rdoc'
 #
 #   ===== *Bold* in a Heading
 #
-# ===== Monofont
+# ====== Monofont
 #
 # Text may be marked as monofont
 # -- sometimes called 'typewriter font' --