class RDoc::MarkupReference

类 RDoc::MarkupReference 的存在仅仅是为了为 RDoc 标记的参考文档提供一个合适的场所。

在此类中定义的所有对象——类、模块、方法、别名、属性和常量——仅用于说明 RDoc 标记，没有其他合法用途。

关于示例 ↑

RDoc 来源 ↑

RDoc 文档的来源根据文件类型而异

RDoc 文档

块 ↑

可以将 RDoc 文档视为各种类型（链接中的详细信息）的块序列，这很方便

关于块

段落 ↑

段落由一行或多行从当前边距开始的普通文本组成。

注意：此处，普通文本是指未通过缩进或不寻常的初始或嵌入字符识别的文本。请参见下文。

段落之间用一个或多个空行分隔。

示例输入

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

呈现的 HTML

RDoc 为 Ruby 项目生成 HTML 和命令行文档。RDoc 包括 rdoc 和 ri 工具，用于从命令行生成和显示文档。

你会喜欢它的。

段落可能包含嵌套块，包括

逐字文本块 ↑

缩进程度大于当前边距的文本将成为逐字文本块（或接下来描述的代码块）。在呈现的 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.

呈现的 HTML

这不是逐字文本。

This is verbatim text.
  Whitespace is honored.     # See?
    Whitespace is honored.     # See?

This is still the same verbatim text block.

这不是逐字文本。

逐字文本块不得包含任何类型的嵌套块 – 它是逐字的。

代码块 ↑

逐字文本的一个特例是代码块，它只是 RDoc 识别为 Ruby 代码的逐字文本

在呈现的 HTML 中，代码块

示例输入

Consider this method:

  def foo(name = '', value = 0)
    @name = name      # Whitespace is still honored.
    @value = value
  end

呈现的 HTML

考虑以下方法

def foo(name = '', value = 0)
  @name = name      # Whitespace is still honored.
  @value = value
end

专业提示：如果缩进的 Ruby 代码未被突出显示，则可能包含语法错误。

代码块不得包含任何类型的嵌套块 – 它是逐字的。

块引用 ↑

您可以使用字符 >>>（未缩进），后跟缩进的文本，将文本视为块引用

示例输入

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.

呈现的 HTML

这是一个块引用

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.

请注意，与逐字文本不同，不会保留单个换行符，但是双换行符会在块引用中开始一个新段落。

块引用可能包含嵌套块，包括

列表 ↑

每种类型的列表项都标有特殊的开头

列表以列表项开头，并继续，即使跨越空白行，只要在相同的缩进级别找到相同类型的列表项。

新列表将当前边距向内重置。与该边距对齐的其他文本行是连续列表项的一部分。

列表项可以在与第一行对齐的其他行上继续。请参见下面的示例。

列表项可能包含嵌套块，包括

项目符号列表 ↑

项目符号列表项以连字符或星号开头。

示例输入

- An item.
- Another.
- An item spanning
  multiple lines.

* Yet another.
- Last one.

呈现的 HTML

  • 一个项目。

  • 另一个。

  • 跨越多行的项目。

  • 还有另一个。

  • 最后一个。

编号列表 ↑

编号列表项以数字和句点开头。

项目会自动重新编号。

示例输入

100. An item.
10. Another.
1. An item spanning
   multiple lines.

1. Yet another.
1000. Last one.

呈现的 HTML

  1. 一个项目。

  2. 另一个。

  3. 跨越多行的项目。

  4. 还有另一个。

  5. 最后一个。

字母列表 ↑

字母列表项以字母和句点开头。

项目会自动“重新字母化”。

示例输入

z. An item.
y. Another.
x. An item spanning
   multiple lines.

x. Yet another.
a. Last one.

呈现的 HTML

  1. 一个项目。

  2. 另一个。

  3. 还有另一个。

  4. 最后一个。

标签列表 ↑

标签列表项以以下之一开头

示例输入

[foo] An item.
bat:: Another.
[bag] An item spanning
      multiple lines.

[bar baz] Yet another.
bam:: Last one.

呈现的 HTML

foo

一个项目。

bat

另一个。

bag

跨越多行的项目。

bar baz

还有另一个。

bam

最后一个。

标题 ↑

标题以最多六个等号开头，后跟标题文本。它们与标题文本之间的空格是可选的。

示例

= 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

标题可能仅包含一种类型的嵌套块

水平线 ↑

水平线由一行带有三个或多个连字符且没有其他内容的行组成。

示例输入

---
--- Not a horizontal rule.

-- Also not a horizontal rule.
---

呈现的 HTML

— 这不是水平线。

– 这也不是水平线。

指令 ↑

用于允许或阻止文档生成的指令 ↑

对于 Ruby 代码，但对于其他 RDoc 源，有 :stopdoc: 和 :startdoc: 的简写形式

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

对于 C 代码，任何指令 :startdoc:、:stopdoc: 和 :enddoc: 都可能出现在独立的注释中

/* :startdoc: */
/* :stopdoc: */
/* :enddoc: */
用于指定 RDoc 源格式的指令 ↑
用于 Method 文档的指令 ↑
用于组织文档的指令 ↑

默认情况下，RDoc 将以下内容分组

您可以使用指令来修改这些行为。

用于包含 File 的指令 ↑

文本标记 ↑

文本标记是影响 HTML 渲染的元文本

字体样式标记 ↑

字体样式标记可以指定文本以斜体、粗体或等宽字体渲染。

字体样式标记只能包含一种类型的嵌套块

斜体 ↑

可以通过 HTML 标签 <i> 或 <em> 将文本标记为斜体。

示例输入

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

呈现的 HTML

段落中的斜体单词。

块引用中的斜体单词.

  • 列表项中的斜体单词。

标题中的斜体单词 ↑

包含粗体和等宽字体的斜体段落。

可以使用简写形式将单个单词斜体化：前缀和后缀下划线。

示例输入

_Italic_ in a paragraph.

>>>
  _Italic_ in a block quote.

- _Italic_ in a list item.

====== _Italic_ in a Heading

呈现的 HTML

段落中的斜体。

块引用中的斜体。

  • 列表项中的斜体。

标题中的斜体 ↑
粗体 ↑

可以通过 HTML 标签 <b> 将文本标记为粗体。

示例输入

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

呈现的 HTML

段落中的粗体单词。

块引用中的粗体单词。

  • 列表项中的粗体单词。

标题中的粗体单词 ↑

包含斜体和等宽字体的粗体段落。

可以使用简写形式将单个单词加粗：前缀和后缀星号。

示例输入

*Bold* in a paragraph.

>>>
  *Bold* in a block quote.

- *Bold* in a list item.

===== *Bold* in a Heading

呈现的 HTML

段落中的粗体。

块引用中的粗体。

  • 列表项中的粗体。

标题中的粗体 ↑
等宽字体 ↑

可以通过 HTML 标签 <tt> 或 <code> 将文本标记为等宽字体（有时称为“打字机字体”）。

示例输入

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

呈现的 HTML

段落中的等宽字体单词。

块引用中的等宽字体单词。

  • 列表项中的等宽字体单词。

标题中的等宽字体单词 ↑

包含斜体和粗体的等宽字体段落。

可以使用简写形式将单个单词设为等宽字体：前缀和后缀加号。

示例输入

+Monofont+ in a paragraph.

>>>
  +Monofont+ in a block quote.

- +Monofont+ in a list item.

====== +Monofont+ in a Heading

呈现的 HTML

段落中的等宽字体。

块引用中的等宽字体。

  • 列表项中的等宽字体。

标题中的等宽字体 ↑

字符转换 ↑

某些字符组合可能会转换为特殊字符；是否发生转换取决于当前编码中是否提供了特殊字符。

RDoc 文本中的某些字符串将转换为链接。可以通过在前面添加反斜杠来抑制任何此类链接。本节介绍如何链接到各种目标。

类
模块
常量

  • 页面内链接：DUMMY_CONSTANT 链接到 DUMMY_CONSTANT。

  • 页面外链接：RDoc::Text::MARKUP_FORMAT 链接到 RDoc::Text::MARKUP_FORMAT。

Singleton Method

注意：有时 RDoc 不会链接到名称仅包含特殊字符的方法。请检查您期望的链接是否实际存在。如果不存在，您需要添加一个显式链接；请参见下文。

专业提示：任何方法的链接都可以在类或模块页面左上角的字母顺序目录中找到。

实例 Method
属性
别名
协议 http

  • 链接：http://yahoo.com 链接到 yahoo.com。

协议 https

  • 链接：https://github.com 链接到 github.com。

协议 ftp
协议 mailto

  • 链接：mailto:/foo@bar.com 链接到 foo@bar.com。

协议 irc
图像文件扩展名

  • 链接：https://ruby-lang.com.cn/images/header-ruby-logo@2x.png 会被转换为内联 HTML img 标签，该标签会在 HTML 中显示图像。

    也适用于 bmp、gif、jpeg 和 jpg 文件。

    注意：仅适用于完全限定的 URL。

标题

请注意，实际标题中的空格在可链接文本中用 + 字符表示。

标点符号和其他特殊字符必须像 CGI.escape 一样进行转义。

专业提示：任何标题的链接都可以在类或模块页面左上角的字母顺序目录中找到。

节

请参阅组织文档的指令。

  • 链接：RDoc::Markup::ToHtml 的 Visitor 链接到 RDoc::Markup::ToHtml 的 Visitor。

如果一个节和一个标题共享相同的名称，则链接目标是该节。

单字文本链接

使用方括号创建单字文本链接

  • GitHub[https://github.com] 链接到 GitHub。

多字文本链接

使用方括号和花括号创建多字文本链接。

rdoc-ref 方案

如果引用的项存在，则使用 rdoc-ref: 方案的链接会链接到该项。引用的项可以是类、模块、方法、文件等。

  • 类：Alias[rdoc-ref:RDoc::Alias] 生成 RDoc::Alias。

  • 模块：RDoc[rdoc-ref:RDoc] 生成 RDoc。

  • 方法：foo[rdoc-ref:RDoc::MarkupReference#dummy_instance_method] 生成 foo。

  • 常量：bar[rdoc-ref:RDoc::MarkupReference::DUMMY_CONSTANT] 生成 bar。

  • 属性：baz[rdoc-ref:RDoc::MarkupReference#dummy_attribute] 生成 baz。

  • 别名：bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias] 生成 bad。

如果引用的项不存在，则不会生成链接，并且整个 rdoc-ref: 方括号子句将从生成的文本中删除。

  • Nosuch[rdoc-ref:RDoc::Nosuch] 生成 Nosuch。

rdoc-label 方案
简单

您可以使用此格式指定链接目标，其中第二部分引用 HTML 元素的 ID。

此链接引用此页面上的常量 DUMMY_CONSTANT

  • {DUMMY_CONSTANT}[rdoc-label:DUMMY_CONSTANT]

因此

DUMMY_CONSTANT

带有返回

您可以同时指定链接目标和一个局部标签，该标签可以用作返回链接的目标。这两个链接相互引用

  • {转到收件人}[rdoc-label:addressee:sender]

  • {返回发送者}[rdoc-label:sender:addressee]

因此

转到收件人

一些文本。

返回发送者

link: 方案
rdoc-image 方案

使用 rdoc-image 方案显示同时也是链接的图像

# {rdoc-image:path/to/image}[link_target]

  • 链接：{rdoc-image:https://ruby-lang.com.cn/images/header-ruby-logo@2x.png}[https://ruby-lang.com.cn] 将图像 https://ruby-lang.com.cn/images/header-ruby-logo@2x.png 显示为指向 https://ruby-lang.com.cn 的链接。

相对路径作为目标也有效

  • 链接：{rdoc-image:https://ruby-lang.com.cn/images/header-ruby-logo@2x.png}[./Alias.html] 链接到 ./Alias.html

转义文本 ↑

否则会被解释为标记的文本可以“转义”，使其不被解释为标记；转义字符是反斜杠 ('\')。

在逐字文本块或代码块中，转义字符始终保留

示例输入

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

呈现的 HTML

这不是逐字文本。

This is verbatim text, with an escape character \.

这不是代码块。

def foo
  'This is a code block with an escape character \.'
end

在字体样式标记（斜体、粗体或等宽字体）中，转义字符会被保留，除非紧跟其后的是嵌套的字体样式标记。

示例输入

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

呈现的 HTML

此列表是关于转义的；它包含

  • 带有未转义嵌套_斜体_的等宽字体文本.

  • 带有转义嵌套\_斜体\_的等宽字体文本.

  • 带有转义字符 \ 的等宽字体文本.

在其他带有文本的块中（段落、块引用、列表项、标题）

从 Ruby 代码派生的文档 ↑

类

默认情况下，RDoc 会记录

  • 类名称。

  • 父类。

  • Singleton 方法。

  • 实例方法。

  • 别名。

  • 常量。

  • 属性。

模块

默认情况下，RDoc 会记录

  • 模块名称。

  • 单例方法。

  • 实例方法。

  • 别名。

  • 常量。

  • 属性。

方法

默认情况下，RDoc 会记录

  • 方法名称。

  • 参数。

  • 产生的值。

请参阅 method。

别名

默认情况下，RDoc 会记录

  • 别名名称。

  • 别名化的名称。

请参阅 dummy_instance_alias 和 dummy_instance_method。

常量

默认情况下，RDoc 会记录

  • 常量名称。

请参阅 DUMMY_CONSTANT。

属性

默认情况下，RDoc 会记录

  • 属性名称。

  • 属性类型（[R]、[W] 或 [RW]）

请参阅 dummy_attribute。