原文标题： A reStructuredText Primer
文档作者： Richard Jones
原文版本： 5801
原文版权： 公有域
原文链接： 这里
文档翻译： Venj Chu
翻译版本： 1
翻译版权： 公有域
状态： 翻译结束
最后修改 2010年5月26日，用Wikidot的标记语言重新排版
下面的文章中包含了像这样的链接“(快速参考)”。这些是指向reStructuredText快速参考这篇文档的相对引用。如果这些链接失效了，请参考 reStructuredText快速参考的原文 。
注意
本文档只是一篇不正式的reStructuredText介绍。文章最后的“下一步做什么？”部分有指向进一步阅读的资料的链接，包括一个正式的参考文档。
结构
最开始，我就开始说“结构化文本”可能有点不太好。更确切的说法应该是遵循某个约定的模式的“格式自由的文本”。这些模式能够被一个HTML转换程序解析并创建为“非常格式化的文本”，使之可以通过一个网页浏览器来阅读。
最基本的模式是段落(快速参考)。也就是由空行分隔的一块一块的文本（一个空行就足够了）。段落内部必须有相同的缩进——也就是说，在每行的左边缘对齐。有缩进的段落将会成为一个引用段落。例如：
This is a paragraph. It's quite
short.
This paragraph will result in an indented block of
text, typically used for quoting other text.
This is another one.
会产生下面的输出：
This is a paragraph. It's quite short.
This is another one.
文本样式
(快速参考)
在段落内部或其他文字体内部，你可能使用“*斜体*”或“粗体”把文本标记为斜体或粗体。这被称为“行内标记”。
如果你想要让部分文本使用等宽字体，你可以使用“双反引号”。注意，双反引号内部的文本将不会被进一步解析——因此，“*”将原样保持。
如果你想在文本中使用“特殊”字符，通常这不会有任何问题——reStructuredText有足够的智能。例如，单独出现的星号*会被很好的处理，这个等式中的星号也是：5*6=30。如果你希望*用星号包围文本*而不被替换为斜体，那么你需要告诉解释器，这个星号没有特殊含义。方法是在星号前面加上一个反斜杠，就像这样“\*”(快速参考)，或者用双反引号包围它（行内字面文本），就像这样：
小技巧
你可以把行内标记看作是(括号)的一种类型，用法也类似括号：紧靠需要标记的文本的前后。行内标记本身（由空白字符包围）或位于一个单词内部的时候时不会被识别的。
参见（标记规约）了解详情。
列表
项目列表有三种风格：有序列表，无序列表和定义列表。无论是那种列表，你可以使用任意多的段落，子列表等，只要段落或其他文本的左手侧与列表项的第一行文本对齐。
列表必须总是以一个新的段落作为开始——也就是它必须位于一个空行之后。
- 有序列表(数字，字母或罗马字起始；快速参考)
- 以一个数字或字母跟一个句点“.”或右括号“)”或用括号包围“()”——选你最习惯的一种方法。以下所有的形式都能被识别：
1. numbers
A. upper-case letters
and it goes over many lines
with two paragraphs and all!
a. lower-case letters
3. with a sub-list starting at a different number
4. make sure the numbers are in the correct sequence though!
I. upper-case roman numerals
i. lower-case roman numerals
(1) numbers again
1) and again
会产生下面的输出（注意，不同的浏览器对有序列表样式的支持也不一样，因此你可能不能看到这里的完整效果）：
- 无序列表(快速参考)
- 与有序列表类似，在行的起始处加上一个点号字符——可以是“-”，“+”或“*”：
* a bullet point using "*"
- a sub-list using "-"
+ yet another sub-list
- another item
会产生如下输出：
- 定义列表(快速参考)
- 与上面的两种列表不同，定义列表有一个名词和名词的定义所组成。定义列表的格式是：
what
Definition lists associate a term with a definition.
*how*
The term is a one-line phrase, and the definition is one or more
paragraphs or body elements, indented relative to the term.
Blank lines are not allowed between term and definition.
产生的输出如下：
- what
- Definition lists associate a term with a definition.
- how
- The term is a one-line phrase, and the definition is one or more
paragraphs or body elements, indented relative to the term.
Blank lines are not allowed between term and definition.
预格式化(代码示例)
(快速参考)
如果是仅仅想创建一段预格式化过的文本，不要想方设法和文本较劲了，只需在之前一个段落的最后使用“::”。当段落的缩进回到与前一个段落一致的时候，意味着预格式化块的结束。例如：
An example::
Whitespace, newlines, blank lines, and all kinds of markup
(like *this* or \this) is preserved by literal blocks.
Lookie here, I've dropped an indentation level
(but not far enough)
no more example
生成输出如下：
An example:
Whitespace, newlines, blank lines, and all kinds of markup
(like *this* or \this) is preserved by literal blocks.
Lookie here, I've dropped an indentation level
(but not far enough)
no more example
如果一个段落仅含有“::”，那么这个段落将不会在输出结果中出现：
::
This is preformatted text, and the
last "::" paragraph is removed
输出结果：
This is preformatted text, and the
last "::" paragraph is removed
区块
(快速参考)
要把一长段文字分割成若干区块，你可以使用区块头。它们包括一行文本（一个或多个单词）和一些装饰：一个下划线行，或一个下划线行加一个上划线行的组合。这些行可以是短横线“-—-”，等号“=========”，波浪线“~~~~~~~~”，或其他非数字和字母字符：= - : ' " ~ ^ _ + # < >，你可以选择你最习惯的符号。仅有一个下划线行的装饰是不同于上划线行和下划线行所组成的装饰的。下划线/上划线至少要与标题文本等长。出于一致性的考虑，有相同装饰风格的区块被视为同一级别的标题。
Chapter 1 Title
===============
Section 1.1 Title
-----------------
Subsection 1.1.1 Title
~~~~~~~~~~~~~~~~~~~~~~
Section 1.2 Title
-----------------
Chapter 2 Title
===============
输出下面的层次结构，我们使用了简化的伪XML代码进行表示：
<section>
<title>
Chapter 1 Title
<section>
<title>
Section 1.1 Title
<section>
<title>
Subsection 1.1.1 Title
<section>
<title>
Section 1.2 Title
<section>
<title>
Chapter 2 Title
(伪XML代码使用缩进表示嵌套，并且没有结束标签。这里不可能显示真是处理的输出，其他例子里也是一样，因为区块不能位于一个块级引用之中。不过你可以把本文档作为例子，试着比较本文档的源码，以及本文档的实际输出。)
文档标题/副标题
整个文档的标题不同于区块标题，并且被格式化的结果也有所不一样（例如，HTML输出程序默认会把标题居中）。
要在reStructuredText中指定文档标题，要在文档开始处使用一个唯一的装饰风格。要指示文档的副标题，要紧挨着文档标题使用另一种唯一的装饰风格。例如：
================
Document Title
================
----------
Subtitle
----------
Section Title
=============
...
注意，上面的“文档标题”和“区块标题”都是用的等号，不过它们使用了不同的，相互无关的风格。使用上划线行加下划线行组合的标题装饰（不是只有下划线行的标题）更多的可能是出于美观的考虑。
图像
(快速参考)
要在文档中包含一个图片，可以使用image标签。例如：
.. image:: images/biohazard.png
将产生输出：
images/biohazard.png指示了你想要插入文档的图片所在的路径。对插入的图片没有限制（格式，尺寸等）。如果图片将在HTML中出现，并且你希望提供额外的信息，你可以这样使用：
.. image:: images/biohazard.png
:height: 100
:width: 200
:scale: 50
:alt: alternate text
查看完整的文档了解更多细节。
下一步做什么？
这篇简介介绍了reStructuredText大部分常见的特征，但是还有很多特征需要你自己去摸索。(reStructuredText快速参考)是一份很好的继续阅读的材料。要了解完整的细节，reStructuredText标记规范是一个很好的参考文献（1）。
有任何关于Docutils或reStructuredText的问题或需要帮助的用户，可以在Docutils-users邮件列表中发消息。
（1）如果那个相对链接不正确，试着从这里访问主文档： http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
(译者按：本译文使用了Wikidot的标记，而没有使用reStructuredText排版。这里的链接是指向原文的源代码的。)
