class RDoc::MarkupReference

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

RDoc Sources

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

An RDoc document:

Blocks

It’s convenient to think of an RDoc document as a sequence of blocks of various types (details at the links):

About the blocks:

Paragraphs

A paragraph consists of one or more non-empty lines of ordinary text, each beginning at the current margin.

Note: Here, ordinary text means text that is not identified 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

Text indented farther than the current margin becomes a verbatim text block (or a code block, described next). In the rendered HTML, such text:

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 code block, which is merely verbatim text that RDoc recognizes as Ruby code:

In the rendered HTML, the code block:

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 >>> (unindented), followed by indented text, to treat the text as a block quote:

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:

Lists

Each type of list item is marked by a special beginning:

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:

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:

  1. An item.

  2. Another.

  3. An item spanning multiple lines.

  4. Yet another.

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

  1. An item.

  2. Another.

  3. Yet another.

  4. Last one.

Labeled Lists

A labeled list item begins with one of:

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:

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

For Ruby code, but not for other RDoc sources, there is a shorthand for :stopdoc: and :startdoc::

# Documented.
#--
# Not documented.
#++
# Documented.

For C code, any of directives :startdoc:, :stopdoc:, and :enddoc: may appear in a stand-alone comment:

/* :startdoc: */
/* :stopdoc: */
/* :enddoc: */
Directive for Specifying RDoc Source Format
Directives for HTML Output
Directives for Method Documentation
Directives for Organizing Documentation

By default, RDoc groups:

You can use directives to modify those behaviors.

Directive for Including a File

Text Markup

Text markup is metatext that affects HTML rendering:

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:

Italic

Text may be marked as italic via HTML tag <i> or <em>.

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:

Italicized words in a paragraph.

Italicized words in a block quote.

  • Italicized words in a list item.

Italicized words in a Heading

Italicized passage containing bold and monofont.

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

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:

Bold words in a paragraph.

Bold words in a block quote.

  • Bold words in a list item.

Bold words in a Heading

Bold passage containing italics and monofont.

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

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:

Monofont words in a paragraph.

Monofont words in a block quote.

  • Monofont words in a list item.

Monofont words in heading

Monofont passage containing italics and bold.

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.

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: DummyClass links to DummyClass.

  • Off-page: RDoc::Alias links to RDoc::Alias.

Module
Constant
  • On-page: DUMMY_CONSTANT links to DUMMY_CONSTANT.

  • Off-page: RDoc::Text::MARKUP_FORMAT links to RDoc::Text::MARKUP_FORMAT.

Singleton Method

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: #dummy_instance_method links to dummy_instance_method.

  • Off-page: RDoc::Alias#html_name links to RDoc::Alias#html_name.

    See the Note and Pro Tip immediately above.

Attribute
  • On-page: #dummy_attribute links to dummy_attribute.

  • Off-page: RDoc::Alias#name links to RDoc::Alias#name.

Alias
  • On-page: #dummy_instance_alias links to dummy_instance_alias.

  • Off-page: RDoc::Alias#new_name links to RDoc::Alias#new_name.

Protocol http
  • Linked: http://yahoo.com links to yahoo.com.

Protocol https
Protocol ftp
Protocol mailto
Protocol irc
Image Filename Extensions
  • Link: https://www.ruby-lang.org/images/header-ruby-logo@2x.png is converted to an in-line HTML img tag, which displays the image in the HTML:

    Also works for bmp, gif, jpeg, and jpg files.

    Note: Works only for a fully qualified URL.

Heading
  • Link: RDoc::RD@LICENSE links to LICENSE at RDoc::RDoc::RD.

Note that spaces in the actual heading are represented by + characters in the linkable text.

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.

  • Link: RDoc::Markup::ToHtml@Visitor links to Visitor at RDoc::Markup::ToHtml.

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:

  • GitHub[https://github.com] links to GitHub.

Multi-Word Text Link

Use square brackets and curly braces to create a multi-word text link.

rdoc-ref Scheme

A link with the rdoc-ref: scheme links to the referenced item, if that item exists. The referenced item may be a class, module, method, file, etc.

  • Class: Alias[rdoc-ref:RDoc::Alias] links to RDoc::Alias.

  • Module: RDoc[rdoc-ref:RDoc] links to RDoc.

  • Method: foo[rdoc-ref:RDoc::Markup::ToHtml#handle_regexp_RDOCLINK] links to foo.

  • Constant: bar[rdoc-ref:RDoc::Markup::ToHtml::LIST_TYPE_TO_HTML] links to bar.

  • Attribute: baz[rdoc-ref:RDoc::Markup::ToHtml#code_object] links to baz.

  • Alias: bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias] links to bad.

If the referenced item does not exist, no link is generated and entire rdoc-ref: square-bracketed clause is removed from the resulting text.

  • Nosuch[rdoc-ref:RDoc::Nosuch] is rendered as Nosuch.

rdoc-label 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:

  • {DUMMY_CONSTANT}[rdoc-label:DUMMY_CONSTANT]

Thus:

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:

  • {go to addressee}[rdoc-label:addressee:sender]

  • {return to sender}[rdoc-label:sender:addressee]

Thus:

go to addressee

Some text.

return to sender

link: Scheme
rdoc-image Scheme

Use the rdoc-image scheme to display an image that is also a link:

# {rdoc-image:path/to/image}[link_target]
  • Link: {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[https://www.ruby-lang.org] displays image https://www.ruby-lang.org/images/header-ruby-logo@2x.png as a link to https://www.ruby-lang.org.

A relative path as the target also works:

  • Link: {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./Alias.html] links to ./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 ('\').

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:

  • Monofont text with unescaped nested italic.

  • Monofont text with escaped nested _italic_.

  • Monofont text with an escape character \ .

In other text-bearing blocks (paragraphs, block quotes, list items, headings):

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 ([R], [W], or [RW])

See dummy_attribute.

Constants

DUMMY_CONSTANT

Example constant.

Attributes

dummy_attribute [RW]

Example attribute.

dummy_attribute_alias [RW]

Example attribute.

Public Class Methods

dummy_singleton_method (foo, bar)

Example singleton method.

# File doc/rdoc/markup_reference.rb, line 1216
def self.dummy_singleton_method(foo, bar); end

Public Instance Methods

args_directive (baz)

The :args: directive overrides the actual arguments found in the Ruby code.

Click on the calling sequence to see the code.

# File doc/rdoc/markup_reference.rb, line 1264
def args_directive(foo, bar) # :args: baz
  nil
end
call_seq_directive(foo, bar)
Can be anything → bar
Also anything more → baz or bat

The :call-seq: 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 Can be anything -> foo, 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 :call-seq: directive given for the method:

:call-seq: 
  call_seq_directive(foo, bar)
  Can be anything -> bar
  Also anything more -> baz or bat
# File doc/rdoc/markup_reference.rb, line 1256
def call_seq_directive
  nil
end
dummy_instance_alias (foo, bar)
dummy_instance_method (foo, bar)

Example instance method.

# File doc/rdoc/markup_reference.rb, line 1219
def dummy_instance_method(foo, bar); end
Also aliased as: dummy_instance_alias
method (foo, bar) { |'baz'| ... }

This method is documented only by RDoc, except for these comments.

Click on the calling sequence to see the code.

# File doc/rdoc/markup_reference.rb, line 1280
def method(foo, bar)
  yield 'baz'
end
yields_directive (foo, bar) { |'bat'| ... }

The :yields: directive overrides the actual yield found in the Ruby code.

Click on the calling sequence to see the code.

# File doc/rdoc/markup_reference.rb, line 1272
def yields_directive(foo, bar) # :yields: 'bat'
  yield 'baz'
end