AsciiDoc简介

原文发表于「桃源」: http://linux.cuit.edu.cn/?p=1157

AsciiDoc是什么?

AsciiDoc 是一种简单的基于纯文本的文档生成工具, 与它类似的还有 reStructuredText, Markdown. 说是生成文档, 其实它可以将纯文本文件转换成各种类型, 比如:

• HTML
• XHTML
• WordPress
• DocBook
• LaTeX
• PDF (示例)
• EPUB (示例)
• DVI
• PostScript
• Man Page (示例)
• 五线谱 (示例)
• 数学公式 (示例)
• Graphviz 图形 (示例)

使用AsciiDoc进行文档编写最著名的恐怕是Git官方的 Git User’s Manual (我表示对于初学者很难看懂), 这篇博客也是通过AsciiDoc生成, 文后会附上本文的原始代码以便参考.

---

使用AsciiDoc

就像reST以及Markdown, AsciiDoc也定义了一套自己的标记符号, 以前没有接触过纯文本标记符号的同学可以参考这篇 官方指南, 而已经学习过其它文档生成工具的同学可以直接看这篇 快速索引.

AsciiDoc自带的 asciidoc 命令只能生成HTML, XHTML, DocBook, WordPress, LaTeX (实验版, 不是很完善)这几种类型的文件, 使用很简单:

$ asciidoc -b wordpress alist.txt

如果需要支持代码语法高亮, 你需要额外安装 GNU Source-highlight 或者 Pygments.

AsciiDoc还自带了一个实用小工具: a2x, 它可以将AsciiDoc与其它工具结合起来生成更多类型的文件, 比如PDF, EPUB等. 这些额外的工具在 a2x 的man page的 “REQUISITES” 小节中都有详细说明. 比如生成PDF文件可以这样:

$ a2x -f pdf alist.txt

---

关于生成包含中文的PDF

说到生成PDF, 就不得不说到中文. 但凡有过排版经验的同学都能了解, 大多数时候我们并不是纠结于文档的格式, 也不是文档的内容, 而是在为了使中文不变成乱码而战斗 (这里无视了使用Word, OpenOffice等现代排版软件的同学). AsciiDoc支持两种生成PDF的外部工具 (准确地说是 a2x): dblatex 和 FOP. 前者依赖LaTeX, 后者依赖Java, 并且默认情况下都不支持中文输出.

我尝试了很久dblatex以解决中文乱码问题, 但始终没有好的方法, 归根结底其实是要解决LaTeX中文乱码的问题, 这早就已经通过各种中文宏包 (xeCJK等) 解决了, 但由于 a2x 命令封装了中途生成TeX文件的过程, 因此修改起来很麻烦, 唯一的解决办法是手动一步一步转换, 最后修改TeX文件以支持中文输出. 不过我不想这么折腾, 毕竟如果必须得这样, 我还不如自己写LaTeX来得直接.

对于FOP, 我简单 在Google上搜索了一下, 解决办法还是有的, 不过貌似看起来比dblatex还麻烦, 有兴趣的同学可以深入研究.

在我看来, 现在最好的PDF中文输出支持还是LaTeX.

2011.3.9更新: Xin Wang 同学在 文后 提供了输出中文PDF的方法, 详细请参考他的博客: http://dram.blog.35.cn/2011/03/09/export-chinese-pdf-from-asciidoc

---

编辑器支持

语法高亮
AsciiDoc安装文件中已经自带了用于Vim的语法高亮文件, 如果你是通过包管理器安装的AsciiDoc, 那Vim应该默认就支持语法高亮. Emacs则需要额外配置, 推荐 这个 Major Mode扩展, 并在 “.emacs” 文件中添加:

;; AsciiDoc Major Mode (autoload 'doc-mode "doc-mode") (add-to-list 'auto-mode-alist (cons "\\.txt\\'" 'doc-mode))

YASnippet
在写这篇博客的同时, 我顺便写了几个用到的AsciiDoc代码片段, 有需要的同学可以参考 这里. 如果你还不知道YASnippet是什么的话, 可以参考 “桃源” 以前的文章: pluskid及其YASnippet, YAAY–Yet Another Artical about Yasnippet.

---

本文的AsciiDoc源码

AsciiDoc是什么?
------------

http://www.methods.co.nz/asciidoc[AsciiDoc] 是一种简单的基于纯文本的文档生成工具, 与它类似的还有 http://docutils.sourceforge.net/rst.html[reStructuredText], http://daringfireball.net/projects/markdown/[Markdown]. 说是生成文档, 其实它可以将纯文本文件转换成各种类型, 比如:

- HTML
- XHTML
- WordPress
- DocBook
- LaTeX
- PDF (http://www.methods.co.nz/asciidoc/asciidoc.pdf[示例])
- EPUB (http://www.methods.co.nz/asciidoc/asciidoc.epub[示例])
- DVI
- PostScript
- Man Page (http://www.methods.co.nz/asciidoc/asciidoc.1.css-embedded.html[示例])
- 五线谱 (http://www.methods.co.nz/asciidoc/music-filter.html[示例])
- 数学公式 (http://www.methods.co.nz/asciidoc/latex-filter.html[示例])
- http://www.graphviz.org/[Graphviz] 图形 (http://www.methods.co.nz/asciidoc/asciidoc-graphviz-sample.html[示例])

使用AsciiDoc进行文档编写最著名的恐怕是Git官方的 http://www.kernel.org/pub/software/scm/git/docs/user-manual.html[Git User's Manual] (我表示对于初学者很难看懂), 这篇博客也是通过AsciiDoc生成, 文后会附上本文的原始代码以便参考.

使用AsciiDoc
-----------

就像reST以及Markdown, AsciiDoc也定义了一套自己的标记符号, 以前没有接触过纯文本标记符号的同学可以参考这篇 http://www.methods.co.nz/asciidoc/userguide.html[官方指南], 而已经学习过其它文档生成工具的同学可以直接看这篇 http://powerman.name/doc/asciidoc[快速索引].

AsciiDoc自带的 +asciidoc+ 命令只能生成HTML, XHTML, DocBook, WordPress, LaTeX (实验版, 不是很完善)这几种类型的文件, 使用很简单:

[source,bash]
----
$ asciidoc -b wordpress alist.txt
----

如果需要支持代码语法高亮, 你需要额外安装 http://www.gnu.org/software/src-highlite/[GNU Source-highlight] 或者 http://pygments.org/[Pygments].

AsciiDoc还自带了一个实用小工具: +a2x+, 它可以将AsciiDoc与其它工具结合起来生成更多类型的文件, 比如PDF, EPUB等. 这些额外的工具在 +a2x+ 的man page的 ``REQUISITES'' 小节中都有详细说明. 比如生成PDF文件可以这样:

[source,bash]
----
$ a2x -f pdf alist.txt
----

关于生成包含中文的PDF
-------------

说到生成PDF, 就不得不说到中文. 但凡有过排版经验的同学都能了解, 大多数时候我们并不是纠结于文档的格式, 也不是文档的内容, 而是在为了使中文不变成乱码而战斗 (这里无视了使用Word, OpenOffice等现代排版软件的同学). AsciiDoc支持两种生成PDF的外部工具 (准确地说是 +a2x+): http://dblatex.sourceforge.net/[dblatex] 和 http://xmlgraphics.apache.org/fop/[FOP]. 前者依赖LaTeX, 后者依赖Java, 并且默认情况下都不支持中文输出.

我尝试了很久dblatex以解决中文乱码问题, 但始终没有好的方法, 归根结底其实是要解决LaTeX中文乱码的问题, 这早就已经通过各种中文宏包 (xeCJK等) 解决了, 但由于 +a2x+ 命令封装了中途生成TeX文件的过程, 因此修改起来很麻烦, 唯一的解决办法是手动一步一步转换, 最后修改TeX文件以支持中文输出. 不过我不想这么折腾, 毕竟如果必须得这样, 我还不如自己写LaTeX来得直接.

对于FOP, 我简单 http://www.google.com.hk/search?sourceid=chrome&ie=UTF-8&q=FOP+%E4%B8%AD%E6%96%87[在Google上搜索了一下], 解决办法还是有的, 不过貌似看起来比dblatex还麻烦, 有兴趣的同学可以深入研究.

在我看来, 现在最好的PDF中文输出支持还是LaTeX.

编辑器支持
-----

.语法高亮
AsciiDoc安装文件中已经自带了用于Vim的语法高亮文件, 如果你是通过包管理器安装的AsciiDoc, 那Vim应该默认就支持语法高亮. Emacs则需要额外配置, 推荐 http://xpt.sourceforge.net/tools/doc-mode/[这个] Major Mode扩展, 并在 ``.emacs'' 文件中添加:

[source,lisp]
----
;; AsciiDoc Major Mode
(autoload 'doc-mode "doc-mode")
(add-to-list 'auto-mode-alist (cons "\\.txt\\'" 'doc-mode))
----

.YASnippet
在写这篇博客的同时, 我顺便写了几个用到的AsciiDoc代码片段, 有需要的同学可以参考 http://code.google.com/p/princess-alist/source/browse/#svn%2Ftrunk%2Fhome%2Fxiaogaozi%2F.emacs.d%2Fsite-lisp%2Fyasnippet-0.6.1c%2Fsnippets%2Fdoc-mode[这里]. 如果你还不知道YASnippet是什么的话, 可以参考 ``桃源'' 以前的文章: http://linux.cuit.edu.cn/?p=558[pluskid及其YASnippet], http://linux.cuit.edu.cn/?p=1099[YAAY–Yet Another Artical about Yasnippet].