Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[DOC] Add some links in intro; delimit rendered HTML output. #904

Merged
merged 4 commits into from
Jul 28, 2022
Merged

[DOC] Add some links in intro; delimit rendered HTML output. #904

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
65ed3a4
Add some links in intro
BurdetteLamar Jul 26, 2022
60e4e2a
Delimit rendered HTML output
BurdetteLamar Jul 26, 2022
6bb2224
Delimit rendered HTML output
BurdetteLamar Jul 27, 2022
4ae7a98
Delimit rendered HTML output
BurdetteLamar Jul 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
68 changes: 55 additions & 13 deletions doc/rdoc/markup_reference.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,29 @@
#
# = \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:
#
# - 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 <tt>:nodoc:</tt>, <tt>:doc:</tt>, and <tt>:notnew</tt>.
# - \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]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# - The Ruby code itself.
# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code]
# - The Ruby code itself;
# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code].

#
# == Markup in Comments
#
Expand Down Expand Up @@ -75,14 +88,16 @@
# #
# # 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
# documentation from the command-line.
#
# You'll love it.
#
# <<<<<<
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't BLOCKQUOTE better?

Suggested change
# >>> 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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rendered using BLOCKQUOTE: image

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @nobu. I was hoping for suggested better delimitation. I'm not sure that all markup will be honored inside a blockquote, but I'll look into it.

Another idea I had was to put Rendered HTML, then the HTML preceded and followed by horizontal rules. That becomes a problem when I need to show a rendered HR. but maybe that's a small price to pay.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see that list items, HR, and verbatim text (including code blocks) survive in a blockquote. Don't know what else does, or not. I'll go ahead and switch over.

#
# A paragraph may contain nested blocks, including:
#
# - Verbatim text blocks.
Expand Down Expand Up @@ -112,7 +127,7 @@
# #
# # This is not verbatim text.
#
# Rendered HTML:
# >>> Rendered HTML >>>
#
# This is not verbatim text.
#
Expand All @@ -123,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 <em>code block</em>,
Expand All @@ -134,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.
#
Expand Down Expand Up @@ -179,7 +211,7 @@
# # * Yet another.
# # - Last one.
#
# Rendered HTML:
# >>> Rendered HTML >>>
#
# - An item.
# - Another.
Expand All @@ -189,6 +221,8 @@
# * Yet another.
# - Last one.
#
# <<<<<<
#
# ===== Numbered Lists
#
# A numbered list item begins with digits and a period.
Expand All @@ -205,7 +239,7 @@
# # 1. Yet another.
# # 1000. Last one.
#
# Rendered HTML:
# >>> Rendered HTML >>>
#
# 100. An item.
# 10. Another.
Expand All @@ -215,6 +249,8 @@
# 1. Yet another.
# 1000. Last one.
#
# <<<<<<
#
# ===== Lettered Lists
#
# A numbered list item begins with a letters and a period.
Expand All @@ -231,14 +267,16 @@
# # x. Yet another.
# # a. Last one.
#
# Rendered HTML:
# >>> Rendered HTML >>>
#
# z. An item.
# y. Another.
#
# x. Yet another.
# a. Last one.
#
# <<<<<<
#
# ===== Labeled Lists
#
# A labeled list item begins with one of:
Expand All @@ -256,7 +294,7 @@
# # [bar baz] Yet another.
# # bam:: Last one.
#
# Rendered HTML:
# >>> Rendered HTML >>>
#
# [foo] An item.
# bat:: Another.
Expand All @@ -266,6 +304,8 @@
# [bar baz] Yet another.
# bam:: Last one.
#
# <<<<<<
#
# ===== Blocks Nested in Lists
#
# A list item may contain nested blocks, including:
Expand Down Expand Up @@ -312,7 +352,7 @@
# #
# # ---
#
# Rendered HTML:
# >>> Rendered HTML >>>
#
# ------
# Stuff between.
Expand All @@ -323,6 +363,8 @@
#
# ---
#
# <<<<<<
#
# ==== Directives
#
# ===== Directives for Allowing or Suppressing Documentation
Expand Down