gotgithub/appendix/markups.rst at master · MonstarCoder/gotgithub · GitHub
Skip to content

markups.rst

Latest commit

 

History

History
1251 lines (1227 loc) · 182 KB

markups.rst

File metadata and controls

1251 lines (1227 loc) · 182 KB
Raw

附录：轻量级标记语言

没有标记语言就没有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[8]等轻量级标记语言来撰写。轻量级标记语言如Markdown是对人友好的标记语言，一些语法参照了我们写电子邮件时的习惯，即使第一次接触用轻量级标记语言撰写的文件，也可以毫无障碍地理解其中的内容。

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

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

在“:ref:`tbl-markups`”中，为使表格更加紧凑使用代号表示各种标记语言。例如：md为Markdown，gfm是GitHub风格的Markdown，rst为reStructedText，ttl为Textile，asc为AsciiDoc，org为Org-mode。

表7-1：常用轻量级标记语言对照

Note

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