文档信息
http://docutils.sourceforge.net/docs/user/rst/quickref.html
可以作为reStructuredText的作弊纸
更新于：2009-07-14 16:05:34 +0200
翻译信息
译者：venj
翻译版本：1
翻译状态：已完成
翻译版权：公有域
翻译时间：2009年11月17日
版权声明：本文档被置于公有域。
注：本文的版面用Wikitext排成，因此在格式上不可能实现和原文完全一致。我已经尽可能的做到保持原文样式，但是总是会有些偏差。因此，如果你遇到格式上不明确的地方，请参考原文。
关于标记语言的全部细节，可以在reStructuredText页面上找到。本文档意在作为一个备忘材料。
类似“（详情）”这样的链接是指向完整版的reStructuredText语言规范文档。它们都是相对链接；如果这些相对链接失效了，请参考“reStructuredText语言规范”（译者按：原来这里写的是参考reStructuredText快速参考文档，大概是作者笔误。）的主文档。
行内标记
（详情）
行内标记允许文本中的单词和词组拥有文字样式（例如倾斜和加粗）和功能（例如超链接）。
| 纯文本 | 典型结果 | 说明 |
| *强调* | 强调 | 通常被渲染成斜体字 |
| 加粗强调 | 加粗强调 | 通常被渲染成粗体字 |
| `解析文本` | （见右边的说明） | 解析文本的渲染和意义跟域或应用程序相关。它可以用作索引实体或显式描述性标记（如，程序标识符）。【需修正】 |
| 行内字面文本（inline literal） | 行内字面文本（inline literal） | 通常被渲染成等宽字体。空格会被保留，但是换行符不会。 |
| reference_ | reference | 简单的只有一个单词的超链接引用。参见超链接目标。 |
| `phrase reference`_ | phrase reference | 包含空格或标点符号的超链接需要使用反引号引用。参见超链接目标。 |
| anonymous__ | anonymous | 如果有两个下划线而不是一个，那么不管是简单引用还是词组引用都可以是匿名的（无需在链接目标中重复输入超链接文本）。参见超链接目标。 |
| _`行内内部目标` | 行内内部目标 | 在文本内部的交叉引用。参见超链接目标。 |
| |替换索引| | （见右边的说明） | 结果会被替换为 替换定义。可以是文本，图像，超链接或这些对象与其他对象的组合。 |
| 脚注索引 [1]_ | 脚注索引 1 | 参见脚注。 |
| 引文索引 [CIT 2002]_ | 引文索引 [CIT 2002]。 | 参见引文。 |
| http://docutils.sf.net/ | http://docutils.sf.net/ | 一个独立的超链接。 |
星号，反引号，管道符和下划线是行内标记字符。星号，反引号和管道符的用法类似引号；用来包围需要被标记的单词或词组，其外围都必须有空白字符或其他引用字符，紧邻着这些标记字符的内部不能有空白字符。如果你需要使用行内标记字符的字面形式，[[#转义|转义（用反斜杠）]]或引用它们（使用双反引号。例如，使用行内字面字符）；
具体来说，根据reStructuredText语言规范关于行内标记的说明，以下规则适用于行内标记的起始标记和结束标记：
- 起始标记必须是一个文本块的起始或紧随着一个空白字符或 ' " ( [ { 和 < 中的任意一个字符。
- 起始标记之后必须紧跟着一个非空白字符。
- 结束标记必须紧跟在一个空白字符之后。
- 结束标记必须是一个文本块的结尾（文档结束或紧跟着一个空行）或后面紧跟着一个空白字符或 ' " . , : ; ! ? - ) ] } / \ 和 > 中的任意一个。
- 如果起始标记是紧跟在' " ( [ { 和 < 之中的一个之后，那么其后不能立刻紧跟着这些字符的配对字符：' " ) ] } 和 >。
- 结束标记和起始标记之间至少要有一个字符作为分隔。
- 位于起始标记或结束标记之前的未[[#转义|转义]]的反斜杠将会禁用标识符识别。行内字面文本的结束标记除外。
另外记住，行内标记不能嵌套（当然，行内字面文本中可以包括任何其他的行内标记字符，但是这不算嵌套，因为这些标记字符不会被处理。）
转义和反斜杠
（详情）
reStructuredText使用反斜杠（“\”）来覆盖标记字符的特殊意义以获取字面字符本身。要获得一个反斜杠的字面字符，使用一个转义的反斜杠（“\\”）。例如：
| 原始reStructuredText | 典型结果 |
| *转义* 使用 "\" | 转义使用"" |
| \*转义\* \使用\ "\\" | *转义* 使用 "\" |
在Python的字符串中，当然需要对所有反斜杠字符进行转义，从而使它们成为真正的reStructuredText。最简单的方法，是使用原始字符串：
| Python字符串 | 典型结果 |
| r"""\*escape* \`with` "\\"""" | *escape* `with` "\" |
| """\\*escape* \\`with` "\\\\"""" | *escape* `with` "\" |
| """\*escape* \`with` "\\"""" | escape with "" |
区块结构
（详情）
| 纯文本 | 典型结果 |
| ==== 标题 ==== 副标题 -- 标题有一个由七位ASCII码编码的 可打印非字母数字字符组成的下划线 （或上划线加下划线）。 推荐选择的字符有： “‘`= - ` : ’ " ~ ^ _ * + # < >``”。 下划线/上划线应该至少与标题文本等长。 一个单独的顶层(子)区块 |
标题
副标题 标题有一个由七位ASCII码编码的可打印非字母数字字符组成的下划线（或上划线加下划线）。推荐选择的字符有：“= - ‘ : ’ " ~ ^ _ * + # < >”。下划线/上划线应该至少与标题文本等长。 一个单独的顶层(子)区块会自动上升成为文档的(副)标题。 |
段落
（详情）
| 纯文本 | 典型结果 |
| This is a paragraph.
Paragraphs line up at their left |
This is a paragraph.
Paragraphs line up at their left edges, and are normally separated by blank lines. |
无序列表
（详情）
| 纯文本 | 典型结果 |
| 无序列表：
- 这是项目1 - 项目标记有：“-”，“*”或“+”。 注意，在第一个项目之前和最后 |
无序列表：
注意，在第一个项目之前和最后一个项目之后需要有一个空行，项目之间的空行是可选的。 |
有序列表
（详情）
| 纯文本 | 典型结果 |
| 有序列表：
3. 这是第一个项目 |
有序列表：
3. 这是第一个项目 |
定义列表
（详情）
| 纯文本 | 典型结果 |
| 定义列表：
是什么 怎么用 |
定义列表：
|
字段列表
（详情）
| 纯文本 | 典型结果 |
| :作者:
Tony J. (Tibs) Ibbs, :版本: 1.0 于 2001/08/08 |
作者: Tony J. (Tibs) Ibbs, David Goodger (and sundry other good-natured folks) 版本: 1.0 于 2001/08/08 献给: 我的父亲 |
字段列表可以用来作为扩展语法的一部分，例如，作为处理指令的选项，或者数据库样记录，以便于做出进一步处理。字段列表还可以被用作通用的文档内双栏表格构造。
选项列表
（详情）
| 纯文本 | 典型结果 |
| -a 命令行选项"a" -b file 包含参数的选项 和长描述 long 也可以使用长选项 input=file 长选项也可以有 参数 /V DOS/VMS-风格的选项也支持 |
-a 命令行选项"a" -b file 包含参数的选项 和长描述 long 也可以使用长选项 input=file 长选项也可以有 参数 /V DOS/VMS-风格的选项也支持 |
在选项和描述之间至少要有两个空格。
字面文本块
（详情）
| 纯文本 | 典型结果 |
| 如果一个段落只有两个冒号， 那么这意味着接下来的缩进 或引用文本是一个字面文本块。 :: 空格字符，换行符，空行和 只有'::'的段落不会显示在 ::可以放在任何段落的最后。如果:: 当文本的缩进恢复到与之前的段落相同时， 我们从这里开始 可以在字面文本块中使用不缩进的单行引用:: |
如果一个段落只有两个冒号，那么这意味着接下来的缩进或引用文本是一个字面文本块。
空格字符，换行符，空行和 只有'::'的段落不会显示在 ::可以放在任何段落的最后。如果::跟在空格字符之后，那么它将被忽略。如果::跟在字符后面，那么它将被转化成单个冒号。就像这里: 当文本的缩进恢复到与之前的段落相同时，文本块也就此结束。这意味着我们可以得到类似这样的输出: 我们从这里开始 可以在字面文本块中使用不缩进的单行引用: > 对于电子邮件中的引用和 |
行文本块
（详情）
| 纯文本 | 典型结果 |
| | 行文本块对地址，诗句，和无需 | 格式化装饰的列表很有用。 | 每一个新行都以一个管道符（“|”）开始。 |
行文本块对地址，诗句，和无需 格式化装饰的列表很有用。 每一个新行都以一个管道符（“|”）开始。 |
块级引用
（详情）
| 纯文本 | 典型结果 |
| 块级引用其实只是：
缩进的段落， 而且它们可以嵌套使用。 |
块级引用其实只是：
|
使用空注释来分隔缩进的上下文，例如块级引用和处理指令内容。
文档测试块
（详情）
| 纯文本 | 典型结果 |
| 文档测试块是交互的Python会话 它们以">>>"起始，以一个空行结束。 »> print "This is a doctest block." |
文档测试块是交互的Python会话 它们以"»>"起始，以一个空行结束。 »> print "This is a doctest block." |
“doctest模块会搜索一个模块的文档字符串，寻找类似Python交互会话的文本，然后执行所有这些会话，来验证它们是否能够像文档中描述的那样工作。”（摘自doctest的文档）
表格
（详情）
在reStructuredText中有两种表格语法。格状表格式完整的表格，但是创建起来比较烦人。简易表格易于创建，但是功能有限（比如，不支持跨行合并单元格，等。）
| 纯文本 | 典型结果 | ||||||||||||||||||
| 格状表格： +--+--+---+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +--+--+---+ | body row 2 | Cells may span columns.| +--+--+---+ | body row 3 | Cells may | - Cells | +--+ span rows. | - contain | | body row 4 | | - blocks. | +--+--+-——+ |
格状表格：
|
||||||||||||||||||
| 简易表格：
===== ===== ====== |
简易表格：
|
||||||||||||||||||
