= RDoc Markup Reference

This document is the comprehensive reference for RDoc's +rdoc+ markup format.
It covers all markup syntax, directives, and formatting options available.

For Ruby-specific features that require actual code (like cross-reference targets
and directives that only work in Ruby comments), see RDoc::Example.

== Anchor Links

RDoc generates GitHub-style anchors for headings.  The anchor is the heading
text converted to lowercase with spaces replaced by hyphens and special
characters removed.

You can link to headings using Markdown-style syntax:

- {Link to Headings}[#headings]
- {Link to Paragraphs}[#paragraphs]
- {Link to Verbatim Text Blocks}[#verbatim-text-blocks]

== About the Examples

- Examples in this reference show RDoc markup syntax.
- An example that shows rendered HTML output displays that output in a blockquote:

  >>>
    Some rendered output

== Markup Sources

The sources of markup documentation vary according to the file type:

- <tt>.rb</tt> (Ruby code file):

  - Markup may be found in Ruby comments:
    A comment that immediately precedes the definition
    of a class, module, method, alias, constant, or attribute
    becomes the documentation for that defined object.
  - A markup 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 below.

  - Documentation may be derived from the Ruby code itself;
    see Derived Documentation below.

- <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> (markup 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.

Note that all of the above applies to RDoc +markup+-formatted documentation:

- A C- or Ruby-coded file may contain <tt>markdown</tt>-formatted documentation,
  though that format must be declared (because the default is +markup+).
- A markdown (<tt>.md</tt>) file contains only <tt>markdown</tt>-formatted documentation.

== Blocks

It's convenient to think of an RDoc document as a sequence of _blocks_
of various types:

- {Paragraph}[rdoc-ref:rdoc@Paragraphs]: an ordinary paragraph.
- {Verbatim text block}[rdoc-ref:rdoc@Verbatim+Text+Blocks]: a block of text to be rendered literally.
- {Code block}[rdoc-ref:rdoc@Code+Blocks]: a verbatim text block containing Ruby code,
  to be rendered with code highlighting.
- {Block quote}[rdoc-ref:rdoc@Block+Quotes]: a longish quoted passage, to be rendered with indentation
  instead of quote marks.
- {List}[rdoc-ref:rdoc@Lists]: items for a bullet list, numbered list, lettered list, or labeled list.
- {Heading}[rdoc-ref:rdoc@Headings]: a heading.
- {Horizontal rule}[rdoc-ref:rdoc@Horizontal+Rules]: a line across the rendered page.
- {Directive}[rdoc-ref:rdoc@Directives]: various special directions for the rendering.
- {Text Markup}[rdoc-ref:rdoc@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@Verbatim+Text+Blocks].
- {Code blocks}[rdoc-ref:rdoc@Code+Blocks].
- {Block quotes}[rdoc-ref:rdoc@Block+Quotes].
- {Lists}[rdoc-ref:rdoc@Lists].
- {Headings}[rdoc-ref:rdoc@Headings].
- {Horizontal rules}[rdoc-ref:rdoc@Horizontal+Rules].
- {Text Markup}[rdoc-ref:rdoc@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}[rdoc-ref:rdoc@Block+Quotes].
- {Paragraphs}[rdoc-ref:rdoc@Paragraphs].
- {Verbatim text blocks}[rdoc-ref:rdoc@Verbatim+Text+Blocks].
- {Code blocks}[rdoc-ref:rdoc@Code+Blocks].
- {Lists}[rdoc-ref:rdoc@Lists].
- {Headings}[rdoc-ref:rdoc@Headings].
- {Horizontal rules}[rdoc-ref:rdoc@Horizontal+Rules].
- {Text Markup}[rdoc-ref:rdoc@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}[rdoc-ref:rdoc@Lists] of any type.
- {Paragraphs}[rdoc-ref:rdoc@Paragraphs].
- {Verbatim text blocks}[rdoc-ref:rdoc@Verbatim+Text+Blocks].
- {Code blocks}[rdoc-ref:rdoc@Code+Blocks].
- {Block quotes}[rdoc-ref:rdoc@Block+Quotes].
- {Headings}[rdoc-ref:rdoc@Headings].
- {Horizontal rules}[rdoc-ref:rdoc@Horizontal+Rules].
- {Text Markup}[rdoc-ref:rdoc@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. An item spanning
     multiple lines.

  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.

You should not use headings beyond level 3, as it becomes difficult
for the reader to track the multiple layers of nesting.

Examples:

  = Section 1
  == Section 1.1
  === Section 1.1.1
  === Section 1.1.2
  == Section 1.2
  = Section 2
  ============Still a Heading (Level 6)
  \== Not a Heading

A heading may contain only one type of nested block:

- {Text Markup}[rdoc-ref:rdoc@Text+Markup].

==== Heading Examples

= Heading level 1

Above is a level one heading.

== Heading level 2

Above is a level two heading.

=== Heading level 3

Above is a level three heading.

==== Heading level 4

Above is a level four heading.

===== Heading level 5

Above is a level five heading.

====== Heading level 6

Above is a level six heading.

=== 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;
  takes optional argument +all+ (<tt>:nodoc: all</tt>).
- Specifies that the defined object should not be documented.

For a method definition in C code, 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>cannot work</em>
because there is no "implementation" place for a constant.

With argument +all+ (<tt>:nodoc: all</tt>),
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>

- 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.

Aliased as <tt>:not_new:</tt> and <tt>:not-new:</tt>.

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:</tt>

- Appears on a line by itself; takes argument +format+ (<tt>:markup: format</tt>).
- Specifies the format for the RDoc input;
  argument +format+ is one of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.

=== 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 RDoc::Example#call_seq_example for a demonstration.

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:</tt>

- Appears on a line by itself; takes argument +arg_names+ (<tt>:args: arg_names</tt>).
- Specifies the arguments to be reported in the HTML,
  overriding the actual arguments in the code.
  See RDoc::Example#args_example for a demonstration.

Aliased as <tt>:arg:</tt>.

==== <tt>:yields:</tt>

- Appears on a line by itself; takes argument +arg_names+ (<tt>:yields: arg_names</tt>).
- Specifies the yield arguments to be reported in the HTML,
  overriding the actual yield in the code.
  See RDoc::Example#yields_example for a demonstration.

Aliased as <tt>:yield:</tt>.

=== 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:</tt>

- Appears on a line by itself; takes argument +section_title+ (<tt>:section: section_title</tt>).
- Specifies that following methods are to be grouped into the section
  with the given +section_title+,
  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:</tt>

- Appears on a line by itself; takes argument +section_title+ (<tt>:category: section_title</tt>).
- 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:</tt>

- Appears on a line by itself; takes argument +filepath+ (<tt>:include: filepath</tt>).
- 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}[rdoc-ref:rdoc@Typeface+Markup]: italic, bold, monofont, strikethrough.
- {Character conversions}[rdoc-ref:rdoc@Character+Conversions]: copyright, trademark, certain punctuation.
- {Links}[rdoc-ref:rdoc@Links].
- {Escapes}[rdoc-ref:rdoc@Escaping+Text]: marking text as "not markup."

=== Typeface Markup

Typeface markup can specify that text is to be rendered
as italic, bold, monofont, or strikethrough.

Typeface markup may contain only one type of nested block:

- More typeface markup:
  {italic}[rdoc-ref:rdoc@Italic], {bold}[rdoc-ref:rdoc@Bold], {monofont}[rdoc-ref:rdoc@Monofont],
  {strikethrough}[rdoc-ref:rdoc@Strikethrough].

==== 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 passage containing *bold* and +monofont+.</i>

Rendered HTML:
>>>
  <i>Italicized words</i> in a paragraph.

  <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.

Rendered HTML:
>>>
  _Italic_ in a paragraph.

==== Bold

Text may be marked as bold via HTML tag <tt><b></tt>.

Example input:

  <b>Bold words</b> in a paragraph.

  <b>Bold passage containing _italics_ and +monofont+.</b>

Rendered HTML:

>>>
  <b>Bold words</b> in a paragraph.

  <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.

Rendered HTML:

>>>
  *Bold* in a paragraph.

==== 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 stylings are disabled: _italics_ and *bold*.</tt>

Rendered HTML:

>>>
  <tt>Monofont words</tt> in a paragraph.

  <tt>Monofont stylings are disabled: _italics_ and *bold*.</tt>

A single word may be made monofont by a shorthand:
prefixed and suffixed plus-signs or backticks.

Example input:

  +Monofont+ in a paragraph.

  `Monofont` in a paragraph.

Rendered HTML:

>>>
  +Monofont+ in a paragraph.

  `Monofont` in a paragraph.

Note: The shorthand (<tt>+...+</tt> and <tt>`...`</tt>) only works for simple content
containing word characters, colons, periods, slashes, brackets, and hyphens.
Content containing HTML tags or other markup delimiters will not be matched.
For complex content, use the HTML tags <tt><tt></tt> or <tt><code></tt> instead:

  <tt>+literal_plus+</tt> shows: +literal_plus+

  <tt>`literal_backtick`</tt> shows: `literal_backtick`

  <tt><code>content</code></tt> shows: <code>content</code>

==== Strikethrough

Text may be marked as strikethrough via HTML tag <tt><del></tt> or <tt><s></tt>.

Example input:

  <del>Strikethrough words</del> in a paragraph.

  <del>Deleted passage containing _italics_ and *bold*.</del>

Rendered HTML:

>>>
  <del>Strikethrough words</del> in a paragraph.

  <del>Deleted passage containing _italics_ and *bold*.</del>

=== 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 Links

- On-page: <tt>RDoc::Example::ExampleClass</tt> links to RDoc::Example::ExampleClass.
- Off-page: <tt>RDoc::Alias</tt> links to RDoc::Alias.

Note: When marking up code (such as class, module,
constant, and method) as "<tt>+code+</tt>" (for interoperability
with other Markdown parsers mainly), any word that refers to a known
code object, and is marked up entirely and separately as "monofont",
is also converted to a link.

- <tt>+RDoc+</tt> links to +RDoc+.

=== Module Links

- On-page: <tt>RDoc::Example::ExampleModule</tt> links to RDoc::Example::ExampleModule.
- Off-page: <tt>RDoc</tt> links to RDoc.

=== Constant Links

- On-page: <tt>RDoc::Example::EXAMPLE_CONSTANT</tt> links to RDoc::Example::EXAMPLE_CONSTANT.
- Off-page: <tt>RDoc::Text::MARKUP_FORMAT</tt> links to RDoc::Text::MARKUP_FORMAT.

=== Singleton Method Links

- On-page: <tt>RDoc::Example::singleton_method_example</tt> links to RDoc::Example::singleton_method_example.
- 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 Links

- On-page: <tt>#instance_method_example</tt> links to #instance_method_example
  (when in the same class context).
- Off-page: <tt>RDoc::Alias#html_name</tt> links to RDoc::Alias#html_name.

See the Note and Pro Tip immediately above.

=== Attribute Links

- Off-page: <tt>RDoc::Alias#name</tt> links to RDoc::Alias#name.

=== Alias Links

- Off-page: <tt>RDoc::Alias#new_name</tt> links to RDoc::Alias#new_name.

=== Protocol Links

[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 +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 Links

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 Links

See Directives for Organizing Documentation above.

- 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> generates Alias[rdoc-ref:RDoc::Alias].
- Module: <tt>RDoc[rdoc-ref:RDoc]</tt> generates RDoc[rdoc-ref:RDoc].
- Method: <tt>foo[rdoc-ref:RDoc::Example#instance_method_example]</tt>
  generates foo[rdoc-ref:RDoc::Example#instance_method_example].
- Constant: <tt>bar[rdoc-ref:RDoc::Example::EXAMPLE_CONSTANT]</tt>
  generates bar[rdoc-ref:RDoc::Example::EXAMPLE_CONSTANT].
- File: <tt>README[rdoc-ref:README.md]</tt> generates README[rdoc-ref:README.md].

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> generates 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 +EXAMPLE_CONSTANT+ on this page:

- <tt>{EXAMPLE_CONSTANT}[rdoc-label:EXAMPLE_CONSTANT]</tt>

==== 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_md.html</tt> links to link:README_md.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:

  - <b>Bold text with unescaped nested _italic_</b>.
  - <b>Bold text with escaped nested \_italic_</b>.
  - <b>Bold text with an escape character \</b>.

Rendered HTML:

>>>
  This list is about escapes; it contains:

  - <b>Bold text with unescaped nested _italic_</b>.
  - <b>Bold text with escaped nested \_italic_</b>.
  - <b>Bold text with an escape character \ </b>.

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.

== Derived Documentation

RDoc can automatically derive documentation from Ruby code.
For demonstrations, see RDoc::Example.

=== Class

By default, RDoc documents:

- Class name.
- Parent class.
- Included modules.
- Singleton methods.
- Instance methods.
- Aliases.
- Constants.
- Attributes.

=== Module

By default, RDoc documents:

- Module name.
- Included modules.
- Singleton methods.
- Instance methods.
- Aliases.
- Constants.
- Attributes.

=== Method

By default, RDoc documents:

- Method name.
- Arguments.
- Yielded values.

See RDoc::Example#derived_docs_example.

=== Alias

By default, RDoc documents:

- Alias name.
- Aliased name.

See RDoc::Example#aliased_method.

=== Constant

By default, RDoc documents:

- Constant name.

See RDoc::Example::EXAMPLE_CONSTANT.

=== Attribute

By default, RDoc documents:

- Attribute name.
- Attribute type (<tt>[R]</tt>, <tt>[W]</tt>, or <tt>[RW]</tt>)

See RDoc::Example#example_attribute.
