代码改变世界

Markdown和reStructuredText语法比较

2014-03-12 20:29  youxin  阅读(8585)  评论(0)  编辑  收藏  举报

reStructuredText在线编辑器 http://rst.ninjs.org/

ReST是Docutils的标记语法，Docutils是Python世界的文档工具集。也因为这样ReST在Python界中被广泛应用，比如Sphinx–这个基于Docutils的文档工具–事实上作为Python中的标准文档工具被广泛使用了。比如Python官方文档。因为Sphinx可以生成多种格式，

设计思路对比
—————

先来看一下 Markdown ，

官方的说法直截了当， Markdown 就是个 text-to-HTML 的工具。

所以说，从一开始，Markdown 就确立了它与 HTML 的亲缘性。这是 Markdown 的设计立足点。

Markdown 包含两个部分，

1. 文本结构化格式，也就是标记语言

2. 另外与之配套的生成 HTML 的 perl 程序。

作为标记语言， Markdown 的目标很明确，就是为了更简单的写 html 。

相比与 Markdown ， reST 显然是经过精心设计的。

reST 的目标是，建立一套标准文本结构化格式用以将文档转化为有用的数据格式。

不得不说的是这句话一点都不 Pythonic ，和政治书上的句子似的。

所以 Pythoner 给出了更具体的阐述：

按重要程度依次罗列：

1. Readable，是可阅读的，reST的原文本必须可以很容易的直接阅读而不需要了解reST的标记语法。

2. Unobtrusive，不突兀的，reST 所使用的标记应该是尽量简单并且不突兀的。越是常用的标记越应该简单和不碍眼的。不太常用的标记，或者是表达特殊意义的标记应该鲜明。

3. Unambiguous，没有歧义的，标记规则是确定的，不能再重载定义，对于给定的一个输入，只有一个可能的输出，包括输出错误。

4. Unsurprising，不出乎预期的，非“魔法”的，标记语言可以不输出不想输出的内容。所以，需要一个方式（标记）作为标记不期望输出标记之用。比如，当你想要向别人展示reST源代码时，你要标记这块reST源码不需要被结构化。

5. Intuitive， 直观的，标签应该尽可能的容易被记住。人们可以在文档中直接使用。

6. Easy，简单，

通过一段时间的使用，我觉得 Markdown 和 reST 都可以说达到了他们的既定目标。

进过一段时间的使用，我觉得 reST 基本达到了预定的目标。

权衡的艺术
~~~~~~~~~~~

通过以上的比较，我们发现， reST 承载的目标要比 Markdown 多很多。最重要的不同就在于 Markdown 只是为了输出 HTML ，而 reST 的目标之一就是可以转化为其他格式。

当然，说权衡是艺术，还不如说其实就是瞎子摸象弄出一些聊以自慰的藉口罢了。

不过从已经获取到的相关信息，我们可以初步做一个判断，用 Markdown 作为中心书写工具（一般是配合 Pandoc ）相对于使用 reST 做中心书写工具是不佳的。何况，又引入了新的工具（ Pandoc ）和语言（ Haskell ），这都是非必要的正熵，背离了 KISS 原则。

说了这么多其实就一句话：

我们选择标记语言实际上是在表意与简便之间做权衡，我们的理想目标是即表意丰富又使用简便。

但是，这个世界上鱼和熊掌得兼的事情不多，往往我们只能根据自己的需要去寻找一个最优平衡点来决策。

 

转自：http://ieqi.net/2012/04/13/markdown-%E8%BF%98%E6%98%AF-restructuredtext/

两者对比：

https://github.com/windfire-cd/note/blob/master/rst_mkd/rst_mkd.rst

 

ReSt文档标题：

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

----------
文档副标题
----------
文档标题和副标题通常用在封面页

章节

Section Header
==============

Subsection Header
-----------------

three sub  三级标题
``````````````
这些是文档各节（section）的标题，文档的目录根据这些标题生成。

标题
可以使用字母数字以外的可打印ACSII字符，官方推荐的是以下字符:

Recommended choices are
"``= - ` : ' " ~ ^ _ * + # < >``"
标题前后的符号数目必须大于等于标题的长度


段落
段落的格式:

段落不需要特殊标记，用空行来分割，
段落内的换行是被忽略的，因此源文件
可以很好地控制一行的长度。

这是一段。

这是第二段。

   段落可以缩进，通常用来表达引用的文字。

 

行内标记
用来实现斜体、粗体、引用、脚注、引用等等:

*斜体*, **粗体**, hyperlink_, 脚注 [3]_

.. [3] 脚注的正文
.. _hyperlink: http://jerrypeng.me
还有更多其他标记，请参考文档

1. 数字和点开始有序列表。

   1. 注意子列表的缩进位置。

      1. 三级列表。
      1. 编号会自动更正。

   1. 二级列表，编号自动更正为2。

2. 返回一级列表。

 

列表中，相同的层级使用相同的缩进。

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

独立链接 ，自动将网址转换为链接。

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

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

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

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

例如 Ubuntu

Ubuntu_

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

表格
表格的格式:

 

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

 

简单表格的格式：

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

 


指令（Directives）
指令是基本的标记之外的扩展机制

有一组标准的指令
目录
图片，内嵌代码
公式
标准指令大全 [4]
不同的工具可以实现自己独特的指令以实现高级功能

[4] http://docutils.sourceforge.net/docs/ref/rst/directives.html

 

  • 指令的格式如下:

    .. directive_type:: directive
   block

嵌入图片：

.. image:: funny.gif
   :height: 100px
   :width: 100px
   :alt: funny cat picture
   :align: center

嵌入代码:

 

.. code:: python

    def say_hello():
        print 'Hello, ReST'

    if __name__ == '__main__':
        say_hello()

docutils-0.9才开始支持，无法演示了……

sphinx和rst2pdf支持code-block这个指令
用法和上面的一致，把code改成code-block即可。

sphinx对嵌入程序代码的支持很好（本来就是为了编写python文档而开发的工具）。

在段落的结尾添加符号 :: ，则表明下面的段落为代码段落。代码段落相对之前的段落要缩进一次。

普通文本段落，下一段是代码段落::

    缩进结束前
        代码段落不会被处理

 普通文本段落

文本

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


上面的例子转自可爱的rst：
http://wiki.jerrypeng.me/rest-tjlug/

http://www.worldhello.net/gotgithub/appendix/markups.html
http://jwch.sdut.edu.cn/book/tool/UseSphinx.html