× 段落行间距，这是因为如果不定义这个，则在打印时（firefox），行间距过小，但在显示器中浏览时却是正常的，我没有去细究为什么，反正简单修改一下就好了。在段落的定义中增加 line-height: 1.5，现在的定义如下：
p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
  line-height: 1.5;
}

× 我喜欢用literal block（一种段落样式，在ascdoc中用"….."来定义）来引用代码，缺省的literal block字体偏大了（也是打印时，在显示器上没有问题），我增加下面一个css定义：
div.literalblock {
  font-size: small;
}

× 我不喜欢缺省的1px的图像边框，因此我改了下面的语句到0px：
div.imageblock img { border: 0px solid silver; }

所有的改动就是这些，得益于css的强大，都很简单的搞定，有时间是应该仔细看看css了。

HTMLS := $(patsubst %.txt,%.html,$(wildcard *.txt))

all: $(HTMLS)

%.html: %.txt
        asciidoc -a toc -a numbered $<

文件头： 文件标题后加一行字数和文件头相同的等号
章节： 这个类似于Mediawiki，用 == 标题 == （后一半等号可省略）
URL： url[]
图像： image::url[]，如果是段落内的图像，则两个冒号改为一个
段落： 可以使用样式打头，比如  NOTES: 内容
表格： 可以用  `—–`—–（内容用空格对齐），也可以用 ““~宽度（内容用逗号分隔）
列表： 用 – 或者 * 打头，要加一个空格

总得来说和wiki比较相似，但基于文件来操作，可以更灵活一些，比如可以使用喜欢的编辑器，可以diff/merge等。

简单的在Ubuntu下sudo apt-get install asciidoc就可以安装了，下载一个例子 http://www.methods.co.nz/asciidoc/faq.txt ，然后执行：
asciidoc faq.txt
就可以得到一份漂亮的内嵌css的html文档faq.html了，不错吧，试试看编辑一下txt文件，加入中文，都没有问题。

asciidoc的过人之处在于：
+ 格式简单，比docbook简单， 这种简单的格式带来的结果是asciidoc文件本身已经可以具备很好的文档可视性（一个docbook源文件看起来还是有些费劲的，被xml tag穿插的有些支离破碎），这可能对写文档的人连贯自己的思路有很大的好处。
+ 表达能力强，在格式简单的基础上，asciidoc的表达能力并不象某些wiki那么弱，比如asciidoc可以支持三种格式输入（doctype）：article，book和manpage（他们三种的基本语法是类似的），显然支持book就意味着asciidoc有较好的表达能力。
+ 工具易用， asciidoc本身的工具只有一个命令文件(asciidoc)，就支持三种格式（backend）输出：xhtml11/docbook/html4，一般情况下用xhtml11就很好用了，如果需要更复杂的输出，可以先转换到docbook，再用docbook toolchain做进一步转换。在命令行下使用 asciidoc -b backend -d doctype file 就可以了，通常 -b/-d都不用指定，缺省值分别为xhtml11和article，所以命令行使用就非常简单，比docbook的一整套toolchain用起来平易近人一些。

写了这么多优点，并不是说asciidoc没有缺点，通常一个新事物总是容易先看到优点，而在使用中再逐步看到缺点，我用的不多，所以不敢妄下结论，不过有一个缺点先提一下，它的官网上的User Guide文档写的不好，比较晦涩 :))

update（2008-04-06）：我用asciidoc写了一篇完整的大约100K的文档（纯文字的部分），感觉还是非常的不错，将来这种纯文本格式的文档一定大有前途（虽然不一定是asciidoc）。