列表表示语法

3.3. 列表表示语法#

3.3.1. 无序列表 Bullet Lists#

reStructuredText中 无序列表 的语法和Markdown中的是一样的。 一般使用 "+ ","- ","* " 来作为无序列表的指示符，利用缩进来指示列表之间的嵌套关系。

  • 列表的起始项和终止项前后是需要空行的

  • 同层级之间的列表项之间空行可加可不加，不同层级之间的列表项必须加空行

  • 层级中内容有多段，则第二段（后续段落内容）无需指示列表标识符，只需保持同样缩进（即左对齐）。

  • 指示标识符可以混用，但是不推荐，推荐同样层级使用同样符号，一般层级顺序就按照 "+ ","- ","* "

示例如下:

+ 一级列表第一项
+ 一级列表第二项

  - 二级列表，换层级加空行

    二级列表的第二段内容，加空行，缩进对齐

  + 依然是二级列表，指示标识符可以混用，但不推荐

    * 第三级

效果如下:

  • 一级列表第一项

  • 一级列表第二项

    • 二级列表，换层级加空行

      二级列表的第二段内容，加空行，缩进对齐

    • 依然是二级列表，指示标识符可以混用，但不推荐

      • 第三级

3.3.2. 有序列表 Enumerated Lists#

枚举列表 即顺序列表(ordered-list)，可以使用不同的枚举序号来表示列表。

枚举指示符有：

  • 阿拉伯数字: 1, 2, 3, ... (无上限)。

  • 大写字母: A-Z。

  • 小写字母: a-z。

  • 大写罗马数字: I, II, III, IV, ..., MMMMCMXCIX (4999)。

  • 小写罗马数字: i, ii, iii, iv, ..., mmmmcmxcix (4999)。

并且可以使用 "#" 来自动自增。

支持添加的前缀和后缀：

  • . 后缀: "1.", "A.", "a.", "I.", "i."。

  • () 包起来: "(1)", "(A)", "(a)", "(I)", "(i)"。

  • ) 后缀: "1)", "A)", "a)", "I)", "i)"。

当正常的文本中包含可被识别为列表的内容时（ A. 1. (b) I 等），为了避免被识别，可以采取如下措施：

  1. 将一行内容，折断为多行书写，这样会被识别为 段落 内容，而不会解析为列表；

  2. 使用反斜杠 "\" 在段首进行转义。

示例如下:

A. Einstein was a really
smart dude. （跨行避免）

A. Einstein was a really smart dude.（未避免）

\A. Einstein was a really smart dude.（使用\转义）

效果如下:

A. Einstein was a really smart dude.

  1. Einstein was a really smart dude.

A. Einstein was a really smart dude.

有序列表也支持嵌套，规则和无序列表一致

1. Item 1 initial text.

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

#. a) Item 2a.使用#号自增
   b) Item 2b.

效果如下:

  1. Item 1 initial text.

    1. Item 1a.

    2. Item 1b.

    1. Item 2a.使用#号自增

    2. Item 2b.

3.3.3. 定义列表Definition Lists#

定义列表 可以理解为解释列表，即名词解释(definition_list, classifier, definition)。

条目占一行，解释文本要有缩进；多层可根据缩进实现。

各个条目由三部分组成，条目名称(term)，条目属性(classifier)，条目定义(definition)， 条目名称和条目属性在同一行，使用空格、冒号、空格（" : "）连接，其中条目属性可以为空，也可以有多个 条目定义需要换行缩进。

示例如下:

term 1
  Definition 1.

term 2
    Definition 2, paragraph 1.

    Definition 2, paragraph 2.

term 3 : classifier
    Definition 3.

term 4 : classifier one : classifier two
    Definition 4.

效果如下:

term 1

Definition 1.

term 2

Definition 2, paragraph 1.

Definition 2, paragraph 2.

term 3classifier

Definition 3.

term 4classifier oneclassifier two

Definition 4.

3.3.4. 字段列表 Field Lists#

字段列表 用于指令解释，或者数据库字段（记录）解释的场景。

它在形式上有点像两列的表格，因此在 field body中的功能是和在表格中一样的（即支持嵌套，跨行等等）。

示例如下：

:Date: 2020-02-02
:Version: 1
:Authors: - fire
          - firewang
          - firewang
:Indentation: Since the field marker may be quite long, the second
   and subsequent lines of the field body do not have to line up with first line.
   解释可能很长，第二行不用和第一行对齐，但是后续行必须和第二行对齐。
:Parameter i: field name可以是phrase，即可以带空格，但是不能带":"

效果如下：

Date:

2020-02-02

Version:

1

Authors:

  • fire

  • firewang

  • firewang

Indentation:

Since the field marker may be quite long, the second and subsequent lines of the field body do not have to line up with first line. 解释可能很长，第二行不用和第一行对齐，但是后续行必须和第二行对齐。

Parameter i:

field name可以是phrase，即可以带空格，但是不能带":"

3.3.5. 参数(选项)列表 Option Lists#

选项列表是一个左列为参数，右列为参数说明的两列列表（无表头），用于command-line参数解释。

支持三种参数书写形式:

  • 由一个短横（Short dash）连接的 POSIX 式。

  • 由两个短横（Short dash）连接的 长POSIX 式。

  • DOS/VMS参数形式，即由 / 起始的参数形式。

示例如下：

-a            command-line option "a"
-b file       options can have arguments
              and long descriptions
--long        options can be long also
--input=file  long options can also have
              arguments
/V            DOS/VMS-style options too

效果如下：

-a

command-line option "a"

-b file

options can have arguments and long descriptions

--long

options can be long also

--input=file

long options can also have arguments

/V

DOS/VMS-style options too

目录