https://git.ruby-lang.org/ruby.git/commit/?id=9fc401b689

From 9fc401b689e64dde5fc7cc56c734d5cddd6aa6e1 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Y...>
Date: Wed, 10 Aug 2022 16:18:27 -0500
Subject: [ruby/rdoc] Treat text markup (italic, bold, monofont) as blocks
 (https://github.com/ruby/rdoc/pull/911)

https://github.com/ruby/rdoc/commit/dc88f1b425
---
 doc/rdoc/markup_reference.rb | 367 +++++++++++++++++++++++++++++--------------
 1 file changed, 253 insertions(+), 114 deletions(-)

diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb
index c59f12cfe3..b3d1d97f4f 100644
--- a/doc/rdoc/markup_reference.rb
+++ b/doc/rdoc/markup_reference.rb
@@ -51,23 +51,37 @@ require 'rdoc' https://github.com/ruby/ruby/blob/trunk/doc/rdoc/markup_reference.rb#L51
 #
 # === Blocks
 #
-# It's convenient to think of markup input as a sequence of _blocks_,
-# such as:
-#
-# - {Paragraphs}[rdoc-ref:RDoc::MarkupReference@Paragraphs].
-# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks].
-# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks].
-# - {Block quotes}[rdoc-ref:RDoc::MarkupReference@Block+Quotes].
-# - {Bullet lists}[rdoc-ref:RDoc::MarkupReference@Bullet+Lists].
-# - {Numbered lists}[rdoc-ref:RDoc::MarkupReference@Numbered+Lists].
-# - {Lettered lists}[rdoc-ref:RDoc::MarkupReference@Lettered+Lists].
-# - {Labeled lists}[rdoc-ref:RDoc::MarkupReference@Labeled+Lists].
-# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings].
-# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules].
-# - {Directives}[rdoc-ref:RDoc::MarkupReference@Directives].
-#
-# All of these except paragraph blocks are distinguished by indentation,
-# or by unusual initial or embedded characters.
+# It's convenient to think of \RDoc markup input as a sequence of _blocks_
+# of various types (details at the links):
+#
+# - {Paragraph}[rdoc-ref:RDoc::MarkupReference@Paragraphs]:
+#   an ordinary paragraph.
+# - {Verbatim text block}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks]:
+#   a block of text to be rendered literally.
+# - {Code block}[rdoc-ref:RDoc::MarkupReference@Code+Blocks]:
+#   a verbatim text block containing Ruby code,
+#   to be rendered with code highlighting.
+# - {Block quote}[rdoc-ref:RDoc::MarkupReference@Block+Quotes]:
+#   a longish quoted passage, to be rendered with indentation
+#   instead of quote marks.
+# - {List}[rdoc-ref:RDoc::MarkupReference@Lists]: items for
+#   a bullet list, numbered list, lettered list, or labeled list.
+# - {Heading}[rdoc-ref:RDoc::MarkupReference@Headings]:
+#   a section heading.
+# - {Horizontal rule}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules]:
+#   a line across the rendered page.
+# - {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.
+#
+# About the blocks:
+#
+# - Except for a paragraph, a block is distinguished by its indentation,
+#   or by unusual initial or embedded characters.
+# - Any block may appear independently
+#   (that is, not nested in another block);
+#   some blocks may be nested, as detailed below.
 #
 # ==== Paragraphs
 #
@@ -98,12 +112,13 @@ require 'rdoc' https://github.com/ruby/ruby/blob/trunk/doc/rdoc/markup_reference.rb#L112
 #
 # A paragraph may contain nested blocks, including:
 #
-# - Verbatim text blocks.
-# - Code blocks.
-# - Block quotes.
-# - Lists of any type.
-# - Headings.
-# - Horizontal rules.
+# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks].
+# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks].
+# - {Block quotes}[rdoc-ref:RDoc::MarkupReference@Block+Quotes].
+# - {Lists}[rdoc-ref:RDoc::MarkupReference@Lists].
+# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings].
+# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules].
+# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
 #
 # ==== Verbatim Text Blocks
 #
@@ -140,6 +155,9 @@ require 'rdoc' https://github.com/ruby/ruby/blob/trunk/doc/rdoc/markup_reference.rb#L155
 #
 #   This is not verbatim text.
 #
+# A verbatim text block may not contain nested blocks of any kind
+# -- it's verbatim.
+#
 # ==== Code Blocks
 #
 # A special case of verbatim text is the <em>code block</em>,
@@ -173,6 +191,9 @@ require 'rdoc' https://github.com/ruby/ruby/blob/trunk/doc/rdoc/markup_reference.rb#L191
 # Pro tip:  If your indented Ruby code does not get highlighted,
 # it may contain a syntax error.
 #
+# A code block may not contain nested blocks of any kind
+# -- it's verbatim.
+#
 # ==== Block Quotes
 #
 # You can use the characters <tt>>>></tt> (unindented),
@@ -181,6 +202,7 @@ require 'rdoc' https://github.com/ruby/ruby/blob/trunk/doc/rdoc/markup_reference.rb#L202
 #
 # Example input:
 #
+#   Here's a block quote:
 #   >>>
 #     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
 #     commodo quam iaculis massa posuere, dictum fringilla justo pulvinar.
@@ -194,27 +216,30 @@ require 'rdoc' https://github.com/ruby/ruby/blob/trunk/doc/rdoc/markup_reference.rb#L216
 # Rendered HTML:
 #
 # >>>
-#   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
-#   commodo quam iaculis massa posuere, dictum fringilla justo pulvinar.
-#   Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.
+#   Here's a block quote:
+#   >>>
+#     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
+#     commodo quam iaculis massa posuere, dictum fringilla justo pulvinar.
+#     Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.
 #
-#   Aenean congue ligula eu ligula molestie, eu pellentesque purus
-#   faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum,
-#   diam in pellentesque aliquet, mi tellus placerat sapien, id euismod
-#   purus magna ut tortor.
+#     Aenean congue ligula eu ligula molestie, eu pellentesque purus
+#     faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum,
+#     diam in pellentesque aliquet, mi tellus placerat sapien, id euismod
+#     purus magna ut tortor.
+#
+# Note that, unlike verbatim text, single newlines are not honored,
+# but that a double newline begins a new paragraph in the block quote.
 #
 # A block quote may contain nested blocks, including:
 #
 # - Other block quotes.
-# - Paragraphs.
-# - Verbatim text blocks.
-# - Code blocks.
-# - Lists of any type.
-# - Headings.
-# - Horizontal rules.
-#
-# Note that, unlike verbatim text, single newlines are not honored,
-# but that a double newline begins a new paragraph in the block quote.
+# - {Paragraphs}[rdoc-ref:RDoc::MarkupReference@Paragraphs].
+# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks].
+# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks].
+# - {Lists}[rdoc-ref:RDoc::MarkupReference@Lists].
+# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings].
+# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules].
+# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
 #
 # ==== Lists
 #
@@ -240,12 +265,13 @@ require 'rdoc' https://github.com/ruby/ruby/blob/trunk/doc/rdoc/markup_reference.rb#L265
 # A list item may contain nested blocks, including:
 #
 # - Other lists of any type.
-# - Paragraphs.
-# - Verbatim text blocks.
-# - Code blocks.
-# - Block quotes.
-# - Headings.
-# - Horizontal rules.
+# - {Paragraphs}[rdoc-ref:RDoc::MarkupReference@Paragraphs].
+# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks].
+# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks].
+# - {Block quotes}[rdoc-ref:RDoc::MarkupReference@Block+Quotes].
+# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings].
+# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules].
+# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
 #
 # ===== Bullet Lists
 #
@@ -370,30 +396,29 @@ require 'rdoc' https://github.com/ruby/ruby/blob/trunk/doc/rdoc/markup_reference.rb#L396
 #   # ============Still a Heading (Level 6)
 #   # \== Not a Heading
 #
+# A heading may contain only one type of nested block:
+#
+# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
+#
 # ==== Horizontal Rules
 #
-# A horizontal rule begins with three or more hyphens.
+# A horizontal rule consists of a line with three or more hyphens
+# and nothing more.
 #
 # Example input:
 #
-#   # ------
-#   # Stuff between.
-#   #
-#   # \--- Not a horizontal rule.
-#   #
-#   # -- Also not a horizontal rule.
-#   #
-#   # ---
+#   ---
+#   --- Not a horizontal rule.
+#
+#   -- Also not a horizontal rule.
+#   ---
 #
 # Rendered HTML:
 # >>>
-#   ------
-#   Stuff between.
-#
-#   \--- Not a horizontal rule.
+#   ---
+#   --- Not a horizontal rule.
 #
 #   -- Also not a horizontal rule.
-#
 #   ---
 #
 # ==== Directives
@@ -584,83 +609,197 @@ require 'rdoc' https://github.com/ruby/ruby/blob/trunk/doc/rdoc/markup_reference.rb#L609
 #
 #   For C code, the directive may appear in a stand-alone comment
 #
-# === Text Markup
+# ==== Text Markup
 #
-# Text in a paragraph, list item (any type), or heading
-# may have markup formatting.
+# Text markup is metatext that marks text as:
 #
-# ==== Italic
+# - Italic.
+# - Bold.
+# - Monofont.
 #
-# A single word may be italicized by prefixed and suffixed underscores.
+# Text markup may contain only one type of nested block:
 #
-# Examples:
+# - More text markup:
+#   italic, bold, monofont.
 #
-#   # _Word_ in paragraph.
-#   # - _Word_ in bullet list item.
-#   # 1. _Word_ in numbered list item.
-#   # a. _Word_ in lettered list item.
-#   # [_word_] _Word_ in labeled list item.
-#   # ====== _Word_ in heading
+# ===== Italic
 #
-# Any text may be italicized via HTML tag +i+ or +em+.
+# Text may be marked as italic via HTML tag <tt><i></tt> or <tt><em></tt>.
 #
-# Examples:
+# Example input:
 #
-#   # <i>Two words</i> in paragraph.
-#   # - <i>Two words</i> in bullet list (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/