结构(Structure)

首先我们说"结构化文本"(Structured Text)可能有一点儿用词不当。它更像使用了前后一致的规则的"松散的文本"(Relaxed Text)。这些规则可以被一个HTML转换器转换为一个可以被Web浏览器浏览的非常结构化的文本。

被认为最基本的规则是段落(paragraph)(quickref)。段落是被空行(一行就够了)分割的开的一段文字。段落必须有相同的缩进,也就是说，他们必须左对齐。缩进的段落会导致缩进的引用段落(Paragraphs that start indented will result in indented quote paragraphs.)。比如:

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 paragraph will result in an indented block of text,typically used for quoting other text.

This is another one.

文本样式(Text styles)

(quickref)

在段落中或者其他文字块中，你可能会用``*italics*``来标记文本为斜体 italics ，或者``**bold**``来标记粗体 bold 。

如果你想显示为一个固定空格的文字，使用"``两个反引号``".注意，在两个反引号中的字符不会被处理，所以，``*``之类的符号会保持原样。

如果你发现你想在文本中使用一个特殊字符，通常是可以的--reStructuredText是足够聪明的。例如，星号会处理的很好。如果你确实想让文字用星号括起来，而不是让它变成斜体，那么你需要指出星号不是特殊字符。你可以在星号之前输入一个反斜杠，象这样 \* (quickref)，或者用两个反引号(内嵌文字)，象这样:\*

列表(Lists)

列表项主要有三种类型： 枚举 ， 要点 和 定义 。在所有的列表实例中，可以有很多段落，子列表等等。只要段落或者别的什么和列表项中第一行的文字左对齐就行。

列表必须总是开始于一个新的段落，也就是说，他们必须在一个空行的后面。

枚举列表 (数字，字符或者罗马字符; quickref )

用一个数字或者字符再加上一个点“.”,右括号")"或者被括号"()"括起来--任何你感到舒服的方法都行。下面所有的形式都可以被识别:

1. 数字

A. 大写字符
    并且使用多行

    并且有两段。

a. 小写字符

    3. 用不同数字开始的子列表

    4. 确认数字有正确的序号！

I.大写的罗马字符

i.小写的罗马字符

(1) 再来一个数字

1) 再来

结果(注意：不是每个Web浏览器都支持所有的枚举类型，所以你可能无法得到这里所有的效果):

1. 数字

1. 大写字符

   并且有多行

   并且有两段!

1. 小写字符

   3. 用不同数字开始的子列表。
   4. 确认数字有正确的序号。

1. 大写罗马字符

1. 小写罗马字符

1. 再来一个数字

1. 再来

要点列表 (quickref)

象枚举列表一样，在一行的开始是点字符，"-","+" 或者 "*"

* a bullet point using "*"
    - a sub-list using "-"
        + yet another sub-list
    - another item

结果：

• a bullet point using "*"

  • a sub-list uing "-"

    • yet another sub-list

  • another item

定义列表 (quickref)

和其他两个不一样，定义列表包含了一个术语，还有术语的定义。定义列表的格式如下:

what
    定义列表关联了一个术语和一个定义。

*how*
    术语是独占一行的词组，定义是一个或多个段落或者正文元素，缩进关联到定义上。在术语和定义之间不允许有空行。

结果：

what

定义列表关联了一个术语和一个定义。

how

术语是独占一行的词组，定义是一个或多个段落或者正文元素，缩进关联到定义上。在术语和定义之间不允许有空行。

原始格式(示例代码)(Preformatting(Sample Codes))

(quickref)

为了包含一大块原始格式，永远不会被篡改的文本，在前面的段落用"::"结尾。原始格式文本块结束于和前面的段落的缩进相同时。例如：

一个例子::

    空格，新行，空行，所有类型的标记
        (例如*这个*或者\这个)都被文本块保护着。
  看这儿，回退了一个缩进等级(但是还不够)

不再是例子

结果：

一个例子:

  空格，新行，空行，所有类型的标记
      (例如*这个*或者\这个)都被文本块保护着。
看这儿，回退了一个缩进等级(但是还不够)

不再是例子

注意，如果一个段落只包含"::",那么在输出的时候会被去掉:

::

    这是一个原始格式，最后的"::"段落被去掉了。

结果：

这是一个原始格式，最后的"::"段落被去掉了。

章节(Sections)

(quickref)

你可以使用章节标题将很长的文本划分为章节。用带修饰符的单行文字(一个或多个单词):下划线，或者同时具有下划线和上划线，单横线"-------",等号"==========",波浪号"~~~~~~~~~~~"或者任何你感到舒服的非字母数字的字符 = - ` : ' " ~ ^ _ * + # < >。一个使用同样字符的下划线修饰符与上下划线修饰符的区别很明显。上下划线必须至少一样长。他们是一致的，因为所有用同种修饰符标记的章节都是处于同样的级别。

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使用缩进来表示嵌套，没有闭合标签。不可能在处理结果中显示出来，和其他例子一样，因为章节不能在区块引用中存在。一个具体的例子，比较本文的源文件的章节结构和处理后的输出)

注意章节的标题可以使用他们的名称来作为连接对象。为了连接 列表(Lists) 的标题，我写了"列表(Lists)_".如果标题有空格，象 文本样式(Text styles) 一样，我们需要将标题引起来" `文本样式(Text styles)`_ ".

=====================
 文档标题
=====================

--------
 子标题
--------

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

...

图片(Images)

(quickref)

为了在你的文档中包含图片，你可以使用 image 指令 。例如:

.. image:: http://docutils.sourceforge.net/docs/user/rst/images/biohazard.png

结果是:

http://docutils.sourceforge.net/docs/user/rst/images/biohazard.png 部分指明了你希望在文档中显示的图片的文件名。没有限制图片的位置(格式，大小等)。如果图片是用来在HTML中显示，你可能会希望提供一些附加的信息，你可以:

.. image:: http://docutils.sourceforge.net/docs/user/rst/images/biohazard.png
   :height: 100
   :width: 200
   :scale: 50
   :alt: alternate text

更多的信息，请查阅完整的 image指令文档 。

下一步(What Next?)

本入门文档只包含了reStructuredText的最普通的特性，还有更多的东西需要探索。 reStructuredText用户快速参考 是进行下一步的好去处。完整的细节，可以参考 reStructuredText 标记规格 。