doc/rdoc/markup_reference.rb
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.
#
# == About the Examples
#
# - Examples in this reference are Ruby code and comments;
# certain differences from other sources
# (such as C code and comments) are noted.
# - Almost all examples on this page are all RDoc-like;
# that is, they have no explicit comment markers like Ruby <tt>#</tt>
# or C <tt>/* ... */</tt>.
# - An example that shows rendered HTML output
# displays that output in a blockquote:
#
# >>>
# Some stuff
#
# == \RDoc Sources
#
# The sources of \RDoc documentation vary according to the type of file:
#
# - <tt>.rb</tt> (Ruby code file):
#
# - Markup may be found in Ruby comments:
# A comment that immediately precedes the definition
# of a Ruby class, module, method, alias, constant, or attribute
# becomes the documentation for that defined object.
# - An \RDoc directive may be found in:
#
# - A trailing comment (on the same line as code);
# see <tt>:nodoc:</tt>, <tt>:doc:</tt>, and <tt>:notnew:</tt>.
# - A single-line comment;
# see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives].
#
# - Documentation may be derived from the Ruby code itself;
# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code].
#
# - <tt>.c</tt> (C code file): markup is parsed from C comments.
# A comment that immediately precedes
# a function that implements a Ruby method,
# or otherwise immediately precedes the definition of a Ruby object,
# becomes the documentation for that object.
# - <tt>.rdoc</tt> (\RDoc markup text file) or <tt>.md</tt> (\RDoc markdown text file):
# markup is parsed from the entire file.
# The text is not associated with any code object,
# but may (depending on how the documentation is built)
# become a separate page.
#
# An <i>RDoc document</i>:
#
# - A (possibly multi-line) comment in a Ruby or C file
# that generates \RDoc documentation (as above).
# - The entire markup (<tt>.rdoc</tt>) file or markdown (<tt>.md</tt>) file
# (which is usually multi-line).
#
# === Blocks
#
# It's convenient to think of an \RDoc document 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 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 a special way.
#
# 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.
# - In a multi-line block,
# \RDoc looks for the block's natural left margin,
# which becomes the <em>base margin</em> for the block
# and is the initial <em>current margin</em> for the block.
#
# ==== 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}[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
#
# 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.
#
# 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>,
# 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 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.
#
# A code block may not contain nested blocks of any kind
# -- it's verbatim.
#
# ==== Block Quotes
#
# You can use the characters <tt>>>></tt> (unindented),
# followed by indented text, to treat the text
# as a {block quote}[https://en.wikipedia.org/wiki/Block_quotation]:
#
# 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.
# 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.
#
# Rendered HTML:
#
# >>>
# 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.
#
# 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}[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
#
# 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.
#
# A list item may contain nested blocks, including:
#
# - Other lists of any type.
# - {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
#
# 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 lettered list item begins with 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.
#
# ==== 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
#
# A heading may contain only one type of nested block:
#
# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
#
# ==== Horizontal Rules
#
# A horizontal rule consists of a line with three or more hyphens
# and nothing more.
#
# Example input:
#
# ---
# --- Not a horizontal rule.
#
# -- Also not a horizontal rule.
# ---
#
# Rendered HTML:
# >>>
# ---
# --- Not a horizontal rule.
#
# -- Also not a horizontal rule.
# ---
#
# ==== Directives
#
# ===== Directives for Allowing or Suppressing Documentation
#
# - <tt># :stopdoc:</tt>:
#
# - Appears on a line by itself.
# - Specifies that \RDoc should ignore markup
# until next <tt>:startdoc:</tt> directive or end-of-file.
#
# - <tt># :startdoc:</tt>:
#
# - Appears on a line by itself.
# - Specifies that \RDoc should resume parsing markup.
#
# - <tt># :enddoc:</tt>:
#
# - Appears on a line by itself.
# - Specifies that \RDoc should ignore markup to end-of-file
# regardless of other directives.
#
# - <tt># :nodoc:</tt>:
#
# - Appended to a line of code
# that defines a class, module, method, alias, constant, or attribute.
#
# - Specifies that the defined object should not be documented.
#
# - For a method definition in C code, it the directive must be in the comment line
# immediately preceding the definition:
#
# /* :nodoc: */
# static VALUE
# some_method(VALUE self)
# {
# return self;
# }
#
# Note that this directive has <em>no effect at all</em>
# when placed at the method declaration:
#
# /* :nodoc: */
# rb_define_method(cMyClass, "do_something", something_func, 0);
#
# The above comment is just a comment and has nothing to do with \RDoc.
# Therefore, +do_something+ method will be reported as "undocumented"
# unless that method or function is documented elsewhere.
#
# - For a constant definition in C code, this directive <em>can not work</em>
# because there is no "implementation" place for a constant.
#
# - <tt># :nodoc: all</tt>:
#
# - Appended to a line of code
# that defines a class or module.
# - Specifies that the class or module should not be documented.
# By default, however, a nested class or module _will_ be documented.
#
# - <tt># :doc:</tt>:
#
# - Appended to a line of code
# that defines a class, module, method, alias, constant, or attribute.
# - Specifies the defined object should be documented, even if it otherwise
# would not be documented.
#
# - <tt># :notnew:</tt> (aliased as <tt>:not_new:</tt> and <tt>:not-new:</tt>):
#
# - Appended to a line of code
# that defines instance method +initialize+.
# - Specifies that singleton method +new+ should not be documented.
# By default, Ruby fakes a corresponding singleton method +new+,
# which \RDoc includes in the documentation.
# Note that instance method +initialize+ is private, and so by default
# is not documented.
#
# For Ruby code, but not for other \RDoc sources,
# there is a shorthand for <tt>:stopdoc:</tt> and <tt>:startdoc:</tt>:
#
# # Documented.
# #--
# # Not documented.
# #++
# # Documented.
#
# For C code, any of directives <tt>:startdoc:</tt>, <tt>:stopdoc:</tt>,
# and <tt>:enddoc:</tt> may appear in a stand-alone comment:
#
# /* :startdoc: */
# /* :stopdoc: */
# /* :enddoc: */
#
# ===== Directive for Specifying \RDoc Source Format
#
# - <tt># :markup: _type_</tt>:
#
# - Appears on a line by itself.
# - Specifies the format for the \RDoc input;
# parameter +type+ is one of +markdown+, +rd+, +rdoc+, +tomdoc+.
#
# ===== Directives for HTML Output
#
# - <tt># :title: _text_</tt>:
#
# - Appears on a line by itself.
# - Specifies the title for the HTML output.
#
# - <tt># :main: _filename_</tt>:
# - Appears on a line by itself.
# - Specifies the HTML file to be displayed first.
#
# ===== Directives for Method Documentation
#
# - <tt># :call-seq:</tt>:
#
# - Appears on a line by itself.
# - Specifies the calling sequence to be reported in the HTML,
# overriding the actual calling sequence in the code.
# See method #call_seq_directive.
#
# Note that \RDoc can build the calling sequence for a Ruby-coded method,
# but not for other languages.
# You may want to override that by explicitly giving a <tt>:call-seq:</tt>
# directive if you want to include:
#
# - A return type, which is not automatically inferred.
# - Multiple calling sequences.
#
# For C code, the directive may appear in a stand-alone comment.
#
# - <tt># :args: _arg_names_</tt> (aliased as <tt>:arg:</tt>):
#
# - Appears on a line by itself.
# - Specifies the arguments to be reported in the HTML,
# overriding the actual arguments in the code.
# See method #args_directive.
#
# - <tt># :yields: _arg_names_</tt> (aliased as <tt>:yield:</tt>):
#
# - Appears on a line by itself.
# - Specifies the yield arguments to be reported in the HTML,
# overriding the actual yield in the code.
# See method #yields_directive.
#
# ===== Directives for Organizing Documentation
#
# By default, \RDoc groups:
#
# - Singleton methods together in alphabetical order.
# - Instance methods and their aliases together in alphabetical order.
# - Attributes and their aliases together in alphabetical order.
#
# You can use directives to modify those behaviors.
#
# - <tt># :section: _section_title_</tt>:
#
# - Appears on a line by itself.
# - Specifies that following methods are to be grouped into the section
# with the given <em>section_title</em>,
# or into the default section if no title is given.
# The directive remains in effect until another such directive is given,
# but may be temporarily overridden by directive <tt>:category:</tt>.
# See below.
#
# The comment block containing this directive:
#
# - Must be separated by a blank line from the documentation for the next item.
# - May have one or more lines preceding the directive.
# These will be removed, along with any trailing lines that match them.
# Such lines may be visually helpful.
# - Lines of text that are not so removed become the descriptive text
# for the section.
#
# Example:
#
# # ----------------------------------------
# # :section: My Section
# # This is the section that I wrote.
# # See it glisten in the noon-day sun.
# # ----------------------------------------
#
# ##
# # Comment for some_method
# def some_method
# # ...
# end
#
# You can use directive <tt>:category:</tt> to temporarily
# override the current section.
#
# - <tt># :category: _section_title_</tt>:
#
# - Appears on a line by itself.
# - Specifies that just one following method is to be included
# in the given section, or in the default section if no title is given.
# Subsequent methods are to be grouped into the current section.
#
# ===== Directive for Including a File
#
# - <tt># :include: _filepath_</tt>:
#
# - Appears on a line by itself.
# - Specifies that the contents of the given file
# are to be included at this point.
# The file content is shifted to have the same indentation as the colon
# at the start of the directive.
#
# The file is searched for in the directory containing the current file,
# and then in each of the directories given with the <tt>--include</tt>
# command-line option.
#
# For C code, the directive may appear in a stand-alone comment
#
# ==== Text Markup
#
# Text markup is metatext that affects HTML rendering:
#
# - Typeface: italic, bold, monofont.
# - Character conversions: copyright, trademark, certain punctuation.
# - Links.
# - Escapes: marking text as "not markup."
#
# ===== Typeface 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
#
# Text may be marked as italic via HTML tag <tt><i></tt> or <tt><em></tt>.
#
# Example input:
#
# <i>Italicized words</i> in a paragraph.
#
# >>>
# <i>Italicized words in a block quote</i>.
#
# - <i>Italicized words</i> in a list item.
#
# ====== <i>Italicized words</i> in a Heading
#
# <i>Italicized passage containing *bold* and +monofont+.</i>
#
# Rendered HTML:
# >>>
# <i>Italicized words</i> in a paragraph.
#
# >>>
# <i>Italicized words in a block quote</i>.
#
# - <i>Italicized words</i> in a list item.
#
# ====== <i>Italicized words</i> in a Heading
#
# <i>Italicized passage containing *bold* and +monofont+.</i>
#
# A single word may be italicized via a shorthand:
# prefixed and suffixed underscores.
#
# Example input:
#
# _Italic_ in a paragraph.
#
# >>>
# _Italic_ in a block quote.
#
# - _Italic_ in a list item.
#
# ====== _Italic_ in a Heading
#
# Rendered HTML:
# >>>
# _Italic_ in a paragraph.
#
# >>>
# _Italic_ in a block quote.
#
# - _Italic_ in a list item.
#
# ====== _Italic_ in a Heading
#
# ====== Bold
#
# Text may be marked as bold via HTML tag <tt><b></tt>.
#
# Example input:
#
# <b>Bold words</b> in a paragraph.
#
# >>>
# <b>Bold words</b> in a block quote.
#
# - <b>Bold words</b> in a list item.
#
# ====== <b>Bold words</b> in a Heading
#
# <b>Bold passage containing _italics_ and +monofont+.</b>
#
# Rendered HTML:
#
# >>>
# <b>Bold words</b> in a paragraph.
#
# >>>
# <b>Bold words</b> in a block quote.
#
# - <b>Bold words</b> in a list item.
#
# ====== <b>Bold words</b> in a Heading
#
# <b>Bold passage containing _italics_ and +monofont+.</b>
#
# A single word may be made bold via a shorthand:
# prefixed and suffixed asterisks.
#
# Example input:
#
# *Bold* in a paragraph.
#
# >>>
# *Bold* in a block quote.
#
# - *Bold* in a list item.
#
# ===== *Bold* in a Heading
#
# Rendered HTML:
#
# >>>
# *Bold* in a paragraph.
#
# >>>
# *Bold* in a block quote.
#
# - *Bold* in a list item.
#
# ===== *Bold* in a Heading
#
# ====== Monofont
#
# Text may be marked as monofont
# -- sometimes called 'typewriter font' --
# via HTML tag <tt><tt></tt> or <tt><code></tt>.
#
# Example input:
#
# <tt>Monofont words</tt> in a paragraph.
#
# >>>
# <tt>Monofont words</tt> in a block quote.
#
# - <tt>Monofont words</tt> in a list item.
#
# ====== <tt>Monofont words</tt> in heading
#
# <tt>Monofont passage containing _italics_ and *bold*.</tt>
#
# Rendered HTML:
#
# >>>
# <tt>Monofont words</tt> in a paragraph.
#
# >>>
# <tt>Monofont words</tt> in a block quote.
#
# - <tt>Monofont words</tt> in a list item.
#
# ====== <tt>Monofont words</tt> in heading
#
# <tt>Monofont passage containing _italics_ and *bold*.</tt>
#
# A single word may be made monofont by a shorthand:
# prefixed and suffixed plus-signs.
#
# Example input:
#
# +Monofont+ in a paragraph.
#
# >>>
# +Monofont+ in a block quote.
#
# - +Monofont+ in a list item.
#
# ====== +Monofont+ in a Heading
#
# Rendered HTML:
#
# >>>
# +Monofont+ in a paragraph.
#
# >>>
# +Monofont+ in a block quote.
#
# - +Monofont+ in a list item.
#
# ====== +Monofont+ in a Heading
#
# ==== Character Conversions
#
# Certain combinations of characters may be converted to special characters;
# whether the conversion occurs depends on whether the special character
# is available in the current encoding.
#
# - <tt>(c)</tt> converts to (c) (copyright character); must be lowercase.
#
# - <tt>(r)</tt> converts to (r) (registered trademark character); must be lowercase.
#
# - <tt>'foo'</tt> converts to 'foo' (smart single-quotes).
#
# - <tt>"foo"</tt> converts to "foo" (smart double-quotes).
#
# - <tt>foo ... bar</tt> converts to foo ... bar (1-character ellipsis).
#
# - <tt>foo -- bar</tt> converts to foo -- bar (1-character en-dash).
#
# - <tt>foo --- bar</tt> converts to foo --- bar (1-character em-dash).
#
# ==== Links
#
# Certain strings in \RDoc text are converted to links.
# Any such link may be suppressed by prefixing a backslash.
# This section shows how to link to various
# targets.
#
# [Class]
#
# - On-page: <tt>DummyClass</tt> links to DummyClass.
# - Off-page: <tt>RDoc::Alias</tt> links to RDoc::Alias.
#
# [Module]
#
# - On-page: <tt>DummyModule</tt> links to DummyModule.
# - Off-page: <tt>RDoc</tt> links to RDoc.
#
# [Constant]
#
# - On-page: <tt>DUMMY_CONSTANT</tt> links to DUMMY_CONSTANT.
# - Off-page: <tt>RDoc::Text::MARKUP_FORMAT</tt> links to RDoc::Text::MARKUP_FORMAT.
#
# [Singleton Method]
#
# - On-page: <tt>::dummy_singleton_method</tt> links to ::dummy_singleton_method.
# - Off-page<tt>RDoc::TokenStream::to_html</tt> links to RDoc::TokenStream::to_html.
#
# Note: Occasionally \RDoc is not linked to a method whose name
# has only special characters. Check whether the links you were expecting
# are actually there. If not, you'll need to put in an explicit link;
# see below.
#
# Pro tip: The link to any method is available in the alphabetical table of contents
# at the top left of the page for the class or module.
#
# [Instance Method]
#
# - On-page: <tt>#dummy_instance_method</tt> links to #dummy_instance_method.
# - Off-page: <tt>RDoc::Alias#html_name</tt> links to RDoc::Alias#html_name.
#
# See the Note and Pro Tip immediately above.
#
# [Attribute]
#
# - On-page: <tt>#dummy_attribute</tt> links to #dummy_attribute.
# - Off-page: <tt>RDoc::Alias#name</tt> links to RDoc::Alias#name.
#
# [Alias]
#
# - On-page: <tt>#dummy_instance_alias</tt> links to #dummy_instance_alias.
# - Off-page: <tt>RDoc::Alias#new_name</tt> links to RDoc::Alias#new_name.
#
# [Protocol +http+]
#
# - Linked: <tt>http://yahoo.com</tt> links to http://yahoo.com.
#
# [Protocol +https+]
#
# - Linked: <tt>https://github.com</tt> links to https://github.com.
#
# [Protocol +www+]
#
# - Linked: <tt>www.yahoo.com</tt> links to www.yahoo.com.
#
# [Protocol +ftp+]
#
# - Linked: <tt>ftp://nosuch.site</tt> links to ftp://nosuch.site.
#
# [Protocol +mailto+]
#
# - Linked: <tt>mailto:/foo@bar.com</tt> links to mailto://foo@bar.com.
#
# [Protocol +irc+]
#
# - link: <tt>irc://irc.freenode.net/ruby</tt> links to irc://irc.freenode.net/ruby.
#
# [Image Filename Extensions]
#
# - Link: <tt>https://www.ruby-lang.org/images/header-ruby-logo@2x.png</tt> is
# converted to an in-line HTML +img+ tag, which displays the image in the HTML:
#
# https://www.ruby-lang.org/images/header-ruby-logo@2x.png
#
# Also works for +bmp+, +gif+, +jpeg+, and +jpg+ files.
#
# Note: Works only for a fully qualified URL.
#
# [Heading]
#
# - Link: <tt>RDoc::RD@LICENSE</tt> links to RDoc::RDoc::RD@LICENSE.
#
# Note that spaces in the actual heading are represented by <tt>+</tt> characters
# in the linkable text.
#
# - Link: <tt>RDoc::Options@Saved+Options</tt>
# links to RDoc::Options@Saved+Options.
#
# Punctuation and other special characters must be escaped like CGI.escape.
#
# Pro tip: The link to any heading is available in the alphabetical table of contents
# at the top left of the page for the class or module.
#
# [Section]
#
# See {Directives for Organizing Documentation}[#class-RDoc::MarkupReference-label-Directives+for+Organizing+Documentation].
#
# - Link: <tt>RDoc::Markup::ToHtml@Visitor</tt> links to RDoc::Markup::ToHtml@Visitor.
#
# If a section and a heading share the same name, the link target is the section.
#
# [Single-Word Text Link]
#
# Use square brackets to create single-word text link:
#
# - <tt>GitHub[https://github.com]</tt> links to GitHub[https://github.com].
#
# [Multi-Word Text Link]
#
# Use square brackets and curly braces to create a multi-word text link.
#
# - <tt>{GitHub home page}[https://github.com]</tt> links to
# {GitHub home page}[https://github.com].
#
# [<tt>rdoc-ref</tt> Scheme]
#
# A link with the <tt>rdoc-ref:</tt> scheme links to the referenced item,
# if that item exists.
# The referenced item may be a class, module, method, file, etc.
#
# - Class: <tt>Alias[rdoc-ref:RDoc::Alias]</tt> links to Alias[rdoc-ref:RDoc::Alias].
# - Module: <tt>RDoc[rdoc-ref:RDoc]</tt> links to RDoc[rdoc-ref:RDoc].
# - Method: <tt>foo[rdoc-ref:RDoc::Markup::ToHtml#handle_regexp_RDOCLINK]</tt>
# links to foo[rdoc-ref:RDoc::Markup::ToHtml#handle_regexp_RDOCLINK].
# - Constant: <tt>bar[rdoc-ref:RDoc::Markup::ToHtml::LIST_TYPE_TO_HTML]</tt>
# links to bar[rdoc-ref:RDoc::Markup::ToHtml::LIST_TYPE_TO_HTML].
# - Attribute: <tt>baz[rdoc-ref:RDoc::Markup::ToHtml#code_object]</tt>
# links to baz[rdoc-ref:RDoc::Markup::ToHtml#code_object].
# - Alias: <tt>bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias]</tt> links to
# bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias].
#
# If the referenced item does not exist, no link is generated
# and entire <tt>rdoc-ref:</tt> square-bracketed clause is removed
# from the resulting text.
#
# - <tt>Nosuch[rdoc-ref:RDoc::Nosuch]</tt> is rendered as
# Nosuch[rdoc-ref:RDoc::Nosuch].
#
#
# [<tt>rdoc-label</tt> Scheme]
#
# [Simple]
#
# You can specify a link target using this form,
# where the second part cites the id of an HTML element.
#
# This link refers to the constant +DUMMY_CONSTANT+ on this page:
#
# - <tt>{DUMMY_CONSTANT}[rdoc-label:DUMMY_CONSTANT]</tt>
#
# Thus:
#
# {DUMMY_CONSTANT}[rdoc-label:DUMMY_CONSTANT]
#
# [With Return]
#
# You can specify both a link target and a local label
# that can be used as the target for a return link.
# These two links refer to each other:
#
# - <tt>{go to addressee}[rdoc-label:addressee:sender]</tt>
# - <tt>{return to sender}[rdoc-label:sender:addressee]</tt>
#
# Thus:
#
# {go to addressee}[rdoc-label:addressee:sender]
#
# Some text.
#
# {return to sender}[rdoc-label:sender:addressee]
#
# [<tt>link:</tt> Scheme]
#
# - <tt>link:README_rdoc.html</tt> links to link:README_rdoc.html.
#
# [<tt>rdoc-image</tt> Scheme]
#
# Use the <tt>rdoc-image</tt> scheme to display an image that is also a link:
#
# # {rdoc-image:path/to/image}[link_target]
#
# - Link: <tt>{rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[https://www.ruby-lang.org]</tt>
# displays image <tt>https://www.ruby-lang.org/images/header-ruby-logo@2x.png</tt>
# as a link to <tt>https://www.ruby-lang.org</tt>.
#
# {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[https://www.ruby-lang.org]
#
# A relative path as the target also works:
#
# - Link: <tt>{rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./Alias.html]</tt> links to <tt>./Alias.html</tt>
#
# {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./Alias.html]
#
# === Escaping Text
#
# Text that would otherwise be interpreted as markup
# can be "escaped," so that it is not interpreted as markup;
# the escape character is the backslash (<tt>'\\'</tt>).
#
# In a verbatim text block or a code block,
# the escape character is always preserved:
#
# Example input:
#
# This is not verbatim text.
#
# This is verbatim text, with an escape character \.
#
# This is not a code block.
#
# def foo
# 'String with an escape character.'
# end
#
# Rendered HTML:
#
# >>>
# This is not verbatim text.
#
# This is verbatim text, with an escape character \.
#
# This is not a code block.
#
# def foo
# 'This is a code block with an escape character \.'
# end
#
# In typeface markup (italic, bold, or monofont),
# an escape character is preserved unless it is immediately
# followed by nested typeface markup.
#
# Example input:
#
# This list is about escapes; it contains:
#
# - <tt>Monofont text with unescaped nested _italic_</tt>.
# - <tt>Monofont text with escaped nested \_italic_</tt>.
# - <tt>Monofont text with an escape character \</tt>.
#
# Rendered HTML:
#
# >>>
# This list is about escapes; it contains:
#
# - <tt>Monofont text with unescaped nested _italic_</tt>.
# - <tt>Monofont text with escaped nested \_italic_</tt>.
# - <tt>Monofont text with an escape character \ </tt>.
#
# In other text-bearing blocks
# (paragraphs, block quotes, list items, headings):
#
# - A single escape character immediately followed by markup
# escapes the markup.
# - A single escape character followed by whitespace is preserved.
# - A single escape character anywhere else is ignored.
# - A double escape character is rendered as a single backslash.
#
# Example input:
#
# This list is about escapes; it contains:
#
# - An unescaped class name, RDoc, that will become a link.
# - An escaped class name, \RDoc, that will not become a link.
# - An escape character followed by whitespace \ .
# - An escape character \that is ignored.
# - A double escape character \\ that is rendered
# as a single backslash.
#
# Rendered HTML:
#
# >>>
# This list is about escapes; it contains:
#
# - An unescaped class name, RDoc, that will become a link.
# - An escaped class name, \RDoc, that will not become a link.
# - An escape character followed by whitespace \ .
# - An escape character \that is ignored.
# - A double escape character \\ that is rendered
# as a single backslash.
#
# == Documentation Derived from Ruby Code
#
# [Class]
#
# By default, \RDoc documents:
#
# - \Class name.
# - Parent class.
# - Singleton methods.
# - Instance methods.
# - Aliases.
# - Constants.
# - Attributes.
#
# [Module]
#
# By default, \RDoc documents:
#
# - \Module name.
# - \Singleton methods.
# - Instance methods.
# - Aliases.
# - Constants.
# - Attributes.
#
# [Method]
#
# By default, \RDoc documents:
#
# - \Method name.
# - Arguments.
# - Yielded values.
#
# See #method.
#
# [Alias]
#
# By default, \RDoc documents:
#
# - Alias name.
# - Aliased name.
#
# See #dummy_instance_alias and #dummy_instance_method.
#
# [Constant]
#
# By default, \RDoc documents:
#
# - \Constant name.
#
# See DUMMY_CONSTANT.
#
# [Attribute]
#
# By default, \RDoc documents:
#
# - Attribute name.
# - Attribute type (<tt>[R]</tt>, <tt>[W]</tt>, or <tt>[RW]</tt>)
#
# See #dummy_attribute.
#
class RDoc::MarkupReference
# Example class.
class DummyClass; end
# Example module.
module DummyModule; end
# Example singleton method.
def self.dummy_singleton_method(foo, bar); end
# Example instance method.
def dummy_instance_method(foo, bar); end;
alias dummy_instance_alias dummy_instance_method
# Example attribute.
attr_accessor :dummy_attribute
alias dummy_attribute_alias dummy_attribute
# Example constant.
DUMMY_CONSTANT = ''
# :call-seq:
# call_seq_directive(foo, bar)
# Can be anything -> bar
# Also anything more -> baz or bat
#
# The <tt>:call-seq:</tt> directive overrides the actual calling sequence
# found in the Ruby code.
#
# - It can specify anything at all.
# - It can have multiple calling sequences.
#
# This one includes <tt>Can be anything -> foo</tt>, which is nonsense.
#
# Note that the "arrow" is two characters, hyphen and right angle-bracket,
# which is made into a single character in the HTML.
#
# Click on the calling sequence to see the code.
#
# Here is the <tt>:call-seq:</tt> directive given for the method:
#
# :call-seq:
# call_seq_directive(foo, bar)
# Can be anything -> bar
# Also anything more -> baz or bat
#
def call_seq_directive
nil
end
# The <tt>:args:</tt> directive overrides the actual arguments found in the Ruby code.
#
# Click on the calling sequence to see the code.
#
def args_directive(foo, bar) # :args: baz
nil
end
# The <tt>:yields:</tt> directive overrides the actual yield found in the Ruby code.
#
# Click on the calling sequence to see the code.
#
def yields_directive(foo, bar) # :yields: 'bat'
yield 'baz'
end
# This method is documented only by \RDoc, except for these comments.
#
# Click on the calling sequence to see the code.
#
def method(foo, bar)
yield 'baz'
end
end