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><标签></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。
类别 | 代码示例 | 输出示例 | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
一级标题
========
二级标题
--------
三级标题
~~~~~~~~
四级标题
^^^^^^^^
五级标题
++++++++
六级标题
````````
|
输出略。 Note
|
|||||||||||||
段落 | 空行分段 | 第一段内容。
第二段和第一段间有一空行。
|
第一段内容。 第二段和第一段间有一空行。 |
|||||||||||
自动续行 | 一个回车不分段,
本行续上行。
|
本行续上行。 | ||||||||||||
不留白续行 | 行尾转义字符让\
续行之间不留白。
|
行尾转义字符让续行之间不留白。 | ||||||||||||
| 保持换行符,
| 本行不续行。
|
保持换行符,
本行不续行。
|
|||||||||||||
.. 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. 列表项可以折行,
对齐则自动续行。
2. 列表项可包含多个段落。
空行开始的新段落,
新段落要和列表项内容对齐。
3. 列表下的代码段注意对齐即可。
::
$ printf "Hello, world.\n"
|
|
|||||||||||||
定义 | 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`
|
|
|||||||||||||
两个连续反引号嵌入代码,如: ``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
|
||||||||||||||
.. _fig1:
.. figure:: /images/github.png
内部跳转图例
上面定义的位置,可以:
- 通过 fig1_ 跳转。
- 或者 `点击这里 <#fig1>`__ 跳转。
- 或者参见 :ref:`fig1`\ 。
|
上面定义的位置,可以: |
|||||||||||||
脚注 | reST脚注的多种表示法:
- 脚注即可以手动分配数字 [1]_ ,
也可以使用井号自动分配 [#]_ 。
- 自动分配脚注 [#label]_ 也可以用
添加标签形式 [#label]_ 多次引用。
- 还支持用星号嵌入符号式脚注,
如这个 [*]_ 和 这个 [*]_ 。
- 使用单词做标识亦可 [CIT2012]_ 。
.. [1] 数字编号脚注。
.. [#] 井号自动编号。
.. [#label] 井号添加标签以便多次引用。
.. [*] 星号自动用符号做脚注标记。
.. [*] 星号自动用符号做脚注标记。
.. [CIT2012] 单词或其他规定格式。
|
reST脚注的多种表示法:
|
||||||||||||
.. 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/
|
||||||||||||||
.. table:: 示例表格
:class: classic
+---------+--------+--------+
| head1 | head2 | head3 |
+=========+========+========+
| | cell | cell |
| rowspan +--------+--------+
| | * 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 |