reStructuredText 简明教程

 

re Structured^Text 简明教程

060724 17:58

作者:	Laurence
邮箱:	[email protected]
ID:	Kardinal @ Ubuntu.org.cn 论坛
版权:	This document has been placed in the public domain
参考:	《结构化文本入门(Karron Qiu)》 《Quick reStructuredText》 《Vim reStructuredText》 《reStructuredText Interpreted Text Roles》

索引

• WYTIWYG & WYSIWYG
  • 所见即所得
  • 所想即所得
• reStructured^Text
• 基本元素
  • 字串元素
  • 行元素
  • 块元素
• 特殊元素
  • 页面元素
  • 行块元素
  • 超级块元素
  • 物件元素
  • 自定义元素
• 对象
  • 标题
  • 行内
  • 脱字符
  • 链接
  • 物件别名
  • 列表
  • 表格
  • 脚注
  • 提示符引用
  • 预定义
• 项目管理
• 搭建reStructuredText环境
  • Linux
  • Windows
• reStructuredText命令
• 定制
• 代码风格
  • 缩进
  • 空行
  • 下划线
  • 标题
  • 标题链接
  • 表格
  • 别名
  • 链接
  • 列表
• 编辑器设定
  • Vim
  • Emacs
• FAQ
  • 空行
  • 消除空格
  • 缩进和空格

WYTIWYG & WYSIWYG

所见即所得

WYSIWYG ( What You See Is What You Get )

这个概念非常流行。就是说制作过程中所见到的，和最终所得到的结果一致。

 

比如我用DW编辑一个网页文件，在编辑的过程中，我可以设定内容的格式、排版、色彩等属性，而最终得到的网页，完全符合了我的愿望。

我们都知道，网页文件使用的是 Html 标记语言。比如加粗某处文字，我们要使用标签 ，然后是我们要加粗的文字，比如 粗体 最后再使用标签 来结束它，不然的话， 粗体 后面的文字也要被加粗了…… 因为 Html 解析器 （一般来说，就是浏览器）没法子判断到底在哪儿结束“加粗”这一行为。源文件大致是这样的：

粗体

一个完整的Html文件就是由许许多多这样的标签构成的。标签和标签之间可以嵌套。比如：

头部

    正文                                              

    这里是段落2                                          

    这里是粗体，这里是红色字体

当然了，大多数时候，Html的源文件比较复杂，远远没有这么简单。可不要被它可怕的外表吓坏了，一个Html文件，无论多么复杂，它总是具有这种结构，只要您熟悉了足够多的标签，Html对于您来说，完全是纸老虎：）

必须承认的是，如果没有所见即所得的工具，比如 DW ，直接使用Html语言编写网页文件，那应该不会是一种享受-_-#

 

可能有许多高手会讲： 我就是喜欢直接编辑Html代码，那绝对是一种享受！

是啊，可能那是一种享受，但是你享受的是编写代码，而不是设计页面。 Html并不是编程，代码不是决定因素，而外观设计才是重要的。所见即所得把开发者从代码中解救出来，使它们把心思都用在设计上，这才是它的伟大之处！

同样的，Word之类的工具，也是一种所见即所得的工具。不同的是，doc 文件的复杂程度要远远高于 Html，您不太可能直接编辑它。

所想即所得

WYTIWYG ( What You Think Is What You Get )

我们已经知道了，所见即所得偏重的是外观设计，而不是代码。看起来不错，不过这种模式也有一些缺点。

比如我想强调某事，我可能就会有点犹豫……我是应该用粗体呢？还是应该用红色的字体？还有什么其它更好的方法么？

假如现在我使用的是白色的背景，我使用红色的字体来表示强调。由于各种可能的原因，我需要把这些内容转移到另外一个地方，不巧的是，那个页面的背景使用的颜色和红色比较接近，比如说粉红色吧，如此一来，我的红色的文字反而没有正文的黑色文字醒目，本来是表示强调的，反而成了忽视……

如果手动修改这些地方，可能会非常的麻烦，因为我可能用红色表示强调，用粗体表示感叹…… 而这些内容可能会出现在许多不同的场合，这可怎么办啊？

 

这个问题很容易解决，答案就是 所想即所得 ！例如：

这里是<强调>强调，这里是<感叹>感叹

……

再使用一个样式定义，例如：

强调 = 红色字体

感叹 = 粗体

……

然后使用转换程序，根据预先定义的样式，自动将 <强调> 转换为 ，将 <感叹> 转换为 就可以了。

如果我们想将强调改用绿色，只要将样式定义改一下：

强调 = 绿色字体

也可以方便的转换为其它文件，比如 pdf 或者其它格式──只要有相应的转换程序就可以了。

 

所见即所得工具不需要编写代码，将开发者从代码只解救出来，使其专注于设计；而所想即所得工具不需要设计外观，把设计者从外观中解救出来，使其专注行思考！

事实上，这种使用标签的模式比较接近 DocBook ，当然了，标签不会是中文的。从国际主义精神的角度，我们要照顾到外国友人──据说外国友人的中文普遍不太好：）

从通用性的角度来考虑，标签基本上使用英文；从减少输入的角度考虑，标签应该尽量简短 ──很多标签使用缩写。

不过标签这种方式本身就很麻烦，特别是使用尖括号的标签。能不能再简单一些呢？

reStructured^Text

re Structured ^Text ，重构建文本，是一种优秀的写作工具，对于元素的定义已经不只是简化，而是进行了充分的优化。

上面我们提到了元素，我们把它理解为一个对象的基本组成部分。例如 粗体 、 <强调>强调 都是元素，只是组成的方式不同而已，一种是所见即所得，另一种是所想即所得。

到 是一种简化，不过还是很麻烦。使用一些不常用而且又容易输入的符号，例如 ** 就是优化了

在 reStructured^Text 中，正是使用 ** 来表示强调！

原始内容	显示结果
* 强调*	强调
** 特别强调**	特别强调
``* 原文引用*``	* 原文引用*
/* 原文*	* 原文*

基本元素

这一部分内容十分重要，理解透彻后便能够无往而不利。

不然的话，在实际使用的过程中，您可能会觉得 reStructured^Text 比较莫名其妙，有点怪怪的……

字串元素

连续的字符串构成的元素，为字串元素。 看下面的例子

** 强调** 就是一个字串元素。普通文本也是一个字串元素。

 

    第三个字串元素

** 强调** 是第一个字串元素；它后面的文本，是第二个字串元素。

如果您够细心，您会发现，字串元素之间使用 空格 分隔。在字串元素的级别， 缩进 和 换行符 也能够分隔字串元素。

严格来说，字串元素 空格 和 . , ? ! 等英文标点结束

行元素

下划线（有时包括上划线）和文本构成的元素，例如标题、表格

标题

====

表格：

===== ===== ======

   Inputs     Output

------------ ------

 A      B    A or B

===== ===== ======

False False False

True   False True

False True   True

True   True   True

===== ===== ======

 

行元素中，下划线使用符号构成，例如

Chapter 1 Title

===============

 

Section 1.1 Title

-----------------

 

Subsection 1.1.1 Title

~~~~~~~~~~~~~~~~~~~~~~

构成下划线的符号长度，应不小于文本长度。（一个汉字占两个字符）

块元素

具有相同缩进的元素为块元素，例如段落、表格

┊   第一行

┊   第二行

┊   第三行

┊

┊   第二段

块元素使用一个 空行 结束，也就是一个 垂直分隔符 。上面的例子中包含了两个块元素。

连续出现多个空行时，作为一个空行处理。

可以使用 Line Blocks 增加空行，使单独一行中只有一个 | 符号即可

（前后都要有空行，因为它也是一个 块元素）

见 行块元素

技巧： 只要没有空行，不管换多少次行，都会处理为一行。建议您将每行的内容控制在50个汉字或者100个字母之内，尽量在标点符号处手动换行，以增加源文件的可读性。

 

块元素也允许逐行增加缩进，例如

┊   第一行

┊   第二行

┊     第三行

┊                        第四行

相同缩进的行处理为一行；不同缩进，无论缩进多少，都处理为一个缩进。上面文本实际显示为

┆    第一行第二行

┆        第三行

┆            第四行

段落的缩进由其首行缩进决定

事实上，这种形式属于 定义列表

注意： 字串元素 可以作为 行元素 的子集，它们都可以作为 块元素 的子集。

特殊元素

这部分内容稍微复杂，建议您动起手来，摸着石头过河。

搭建reStructuredText环境 和 reStructuredText命令部分内容，您可以先参考一下：）

当然了，前面部分的内容，尽管看起来比较简单，不过您还是可以实验一下，多少会有一些帮助的……

页面元素

类似行元素，但是不包含缩进，例如标题、分隔线

==============

文档标题

==============

 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ( 分隔线)

 

章节标题

===========

 

二级章节标题

-----------

 

二级章节标题

-----------

 

章节标题

===========

行块元素

在某些情况下，一个段落中需要用逐行向外缩进，比如中文排版；

段落首行

第二行向外缩进

其它行和第二行相同

或者手动换行而不分段，甚至是更加复杂的装饰性文字……

<> 

< >

< <> >

< >

<> 

而段落中只能逐行向内缩进；相同的缩进会自动合并为一行，不能手动换行

 

这些问题可以使用 行块元素 来解决。

在每一行起始处添加引导符 | 和 缩进

|          段落首行

|       第二行向外缩进

|       其它行和第二行相同

相邻的行块元素，它们的引导符缩进应相同。

行块引导符后的一个空格为分隔符，是必须的！处理时忽略

超级块元素

类似块元素，但是可以包含空行，并且内部可以随意缩进。例如注释、块引用

包含有超级块引导符的行为引导行。超级块起始时相对引导行向内缩进；结束时使用一个空行，并且向外缩进等于或者超过引导行

外部块

  引导行 <引导符>

 

      向内缩进

    超级块内部可以自由缩进

 

    可以使用空行

 

  新的开始.这一行前需要空行，起码与引导行缩进相同，或者更外

注释

注释是以 .. 起始的超级块元素，注释中的内容只在源文件中显示，并不在结果中显示

.. 注释

  第二行

  第三行

 

  第二段

  第六行

 

新的开始

引导符 .. 前不能有其它字符，之后要有一个空格与注释内容分隔开（ .. 同时是一个字串元素，前后都要有分隔符）

块引用

块引用是以 :: 起始的超级块元素，块引用的内容不作任何处理，以原文显示

块引用 ::

 

  第一行

  第二行

 

  第四行

 

新的开始

引导符 :: 后必须有一个空行

物件元素

用来定义一个物件，物件元素由行内字串元素或注释中的块元素构成

以 _ 结尾的字串元素，例如 链接_ [脚注]

以 | 包裹的字串元素，例如 |别名|

它们都需要在注释中进行解释：

这里是一个 链接_ 。 [脚注]_

 

.. _ 链接: http://xxx

 

.. [ 脚注] xxxxxx

 

 

.. note:: 注意

一些具有特殊功能的物件，比如索引 contents:: ，被直接写到注释中去

.. image:: 图片

.. contents:: 索引

参见 预定义

自定义元素

例如文档信息，实际效果见页面顶部

: 作者: Laurence

: 邮箱: [email protected]

:ID: Kardinal

: 版权: This document has been placed in the public domain

: 参考: 《Quick |rst| 》《结构化文本入门(Karron Qiu)》

 

.. 技巧:: 自定义

使用以下格式

:< 名称>:`字符串`

 

.. < 名称>:: 字符串

在Html输出中添加

名称>">字符串

 

re Structured ^Text 系统内建了许多预定义对象，来完成特定功能。见 预定义

对象

标题

re Structured ^Text 会根据下划线读取文档的标题，并且可以自动组织索引

=====================

文档标题

=====================

 

--------

子标题

--------

 

章节标题

========

 

...

具有同样带修饰线类型的标题，属于树状索引的同一层级

带有上划线的标题，和不带上划线的标题是不同类型。上面例子中，文档标题和章节标题就不属于同一层级

自上而下，越先出现的标题类型，层级越高

为了简单起见，我们只写标题的修饰线

===

---

---

^^^

^^^

^^^

---

---

^^^

我们可以看到，自上而下，最先出现的标题是 === ，所以它处于最高层级；然后是 --- ，所以它处于第二层；最后是 ^^^

如果画成树形图，就是这样的

===

│

├ ---

├ ---

│   ├ ^^^

│   ├ ^^^

│   └ ^^^

├ ---

├ ---

│   └ ^^^

行内

多表示语气，如 **强调**

源文本	显示结果	说明
* 强调*	强调	通常显示为斜体
** 特别强调**	特别强调	通常显示为粗体
` 字符串`	字符串	字符串内包含空格和标点符号时，处理为单个字串
`` 行内引用``	行内引用	显示为等宽字体，保留空格，不断行
简单链接_	简单链接	简单的链接名称 <链接名称>_
` 词组 链接`_	词组链接	带空格、标点的链接名称
无名链接__	....Ubuntu.......	链接目标中不使用名称。适合大段文字的链接
_` 链接目标`	链接目标	链接的实际指向 _<链接名称>:
| 物件别名|	用来给物件指定一个别名。文本、图片、链接及其它
脚注名称 [1]_	[1]	见脚注
引文名称 [引文]_	[ 引文]	见引文
http://...	http://...	独立链接

.. _ 简单链接:

.. _` 词组 链接`:

__ http://forum.ubuntu.org.cn/    无名链接

.. | 物件别名| image:: http://forum.ubuntu.org.cn

   /templates/subSilver/images

   /folder_big.gif

[1]

脚注1

.. [1] 脚注1

[ 引文]

内容

.. [ 引文] 内容

脱字符

re Structured ^Text 使用 / 作为脱字符，脱字符引导的字串元素不具有特殊涵义，以本来面目显示

** 强调**	强调
/** 强调**	** 强调**

输入 / 字符，可以使用 //

Tip

使用 脱字符+空格 (/_)作为分隔符，可以消除字串元素之间的空格

链接

链接主要包括以下几种

独立链接 ， reStructured^Text 会自动将网址转换为链接。

例如 http://www.ubuntu.org.cn/

http://www.ubuntu.org.cn/

 

命名链接 ，为链接命名，有助记忆和减少空间占用。

在正文中使用 <链接名>_ ，注释中使用 _<链接名>: [链接目标]

例如 Ubuntu

Ubuntu_

 

.. _Ubuntu: http://www.ubuntu.org.cn/

如果链接名中出现空格和标点符号，可以使用 ` 将链接名包裹起来

`Ubuntu cn`_

 

.. _`Ubuntu cn`: http://www.ubuntu.org.cn/

 

无名链接 ，不使用链接名的链接

主要用于将大段文字转换为链接。如果将这部分文字作为链接名，链接名也将被写进注释中……

` 主要用于将大段文字转换为链接。如果将这部分文字作为链接名，

链接名也将被写进注释中……`__

 

__ http://www.ubuntu.org.cn/

 

无名链接经常与命名链接一起使用

` 这里是一大段文字………………`__

 

__ 一个命名链接_

可以在任意位置定义这个命名链接

.. _ 一个命名链接:

 

锚点 ，链接的目标地址留空，可以在当前位置标记锚点。

跳转到 锚点_

 

.. _ 锚点:

 

< 页面位置>

点击锚点名称跳转到锚点标记处。

 

标题链接 ，跳转到文章内部的标题

re Structured ^Text 定义标题的同时，还定义了一个标题链接，在正文中使用 标题名称_ 可以跳转相应标题

标题名称

========

 

跳转到 标题名称_

 

嵌入式链接 ，链接目标嵌入到链接中。(reStructured^Text 中没有通过，不建议使用)

`Ubuntu `_

物件别名

为一个物件元素定义一个别名

|H2O|

 

.. |H2O| replace:: H/ :sub:`2`/ O

输入 |别名| 便可以得到所定义的内容

上面例子中，输入 |H2O| ，得到 H/ :sub:`2`/ O ，也就是 H₂O

 

可以定义别名的元素有 文本 链接 图像 Unicode字符 日期时间等

链接：

.. | 别名| replace:: 字符串 （可以是独立链接）

 

.. _ 链接: 目标地址

.. | 别名| replace:: 链接_

为链接创建别名时，使用命名链接，则别名替换为链接名称；使用独立链接，则别名替换为目标地址。

为链接创建别名的时候，可以随意修改目标地址，但是链接名称要使两处保持一致，不够方便；并且使用别名时一定要带链接，不够灵活

我们建议您使用 别名链接 ，它能够方便的修改链接名称和目标地址，并且可以灵活的输出各种格式

别名链接 ，使用一个别名，定义链接名称和目标地址。

这是一个 |别名链接|_

 

.. | 别名链接| replace:: 实际显示的链接名称

 

.. _ 别名链接: http://目标地址

实际相当于先定义一个别名，然后定义别名的链接。

Note

·         | 别名链接| 输出replace定义的字符串

·         别名链接_ 输出使用别名作为链接名称的链接

·         | 别名链接|_ 输出链接名称定义的链接

 

图片：

.. | 图片名称| image:: 图片路径

   :width: 宽度

   :height: 高度

   :target: 目标链接

Unicode 字符：

.. | 别名| unicode:: U+211

.. |200E| unicode:: 200 U+20AC

时间日期：

.. | 当前时间| date:: %H:%M

列表

列表中，相同的层级使用相同的缩进。列表中的所有条目都是块元素，要使用空行分隔

列表中同一层级不需要空行分隔。不同层级起始处必须有空行

列表：

 - 条目

 - 条目

 

      - 条目

      - 条目

 - 条目

·   如果不包含复杂的层级，只要使用缩进开始列表，并且不需要空行

·   如果层级复杂，那么最好所有条目都以空行分隔，避免发生混乱

 

 

要点列表 以 - + ** 和一个空格作引导符，条目不计数

·   第一条

o      子条目一

§ 第三级

§ 第三级

o      子条目二

·   第二条还是第一行

第二条第二行

o      子条目

·   第三条

代码如下 ：

- 第一条

 

 - 子条目一

 

     - 第三级

 

     - 第三级

 

 - 子条目二

 

- 第二条

  还是第一行

 

  第二条第二行

 

 - 子条目

 

- 第三条

 

 

 

枚举列表 使用一个数字或者字符，后跟 . ) 或者使用 () 括起来，加一个空格

1. 数字

 

A. 大写字符

 

a. 小写字符

 

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

 

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

 

I. 大写的罗马字符

 

i. 小写的罗马字符

 

(1) 再来一个数字

 

1) 再来

可以使用 # 代替数字， reStructured^Text 会自动排序

#) 一

 

#) 二

 

#) 三

1.    一

2.    二

3.    三

 

 

 

定义列表 为列表中的条目定义一个名称

要点列表

  只列出要点，条目不记数

 

定义列表

  为列表中的条目定义一个名称

 

枚举列表

  条目进行计数

要点列表

只列出要点，条目不记数

定义列表

为列表中的条目定义一个名称

枚举列表

条目进行计数

 

 

 

区块列表 ，常用作联系薄

: 作者: Laurence

: 邮箱: [email protected]

:ID: Kardinal @ Ubuntu.org.cn 论坛

: 版权: This document has been placed in the public domain

: 参考: 《结构化文本入门(Karron Qiu)》

      《Quick |rst|/ 》

      《Vim |rst|/ 》

      《/ |rst| Interpreted Text Roles》

作者:	Laurence
邮箱:	[email protected]
ID:	Kardinal @ Ubuntu.org.cn 论坛
版权:	This document has been placed in the public domain
参考:	《结构化文本入门(Karron Qiu)》《Quick reStructuredText》《Vim reStructuredText》《reStructuredText Interpreted Text Roles》

表格

表格使用一条带有分隔符的上划线，和最少一条下划线构成

========   ==========

表格        表格

========   ==========

上划线下面为多行缩进相同的 行元素，行元素的下划线应不短于行字符。

表格同一列的下划线，长度应相等。

上划线（顶部）的分隔符是必须的，它决定了表格可以拥有的列数，但是不影响相邻列的合并。

合并相邻的列，只要取消下划线的分隔符就可以了。

底部的下划线，应和上划线使用同样符号

===== ===== ===== ===== =====   以空格作分隔符，间距均匀。决定了这个表格最多可以有5列

11    12    13    14    15

----------- -----------------   下划线的长度应不小于字符长度

21    22    23    24    25

----- ----- ----- ----- -----   每一行的下划线，决定了相信列是否合并

31    32    33    34    35

----- ----------- -----------   如果不打算合并列，可以取消表内分隔线

41    42    42    44    45

=============================   底线必须与上划线使用相同符号

11 12		13 14 15
21	22	23	24	25
31	32 33		34 35
41 42 42 44 45

 

如果想制作更复杂的表格，例如合并相邻行，则需要使用列分隔线

+------------+------------+-----------+

| 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. |

+------------+------------+-----------+

 

 

脚注

脚注使用方括号包裹起来

这里是一个脚注 [1]_

 

.. [1] 这里是脚注的内容

行内脚注后面也有一个 _ 符号，它是当作一个链接处理的。

脚注的名称可以使用 数字 # 和 * ，使用数字时需要手机排列

推荐使用 # 作为脚注名称， reStructured^Text 会自动计数。使用 * 作为脚注名称， reStructured^Text 会把它们替换成一些花哨的符号

提示符引用

使用 >>> 作为引导符，模仿交互式命令提示行

>>> rst2html -r 4 --stylesheet-path=/home/user/html4css1.css rst html

引用块不能空行

原文本

>>> rst2html -r 4 --stylesheet-path=/home/user/html4css1.css rst html

预定义

re Structured ^Text 中内建了许多字串元素作为功能对象

标准。行内使用：

:emphasis:

* 强调*

:emphasis:` 强调`

 

:literal:

`` 原文``

:literal:` 原文`

 

:strong:

** 特别强调**

:strong:` 特别强调`

 

:subscript:` 下标`

:sub:` 下标`

 

:superscript:` 上标`

:sup:` 上标`

 

:title-reference:` 标题`

:title:` 标题`

:t:` 标题`

特殊。注释中使用：

.. contents:: 索引

   :depth: 3  标题搜索深度

 

.. image :: ( 路径)/image.png

    :target: http://ubuntu.org.cn

 

.. figures :: 形状/figures.png

 

 

.. sidebar:: 侧边栏标题

   :subtitle: 子标题

 

     These lines are sidebar content interpreted

     as body elements.

 

.. rubric:: 醒目提示（内容）

 

.. topic:: 话题

 

 

.. tip:: tip 内容

 

.. note:: note 内容

 

.. warning:: warning 内容

 

.. important::

 

.. attention::

 

.. danger::

 

.. error::

 

.. caution::

 

 

字串元素间使用脱字符和空格作为分隔符，可以不显示空格，例如:

H₂O

H/ :sub:`2`/ O

项目管理

编写一个较大规模的文档时，使用单一源文件，编辑起来可能十分吃力。

re Structured ^Text 允许使用一个文件，在转换时将其它文件的内容读取进来，以便更好的管理文档项目

.. header:: 源文件路径，读取到文件头部

.. include:: 源文件路径，按顺序读取

.. footer:: 源文件路径，读取到文件尾部

例如：

.. header:: dir/header.rst

.. include:: dir/1.rst

.. include:: dir/2.rst

.. include:: dir/3.rst

.. footer:: footer.rst

Note

不能够递归读取

搭建reStructuredText环境

Linux

Ubuntu 或者 Debian 系统中，使用APT安装

>>> sudo apt-get install python-docutils

/usr/share/python-docutils/ 目录中包含了相关的工具，我们经常要用到的工具是 rst2html.py 。

在安装好之后，系统通常自动为它建立了链接，直接运行 rst2html 命令即可。

Windows

reStructuredText命令

rst2html [ 参数] <源文件.rst> [目标文件.html]

如果不指定目标文件，而输出Html代码，并不生成文件

-r 设定报告级别，默认为 2

--tab-width= 设定输出的缩进宽度，默认8个空格

--stylesheet-path= 指定CSS文件

--embed-stylesheet 使用嵌入式CSS

--footnote-references= 脚注格式。 barckets方括号 superscript上标

--compact-lists 忽略列表中多余的空行，默认 enabled

--config= 指定配置文件

--footnote-backlinks 允许从脚注跳回原文，默认选项

--toc-top-backlinks 允许从标题跳回索引，默认选项

定制

/usr/share/python-docutils/docutils.conf 为配置文件

# These entries affect all processing:

[general]

source-link: yes

datestamp: %Y-%m-%d %H:%M UTC

generator: on

 

# These entries affect HTML output:

[html4css1 writer]

# Required for docutils-update, the website build system:

stylesheet-path: ../docutils/writers/html4css1/html4css1.css

embed-stylesheet: no

field-name-limit: 20

代码风格

缩进

尽量使用固定长度的空格作为缩进，推荐您使用 4 个空格作为一个缩进

虽然在理论上，缩进可以使用任意长度，但是那样容易引起混乱，例如：

空行

有些情况下，空行并不是必须的，比如标题和之后的内容。

不过我们建议您还是尽量使用空行，以免不必要的麻烦。

下划线

理论上，下划线只要和文字的长度相同就可以了，不过我们建议主您使用比较长，且长度固定的下划线 例如 50

标题

下划线使用的符号比较重要。

如果能够养成一个固定的习惯，在处理较大规模的文档时，可以避免许多麻烦

推荐以下几套

#####	=====	^^^^^
+++++	-----	>>>>>
*****	~~~~~	<<<<<

建议您使用带上划线的第一级符号作为文章标题

全部可选符号包括

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

标题链接

请尽量避免重复的标题，特别是存在大量标题链接的情况下。

如果同时存在多个名称相同的标题，并且有指向该名称的标题链接， reStructured^Text 无法确定哪一个标题是真正的目标，这时就会发生错误。

而使用标题链接链接越多，发生这种错误的几率越大~

表格

表格尽量使用空格作分隔符

如果没有特殊要求，表格包含上划线和底线就可以了，例如：

======= =======

aaaaaa   111111

bbbbb    2222222

cccc     3

======= =======

别名

建议将别名定义放在页面顶部，便于维护

链接

请尽量使用独立链接、无名链接、标题链接和别名链接

定义别名链接的两行注释中间不要空行，便于阅读

.. |bmlj| replace:: ** 别名链接**

.. _bmlj:

 

** 别名链接**

列表

如无必要，请尽量使用要点列表和定义列表。枚举列表更适合作为章节

编辑器设定

Vim

下载 vst.vim 文件，拷贝到Vim的插件目录即可。

Emacs

安装 rst.el 插件

将如下内容添加到 ~/.emacs 文件中

;;RST

(require 'rst)

(add-hook 'text-mode-hook 'rst-text-mode-bindings)

 

(setq auto-mode-alist

(append '(("//.rst$" . rst-mode)

("//.rest$" . rst-mode)) auto-mode-alist))

FAQ

空行

可以使用 Line Blocks 增加空行，使单独一行中只有一个 | 符号即可（前后都要有空行，因为它也是一个 块元素）

消除空格

使用 /_ (脱字符和空格)代替空格作为分隔符，可以消除空格。

缩进和空格

它们是等效的，如果不怕麻烦，您大可以完全使用空格，而不使用缩进