AsciiDoc简介

标签： 学习笔记 AsciiDoc emacs HTML LaTeX | 发表时间：2011-01-21 00:23 | 作者：小高子 dayu
出处：http://linux.cuit.edu.cn

AsciiDoc是什么?

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

使用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.
 
[red]#2011.3.9更新: http://dram.blog.35.cn/[Xin Wang] 同学在 http://linux.cuit.edu.cn/?p=1157#comment-1295[文后] 提供了输出中文PDF的方法, 详细请参考他的博客: http://dram.blog.35.cn/2011/03/09/export-chinese-pdf-from-asciidoc#
 
编辑器支持
----------
 
.语法高亮
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].

相关 [asciidoc 简介] 推荐：

AsciiDoc简介

- dayu - 桃源
AsciiDoc 是一种简单的基于纯文本的文档生成工具, 与它类似的还有 reStructuredText, Markdown. 说是生成文档, 其实它可以将纯文本文件转换成各种类型, 比如:. Man Page (示例). Graphviz 图形 (示例). 使用AsciiDoc进行文档编写最著名的恐怕是Git官方的 Git User’s Manual (我表示对于初学者很难看懂), 这篇博客也是通过AsciiDoc生成, 文后会附上本文的原始代码以便参考..

Flask-Babel 简介

- yinseny - python.cn(jobs, news)
本文有一个格式好看一点，并且有语法高亮的版本放在 readthedocs，欢迎浏览. 本文是原创，不是翻译，不过本文其实是谈翻译的. 话说用 wordpress 的 WYSIWYG 编辑器写这样的文章真痛苦啊，格式一不小心就乱了，本文是用 rst 写成，编译为 html，然后贴到这边来的. 最近用 Flask 给公司做了个小 web 应用，做的时候用英文了，现在要求翻译成中文.

ABAP简介

- - 博客园_首页
中文名称：高级企业应用编程语言. 英文全称：Advanced Business Application Programming. 德语全称：Allgemeiner Berichtsaufbereitungsprozessor（通用报表预处理器）. 概述：一种高级编程语言，起源于20世纪80年代，由德国软件公司SAP开发，主要用作SAP的编程，现行版本为ABAP/4，同时支持面向过程和面向对象.

json简介

- - ITeye博客
    JSON(JavaScript Object Notation) 是一种轻量级的数据交换格式，易于阅读和编写，同时也易于机器解析和生成. 它基于ECMA262语言规范（1999-12第三版）中JavaScript编程语言的一个子集. JSON采用与编程语言无关的文本格式，但是也使用了类C语言（包括C， C++， C#， Java， JavaScript， Perl， Python等）的习惯，这些特性使JSON成为理想的数据交换格式.

[转]amanda 简介

- - 小鸥的博客
    安装mysql数据库是会发现三个用户 mysql 、postmyql 、amanda，其中amanda是什么呢. 　　Amanda 是最早出现的开源备份 软件. 它的名字来自Maryland大学. Amanda的意思是高级Maryland 硬盘归档器.. 　　Amanda通过 操作系统上 一些自带的备份工具，例如tar(Unix/linux)、zip(Windows)来实现备份的计划，自动化和跟踪等功能.

[转]HBase简介

- - 小鸥的博客
   Hbase是一个分布式开源数据库，基于Hadoop分布式文件系统，模仿并提供了基于Google文件系统的Bigtable数据库的所有功能. 其目标是处理非常庞大的表，可以用普通的计算机处理超过10亿行数据，并且有数百万列元素组成的数据表. Hbase可以直接使用本地文件系统或者Hadoop作为数据存储方式，不过为了提高数据可靠性和系统的健壮性，发挥Hbase处理大数据量等功能，需要使用Hadoop作为文件系统.

Learning to Rank 简介

- - 博客园_首页
  去年实习时，因为项目需要，接触了一下Learning to Rank(以下简称L2R)，感觉很有意思，也有很大的应用价值. L2R将机器学习的技术很好的应用到了排序中，并提出了一些新的理论和算法，不仅有效地解决了排序的问题，其中一些算法(比如LambdaRank)的思想非常新颖，可以在其他领域中进行借鉴.

CSRF简介

- - 互联网 - ITeye博客
转自： http://www.cnblogs.com/hyddd/archive/2009/04/09/1432744.html. 　　CSRF（Cross-site request forgery），中文名称：跨站请求伪造，也被称为：one click attack/session riding，缩写为：CSRF/XSRF.

storm简介

- - 搜索技术博客－淘宝
伴随着信息科技日新月异的发展，信息呈现出爆发式的膨胀，人们获取信息的途径也更加多样、更加便捷，同时对于信息的时效性要求也越来越高. 举个搜索场景中的例子，当一个卖家发布了一条宝贝信息时，他希望的当然是这个宝贝马上就可以被卖家搜索出来、点击、购买啦，相反，如果这个宝贝要等到第二天或者更久才可以被搜出来，估计这个大哥就要骂娘了.

MALLET简介

- - CSDN博客推荐文章
MALLET：基于Java语言的用于统计自然语言处理，文件分类，聚类，主题建模，信息提取，和其他的用于文本的机器学习应用的Java包. MALLET包括复杂的用于 文件分类的工具：. 有效的用于转换文本到“特征”的程序，多种多样的算法（包括朴素贝叶斯，最大熵，和决策树）. 以及一些通用的指标用于评估分类器性能.