ruby-changes:72682
From: Peter <ko1@a...>
Date: Tue, 26 Jul 2022 05:29:30 +0900 (JST)
Subject: [ruby-changes:72682] ba098fa151 (master): Sync RDoc
https://git.ruby-lang.org/ruby.git/commit/?id=ba098fa151 From ba098fa151bd842215d4840107b57fc0253c7ecf Mon Sep 17 00:00:00 2001 From: Peter Zhu <peter@p...> Date: Mon, 25 Jul 2022 15:51:08 -0400 Subject: Sync RDoc --- doc/rdoc/markup_reference.rb | 916 +++++++++++++++++++++++++++++++++++++++++++ lib/rdoc/rdoc.gemspec | 5 - 2 files changed, 916 insertions(+), 5 deletions(-) create mode 100644 doc/rdoc/markup_reference.rb diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb new file mode 100644 index 0000000000..74594e5483 --- /dev/null +++ b/doc/rdoc/markup_reference.rb @@ -0,0 +1,916 @@ https://github.com/ruby/ruby/blob/trunk/doc/rdoc/markup_reference.rb#L1 +require 'rdoc' + +# \Class \RDoc::MarkupReference exists only to provide a suitable home +# for a reference document for \RDoc markup. +# +# All objects defined in this class -- classes, modules, methods, aliases, +# attributes, and constants -- are solely for illustrating \RDoc markup, +# and have no other legitimate use. +# +# = \RDoc Markup Reference +# +# [Note] +# +# 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). +# - The Ruby code itself. +# +# == Markup in Comments +# +# A single-line or multi-line comment that immediately precedes +# the definition of a class, module, method, alias, constant, or attribute +# becomes the documentation for that defined object. +# +# (\RDoc ignores other such comments that do not precede definitions.) +# +# === Margins +# +# In a multi-line comment, +# \RDoc looks for the comment's natural left margin, +# which becomes the <em>base margin</em> for the comment +# and is the initial <em>current margin</em> for for the comment. +# +# The current margin can change, and does so, for example in a list. +# +# === 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]. +# - {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. +# +# ==== Paragraphs +# +# A paragraph consists of one or more non-empty lines of ordinary text, +# each beginning at the current margin. +# +# Note: Here, <em>ordinary text</em> means text that is <em>not identified</em> +# by indentation, or by unusual initial or embedded characters. +# See below. +# +# Paragraphs are separated by one or more empty lines. +# +# Example input: +# +# # \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: +# +# - Verbatim text blocks. +# - Code blocks. +# - Lists of any type. +# +# ==== Verbatim Text Blocks +# +# Text indented farther than the current margin becomes a <em>verbatim text block</em> +# (or a code block, described next). +# In the rendered HTML, such text: +# +# - Is indented. +# - Has a contrasting background color. +# +# The verbatim text block ends at the first line beginning at the current margin. +# +# Example input: +# +# # This is not verbatim text. +# # +# # 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. +# +# Rendered HTML: +# +# This is not verbatim text. +# +# 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. +# ==== Code Blocks +# +# A special case of verbatim text is the <em>code block</em>, +# which is merely verbatim text that \RDoc recognizes as Ruby code: +# +# In the rendered HTML, the code block: +# +# - Is indented. +# - Has a contrasting background color. +# - Has syntax highlighting. +# +# Example: +# +# 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. +# +# ==== Lists +# +# Each type of list item is marked by a special beginning: +# +# - Bullet list item: Begins with a hyphen or asterisk. +# - Numbered list item: Begins with digits and a period. +# - Lettered list item: Begins with an alphabetic character and a period. +# - Labeled list item: Begins with one of: +# - Square-bracketed text. +# - A word followed by two colons. +# +# A list begins with a list item and continues, even across blank lines, +# as long as list items of the same type are found at the same indentation level. +# +# A new list resets the current margin inward. +# Additional lines of text aligned at that margin +# are part of the continuing list item. +# +# A list item may be continued on additional lines that are aligned +# with the first line. See examples below. +# +# ===== Bullet Lists +# +# A bullet list item begins with a hyphen or asterisk. +# +# Example input: +# +# # - 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 +# +# A numbered list item begins with digits and a period. +# +# The items are automatically re-numbered. +# +# Example input: +# +# # 100. An item. +# # 10. Another. +# # 1. An item spanning +# # multiple lines. +# # +# # 1. Yet another. +# # 1000. Last one. +# +# Rendered HTML: +# +# 100. An item. +# 10. Another. +# 1. An item spanning +# multiple lines. +# +# 1. Yet another. +# 1000. Last one. +# +# ===== Lettered Lists +# +# A numbered list item begins with a letters and a period. +# +# The items are automatically "re-lettered." +# +# Example input: +# +# # z. An item. +# # y. Another. +# # x. An item spanning +# # multiple lines. +# # +# # x. Yet another. +# # a. Last one. +# +# Rendered HTML: +# +# z. An item. +# y. Another. +# +# x. Yet another. +# a. Last one. +# +# ===== Labeled Lists +# +# A labeled list item begins with one of: +# +# - Square-bracketed text: the label and text are on two lines. +# - A word followed by two colons: the label and text are on the same line. +# +# Example input: +# +# # [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 +# +# A list item may contain nested blocks, including: +# +# - Paragraphs. +# - Verbatim text blocks. +# - Code blocks. +# - Other lists of any type. +# +# ==== Headings +# +# A heading begins with up to six equal-signs, followed by heading text. +# Whitespace between those and the heading text is optional. +# +# Examples: +# +# # = Section 1 +# # == Section 1.1 +# # === Section 1.1.1 +# # === Section 1.1.2 +# # == Section 1.2 +# # = Section 2 +# # = Foo +# # == Bar +# # === Baz +# # ==== Bam +# # ===== Bat +# # ====== Bad +# # ============Still a Heading (Level 6) +# # \== Not a Heading +# +# ==== Horizontal Rules +# +# A horizontal rule begins with three or more hyphens. +# +# Example input: +# +# # ------ +# # Stuff between. +# # +# # \--- Not a horizontal rule. +# # +# # -- Also not a horizontal rule. +# # +# # --- +# +# Rendered HTML: +# +# ------ +# Stuff between. +# +# \--- Not a horizontal rule. +# +# -- Also not a horizontal rule. +# +# --- +# +# === Text Markup +# +# Text in a paragraph, list item (any type), or heading +# may have markup formatting. +# +# ==== Italic +# +# A single word may be italicized by prefixed and suffixed underscores. +# +# Examples: +# +# # _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 +# +# Any text may be italicized via HTML tag +i+ or +em+. +# +# Examples: +# +# # <i>Two words</i> in paragraph. +# # - <i>Two words</i> in bullet list item. +# # 1. <i>Two words</i> in numbered list item. +# # a. <i>Two words</i> in lettered list item. +# # [<i>Two words</i>] <i>Two words</i> in labeled list item. +# # ====== <i>Two words</i> in heading +# +# ==== Bold +# +# A single word may be made bold by prefixed and suffixed asterisks. +# +# Examples: +# +# # *Word* in paragraph. +# # - *Word* in bullet list item. +# # 1. *Word* in numbered list item. +# # a. *Word* in lettered list item. +# # [*word*] (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/