4. 附录:轻量级标记语言

没有标记语言就没有Web和丰富多彩的互联网,但创造了Web的HTML语言并非尽善尽美,存在诸如难读、难写、难以向其他格式转换的问题。究其根源是因为HTML语言是一种“重”标记语言,对机器友好而并非对人友好。

下面这段HTML源码,非技术控阅读起来会遇到困难。

<html>
<head>
  <meta content='application/xhtml+xml;charset=utf-8' http-equiv='Content-type' />
  <title>轻量级标记语言</title>
</head>
<body>
  <h1 id='id1'>轻量级标记语言</h1>

  <p><strong>轻量级标记语言</strong> 是一种 <em>语法简单</em> 的标记语言。
  它使用易于理解的格式标记,没有古怪的 <code>&lt;标签&gt;</code> 。</p>

  <ul>
  <li>可以使用最简单的文本编辑器编辑。</li>
  <li>所见即所得,非技术控亦可直接阅读源码。</li>
  <li>可版本控制。</li>
  <li>实现单一源文件出版。</li>
  </ul>
<body>
</html>

同样的信息如果换用轻量级标记语言来表达,就非常直观了。如下所示:

轻量级标记语言
==============

**轻量级标记语言** 是一种 *语法简单* 的标记语言。
它使用易于理解的格式标记,没有古怪的 `<标签>` 。

- 可以使用最简单的文本编辑器编辑。
- 所见即所得,非技术控亦可直接阅读源码。
- 可版本控制。
- 实现单一源文件出版。

GitHub令人着迷的一个因素就在于GitHub为用户提供更为便捷地创建UGC(用户生成内容)的方法,其奥秘就在于使用了轻量级标记语言。无论是代码提交说明、提交评注、问题描述、项目的README文件、维基页面、用户主页和项目主页都可以使用Markdown[4]等轻量级标记语言来撰写。轻量级标记语言如Markdown是对人友好的标记语言,一些语法参照了我们写电子邮件时的习惯,即使第一次接触用轻量级标记语言撰写的文件,也可以毫无障碍地理解其中的内容。

虽然GitHub更倾向于使用Markdown标记语言[5],但很多地方也提供对其他轻量级标记语言的支持。包括为Python程序员所熟悉的reStructedText[6],为Ruby程序员所熟悉的Textile[7]、RDoc[8],为Perl程序员所熟悉的POD[9],为Emacs用户所熟悉的Org-mode[10],为维基用户所熟悉的MediaWiki[11]和Creole[12],以及可作为DocBook[13]前端的颇有前途的AsciiDoc[14]标记语言。

下面通过一张表格对几种常用的轻量级标记语言加以对照,供有不同标记语言偏好的用户参考,便于在GitHub某些不能随意更换标记语言而只能使用GFM(GitHub风格的Markdown)的场合可以自如地转换。

在“表7-1:常用轻量级标记语言对照”中,为使表格更加紧凑使用代号表示各种标记语言。例如:md为Markdown,gfm是GitHub风格的Markdown,rst为reStructedText,ttl为Textile,asc为AsciiDoc,org为Org-mode。

表7-1:常用轻量级标记语言对照
类别 代码示例 输出示例
 
一级标题
========

二级标题
--------

三级标题
~~~~~~~~

四级标题
^^^^^^^^

五级标题
++++++++

六级标题
````````

输出略。

Note

  • 标题级别和下划线无对应,文档中保持一致就好。
  • reST标题可用下列符号标记: # * = - ^ ~ ` : . _ + ” 等。
段落 空行分段
第一段内容。

第二段和第一段间有一空行。

第一段内容。

第二段和第一段间有一空行。

自动续行
一个回车不分段,
本行续上行。
本行续上行。
不留白续行
行尾转义字符让\
续行之间不留白。
行尾转义字符让续行之间不留白。
 
| 保持换行符,
| 本行不续行。
保持换行符,
本行不续行。
.. role:: raw-html(raw)
   :format: html

用新定义的role插入换行,
:raw-html:`<br />`
本行不再续行。
用新定义的role插入换行,
本行不再续行。
段落缩进
邮件体段落缩进:

> 第一级段落缩进。
>
> > 第二级段落缩进。
>
> 返回一级段落缩进。

邮件体段落缩进:

第一级段落缩进。

第二级段落缩进。

返回一级段落缩进。

Python式段落缩进:

  第一级段落缩进。

    第二级段落缩进。

  返回一级段落缩进。

Python式段落缩进:

第一级段落缩进。

第二级段落缩进。

返回一级段落缩进。

 
双冒号后缩进为代码块。

::

  $ printf "Hello, world.\n"

还可声明语言类型实现语法加亮。

.. code-block:: sh

   $ printf "Hello, world.\n"

双冒号后缩进为代码块。

$ printf "Hello, world.\n"

还可声明语言类型实现语法加亮。

$ printf "Hello, world.\n"
列表 无序列表
* 星号、减号、加号开始列表。

  - 列表层级和缩进有关。

    + 和具体符号无关。

* 返回一级列表。
  • 星号、减号、加号开始列表。
    • 列表层级和缩进有关。
      • 和具体符号无关。
  • 返回一级列表。
 
1. 数字和点是一种编号方式。

   A. 大写字母编号。

      a. 小写字母编号。

2. 继续一级列表。

   (I) 大写罗马编号。

       i) 小写罗马编号。
  1. 数字和点是一种编号方式。
    1. 大写字母编号。
      1. 小写字母编号。
  2. 继续一级列表。
    1. 大写罗马编号。
      1. 小写罗马编号。
1. 列表项可以折行,
   对齐则自动续行。

2. 列表项可包含多个段落。

   空行开始的新段落,
   新段落要和列表项内容对齐。

3. 列表下的代码段注意对齐即可。

   ::

     $ printf "Hello, world.\n"
  1. 列表项可以折行, 对齐则自动续行。

  2. 列表项可包含多个段落。

    空行开始的新段落, 新段落要和列表项内容对齐。

  3. 列表下的代码段注意对齐即可。

    $ printf "Hello, world.\n"
    
定义
git
  Simple and beautiful.

hg
  Another DVCS.

subversion
  VCS with many constrains.

  Why not Git?
git
Simple and beautiful.
hg
Another DVCS.
subversion

VCS with many constrains.

Why not Git?

 
四条短线或以上显示为分隔线。

----
输出略。
   
这是 **粗体** ,这是 *斜体* 。

不留白的\ **粗体**\ 和\ *斜体*\ 效果。

这是 粗体 ,这是 斜体

不留白的粗体斜体效果。

 
.. role:: strike
   :class: strike

:strike:`删除线` 效果

不留白的\ :strike:`删除线`\ 效果

删除线 效果

不留白的删除线效果

 
.. role:: ul
   :class: underline

:ul:`下划线` 效果

不留白的\ :ul:`下划线`\ 效果

下划线 效果

不留白的下划线效果

 
- Water: H\ :sub:`2`\ O
- E = mc\ :sup:`2`
  • Water: H2O
  • E = mc2
 
两个连续反引号嵌入代码,如: ``git status`` 。

两个连续反引号嵌入代码,如: git status

Note

相当于 :literal:`git status` 。 只用一个反引号则相当于 :title-reference:`引言` 。

引言
`Got GitHub` by Jiang Xin.
Got GitHub by Jiang Xin.
链接 URL自动链接
- 网址 http://github.com/
- 邮件 me@foo.bar
 
- 访问 `Google <http://google.com/>`_ 。
- 上面已定义,直接引用 google_ 链接。
- 链接地址在后面定义,如: GitHub_ 。
- 反引号括起多个单词的链接。如 `my blog`_ 。

.. _GitHub: http://github.com
.. _my blog: http://www.worldhello.net
  • 访问 Google
  • 上面已定义,直接引用 google 链接。
  • 链接地址在后面定义,如: GitHub
  • 反引号括起多个单词的链接。如 my blog
 
.. _fig1:

.. figure:: /images/github.png

   内部跳转图例

上面定义的位置,可以:

- 通过 fig1_ 跳转。
- 或者 `点击这里 <#fig1>`__ 跳转。
- 或者参见 :ref:`fig1`\ 。
../_images/github.png

内部跳转图例

上面定义的位置,可以:

脚注
reST脚注的多种表示法:

- 脚注即可以手动分配数字 [1]_ ,
  也可以使用井号自动分配 [#]_ 。

- 自动分配脚注 [#label]_ 也可以用
  添加标签形式 [#label]_ 多次引用。

- 还支持用星号嵌入符号式脚注,
  如这个 [*]_ 和 这个 [*]_ 。

- 使用单词做标识亦可 [CIT2012]_ 。


.. [1] 数字编号脚注。
.. [#] 井号自动编号。
.. [#label] 井号添加标签以便多次引用。
.. [*] 星号自动用符号做脚注标记。
.. [*] 星号自动用符号做脚注标记。
.. [CIT2012] 单词或其他规定格式。

reST脚注的多种表示法:

  • 脚注即可以手动分配数字[1], 也可以使用井号自动分配[2]
  • 自动分配脚注[3]也可以用添加标签形式[3]多次引用。
  • 还支持用星号嵌入符号式脚注, 如这个[*]和 这个[†]
  • 使用单词做标识亦可[CIT2012]
[1]数字编号脚注。
[2]井号自动编号。
[3](1, 2) 井号添加标签以便多次引用。
[*]星号自动用符号做脚注标记。
[†]星号自动用符号做脚注标记。
[CIT2012]单词或其他规定格式。
 
.. figure:: /images/github.png
   :width: 32

   图:GitHub Octocat

- GitHub Logo: |octocat|
- 带链接的图片:
  |imglink|_
- 下图向右浮动。
   .. image:: /images/github.png
      :align: right

.. |octocat| image:: /images/github.png
.. |imglink| image:: /images/github.png
.. _imglink: https://github.com/
../_images/github.png

图:GitHub Octocat

  • GitHub Logo: octocat

  • 带链接的图片: imglink

  • 下图向右浮动。
    ../_images/github.png
 
.. table:: 示例表格
   :class: classic

   +---------+--------+--------+
   | head1   | head2  | head3  |
   +=========+========+========+
   |         | cell   | cell   |
   | rowspan +--------+--------+
   |         | * colspan       |
   |         | * another line  |
   +---------+-----------------+
示例表格
head1 head2 head3
rowspan cell cell
  • colspan
  • another line
  转义
反斜线作为转义字符,\
禁止对后面 \*字符* 做语法解析。
反斜线作为转义字符,禁止对后面 *字符* 做语法解析。
注释
.. 注释

..
   缩进内容也是注释
无输出。

Note

  • 部分标记语言代号后添加了星标,代表该标记语言相应的语法实现稍有区别,或者GitHub的具体实现和标准有出入。
  • 为突出部分空格,使用符号 ° 标记。

[4]Markdown是在Ruby应用中广泛使用的标记语言,语法简洁并可混用HTML。标准的Markdown语法缺乏如表格等关键特性的支持,虽然不同的解析器都对其语法进行了扩展,但实现各有不同,造成一定的混乱。网址:http://daringfireball.net/projects/markdown/
[5]GitHub使用Redcarpet作为Markdown的解析工具,并添加了额外的语法扩展。网址:http://github.github.com/github-flavored-markdown/
[6]reStructuredText可简写为reST或RST,是在Python中广泛使用的标记语言。reST的语法简洁严谨,本书就是使用Sphinx扩展的reST语法和工具撰写的。网址:http://docutils.sourceforge.net/rst.html
[7]Textile是在Ruby应用中广泛使用的标记语言,例如Redmine就将Textile作为内置的标记语言。网址:http://redcloth.org/textile
[8]RDoc是内嵌于Ruby代码中用于维护软件文档的标记语言。网址:http://rdoc.sourceforge.net/doc/
[9]POD是内嵌于Perl代码中用于维护软件文档的标记语言。网址:http://perldoc.perl.org/perlpod.html
[10]Org-mode是Emacs的一种编辑模式,除文档外还被广泛应用于维护TODO列表、项目计划等。网址:http://orgmode.org/org.html
[11]MediaWiki是著名的维基百科(WikiPedia)所使用的维基语言。网址:http://www.mediawiki.org/wiki/Help:Formatting
[12]维基的实现有上百种,语法各不相同。Creole试图建立统一的维基语法标准。网址:http://www.wikicreole.org/
[13]DocBook是著名的用于文档撰写的标记语言,采用XML文件格式及大量的面向出版的格式标签,能够实现单一源文件出版(Single-Source Publishing),即一次撰写多种格式输出(Write once, publish many)。但复杂的XML标签给写作过程带来不小的负担。网址:http://www.docbook.org/
[14]AsciiDoc的轻量级标签和DocBook的XML标签语法有着清晰的对应关系,既解决了DocBook语言标签复杂、难读难写的问题,又可利用DocBook丰富的工具链实现单一源文件向多种格式的输出转换。网址:http://www.methods.co.nz/asciidoc
[15]https://github.com/mojombo/god/commit/cea00609ca8441c82bc9760ae5eea7d7509d85b3
[16]https://github.com/mojombo/god/issues/1