From 65ed3a4851f591c597f65dc9ad91ed67c07375b3 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 26 Jul 2022 15:26:10 -0500 Subject: [PATCH 1/4] Add some links in intro --- doc/rdoc/markup_reference.rb | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb index cc10b04871..53caba4415 100644 --- a/doc/rdoc/markup_reference.rb +++ b/doc/rdoc/markup_reference.rb @@ -16,9 +16,14 @@ # # \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). +# - 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 :nodoc:, :doc:, and :notnew. +# - \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 # From 60e4e2ae732473f986b64b144c7854b07244197f Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 26 Jul 2022 15:57:04 -0500 Subject: [PATCH 2/4] Delimit rendered HTML output --- doc/rdoc/markup_reference.rb | 59 +++++++++++++++++++++++++++++------- 1 file changed, 48 insertions(+), 11 deletions(-) diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb index 53caba4415..879ea7b9bf 100644 --- a/doc/rdoc/markup_reference.rb +++ b/doc/rdoc/markup_reference.rb @@ -9,10 +9,18 @@ # # = \RDoc Markup Reference # -# [Note] +# Notes: +# +# - 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 +# delimits that output with beginning and ending markers: +# +# >>> Rendered HTML >>> +# ... +# <<<<<< # -# Examples in this reference are Ruby code and comments. -# Certain differences among the sources are noted. # # \RDoc-generated documentation is derived from and controlled by: # @@ -80,7 +88,7 @@ # # # # You'll love it. # -# Rendered HTML: +# >>> Rendered HTML >>> # # \RDoc produces HTML and command-line documentation for Ruby projects. # \RDoc includes the rdoc and ri tools for generating and displaying @@ -88,6 +96,8 @@ # # You'll love it. # +# <<<<<< +# # A paragraph may contain nested blocks, including: # # - Verbatim text blocks. @@ -117,7 +127,7 @@ # # # # This is not verbatim text. # -# Rendered HTML: +# >>> Rendered HTML >>> # # This is not verbatim text. # @@ -128,6 +138,9 @@ # This is still the same verbatim text block. # # This is not verbatim text. +# +# <<<<<< +# # ==== Code Blocks # # A special case of verbatim text is the code block, @@ -139,13 +152,27 @@ # - Has a contrasting background color. # - Has syntax highlighting. # -# Example: +# Example input: +# +# 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. # @@ -184,7 +211,7 @@ # # * Yet another. # # - Last one. # -# Rendered HTML: +# >>> Rendered HTML >>> # # - An item. # - Another. @@ -194,6 +221,8 @@ # * Yet another. # - Last one. # +# <<<<<< +# # ===== Numbered Lists # # A numbered list item begins with digits and a period. @@ -210,7 +239,7 @@ # # 1. Yet another. # # 1000. Last one. # -# Rendered HTML: +# >>> Rendered HTML >>> # # 100. An item. # 10. Another. @@ -220,6 +249,8 @@ # 1. Yet another. # 1000. Last one. # +# <<<<<< +# # ===== Lettered Lists # # A numbered list item begins with a letters and a period. @@ -236,7 +267,7 @@ # # x. Yet another. # # a. Last one. # -# Rendered HTML: +# >>> Rendered HTML >>> # # z. An item. # y. Another. @@ -244,6 +275,8 @@ # x. Yet another. # a. Last one. # +# <<<<<< +# # ===== Labeled Lists # # A labeled list item begins with one of: @@ -261,7 +294,7 @@ # # [bar baz] Yet another. # # bam:: Last one. # -# Rendered HTML: +# >>> Rendered HTML >>> # # [foo] An item. # bat:: Another. @@ -271,6 +304,8 @@ # [bar baz] Yet another. # bam:: Last one. # +# <<<<<< +# # ===== Blocks Nested in Lists # # A list item may contain nested blocks, including: @@ -317,7 +352,7 @@ # # # # --- # -# Rendered HTML: +# >>> Rendered HTML >>> # # ------ # Stuff between. @@ -328,6 +363,8 @@ # # --- # +# <<<<<< +# # ==== Directives # # ===== Directives for Allowing or Suppressing Documentation From 6bb2224640c764ba2f102e1978a33fa0d7f1a6b4 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 27 Jul 2022 10:01:25 -0500 Subject: [PATCH 3/4] Delimit rendered HTML output --- doc/rdoc/markup_reference.rb | 139 +++++++++++++++-------------------- 1 file changed, 61 insertions(+), 78 deletions(-) diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb index 879ea7b9bf..bfce9bd38a 100644 --- a/doc/rdoc/markup_reference.rb +++ b/doc/rdoc/markup_reference.rb @@ -15,12 +15,11 @@ # certain differences from other sources # (such as C code and comments) are noted. # - An example that shows rendered HTML output -# delimits that output with beginning and ending markers: -# -# >>> Rendered HTML >>> -# ... -# <<<<<< +# displays that output in a blockquote: # +# Rendered HTML: +# >>> +# Some stuff # # \RDoc-generated documentation is derived from and controlled by: # @@ -88,15 +87,13 @@ # # # # 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. -# -# 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. # -# <<<<<< +# You'll love it. # # A paragraph may contain nested blocks, including: # @@ -127,19 +124,17 @@ # # # # This is not verbatim text. # -# >>> Rendered HTML >>> +# 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 not verbatim text. +# This is still the same verbatim text block. # -# <<<<<< +# This is not verbatim text. # # ==== Code Blocks # @@ -162,16 +157,14 @@ # end # # -# >>> Rendered HTML >>> -# -# 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. @@ -211,17 +204,15 @@ # # * Yet another. # # - Last one. # -# >>> Rendered HTML >>> -# -# - An item. -# - Another. -# - An item spanning -# multiple lines. -# -# * Yet another. -# - Last one. +# Rendered HTML +# >>> +# - An item. +# - Another. +# - An item spanning +# multiple lines. # -# <<<<<< +# * Yet another. +# - Last one. # # ===== Numbered Lists # @@ -239,17 +230,15 @@ # # 1. Yet another. # # 1000. Last one. # -# >>> Rendered HTML >>> +# 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 # @@ -267,15 +256,13 @@ # # x. Yet another. # # a. Last one. # -# >>> Rendered HTML >>> -# -# z. An item. -# y. Another. +# Rendered HTML: +# >>> +# z. An item. +# y. Another. # -# x. Yet another. -# a. Last one. -# -# <<<<<< +# x. Yet another. +# a. Last one. # # ===== Labeled Lists # @@ -294,17 +281,15 @@ # # [bar baz] Yet another. # # bam:: Last one. # -# >>> Rendered HTML >>> -# -# [foo] An item. -# bat:: Another. -# [bag] An item spanning -# multiple lines. -# -# [bar baz] Yet another. -# bam:: Last one. +# Rendered HTML: +# >>> +# [foo] An item. +# bat:: Another. +# [bag] An item spanning +# multiple lines. # -# <<<<<< +# [bar baz] Yet another. +# bam:: Last one. # # ===== Blocks Nested in Lists # @@ -352,18 +337,16 @@ # # # # --- # -# >>> Rendered HTML >>> -# -# ------ -# Stuff between. -# -# \--- Not a horizontal rule. +# Rendered HTML: +# >>> +# ------ +# Stuff between. # -# -- Also not a horizontal rule. +# \--- Not a horizontal rule. # -# --- +# -- Also not a horizontal rule. # -# <<<<<< +# --- # # ==== Directives # From 4ae7a98403bf5b42001673b61a93e33c4045df37 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 27 Jul 2022 10:39:06 -0500 Subject: [PATCH 4/4] Delimit rendered HTML output --- doc/rdoc/markup_reference.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb index bfce9bd38a..cc682f987e 100644 --- a/doc/rdoc/markup_reference.rb +++ b/doc/rdoc/markup_reference.rb @@ -29,7 +29,7 @@ # see :nodoc:, :doc:, and :notnew. # - \RDoc directives in single-line comments; # see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives]. -# - The Ruby code itself. +# - The Ruby code itself; # see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code] # # == Markup in Comments @@ -204,7 +204,7 @@ # # * Yet another. # # - Last one. # -# Rendered HTML +# Rendered HTML: # >>> # - An item. # - Another.