reStructuredText标记语言之二

reSructuredText是一种通俗易懂的标记文本语言，可以用于内联程序文件，快速创建简单的网页等。

本单元主要以文档 Quick reStructuredText 为基础，旨在介绍这种标记语言的语法规则。

3.文本结构–章节，段落设置

• 文本标题是由文本中的标题符控制的，从文本开始，从文本开始依次判定遇到的文本标题符样式为主标题，子标题，子子标题等。标题符是由同种符号连续输入，至少覆盖标题。可用于构造标题符的符号有:

  ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ } ^ _ ` { | } ~

• 一般用来构造标题的符号有:

  = - ` : . ' " ~ ^ _ * + #

• 一些标题的例子:

  ==================
    Section Title
  ==================
  
  ------------------
    Section Title
  ------------------
  
    Section Title
  ==================
  
    Section Title
  ------------------
  
    Section Title
  ``````````````````
  
    Section Title
  ''''''''''''''''''
  
    Section Title
  ..................
  
    Section Title
  ~~~~~~~~~~~~~~~~~~
  
    Section Title
  ******************
  
    Section Title
  ++++++++++++++++++
  
    Section Title
  ^^^^^^^^^^^^^^^^^^

• 本节中 reStructuredText标记语言之二 就是主标题, 3.文本结构–章节，段落设置 就是子标题。

• 段落结构是按照书写的层次结构来划分以及缩行的，新起一段必须要有空白行；要出现子段落必须开始的段缩行。

4.几类列表

本单元主要列举一些常用的列表格式，主要有项目列表、枚举列表、自定义列表、字段列表以及选项列表。

4.1 项目列表

项目列表符有：”-”,”*”，”+”,”-”, “•”, “‣”或”⁃”,必须对齐项目列表符，并且与文本之间要有空格，下面是例子:

项目列表:
 - 这是列表1
 - 这是列表2
 - 这是列表3

输出结果：

项目列表:

• 这是列表1
• 这是列表2
• 这是列表3

4.2 枚举列表

枚举列表的序号不一定从第一个开始，但是只要开始之后就是依次按照序号排列的，可以用“#”代替要输入的序号，可以用于作为枚举列表的序号有:

• 阿拉伯数字：1,2,3,...（没有上限）
• 大写字母字符：A,B,C,...,Z.
• 小写字母字符：a,b,c,...,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)”.

比如下面的例子:

枚举列表：

3. 这是第一个列表：

   a) 子一列表1
   b) 子一列表2
   c) 子一列表3
4. 这是第二个列表；
#. 这是第三个列表：

   (II) 子二列表1
   (III) 子二列表2
   (#) 子二列表3
#. 这是第四个列表。

输出结果：

枚举列表：

3. 这是第一个列表：
   1. 子一列表1
   2. 子一列表2
   3. 子一列表3
4. 这是第二个列表；
5. 这是第三个列表：
   2. 子二列表1
   3. 子二列表2
   4. 子二列表3
6. 这是第四个列表。

4.3 自定义列表

给定一个自定义词组单独占据一行，从下一行开始缩进一格作为自定义词组的说明，说明部分可以是一段也可以是多段（多段时每段都要相同的缩进），下面是一个例子:

我的自定义列表之12生肖：

鼠
 吸引力，社交能力，影响力，智力，俭省，魅力，紧张，权力欲，赘言  ，狡计，贪得无厌，干预。

牛
 正直，创新，有目的，勤勉，稳定，善言，固执，冷漠，偏见，缓慢，报复。

虎
 热诚，好运，勇敢，慈善，魅力，权威，冲动，吹嘘，易怒，放纵，不服从，飘荡。

兔
 机智，洁癖，谨慎，技巧，长寿，敏捷，德行，秘密，业余，过于拘谨，忧郁，自炫，善良，希望，。

龙
 力量，热心，成功，胆量，健康，多情，僵直，迷惑，不信任，自夸，不满多言。

蛇
 蛇：直觉，睿智，吸引力，机敏，谨慎，同情，掩饰，贪得，奢侈，傲慢，懒惰，孤芳自赏。

输出结果：

我的自定义列表之12生肖：

鼠

吸引力，社交能力，影响力，智力，俭省，魅力，紧张，权力欲，赘言 ，狡计，贪得无厌，干预。

牛

正直，创新，有目的，勤勉，稳定，善言，固执，冷漠，偏见，缓慢，报复。

虎

热诚，好运，勇敢，慈善，魅力，权威，冲动，吹嘘，易怒，放纵，不服从，飘荡。

兔

机智，洁癖，谨慎，技巧，长寿，敏捷，德行，秘密，业余，过于拘谨，忧郁，自炫，善良，希望，。

龙

力量，热心，成功，胆量，健康，多情，僵直，迷惑，不信任，自夸，不满多言。

蛇

直觉，睿智，吸引力，机敏，谨慎，同情，掩饰，贪得，奢侈，傲慢，懒惰，孤芳自赏。

4.4 字段列表

字段列表是用一对冒号来包含特定含义的词或词组，之后是其说明的文字，它们之间必须要有一个空格，若说明文字有多行时必须要有相同的缩进格式。字符列表可以用来作为扩展语法的一部分，例如，作为处理指令的选项，或者数据库样记录，以便于做出进一步处理。字段列表还可以被用作通用的文档内双栏表格构造。下面是例子:

:作者: Robbert J. liuer
:版本: 2.7.3
:日期: 2012/01/01

输出结果：

作者:Robbert J. liuer 版本:2.7.3 日期:2012/01/01

4.5 选项列表

选项列表有两列列表组成，包括命令行选项及对其的描述，记录了程序选项。命令行选项和描述之间至少要有两个空格，可以看如下的例子:

-a         Output all.
-b         Output both (this description is quite long).
-c arg     Output just arg.
--long     Output all day long.

-p         This option has two paragraphs in the description.
           This is the first.

输出的结果：

-a	Output all.
-b	Output both (this description is quite long).
-c arg	Output just arg.
--long	Output all day long.
-p	This option has two paragraphs in the description. This is the first.

参考资料

快速参考: http://docutils.sourceforge.net/docs/user/rst/quickref.html