1 reStructuredText标记规范 ¶

Author:	eonwen
Contact:	eonwen@hotmail.com

注解

本文档为技术规范细节，而非教程或入门。如果你第一次接触 reStructuredText，请先阅读 ReStructuredText介绍和 ReStructuredText快速开始用户手册。

reStructuredText 是使用简单直观结构来展示文档结构的纯文本。这些结构无论是原生状态还是处理后的形式都相当易于阅读。这篇文档本身就是一个reStructuredText的例子(原生的，如果你阅读的是文本文件；或处理后的，如果你阅读的是一个HTML文档)。reStructuredText解析器是 Docutils 的一个组件。

简单的隐式标记用于展示特殊的结果，如段落标题、无序列表和强调。使用的标记尽可能小且不显眼。reStructuredText基本语法中不常用的结构和扩展可能会更显眼或使用显式标记。

reStructuredText适用于任何长度的文档，从非常小的(如行内程序文档片段 – Python文档字符串)到非常大的(本文档)。

第一节通过例子展示了reStructuredText标记的语法快速概览。完整的规范可以在语法细节章节看到。

文本块 (其中的标记不被处理)用于展示本文档的示例，其以纯文本的形式来说明标记。

Contents

1 reStructuredText标记规范
- 1.1 语法快速概述
- 1.2 语法细节
  - 1.2.1 空格
    - 1.2.1.1 空行
    - 1.2.1.2 缩进
  - 1.2.2 转义机制
  - 1.2.3 引用名称
  - 1.2.4 文档结构
    - 1.2.4.1 文档
    - 1.2.4.2 章节
    - 1.2.4.3 过渡
  - 1.2.5 正文元素
    - 1.2.5.1 段落
    - 1.2.5.2 无序列表
    - 1.2.5.3 有序列表
    - 1.2.5.4 定义列表
    - 1.2.5.5 字段列表
      - 1.2.5.5.1 目录字段
      - 1.2.5.5.2 RCS关键字
    - 1.2.5.6 选项列表
    - 1.2.5.7 文本块
      - 1.2.5.7.1 缩进文本块
      - 1.2.5.7.2 引用文本块
    - 1.2.5.8 行块
    - 1.2.5.9 引用块
    - 1.2.5.10 测试文档块
    - 1.2.5.11 表格
      - 1.2.5.11.1 网格表格
      - 1.2.5.11.2 简单表格
    - 1.2.5.12 显式标记块
  - 1.2.6 隐式超链接目标
  - 1.2.7 行内标记
  - 1.2.8 单位
    - 1.2.8.1 长度单位
    - 1.2.8.2 百分数单位
- 1.3 错误处理

1.1 语法快速概述 ¶

reStructuredText文档由正文或块级元素组成，可以使用章节的方式来组织。章节表现为标题风格（下划线和可选的上划线）。章节包含正文元素及/或子标题。某些正文元素包含其他元素，如列表包含列表项，列表项包含段落及其他正文元素。其他的，如段落包含文本和行内标记元素。

这是正文元素的例子：

段落 (和行内标记 ):

段落包含文本，还可能包含行内标记: *强调* 、 **特别强调** 、 `解释文本` 、 ``行内文本`` 、 独立超链接(http://www.python.org)、扩展超链接(Python_)、内部交叉引用(example_)、脚注引用([1]_)、引文引用([CIT2002]_)、替代引用(|example|)和 _`行内内部目标`.

段落使用空行分隔，左对齐。

五种类型的列表:

无序列表:

- 这是无序列表

- 序号可以是"* + -"

有序列表:

这是一个有序列表

序号可以是任何数字、字母或罗马数字

定义列表:

是什么
      定义列表关联一个术语到一个定义
如何
      术语是一个一行句子，定义是一个或多个段落或正文元素，使用缩进联系到术语

字段列表:

:是什么: 字段列表映射字段名到字段体，如数据库记录。它们通常是扩展语法的一部分
:怎么样: 字段标记是一个冒号，字段名，另一个冒号

选项列表，用于列出命令行选项:

-a            命令行选项"a"
-b file       选项可以有参数和描述
--long        选项也可以长
--input=file  长选项也可以有参数
/v            DOS/VMS风格的选项也行

选项与描述之间需要至少两个空格

文本块:

文本块可以是缩进或段落最后的行前缀块（表现为两个冒号"::"）::

    if literal_block:
      text = 'is left as-is'
      spaces_and_linebreaks = 'are preserved'
      markup_processing = None

引用块:

引用快包括缩进的正文元素：

  Tis theory, that is mine, is mine.

  -- Anne Elk (Miss)

测试文档块::

>>> print 'Python专用用例；以">>>"'
Python专用用例；以">>>"
>>> print '(cut and pasted from interactive Python sessions)'
(cut and pasted from interactive Python sessions)

表格有两种语法:

网格表格：完整的，但复杂、冗长:

+------------------------+------------+----------+
| Header row, column 1   | Header 2   | Header 3 |
+========================+============+==========+
| body row 1, column 1   | column 2   | column 3 |
+------------------------+------------+----------+
| body row 2             | Cells may span        |
+------------------------+-----------------------+

简单表格：简单且紧凑，但有限制:

====================  ==========  ==========
Header row, column 1  Header 2    Header 3
====================  ==========  ==========
body row 1, column 1  column 2    column 3
body row 2            Cells may span columns
====================  ======================

显式标记块都是以一个显式块标记，两个点和一个空格:

脚注:

.. [1] 个脚注包含正文元素、最少3个空格的一致缩进

引文:

.. [CIT2002] 似脚注，除了标签是文本

超链接目标:

.. _Python: http://www.python.org

.. _example:

上面的"_example"指向这一段

指令:
```
.. image:: mylogo.png
```
替代定义:
```
.. |symbol here| image:: symbol.png
```

注释:

.. 注释以两个点和一个空格开始。可以接除了脚注/引文、超谅解、指令或替代定义之外的任何东西。

1.2 语法细节 ¶

下面的描述列出了”文档树元素”(文档树元素名称、XML DTD通用标识符)所对应的语法结构。想查看元素层次结构的细节，请阅读 Docutils文档树和 Docutils通用DTD XML文档类型定义。

1.2.1 空格 ¶

议使用空格进行缩进，但tab也可以使用。tab会转换为空格。tab会停在每个第八列。

其他空白字符（form feeds [chr(12)] and vertical tabs [chr(11)]）会在处理前转为单个空格。

1.2.1.1 空行 ¶

空行用于分隔段落和其他元素。除了在文本块（所有的空格被保留）中之外，多个连续的空行相当于一个空行。当标记使元素分离不明确时，空行会被忽略。文档的第一行会被当做其之前有一个空行，文档的最后一行会被当做其之后有一个空行。

1.2.1.2 缩进 ¶

缩进是用来表示引用块、定义（在定义列表项中）和本地嵌套内容的唯一重要标示:

列表项内容（列表项多行内容和一个列表项中多个正文元素包括嵌套列表）
文本块的内容
显式标记块的内容

任何文本的缩进少于当前级别，会结束当前级别的缩进

因为所有的缩进都是重要的标志，因此缩进的级别应当一致。例如，缩进是引用块的唯一标记：

这是一个顶级段落。

该段落属于一级引用块。

一级引用块的第二段。

一个引用块内的多级缩进会导致复杂的结构：

这是一个顶级段落。

该段落属于一级引用块。

该段落属于二级引用块

另一个顶级段落

这一段属于二级引用块。

这一段属于一级引用块。上面的二级引用块在这个一级引用块里面。

当一个段落或其他结构有不止一行文本，行应该左对齐:

这是一个段落。段落各行
左对齐。

    这个段落有问题。行
没有左对齐。除了潜在的误解，还会
  由解析器生成警告和/或错误信息。

几种结构以同一个标记开始，结构体必须以缩进与标记联系。对于使用简单标记的结构(无序列表、有序列表、脚注、引文、超链接目标、指令和注释 )，正文的缩进级别由文本第一行的位置决定，与标记在同一位置。举例，无序列表体必须必子弹字符缩进至少2列:

- 这是无序列表项目的段落的第一行。
  所有行必须与这一行对齐。 [1]_

      这个缩进段落解释为一个引用块

因为其没有充分缩进，
这个段落不属于列表项。

.. [1] 这里是脚注。第二行与
   注标签对齐。".."标记
   用于决定缩进。

对于使用复杂标记( 字段列表、选项列表 )的结构，标记可能包含任意文本，标记后的第一行的缩进决定了正文的左边。举例，字段列表可能有非常长的标记（包含字段名）:

:Hello: 这个字段有一个很短的名字，因此
        对齐到第一行就行了。

:Number-of-African-swallows-required-to-carry-a-coconut: 这个
    很难将字段体对齐到第一行左边。甚至可能与标记不在同一行开
    始字段体。

1.2.2 转义机制 ¶

7位ASCII普遍适用，是有限的。不管用什么字符作标记，它们都会在文本中具有多重意义。因此，标记字符在文本中有时会出现，而不被认为是标记。任何严谨的标记系统都需要一个转义机制来重写标记字符的默认含义。我们使用与其他常用领域相同的转义字符，反斜杠。

反斜杠可以将任何非空白字符转义为字符。转义的字符表示字符本身，并阻止其在标记中扮演任何角色。反斜杠会在输出时去除。反斜杠文本用两个反斜杠表示(第一个反斜杠转义第二个，阻止其变被解释为转义角色)。

反斜杠转义空白字符会被从本文档中删除。在字符级行内标记中是允许的。

在两种上下文中反斜杠没有特殊含义：文本块和行内文本。在这些上下文中，单个的反斜杠表示反斜杠文本，无须重复。

注意：reSturcturedText规范和解析器不处理文本输入的表示或提取的问题（文本以如何和以何种形式到达解析器）。反斜杠与其他字符可能在特定的上下文中作为转义字符，其必须被合适的处理。例如，Python在字符串中使用反斜杠来转义特定字符，而不是其他的。在Python文档字符串中出现反斜杠最简单的处理方法就是使用原生文档字符串:

r"""This is a raw docstring.  Backslashes (\) are not touched."""

1.2.3 引用名称 ¶

简单引用名称是由字母和内部连字符、下划线、点、冒号和加号组成的单个单词，不能有空白或其他字符。脚注标签（脚注和脚注引用）、引文标签（引文和引文引用）、解释文本角色以及某些超链接引用使用简单引用名称语法。

引用名称使用标点符号或短语（2个或更多空格分隔的单词），被称为“短语引用”。短语引用由在反引号封闭的短语表示，并将反引号文本作为引用名称:

想要学习 `我最喜欢的编程语言`_ ?

.. _我最喜欢的编程语言: http://www.python.org

简单引用名称也可以可选的使用反引号。

引用名称是空白中立的且不区分大小写。在内部解析引用名称时：

空白会被归一(一个或多个空格、横向或纵向的tabs、新行、换行会被解释为一个空格)
大小写会被归一（所有字母被转为小写）

举例，如下超链接引用是等价的:

- `A HYPERLINK`_
- `a    hyperlink`_
- `A
  Hyperlink`_

超链接、脚注和引文对于引用名称共享相同的命名空间。引文的标签（简单引用名称）和手动编号脚注（数字）会进入相同的数据库作为其他超链接名称。这意味着一个可以被脚注引用([1]_)指向的脚注（定义为”.. [1]”）也可以被纯超链接引用 (1)指向。当然，每个类型的引用（超链接、脚注、引文）可能会以不同的方式处理和渲染。应该注意避免引用名称混淆。

1.2.4 文档结构 ¶

1.2.4.1 文档 ¶

文档树元素：文档

解析过的reStructuredText文档的顶级元素是”文档”元素。在初始化解析之后，文档元素是一个文档片段的简单容器，包含正文元素、过渡和章节，但不包括文档标题或其他目录元素。调用解析器的代码可以选择运行一个或多个可选的post-parse transforms ，将文档片段重新组织为一个带有标题和其他可能的元数据的完整文档（作者、日期等等。详见目录字段）。

具体来说，没有办法在reStructuredText中显式的表示文档的标题和子标题。作为替代，一个长的顶级章节标题(见下面的章节 )可以作为文档标题。类似的，紧跟在”文档标题”之后的长的二级章节标题，可以作为文档的子标题。其他所有章节会提升一到两级。详见：文档标题转换。

1.2.4.2 章节 ¶

文档树元素：章节、标题

章节通过其标题识别，在标题文本下使用下划线进行标记或下划线和匹配的上划线。下划线/上划线是单个重复的标点字符，从左边第一列开始最少到与文档标题右边对齐。具体来说，一个下划线/上划线字符可以是任何非字母打印7位ASCII字符 [1] 。当使用上划线时，上划线的长度与使用的字符必须与下划线相同。可以有任意数字级别的章节标题，但某些输出格式可能有限制（HTML只有6级标题）。

[1]	下面是有效的章节标题装饰字符: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { \| } ~ 有一些字符比其他字符更适用，建议使用它们: = - ` : . ' " ~ ^ _ * + #

相比强加一个固定数字和顺序的章节标题装饰风格，其执行的顺序是碰到每个标题的先后顺序。碰到的第一种类型是最外层标题（如HTML H1），第二种类型则成为子标题，第三种将成为子子标题，以此类推。

下面是章节标题样式的例子:

========
章节标题
========

--------
章节标题
--------

章节标题
========

章节标题
--------

章节标题
````````

章节标题
''''''''

章节标题
........

章节标题
~~~~~~~~

章节标题
********

章节标题
++++++++

章节标题
^^^^^^^^

当一个标题同时有上下划线，标题文本可以插入，类似上述前两个例子。这只是为了美观而非必要的。只有下划线的标题文本不可以插入。

标题后的空行是可选的。到下一个标题的所有文本块或更高级别会包含在章节中（或子章节，等等）。

所有章节标题样式不需要使用，也不需要使用任何特定的段落标题样式。然而，一个文档使用的章节标题必须是一致的：一旦建立了标题样式的层次结构，章节必须使用该层次结构。

每个章节标题会自动生成指向章节的超链接。超链接的文本（即引用名称）与章节标题一致。详见隐式超链接目标。

章节可以包含正文元素、过渡和嵌套的章节。

1.2.4.3 过渡 ¶

文档元素：过渡

取代小标题，段落之间的额外空间或类型装饰符可用来标记文本分隔或主题或重点的改变。

(The Chicago Manual of Style, 14th edition, section 1.80)

过渡常见于小说，作为一个跨越一行或多行的间隙，有或没有类似于一行星号的类型装饰符。过渡分隔其他正文元素。过渡不应开始或结束一个章节或文档，两个过渡也不应该直接相邻。

过渡标记的语法是一排至少4个重复的标点符号。该语法与章节标题下划线一样。过渡标记前后需要空行:

段落

----------

段落

不像章节标题下划线，章节标题不需要体系结构。建议使用同一种风格。

处理系统可以以任何其希望的方式在输出中渲染过渡。如，HTML中的<hr>输出是一种明显的选择。

1.2.5 正文元素 ¶

1.2.5.1 段落 ¶

文档树元素：段落

段落包含没有任何标记指向其他正文元素的左对齐文本块。使用空行分隔段落及其他正文元素。段落可以包含行内标记。

语法图:

+------------------------------+
| 段落                         |
|                              |
+------------------------------+

+------------------------------+
| 段落                         |
|                              |
+------------------------------+

1.2.5.2 无序列表 ¶

文档树元素：无序列表、列表项

以一个 “*”, “+”, “-“开头，后面根一个空格的文本块是一个无序列表项。列表项正文必须与bullet缩进左对齐。文本紧接在bullet分隔符之后。例如:

- 这是第一个无序列表项。上面的空行是必须的。两个列表项
  之间的空行（如这一段下面的）是可选的。

- 这是列表第二项的第一个段落

  这是列表第二项的第二个段落。
  这一段上面的空行是必须的。段落的左边与上一个段落对其
  所有的缩进与无序符号对齐。

  - 这是一个子列表。无序符号与上一行的左边对其。
    子列表是一个新的列表，因此要求上下都有空行。

- 这是主列表的第三项

这个段落不是列表的一部分。

下面是一些错误的无序列表格式的例子:

- 第一行没问题
列表项与段落之间需要空行(警告)

- 下面一行看似一个新的子列表，但实际上不是:
  - 这是一个连续的段落而非子列表（因为没有空行）
    这一行缩进也不对。
  - 可能会生成警告。

语法图:

+------+-----------------------+
| "- " | list item             |
+------| (body elements)+      |
       +-----------------------+

1.2.5.3 有序列表 ¶

文档树元素：有序列表、列表项

有序列表与无序列表类似，但是用序号而非圆点。序号包含有序成员和格式，之后跟着空格。以下有序序列可以识别:

任意数字：1 2 3 ... (无上限)
大写字母：A B C ... Z
小写字母：a b c ... z
大写罗马数字：I II III IV ... MMMMCMXCIX(4999)
小写罗马数字：i ii iii iv ... mmmmcmxcix(4999)

另外，自动编号符”#”可以用于自动编号列表。自动编号列表可以以显示的编号开始设置序列。完整的自动有序列表使用以1开始的任意数字(自动有序列表为 Docutils 0.3.8新增)

以下格式可以识别：

以点为后缀：”1.” “A.” “a.” “I.” “i.”
以括号包围：”(1)” “(A)” “(a)” “(I)” “(i)”
以右括号为后缀：”1)” “A)” “a)” “I)” “i)”

解析一个有序列表时碰到下列情况，会开始一个新列表：

碰到与当前列表序号的类型和格式不一致的序号（如，”1.”和”a.”分属两个列表）
序号不在序列内有序（如，”1”、”3”产生连个独立的列表）

建议使用1 (“1”, “A”, “a”, “I”, or “i”)作为第一个列表项的序号。当然以其他的数字开始也会被识别，但输出格式可能不支持。任何不以传统的1开始的列表都会生成一个一级[info]系统信息。

使用罗马数字的列表必须以”I/i”或一个多字符值如”II”或”XV”开始。任何其他单字符罗马数字（”V”, “X”, “L”, “C”, “D”, “M”）会被解释为一个字母而非罗马数字。同样，使用字母开始的列表不能使用”I/i”，因为其会被识别为罗马数字1。

有序列表项的第二行会被验证。这会阻止原始段落被解释为列表项。例如，下面的文本会被解释为原始的段落:

A. Einstein was a really
smart dude.

但段落仅包含一行必然含糊不清。这段文本被解析为一个有序列表:

A. Einstein was a really smart dude.

如果一个单行段落以序号(“A.”, “1.”, “(b)”, “I)”, 等等)开始，第一个字符需要转义，以便其被解析为一个段落:

\A. Einstein was a really smart dude.

嵌套的有序列表的例子:

1. Item 1 initial text.

   a) Item 1a.
   b) Item 1b.

2. a) Item 2a.
   b) Item 2b.

语法图:

+-------+----------------------+
| "1. " | list item            |
+-------| (body elements)+     |
        +----------------------+

1.2.5.4 定义列表 ¶

文档树元素：定义列表、定义列表项、术语、分类器、定义

每个定义列表项包含一个术语、可选的分类器和一个定义i。术语是一个简单的一行单词或句子。可选的分类器与术语在同一行，跟在它后面。每个分类器跟在一个行内”:”(空格冒号空格)之后。定义是一个块通，过缩进与术语联系，可以包含多个段落和其他正文元素。术语与定义块之间不允许有空格（这区分了定义列表与引用块）。定义列表第一行之前和最后一行之后需要空行，中间的列表项是否空行是可选的。例如:

术语 1
    定义 1.

术语 2
    定义 2, 段落 1.

    定义 2, 段落 2.

术语 3 : 分类器
    定义 3.

术语 4 : 分类器 1 : 分类器 2
    定义 4.

行内标记在术语行被解析，在分类器分隔符(”:”)被识别之前。分隔符仅在出现在任何行内标记之外时被识别。

定义列表可用于多种用途，包括:

作为一个字典或术语表。术语是单词本身，分类细可用于根据用途分类术语（动词、名词等等），定义跟在后面。
用于描述程序变量。术语是变量名，分类器用于区分变量类型（字符串、整形等等），定义描述变量在程序中的用法。定义列表的该用途支持分类器语法 Grouch ，一种描述和执行Python对象约束的系统。

语法图:

+----------------------------+
| term [ " : " classifier ]* |
+--+-------------------------+--+
   | definition                 |
   | (body elements)+           |
   +----------------------------+

1.2.5.5 字段列表 ¶

文档树元素: 字段列表、字段、字段名、字段正文

字段列表作为扩展语法的一部分被使用，如指令的选项或等待进一步处理的类数据库记录。它们也被用于两列类列表结构类似于数据库记录（标签和数据对）。reStructuredText应用可以在特定上下文中识别字段名和变形字段或字段正文。例如，阅读下面的目录字段或指令中的 “图片“和”元” 指令 .

字段列表会映射字段名到字段正文，仿照 RFC822 头。一个字段名可以包含任何字符，但字段名中的冒号(”:”)必须使用反斜杠转义。行内标记被解析为字段名。在进一步处理或传输时，字段名大小写敏感。字段名. 字段名与一个单独的冒号前后缀一起构成字段标记。字段表及之后跟空格和字段正文。字段正文可以包含多个正文元素，缩进到字段标记处。字段名标记之后的第一行决定字段正文的缩进。如:

:Date: 2001-08-16
:Version: 1
:Authors: - Me
          - Myself
          - I
:Indentation: 因为字段标记可能很长，字段正文的第二行
   及随后的行不必与第一行对齐，但必须缩进到字段名标记
   处，且它们应当互相对齐。
:Parameter i: integer

一个多单词字段名中的单个词的解释是应用程序。该应用程序可以为该字段名指定一个语法。例如，第二个单词及其后面的单词可以被视为“参数”，引用短语可以被视为一个单一的参数，并可能会增加直接支持“键=值”的语法。

除了潜在的可能导致误解的标准 RFC822 标题不能用于这种构造是因为它们模糊不清。以一个单词后面跟一个冒号开始一行是一种通用的书写文本。然而，在定义良好的上下文如当一个字段列表总是在文档的开头（PEPS和电子邮件）时，标准RFC822头可以使用。

语法图(简化):

+--------------------+----------------------+
| ":" field name ":" | field body           |
+-------+------------+                      |
        | (body elements)+                  |
        +-----------------------------------+

1.2.5.5.1 目录字段 ¶

文档树元素: 文档信息、作者、多个作者、组织、联系方式、版本、状态、日期、版权、字段、主题

当一个字段列表是文档的第一个非注释元素时(只在文档标题之后，如果有)，它可以从字段转换为文档目录数据。这个目录数据对应一本书的封面，如标题页和版权页。

特定的注册过的字段名(见下表)会被识别并转换为对应的文档树元素，大部分会变为”docinfo”元素的子元素。对于这些字段，没有顺序要求，但它们会被重新组织以适应文档的结构。除非另有说明，每一个目录元素的字段正文只能包含一个段落。字段正文会被 RCS关键字检查和清理。任何不能识别的字段会被作为通用字段保留在docinfo元素中。

注册过的目录字段名和它们对应的文档树元素如下:

字段名 “Author”: 作者元素
“Authors”: 作者.
“Organization”: 组织.
“Contact”: 联系方式.
“Address”: 地址.
“Version”: 版本.
“Status”: 状态.
“Date”: 日期.
“Copyright”: 版权.
“Dedication”: 主题.
“Abstract”: 主题.

“Authors”字段可以包含: 一个包含作者列表（冒号或逗号分隔）的段落；或一个无序列表，其每个元素包含一个单独的段落每作者。首先检查”;”，因此”Doe, Jane; Doe, John”是可以的。如果单个饼子包含逗号，使用分号结束它: ”:Authors: Doe, Jane;”。

“Address”字段用于多行邮件地址。新行和空格会被保留。

“Dedication”和”Abstract”字段可以包含任意正文元素。每种一个。它们会称为紧跟在docinfo元素之后的使用”Dedication”或”Abstract”标题（或语言相等）的主题元素。

这个字段名到元素的映射可以替换为其他语言。详见文档信息转换实现文档。

未注册/通用字段可以包含一个或多个段落或任意正文元素。

1.2.5.5.2 RCS关键字 ¶

被解析器识别的目录字段通常会检查并清理 RCS [2] 关键字 [3] 。RCS关键字会作为”$keyword$”进入源文件，一旦存储为 RCS 或 CVS [4] ，它们会扩展为”$keyword: expansion text $”。例如，一个”Status”字段会被转换为一个”status”元素:

:Status: $keyword: expansion text $

[2]	修订控制系统（Revision Control System）。

[3]	RCS关键字处理可以关闭（未实现）。

[4]	并发版本系统（Concurrent Versions System）。CVS使用与RCS相同的关键字。

处理后，”status”元素的文本会变为简单的”扩展文本”。美元分隔符和开头的RCS关键字名会被去除。

RCS关键字仅处理目录上下文（文档标题，如果有，之后的文档中第一个非注释结构）中的字段列表。

1.2.5.6 选项列表 ¶

文档树元素: 选项列表、选项列表项、选项组、选项、选项字符串、选项参数、描述

选项列表是一个包含命令行参数和描述的两列列表，用于记录程序的选项。例如:

-a         输出全部
-b         都输出(该描述有点
           长)
-c arg     只输出参数
--long     整天输出

-p         这个选项的描述有两段
           这是第一段

           这是第二段。选项间的空行可能被
           忽略（像上面一样）或左对齐（像这里一样）

--very-long-option  一个VMS风格的选项。注意调整
                    必须的两个空格

--an-even-longer-option
           表述也可以从另一行开始

-2, --two  这个选项有两个变量

-f FILE, --file=FILE  这两个选项是同义词；
                      都有参数。

/V         一个VMS/DOS风格的选项

reStructuredText能够识别几种类型的选项:

POSIX短选项，由连字符和选项字符组成
POSIX长选项，由两个连字符和一个选项单词组成；某些系统使用一个连字符。
老式GNU风格”plus”选项，由一个plus和选项字符组成(“plus” 选项已经被废弃了，不鼓励使用它们)。
DOS/VMS选项，由一个斜杠和一个选项字符或单词组成。

请注意：DOS或Windows软件可能使用POSIX风格和DOS/VMS风格的选项。这些和其他变体有时可能会混合使用。选择上面的名字只是为了方便。

POSIX长/短选项的语法基于Python的 getopt.py 模块所提供的语法，其实现一个类似于 GNU libc getopt_long() 函数但有某些约束的选项解析器。有许多不同的选项系统，reStructuredText并非全部都支持。

尽管POSIX长选项和DOS/VMS选项单词可能允许在使用命令行时被操作系统或应用程序截取，但reStructuredText并不展示或支持这种方式。应提供完整的选项单词。

选项可以跟在一个参数占位符之后，其角色和语法应该被解释为描述文本。使用空格或等号作为选项与选项参数占位符之间的分隔符；短选项(只有”-“或”+”前缀)可能会省略分隔符。选项参数有两种形式:

字母([a-zA-Z])开头，其后紧跟字母、数字、下划线和连字符 ([a-zA-Z0-9_-])。
以尖括号(<)开始，以反尖括号(>)结束；中间可以是除此之外的任何字符。

多选项”同义词”可以列出并共享同一个描述。以逗号空格分隔。

选项和描述之间至少需要两个空格描述可以包含多个正文元素。选项标记分隔符后的第一行缩进为描述。与其他类型的列表类似，第一个列表项之后和最后一个列表项之后需要一个空行，中间的空行可选。

语法图(简化):

+----------------------------+-------------+
| option [" " argument] "  " | description |
+-------+--------------------+             |
        | (body elements)+                 |
        +----------------------------------+

1.2.5.7 文本块 ¶

文档树元素: 文本块

一个包含两个冒号(”::”)的段落表示接下来的文本由文本块组成。文本块必须缩进或引用（看下面）。文本块内的任何标记都不会被处理。它会被留下，通常适用等快字体渲染:

这是一个典型的段落，后面跟着一个缩进的文本块。

::

    for a in [5,4,3,2,1]:   # this is program code, shown as-is
        print a
    print "it's..."
    # a literal block continues until the indentation ends

这段文本恢复了缩进，其在文本块之外，因此会被当做普通的段落。

只包含”::”的段落会在输出时完全移除；不会保留空段落。

为了方便，段落结尾处的”::”可以被识别。如果后面紧跟空格，输出时两个冒号都会被移除。当文本之后紧跟”::”，其中一个冒号违背保留(如，”::”会变为”:”)。

换句话说，这些全部是等价的(请注意段落之后的冒号):

扩展形式:
```
段落:

::

    文本块
```
部分最小化形式:
```
段落: ::

    文本块
```
完全最小化形式:
```
段落::

    文本块
```

所有的空白(包括折行，但不包括对于缩进文本块最低限度的缩进)会被保留。前后各需要一个空行，但这些空行不被认为是文本块的一部分。

1.2.5.7.1 缩进文本块 ¶

缩进文本块通过缩进关联到包围的文本(每行以空白开头)。缩进文本块的每一行的最低限度的缩进会被移除。该文本块不需要是连续的，缩进文本的章节之间允许空行。该文本块以缩进的结束而结束。

语法图:

+------------------------------+
| paragraph                    |
| (ends with "::")             |
+------------------------------+
   +---------------------------+
   | indented literal block    |
   +---------------------------+

1.2.5.7.2 引用文本块 ¶

引用文本块是非缩进的连续文本块，其每一行以相同的非字母可打印7位ASCII 字符 [5] 开始。引用文本快由空行结束。引用文本快会在处理过的文档中保存。

[5]	以下是所有有效缩进字符: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { \| } ~ 注意：这与有效的章节标题装饰相同。

语法图:

+------------------------------+
| paragraph                    |
| (ends with "::")             |
+------------------------------+
+------------------------------+
| ">" per-line-quoted          |
| ">" contiguous literal block |
+------------------------------+

1.2.5.8 行块 ¶

文档树元素: 行块、行(Docutils 0.3.5新增)

行块对于地址块很有用。诗(诗歌、歌词)和无装饰列表等行结构有重要意义。行块是一组由竖线(“|”)前缀开头的行。每个竖线前缀表示一个新行，因此折行会被保留。初始缩进对于嵌套结构也很重要。支持行内标记。连续行辈包装为一个长的行，他们以一个空格代替竖线开始，左边必须对其，但不需要与上面的文字的左边对其。行块以空行结束。

这个例子展示了连续行:

| Lend us a couple of bob till Thursday.
| I'm absolutely skint.
| But I'm expecting a postal order and I can pay you back
  as soon as it comes.
| Love, Ewan.

这个例子展示了嵌套的行块，通过初始缩进表示新行:

Take it away, Eric the Orchestra Leader!

    | A one, two, a one two three four
    |
    | Half a bee, philosophically,
    |     must, *ipso facto*, half not be.
    | But half the bee has got to be,
    |     *vis a vis* its entity.  D'you see?
    |
    | But can a bee be said to be
    |     or not to be an entire bee,
    |         when half the bee is not a bee,
    |             due to some ancient injury?
    |
    | Singing...

语法图:

+------+-----------------------+
| "| " | line                  |
+------| continuation line     |
       +-----------------------+

1.2.5.9 引用块 ¶

文档树元素: 引用块、属性

一个以缩进与前面的文本关联的文本块，前面没有标记表示其为文被快或其他内容的，是引用块。里面的所有标记会被连续处理（对于正文元素和行内标记):

这是一个原始段落，介绍引用快。

    "It is my business to know things.  That is my trade."

    -- Sherlock Holmes

引用块可能以一个属性结束: 以”–”或”—”开始的文本块。如果属性包含多行，第二行及随后的行必须对其。

如果以属性结束，可能连续出现多个引用快。

非缩进段落

引用块 1.

—属性 1

引用块 2.

空注释用于显式的结束前面可能会被当做一个引用块的结构:

* 列表项

..

    引用块 3.

空注释也可以用来分隔引用快:

    引用块 4.

..

    引用块 5.

前后均需要空行，但空行不是引用块的一部分。

语法图:

+------------------------------+
| (current level of            |
| indentation)                 |
+------------------------------+
   +---------------------------+
   | block quote               |
   | (body elements)+          |
   |                           |
   | -- attribution text       |
   |    (optional)             |
   +---------------------------+

1.2.5.11 表格 ¶

文档树元素: 表格、表格组、行、表头、表正文、行、入口

ReStructuredText提供两种语法来处理表格单元: 网格表格和简单表格。

类似于其他正文元素，表格前后都需要空行。表格应当与前面的文本块左对齐。如果缩进，表格会被当做引用块的一部分。

一旦隔离，每个表格单元会被当做一个小型文档；顶部和底部的单元格分界线作为分隔空行。每个单元格包含0个或多个正文元素。单元格的内容可以包含左和/或右边距，其会在处理时删除。

1.2.5.11.1 网格表格 ¶

网格表格通过类网格”ASCII art”提供一个完整的表格表示。网格表格允许任意单元格内容（正文元素），及跨行和列。但网格表格难以生成，特别是对于简单数据集合来说。 Emacs表格模式是一个Emacs中允许简单编辑网格表格的工具。查看简单表格以获取一个简单（但有限制）的表示。

网格表格通过字符”-“、”=”、”|”和”+”被描述为一个视觉网格。连字符(“-”)被用于行行(行分隔符)。等号(“=”)可以用作分隔可选的标题行与表格正文(不被 Emacs表格模式支持)。竖线 (“|”)用于竖行(列分隔符)。加号用于横行与竖行的交叉。例如

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

必须小心避免不需要的一起活动。例如，下面的表格第2行包含一个横跨三列的单元格，从第二列到第四列

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        |                                  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

如果在单元格文本中使用了竖线，它会起到非缩进效果（如果与列分界线对其）:

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        | Use the command ``ls | more``.   |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

有几种解决办法。所有都是只需要将连续的单元格分开。一个可行的办法是变换文本，在前面添加额外的空格:

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        |  Use the command ``ls | more``.  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

另一个可行的办法是在其中添加额外的行:

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        | Use the command ``ls | more``.   |
|              |                                  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

1.2.5.11.2 简单表格 ¶

简单表格为简单数据集合提供一个简洁、容易的输入但有限的行导向的表格表示方式。单元格的内容是典型的单个段落，但任意的征文元素可以表现在大部分单元格中。简单表格允许跨行的行（除了第一列之外的所有行）和跨列，但不允许跨行。参见上面的网格表格以获取完整的表格表现形式。

简单表格被描述为使用由等号”=”组成的横向边框和连字符”-“组成。等号 (“=”)用于表格的顶部和底部边框，也用于分隔可选的标题行。连字符 (“-”)通过下划线合并列，用于在一个单行中展示列，可以可选的用于显式和/或可视的分隔行。

一个简单表格以由等号组成的顶部边框和以空格（建议两个或以上）作为每列的分界线开始。无论何种跨度，顶边必须完全描述整个表格列。表格必须有至少两列（以便将其与章节标题区分开）。顶边之后可以是标题行，且最后一个可选标题行以’=’作为下划线及以空格作为列分界线。标题行分隔符下不可以有空行；其会被解释为表格的底边。表格的底边分界线由’=’下划线组成，也以空格分隔列边界。例如，下面是一个正向表格，一个三列表格，包含一个标题行和4个正文行:

=====  =====  =======
  A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

下划线’-‘可以用于展示列跨度。列跨度下华夏必须完整(必须覆盖所有列)并与已建立的列边界对其。包含列跨度下划线的文本行不能包含任何其他文本。一个列跨度下划线仅对其紧邻的上一行起效。例如，下面是一个在标题中包含列跨度的表格:

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

每一行文本必须在列边界处包含空格，处理被列跨度合并的单元格。每行文本开启一个新行，除非第一列有一个空行。如果是那样，该行文本被解析为连续行。因此，新行( 非连续行)的第一列单元格单元格必须包含某些文本；空单元格会导致误解(但看看下面的tip)。同时，该机制限制第一列单元格为单行文本。如果不能接受这些限制，请使用网格表格。

小技巧

要在第一列没有文本需要处理输出的简单表格中开启一个新行，使用下列一种:

一个空注释(”..”)，其会在输出时忽略掉(详见注释 )
一个反斜杠转义(“\”)后面跟一个空格(见上面的转义机制 )

下划线’-‘也可用于可视的分隔行，即使没有跨列。这对行里有许多行的长表格特别有用。

简单表格内允许空行。它们的表现取决于上下文。行之间的空行会被忽略。多行行中的空行能够分隔单元格中的段落或其他正文元素。

最右边的列是无限的；文本可以超出表格边界(表格边框表示)。但建议输入足够长的边界来包含整个文本。

下面的例子展示了连续行(第二行包含2航文本，第三行包含四行文本)、一个空行分隔段落（第三行第二列）、文本扩展到超出表格右边和第一列中没有文本需要处理输出的新行（第四行）:

=====  =====
col 1  col 2
=====  =====
1      Second column of row 1.
2      Second column of row 2.
       Second line of paragraph.
3      - Second column of row 3.

       - Second item in bullet
         list (row 3, column 2).
\      Row 4; column 1 will be empty.
=====  =====

1.2.5.12 显式标记块 ¶

显示标记快是一个文本块:

其第一行以”..”之后紧跟空格(显式标记开始）开始
其第二行和接下来的行（如果有）以缩进与第一行关联
以非缩进行结束

显式标记块与无序列表项相似，使用”..”作为无序符号。文本紧跟在显式标记开始分隔符缩进的正文块。最常用缩进总是会被从第二行及其后的行的正文块中删除。因此，如果第一个结构满足只有一行，且第一和第二个结构的缩进应该不一样，第一个结构应该不与显式标记开始的地方同一行。

显式标记块和其他元素之间需要空行，但显式标记块之间的空行是可选。

显式标记语法用于脚注、引文、超链接、指令、替代定义和注释。

1.2.5.12.1 脚注 ¶

文档树元素: 脚注、标签

每个脚注由一个以(”.. ”)开头的显式标记、一个左方括号、一个脚注标签、一个右方括号和一个空格组成。脚注标签可以是:

由一个或多个数字组成的完整的十进制数
一个单独的”#”(表示自动编号脚注 ),
一个”#”后紧跟一个简单的引用名称(一个自动编号标签 )，
一个单独的”*”(表示自动符号脚注 )。

脚注内容（正文元素）必须包含缩进（至少3个空格）并且左对齐。脚注的第一个正文元素一般与脚注标签在同一行中。但如果第一个元素适合单独成行，且缩进与其他元素不同，那么第一个元素必须在脚注标签下一行开始，否则无法检测到缩进的区别。

脚注可以在文档的任何位置，而非仅在末尾。在哪里及怎样处理后输出取决于处理下系统。

这是一个手动编号脚注:

.. [1] 这是正文元素

每个脚注自动生成一个指向自己的超链接目标。超链接目标名字的文本与脚注标签相同。自动编号脚注生成一个数字标签及引用名。详见隐式超链接目标。

语法图:

+-------+-------------------------+
| ".. " | "[" label "]" footnote  |
+-------+                         |
        | (body elements)+        |
        +-------------------------+

1.2.5.12.1.1 自动编号脚注 ¶

一个数字符号(“#”)可以用作脚注标签的第一个字符以便自动编号脚注或脚注引用。

第一个需要自动编号的脚注的标签为”1”，第二个为”2”，依次类推(如果没有手动编号脚注出现；详见混合手动和自动编号脚注和自动编号脚注 )。一个标签为”1”的脚注会生成一个名为”1”的隐式超链接目标，就像该标签被显式的指定了。

脚注在使用自动编号的同时还可一个显式的指定一个标签: [#label]。这些标签称为自动编号标签。自动编号标签做两件事:

在脚注上，它生成一个超链接目标，其名字为自动编号标签（不包括”#”）

它允许一个自动编号脚注被多次引用，就像是一个超链接引用。例如:

如果 [#note]_ 是第一个脚注引用，它会表示为"[1]"。我们可以将其作为[#note]_ 再次指向它并在次看到"[1]"。我们也可以将其作为note_ （一个原
始内部超链接引用）再次指向它

.. [#note] 这是标签为"note"的脚注。

编号由脚注的顺序决定，而非引用的顺序。对于没有自动编号标签 ([#]_)的脚注引用，脚注和脚注引用必须必须以相同的编号关联，但无需使用lock-step替代。如:

[#]_ 是指向脚注1的引用，[#]_ 是指向脚注2的引用

.. [#] 这是脚注 1.
.. [#] 这是脚注 2.
.. [#] 这是脚注 3.

[#]_ 这是指向脚注3的引用

如果脚注包含自动编号引用或多个引用在相近的位置生成，则必须特别小心。脚注和引用会被按照其在文档中生成的顺序记录，这与人们阅读的顺序不一定相同。

1.2.5.12.1.2 自动符号脚注 ¶

一个星号(“*”)可以用于需要自动符号生成脚注标签。星号可以是标签中的单个字符。例如:

只是一个符号脚注引用: [*]_ 。

.. [*] 这是脚注。

符号会被转变为标签指向对应的脚注和脚注引用。引用的数量必须与脚注的数量相等。一个符号脚注不可以被多次引用。

标准Docutils系统使用如下符号和脚注标记 [6]:

型号 (“*”)
dagger (HTML character entity “&dagger;”, Unicode U+02020)
double dagger (“&Dagger;”/U+02021)
章节标记 (“§”/U+000A7)
段落标记 (“¶”/U+000B6)
数字符号 (“#”)
黑桃 (“&spades;”/U+02660)
红心 (“&hearts;”/U+02665)
方片 (“&diams;”/U+02666)
梅花 (“&clubs;”/U+02663)

[6]	这个列表受到了”Note Reference Marks”符号列表（The Chicago Manual of Style, 14th edition, section 12.51.）的影响。

如果需要多余10个符号，相同的符号会被重用、双用或三用，依此类推(“**”等等)。

注解

当使用自动符号脚注时，选择输出的编码很重要。许多符号在特定的普通文本（如使用Latin-1编码的）中无法被编码。建议使用UTF-8作为输出编码。对于HTML和XML输出，可以使用 “xmlcharref替代” 输出编码错误处理程序.

1.2.5.12.1.3 混合手动和自动编号脚注 ¶

手动和自动脚注编号可能在同一个文档中使用，因此结果有时会不符合预期。手动编号优先级较高。只有未使用的脚注编号会分配给自动编号脚注。下面的例子可以展示这点:

[2]_ will be "2" (manually numbered),
[#]_ will be "3" (anonymous auto-numbered), and
[#label]_ will be "1" (labeled auto-numbered).

.. [2] 这个脚注是手动标签，因此数字被固定了。

.. [#label] 这个自动编号标签会是"1"
   它是第一个自动编号脚注，且没有其他标签为"1"的脚注存在。
   脚注的顺序用于决定数字，而非脚注引用。

.. [#] 这个脚注的标签为"3"。它是第二个自动编号脚注，但脚注
   标签"2"已经被占用了。

1.2.5.12.2 引文 ¶

引文被展示位非数字标签的脚注，如``[note]``或``[GVR2001]``。引文标签是简单的引用名称（大小写不敏感的单个单词，包含由连字符连接的字母、下划线和点，不包括空格）。引文会被独立于脚注进行渲染，如:

这是一个引文引用: [CIT2002]_.

.. [CIT2002] 这是引文。除标签文本外，它类似于脚注。

1.2.5.12.3 超链接目标 ¶

文档树元素: target

也被称为显式超链接目标 , 用于区分下面定义的隐式超链接目标。

超链接目标定义了文档内或文档外可以通过超链接引用链接的一个位置。

超链接目标可以是命名的或匿名的。命名的超链接目标包含一个以(”..”)开头的显式标记、一个下划线、引用名没有尾部下划线）、一个冒号、一个空格和一个行块:

.. _hyperlink-name: link-block

引用名称是自然空格的且大小写不敏感。详见引用名称。

匿名超链接目标包含一个以(”..”)开头的显式标记、两个个下划线、一个冒号、一个空格和一个行块，没有引用名称:

.. __: anonymous-hyperlink-target-link-block

匿名超链接有一个替代语法，包括两个下划线、一个空格和一个行块:

__ anonymous-hyperlink-target-link-block

详见匿名超链接。

有三种形式的超链接目标：内部、扩展和间接。

1. 内部超链接目标有空行块。它们支持允许超链接连接的文档内的结束位置。内部超链接目标指向后面跟着目标的元素。如:

    点击内部超链接会将我们带到下面的 target_ 处。

    .. _target:

    上面的超链接目标指向这一段。

内部超链接目标可以是链式的。多个临近的内部超链接目标全
部指向同一个元素::

    .. _target1:
    .. _target2:

    目标"target1"和"target2"是同义词；它们同时指向这一段。

如果元素所"指向"的是一个扩展超链接目标(其行块中有一个URI。
见#2)从扩展超链接目标传播到内部超链接目标，它们全都会"指向"
同一个URI。没必要重复一个URI。例如，下面三个超链接目标指向
同一个URI::

    .. _Python DOC-SIG mailing list archive:
    .. _archive:
    .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/

内部超链接目标的行内形式是有效的。详见 行内内部目标_ 。

扩展超链接目标的文本块内有一个绝对或相对URI或email地址。如下面的输入:
```
详见 Python_ 主页。

写给我_ 你的问题。

.. _Python: http://www.python.org
.. _写给我: jdoe@example.com
```
在处理成HTML后，超链接可能扩展为:
```
详见 <a href="http://www.python.org">Python</a> 主页。

<a href="mailto:jdoe@example.com">写给我</a> 你的问题
```
扩展超链接的URI可以在同一行开始，类似显式标记开始和目标名称或其也可以以一个紧跟在后面中间没有空行的缩进文本块开始。如果文本块有多行，它们会被连接在一起。任何空格都会被移除（空行为行包装器所允许)。下面的扩展超链接目标是等价的:
```
.. _one-liner: http://docutils.sourceforge.net/rst.html

.. _starts-on-this-line: http://
   docutils.sourceforge.net/rst.html

.. _entirely-below:
   http://docutils.
   sourceforge.net/rst.html
```
如果一个扩展超链接的目标包含下划线为其最后一个字符，下划线必须被转移以避免与间接超链接目标混淆:
```
这个 链接_ 指向一个名为``underscore_``的文件.

.. _link: underscore\_
```
可以（但不推荐）在超链接引用中直接包含URI。详见嵌套URI和别名 below.
间接超链接目标在其链接块中有一个超链接引用。在下面的例子中，目标一展示了引用，无论目标二引用是什么，目标而引用了目标三，一个内部超链接目标。实际上，这三个引用是一样的:
```
.. _one: two_
.. _two: three_
.. _three:
```
类似于文档任何位置的`超链接引用`_ ，如果在一个链接中使用了一个段落引用，其必须使用反引号封闭。类似于扩展超链接目标，间接超链接目标的链接块必须与显式标记的开始在同一行或下一行。其也可以分割多行，这样行会在变为正常时被空格连接。

例如，下面的间接超链接目标是等价的:
```
.. _one-liner: `A HYPERLINK`_
.. _entirely-below:
   `a    hyperlink`_
.. _split: `A
   Hyperlink`_
```
可以在超链接引用中直接包含别名。详见嵌套URI和别名。

如果应用名称包含任何冒号:

该短语必须使用反引号封闭:

.. _`FAQTS: Computers: Programming: Languages: Python`:
   http://python.faqts.com/

或将链接目标中的冒号转义:

.. _Chapter One\: "Tadpole Days":

It's not easy being green...

参见隐式超链接目标解决引用名称重复问题。

语法图:

+-------+----------------------+
| ".. " | "_" name ":" link    |
+-------+ block                |
        |                      |
        +----------------------+

1.2.5.12.3.1 匿名超链接 ¶

万维网联盟在他们的`为网页内容可访问性指南提供的HTML技术`_ 中建议作者应当”清楚的识别每个连接的目标”。超链接引用应当尽可能的长，但在目标中重复一个长超链接名称是繁重且容易出错的。匿名超链接就是为了方便长超链接引用设计的，同时也类似于`自动编号脚注`_ 。他们通常在短小的或单个文档中很有用。但是，该功能很可能遭到滥用，并导致纯文本不可读和/或不可维护的文档。建议慎用。

匿名`超链接引用`_ 由两个下划线指定，而不是一个:

参见`我最爱的编程语言的网站`__.

匿名目标以”.. __:”开始，不需要也不允许使用引用名称:

.. __: http://www.python.org

作为一个方便的替代，匿名目标可以只以”__”开始:

__ http://www.python.org

该引用的引用名称不用于匹配引用和目标。取而代之，文档内的匿名超链接引用和目标的顺序是有很重要的: 第一个匿名引用会连接到第一个匿名目标。文档中匿名超链接引用的个数必须与匿名目标的个数匹配。为了便于阅读，建议目标与引用在一起。小心编辑带有匿名引用的文本，添加、删除、重新组织引用需要注意对应目标的顺序。

1.2.5.12.4 指令 ¶

文档树元素: 取决于指令.

指令是reStructuredText的扩展机制，一种添加支持新结构而不用添加新的语法（指令支持额外的本地语法）的方法。所有的标准指令(那些已经在 reStructuredText解析器中实现和注册过的)在`指令`_ 文档中都有描述，它们是特定域的，在处理文档时，可能需要特定操作以使其生效。

例如，这是图片如何被定位:

.. image:: mylogo.jpeg

一个 figure (带一个标题的图片)这样定位:

.. figure:: larch.png

   The larch.

一个 admonition (注意、小心，等等)包含其他正文元素:

.. note:: 这是一个段落

   - 这是一个无序列表。

指令由以开始后跟指令类型、两个冒号、空格（一起被称为指令标记）的显式标记展示。指令类型是大小写不敏感的单个单词(字母+单个连字符、冒号、点不包括空格)。指令类型后使用两个冒号是因为:

两个冒号更有特色，且不太会被用于普通文本
两个冒号可以避免与普通的注释文本冲突:
```
.. Danger: modify at your own risk!
```
如果reStructuredText的某种实现不能识别一个指令(如，指令处理器未安装 )，会生成一个3级(error)系统信息，且整个指令块(包括指令本身)会被包含为一个文本块。因为”::”是一个自然选择。

指令块由指令标记后的指令所在的第一行所包含的任何文本和任何紧跟的缩进文本组成。指令块的解释由指令代码完成。指令块有三个逻辑部分:

指令参数
指令选项
指令内容

个别指令可以采用这些部件的任何组合。指令参数可以是文件系统路径、URL、标题文本，等等。指令选项使用字段列表表示。字段名和内容由指令指定。参数和选项必须组成一个在指令第一、二行开始的连续的块。空行表示指令内容块开始了。如果参数和/或选项被指令所使用，必须用一个空行分将他们与指令内容分隔开。 “figure”指令使用所有这三个部分:

.. figure:: larch.png
   :scale: 50

   The larch.

简单指令可以不需要内容。如果一个指令不使用内容块而后面跟着任何缩进的文本，会产生一个错误。如果一个引用块后立即是一个指令，使用空注释(见注释 )分隔它们。

在指令内容块或随后的文本块中，指令和解释文本所作的任何动作都取决于指令。详见指令。

指令是对其内容的处理，它可以被转换成一些可能与原文无关的东西。它也可能被用来作为编译指令、修改解析器的行为，如实验替代语法。目前没有解析器支持此功能。如果发现一个对编译器指令是合理的需求，它们可能会支持。

指令不会生成”指令”元素，它们只是一个”解析器结构”，在reStructuredText 以外没有任何意义。解析器会将可以识别的指令变形为文档元素。未知的指令会触发3级系统信息（错误）。

语法图:

+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block                         |
        |                               |
        +-------------------------------+

1.2.5.12.5 替代定义 ¶

文档树元素: 替代定义

替代定义由一个以(”.. ”)开始后面跟着竖线、替代文本、竖线、空格和定义块的显式标记。替代文本不能以空格开始或结束。一个替代定义块包含一个嵌套的行内兼容指令(没有开头的”.. ”)，如” 图片 “或”替代“。举例，:

The |biohazard| symbol must be used on containers used to
dispose of medical waste.

.. |biohazard| image:: biohazard.png

替代定义块直接或间接包含一个子替代引用会发生一个错误。

替代引用会在行内被处理过的定义对应的内容所替代。匹配是大小写敏感但可以宽容的，如果没有发现匹配，会尝试大小写不敏感的短语。

替代指令允许在行内文本共享强大而灵活的块级指令。它们是一种在文本内包含任意复杂行内结构并将细节保存在文本之外的方法。等价于SGML/XML的命名实例或编程语言的宏。

没有替代机制，无论何时需要具体应用新行内结构，都必须改变语法。通过与现有的指令语法结合，任何行内结构都可以使用而无需新的语法（除非可能是一个新指令)。

语法图:

+-------+-----------------------------------------------------+
| ".. " | "|" substitution text "| " directive type "::" data |
+-------+ directive block                                     |
        |                                                     |
        +-----------------------------------------------------+

下面是替代机制的一些例子。请注意，大部分嵌入指令只能在例子中使用，其尚未被实现。

对象

替代引用可以用于关联含糊的文本到一个唯一的对象识别符

例如，许多网站可能希望实现一个行内”用户”指令:

|Michael| and |Jon| are our widget-wranglers.

.. |Michael| user:: mjones
.. |Jon|     user:: jhl

根据网站的需求，这些可能用于索引文件供以后检索、以各种方式链接文本（邮件，网页，鼠标悬停JavaScript的简介和联系信息，等）或自定义文字显示（包括内联文本，包括旁边的用户名文本，链接图标图像使文字加粗或不同的颜色，等等）。

同样的目的可用于在需要经常引用具有独特标识符但具有模糊的通用名称的的一个特定类型对象的文档中。电影、唱片、书籍、照片、法庭案件和法律都是可能的。例如:

|The Transparent Society| offers a fascinating alternate view
on privacy issues.

.. |The Transparent Society| book:: isbn=0738201448

模块名或类名不明确和/或解释文本不能使用的上下文中的类或函数，是另一种可能:

4XSLT has the convenience method |runString|, so you don't
have to mess with DOM objects if all you want is the
transformed output.

.. |runString| function:: module=xml.xslt class=Processor

图片

图片是替代引用的一种普遍用法:

West led the |H| 3, covered by dummy's |H| Q, East's |H| K,
and trumped in hand with the |S| 2.

.. |H| image:: /images/heart.png
   :height: 11
   :width: 11
.. |S| image:: /images/spade.png
   :height: 11
   :width: 11

* |Red light| means stop.
* |Green light| means go.
* |Yellow light| means go really fast.

.. |Red light|    image:: red_light.png
.. |Green light|  image:: green_light.png
.. |Yellow light| image:: yellow_light.png

|-><-| is the official symbol of POEE_.

.. |-><-| image:: discord.png
.. _POEE: http://www.poee.org/

“图片“指令已经被实现了。

风格 [7]

替代引用可以用于将行内文本关联到一种扩展定义的表示风格:

Even |the text in Texas| is big.

.. |the text in Texas| style:: big

在某些特定输出上下文(HTML输出的CSS类名、LaTeX风格名，等等)中风格名有有意义的，其会被另一种输出格式（如纯文本）忽略。

[7]	有可能有足够的必要的“风格”机制，以保证简单的语法，如扩展到解释的文本角色的语法。简单的文本样式的替换机制是繁琐的。

模板

行内标记可能会稍后被一个模板引擎处理。如，一个 Zope 作者可能这么写:

Welcome back, |name|!

.. |name| tal:: 替代 user/getUserName

处理后，这个ZPT的输出结果可能是:

Welcome back,
<span tal:替代="user/getUserName">name</span>!

然后Zope在你某个实际用户的会话中将这个传递给某些类似于”Welcome back, David!”的东西。

替换文本

替代机制可以用于简单的宏替代。替换文本在一个或多个文档中重复多次，特别是在以后可能需要更改时，这可能是适当的。一个简短的例子是不可避免:

|RST|_ is a little annoying to type over and over, especially
when writing about |RST| itself, and spelling out the
bicapitalized word |RST| every time isn't really necessary for
|RST| source readability.

.. |RST| 替代:: reStructuredText
.. _RST: http://docutils.sourceforge.net/rst.html

注意：第一个替代引用的最后的下划线。它表示引用对应的超链接目标。

替代适用于当替换文本不能用其他行内结构表示或非常长的时候:

But still, that's nothing compared to a name like
|j2ee-cas|__.

.. |j2ee-cas| 替代::
   the Java `TM`:super: 2 Platform, Enterprise Edition Client
   Access Services
__ http://developer.java.sun.com/developer/earlyAccess/
   j2eecas/

“替代“指令已被实现.

1.2.5.12.6 注释 ¶

文档树元素: 注释

任意缩进文本可以跟在显示标记开始且会被处理为一个注释元素的后面。注释块文本不会再做处理。一个注释包含一个单独的”text blob”。取决于输出格式，注释可能被处理后的输出移除。对于注释唯一的限制是，它们与其他任何显式标记机构使用不同的语法: 替代定义、指令、脚注、引文或超链接目标。为了确保其他任何显式标记结构都能被识别，在行中只使用”..”:

.. This is a 注释
..
   _so: is this!
..
   [and] this!
..
   this:: too!
..
   |even| this:: !

一个显示标记开始，后面跟着空行且没有其他东西（除了空白）是一个 “empty 注释“。它用于结束一个前面的结构且不需要跟任何缩进文本。需要一个块引用跟在一个列表或任何缩进结构之后，在它们之间插入一个空注释即可。

语法图:

+-------+----------------------+
| ".. " | 注释                 |
+-------+ 块                   |
        |                      |
        +----------------------+

1.2.6 隐式超链接目标 ¶

隐式超链接目标由章节标题、脚注、引文生成，也可以由扩展结构生成。隐式超链接目标的行为也可能表现为显式的超链接目标 .

通过以下步骤避免了重复的隐式和显式引用名称的歧义问题：

显式超链接目标重写任何包含相同引用名称的隐式目标。隐式超链接目标会被移除，1级系统信息（info）会被插入。
重复的隐式超链接目标会被移除，1级系统信息（info）会被插入。例如，如果两个或更多章节名称相同（如文档必须的结构”Introduction”子标题），会出现重复的隐式超链接目标。
重复的显式超链接目标会被移除，2级系统信息(warning)。除了: 重复的扩展超链接目标 (表示为超链接名称和应用URI)不会混淆，也不会被移除。

系统信息会被插入目标连接被移除处。详见 PEP 258 中的”错误处理”。

解析器必须返回一个唯一超链接目标的集合。调用软件(如 Docutils )可以警告无法解决的连接，给出原因信息。

1.2.7 行内标记 ¶

在reStructuredText中，行内标记是提供给文本块中的单词或句子的。在书写的文本中使用相同的空白和标点符号用于分隔单词，就是行内标记语法结构。含有行内标记的文本不能以空白开始或结束。任意字符级行内标记都能被支持，但并不鼓励。行内标记不能嵌套。

有9个行内标记结构。5个结构使用相同的开始字符和结束字符来表示标记:

斜体: “*”
粗体: “**”
解释文本: “`”
行内文本: “``”
替代引用: “|”

三种结构使用不同的开始与结构字符:

行内内部目标: “_`”和”`”
脚注引用: “[“和”]_”
超链接引用: “`”和”`_” (句子)，或只有一个单独的”_”(单个单词)

独立超链接能被隐式的识别，且不适用额外的标记。

1.2.7.1 行内标记识别规则 ¶

行内标记开始、结束字符只要在所有条件都满足的情况下才会被识别:

行内标记开始字符必须开始一个文本块或前面紧接着
- 空白
- ASCII字符中的一个 - : / ' " < ( [ { 或
- 一个使用 Unicode category Pd (Dash)、Po (Other)、 Ps (Open)、Pi (Initial quote)或`Pf` (Final quote) [8] 的非ASCII标点符号。
行内标记开始字符必须紧跟在非空白之后
行内标记结束字符必须之后必须是非空白字符
行内标记结束字符必须结束一个文本块或后面紧接
- 空白
- ASCII字符中的一个 - . , : ; ! ? \ / ' " ) ] } > 或
- 一个使用 Unicode category Pd (Dash)、Po (Other)、 Ps (Open)、Pi (Initial quote)或`Pf` (Final quote) [8] 的非ASCII标点符号。
如果一个行内标记开始字符之前是一个ASCII字符 ' " < ( [ { ，或一个使用Unicode字符category Ps, Pi, or Pf`的字符，其之后必须是对应的 [#corresponding_quotes]_ 结束字符 `‘ ” ) ] } >`` 或categories Pe, Pf, or Pi.
行内开始、结束字符之间必须至少有个一个字符
一个没有转义的反斜杠在开始或结束字符之前会终止标记识别，除非是行内文本结束字符。详见转义机制。

[8]	(1, 2) Pi (Punctuation, Initial quote) characters are “usually closing, sometimes opening”. Pf (Punctuation, Final quote) characters are “usually closing, sometimes opening”.

[9]	对于引文，对应字符可以是任何 quotation marks in international usage

行内识别规则计划允许90%的非标记使用”*”、”`”、”_”、和”|”而无需转义。例如，下面的属于没有一个会被识别为包含行内标记的字符:

2*x a**b O(N**2) e**(x*y) f(x)*f(y) a|b file*.* (breaks 1)
2 * x a ** b (* BOM32_* ` `` _ __ | (breaks 2)
“*” ‘|’ (*) [*] {*} <*> (breaks 5)
|| (breaks 6)
__init__ __init__()

下列行内标记的例子不需要转义:

2 * x *a **b *.txt (breaks 3)
2*x a**b O(N**2) e**(x*y) f(x)*f(y) a*(1+2) (breaks 4)

其中一些可能别描述为使用行内文本，特鄙视如果它们表现为代码段。这是一个判断调用。

1.2.7.2 识别顺序 ¶

行内标记分隔符被用于多个结构，因为为了避免混淆，必须有特定的识别顺序。行内标记识别顺序如下:

星号: 粗体 (“**”) 先于斜体 (“*”)被识别。
反引号: 行内文本 (“``”)、行内内部目标 (以”_`”开头，”`”结尾)相互独立，会在短语超链接引用 (以”`”开头，”`_”结尾) 解释文本 (“`”)之前被解析。
后面的下划线: 脚注引用(“[” + label + “]_”)和简单超链接引用 (name + trailing “_”) 相互独立。
竖线: 替代引用 (“|”)会被独立识别
独立超链接最后一个被识别。

1.2.7.3 字符级行内标记 ¶

可以使用反斜扛转义，在单词内制造独立字符(见转义机制 )。反斜杠转义可以用在行内标记之后的任何文本上:

Python ``list``\s use square bracket syntax.

反斜杠会在处理文档后消失。单词”list”会作为行内文本呈现，且字母”s”会紧跟在它后面作为普通文本，中间无需空格。

行内标记之前的任意文本可以使用反斜杠空格:

Possible in *re*\ ``Structured``\ *Text*, though not encouraged.

反斜杠和空格分隔”re”、”Structured”和”Text”，并会在文档处理后消失。

警告

不建议在字符级行内标记使用反斜杠转义。这种用法是丑陋的，对未经处理的文档的可读性是有害的。请只在确实需要的地方使用该功能。

1.2.7.4 斜体 ¶

文档树元素: 斜体

开始字符，结束字符 = “*”.

以单个星号封闭的文本是斜体:

This is *emphasized text*.

1.2.7.5 粗体 ¶

文档树元素: strong.

开始字符 = 结束字符 = “**”.

被双星号封闭的文本是粗体:

这是 **粗体文本**.

强调文本通常以粗体显示。

1.2.7.6 解释文本 ¶

文档树元素: 取决于显式或隐式角色和处理

开始字符 = 结束字符 = “`”.

文史文本是这样一种文本，它意味着被关联、索引、链接、概括或不同的处理，但文本本身会被典型保留。解释文本由单反引号字符封闭:

This is `interpreted text`.

解释文本的”role”决定了文本如何被解释。角色可能会被隐式的推断(像上面，使用了 “默认角色”)或显式的表示，使用一个角色标记。角色标记由一个冒号、角色名、另一个冒号组成。角色名是一个由字母加可能存在的连字符、下划线、加号、冒号、点组成的单个单词，不能有空格或其他字符。角色标记是解释文本的前缀或后缀，取决于怎么读更合适，由作者决定:

:role:`interpreted text`

`interpreted text`:role:

解释文本允许扩展有效的行内描述标记结构。对于斜体 , 粗体 , 行内文本和超链接引用，我们可以添加”标题引用”、”索引入口”、”缩写”、”类”、”红色”、”闪烁”或任何你想要的东西。只有预制的角色能够被识别，未知角色会生成错误。标准角色的核心集合在引用解析器中实现了。详见 reStructuredText解释文本角色。角色指令可以用于定义自定义解释文本角色。另外，程序可能支持特定的角色。

1.2.7.7 行内文本 ¶

文档树元素: 文本.

开始字符 = 结束字符 = “``”.

文本被双反引号封闭会被作为行内文本:

该文本是 ``行内文本`` 的一个例子。

行内文本可以包含任何字符除了与结束字符响铃的反引号根据上述识别规则）。没有标记的解释包括转义字符的解释）会在行内文本内完成。

在行内文本中，折行不会被保留。尽管reStructuredText解析器会在输出时保留空格，处理过的文本的最后表示取决于输出格式，因此不能放心的保留空白。如果折行和/或其他空白的表现是重要的，则应该使用文本块。

行内文本为简短的代码片段很有用。例如:

正则表达式 ``[+-]?(\d+(\.\d*)?|\.\d+)`` 匹配浮点数(没有指数)。

1.2.7.8 超链接引用 ¶

文档树元素: 引用

命名的超链接引用:
- 开始字符 = “”(空字符串)，结束字符 = “_”
- 开始字符 = “`”，结束字符 = “`_”。(短语引用)
匿名超链接引用:
- 开始字符 = “” (空字符串)，结束字符 = “__”
- 开始字符 = “`”，结束字符 = “`__”。(短语引用)

超链接引用由结尾的下划线表示，除了独立超链接，其会被单独识别。下划线可以认为是一个向右的箭头。结尾的下划线指向超链接引用，开始的下划线指向超链接目标.

超链接由两部分组成。在文本正文中，有一个源链接，一个引用名和一个结尾的下划线(或匿名超链接的两个下划线):

See the Python_ home page for info.

有一个匹配的引用名称的目标链接必须存在于文档之外(详见超链接目标 )

匿名超链接不使用引用名称匹配引用和目标，其行为类似命名的超链接。

1.2.7.8.1 嵌套URI和别名 ¶

超链接引用可以直接嵌套一个目标URI(从Docutils 0.11开始)或一个尖括号内的超链接引用:

See the `Python home page <http://www.python.org>`_ for info.

This `link <Python home page_>`_ is an alias to the link above.

这等价于:

See the `Python home page`_ for info.

This link_ is an alias to the link above.

.. _Python home page: http://www.python.org
.. _link: `Python home page`_

括起来的URI前面必须有空格，且为结束字符前最后的文本。

使用一个单独的结尾下划线，引用会被命名，同样地URI会被再次引用使用两个结尾下划线，引用和目标都是你ing的，目标不能被再次引用。这是一个一次性的超链接。例如:

`RFC 2396 <http://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC
2732 <http://www.rfc-editor.org/rfc/rfc2732.txt>`__ together
define the syntax of URIs.

等价于:

`RFC 2396`__ and `RFC 2732`__ together define the syntax of URIs.

__ http://www.rfc-editor.org/rfc/rfc2396.txt
__ http://www.rfc-editor.org/rfc/rfc2732.txt

即使以一个下划线结尾，独立超链接也会被当做URI:

`__init__ <http:example.py.html#__init__>`__

如果目标URI没有被识别为独立超链接碰巧以下划线结尾，则需要对其进行转义以避免被解析为超链接引用。例如:

Use the `source <parrots.txt\_>`__.

创建一个到文件的匿名引用 parrots.txt_。

如果引用文本碰巧以尖括号文本结束，而不是一个URI或一个超链接引用，至少有一个尖括号需要被反斜杠转义或跟一个转义的空格。例如，这是三个到描述一个标签的标题的引用:

See `HTML Element: \<a>`_, `HTML Element: <b\> `_, and
`HTML Element: <c>\ `_.

引用文本会被省略，这种情况下URI会被作为引用文本重复使用。这对关联地址或文件名也是需要的引用文本的URI很有用:

See `<a_named_relative_link>`_ or `<an_anonymous_relative_link>`__
for details.

警告

该结构以牺牲一般可读性提供了对超链接简单的创作与维护。特别长的行内URI不可避免的打断文本的自然流程。对将要以源文件阅读的文档， 强烈建议 使用独立的块级超链接目标。嵌套的URI结构最适合只在处理后的格式下阅读的文档。

1.2.7.9 行内内部目标 ¶

文档树元素: target.

开始字符 = “_`”，结束字符 = “`”.

行内内部目标等价于显式内部超链接目标，但可能呈现在运行的文本恶逆。该语法以一个下华夏和一个反引号开始，后面跟一个超链接名或短语，以一个反引号结束。行内内部目标不可以匿名。

例如，下面的段落包含一个名为”Norwegian Blue”的超链接目标:

Oh yes, the _`Norwegian Blue`.  What's, um, what's wrong with it?

参见隐式超链接目标以解决引用名重复的问题。

1.2.7.10 脚注引用 ¶

文档树元素: 脚注引用

开始字符 = “[“，结束字符 = “]_”.

每个脚注引用包含一个方括号标签后面跟一个下划线。脚注标签是以下之一:

一个或多个数字
一个单独的”#”( 自动编号脚注的符号),
一个”#”后面跟着简单引用名称(一个自动编号标签),
一个单独的”*”( 自动符号脚注的符号).

例如:

Please RTFM [1]_.

.. [1] Read The Fine Manual

1.2.7.11 引文引用 ¶

文档树元素: 引文引用

开始字符 = “[“，结束字符 = “]_”.

每个引文引用由一个方括号标签后面跟一个下划线组成。引用标签是简单的引用名称 (大小写不明感的单个单词，由字母加内部连字符、下划线、点组成，不能有空白)。

例如:

Here is a citation reference: [CIT2002]_.

见引文。

1.2.7.12 替代引用 ¶

文档树元素: 替代引用、引用

开始字符 = “|”，结束字符 = “|” (可选的接”_”或”__”).

竖线用于阔气替代引用文本。一个替代引用也可以是一个超链接引用，通过添加一个”_”(命名)或”__” (匿名)前缀，替代文本用于引用文本的命名的情况。

处理系统使用对应的处理后的内容替换替代引用中的替代定义。替代定义生成行内兼容的元素。

举例:

This is a simple |substitution reference|.  It will be 替代d by
the processing system.

This is a combination |substitution and hyperlink reference|_.  In
addition to being 替代d, the 替代ment text or element will
refer to the "substitution and hyperlink reference" target.

1.2.7.13 独立超链接 ¶

文档树元素: 引用

开始字符，结束字符 = “”(空字符串)

文本块内的URI(绝对URI [10] 或独立的email地址)被当做一个通用扩展超链接，其URI被当做链接文本。举例:

See http://www.python.org for info.

可以在HTML中组成:

See <a href="http://www.python.org">http://www.python.org</a> for
info.

可以识别两种形式的URI:

绝对URI。这由一个约束、一个冒号(”:”)和一个约束特性部分（由约束解释）组成。

约束是协议的名称，如”http”、”ftp”、”mailto”或”telnet”。约束由一个初始字母后面接字母、数字和/或”+”, “-”, ”.”组成。只有有限的约束能被识别，只有 Official IANA Registry of URI Schemes 和W3C的 Retired Index of WWW Addressing Schemes 。

资源标识符的约束特性部分可以是分层的或不透明的:
- 分层标识符以一个或两个斜线组成，可以使用斜线分隔路径的分层组件。例子是网页和FTP站点:
```
http://www.python.org

ftp://ftp.python.org/pub/python
```
- 不透明标识符不以斜线开头，例如email地址和新闻组:
```
mailto:someone@somewhere.com

news:comp.lang.python
```
使用查询、片段和%-escape顺序，URI可以变得很复杂。一个reStructuredText解析器必须能够识别任何绝对定义在 RFC2396 和 RFC2732 中的URI。
独立email地址会被当作包含一个”mailto:”约束的绝对URI。例如:
```
someone@somewhere.com
```

URI最后的标点符号不被认为是URI的一部分，除非URI由一个反尖括号(“>”)分隔。反斜线可以用在URI中以转移标记字符，特定的星号(“*”)和下划线(“_”)等URI有效字符(详见转义机制 )。

[10]	统一资源标识符。URI是URL(统一资源定位符)的一种通用形式 URI语法详见 RFC2396 和 RFC2732.

1.2.8 单位 ¶

(Docutils 0.3.10. 新增)

所有的单位由一个标准(非科学)符号正浮点数和一个单位组成，可能由一个或多个空格分隔。

只支持参考手册中显式的提到的单位。

1.2.8.1 长度单位 ¶

reStructuredText解析器支持下列长度单位:

em (ems, 元素字体的高度)
ex (x-height, 字母”x”的高度)
px (像素，关联到相对于画布的分辨率)
in (inches; 1in=2.54cm)
cm (厘米; 1cm=10mm)
mm (毫米)
pt (点; 1pt=1/72in)
pc (活字; 1pc=12pt)

该集合对应 CSS长度单位.

(列表和解释取自 http://www.htmlhelp.com/reference/css/unit.html#length)

以下是所有有效的长度值: “1.5em”, “20 mm”, ”.5in”.

不带单位的长度值会被自动添加(如，px with html4css1, pt with latex2e)。详见用户文档。

1.2.8.2 百分数单位 ¶

百分数值有一个百分数符(“%”)作为单位。百分数值与其他值关联，取决于其所处的上下文。

1.3 错误处理 ¶

文档树元素: 系统信息、problematic

标记错误根据 PEP 258 规范处理。