Asciidoc
From PostgreSQL 中文维基, PostgreSQL 中文站, PostgreSQL 中国社区, PostgreSQL Chinese community
- asciidoc 是 Linus 选来写 [git 文档]的工具
- slackware 把 asciidoc 归类为 linuxdocs-tools
- asciidoc-8.2.6 版本由 4246 行 python 写成
- asciidoc 源文件类似 wiki 语法，后端可生成
- html
- manpage
- docbook
- latex （试验性质）
然后再籍由 docbook tool-chain 生成 pdf 、odf 等各种格式的文档
- asciidoc 发行包包含 asciidoc.py 和 a2x 两个可执行程序
- asciidoc.py 生成 xhtml 1.1 文档的时候用
- a2x 适合生成 pdf 、manpage 等高级格式
- 我觉得 asciidoc 最好不要执行 ./install.sh 而是直接执行发行包内的 py 脚本比较好，这样它会自动找到本发行包内的各种配置文件，免去路径配置的烦扰
- 用 asciidoc 写文档，全部使用 utf-8 省得麻烦
- 要使用 source-hightlight 功能，需要使用 GNU-source-highlight，这个东西需要 boost ，两个包 slackware 都默认没装，要自己从网上抓 （boost 的 tgz 已经有现成的，source-highlight 还没有）。
- 生成 xhtml 很简单
luoyi@skyking: asciidoc$ ./asciidoc-8.2.6/asciidoc.py article.txt ERROR: unsafe: include file: /etc/asciidoc/./stylesheets/xhtml11.css ERROR: unsafe: include file: /etc/asciidoc/./stylesheets/xhtml11-quirks.css luoyi@skyking: asciidoc$
由于系统在 /etc 下已经有老版本的配置，因此会有一些 warning ，无所谓，忽略。
- 生成 pdf 有点烦
- xsltproc 一般系统都自带
- 要下载 Apache FOP 供 fo 转换为 pdf 之用
- asciidoc 的作者用的是比较古老的 FOP-0.20.5 版本，用最新的 0.95beta 的话，需要加上如下 fix ：
(debian 社区找到的解法，sorry ，我找不到 debian 社区讨论的帖子了，很佩服 debian 社区的强大！)
--xsltproc-opts="--param fop.extensions 0" --xsltproc-opts="--param fop1.extensions 1"
- asciidoc 生成的 fo 文件有些不标准，用下面的命令能 fix fo files：（假设 fo 是 ssh.fo）
sed -i -e 's/bgcolor="#E0E0E0"//g' ./ssh.fo
- [fop 官方 font 指南] 里面有给 fop 增加 font 的方法，其思路大致是：
- 通过 ttf 生成 font-metrics xml 配置
- 在自定义的 configure 中包括 font-metrics xml 配置文件
- 调用 fop 的时候传入自定义的 configure
luoyi@skyking:/export/m1/luoyi/asciidoc$ /usr/lib/java/bin/java -classpath "/export/m1/luoyi/src/fop/fop-0.95beta/lib/xmlgraphics-commons-1.3.jar:/export/m1/luoyi/src/fop/fop-0.95beta/lib/xml-apis-ext.jar:/export/m1/luoyi/src/fop/fop-0.95beta/lib/xml-apis-1.3.02.jar:/export/m1/luoyi/src/fop/fop-0.95beta/lib/xercesImpl-2.7.1.jar:/export/m1/luoyi/src/fop/fop-0.95beta/lib/xalan-2.7.0.jar:/export/m1/luoyi/src/fop/fop-0.95beta/lib/serializer-2.7.0.jar:/export/m1/luoyi/src/fop/fop-0.95beta/lib/commons-logging-1.0.4.jar:/export/m1/luoyi/src/fop/fop-0.95beta/lib/commons-io-1.3.1.jar:/export/m1/luoyi/src/fop/fop-0.95beta/lib/batik-all-1.7.jar:/export/m1/luoyi/src/fop/fop-0.95beta/lib/avalon-framework-4.2.0.jar:/export/m1/luoyi/src/fop/fop-0.95beta/build/fop.jar:/export/m1/luoyi/src/fop/fop-0.95beta/build/fop-sandbox.jar:/export/m1/luoyi/src/fop/fop-0.95beta/build/fop-hyph.jar:" org.apache.fop.fonts.apps.TTFReader /export/m1/luoyi/src/fop/fonts/simsun.ttc -ttcname 'SimSun' ./simsun.xml TTF Reader for Apache FOP 0.95beta Parsing font... Reading /export/m1/luoyi/src/fop/fonts/simsun.ttc... This is a TrueType collection file with 2 fonts Containing the following fonts: SimSun <-- selected NSimSun Font Family: [[▒OS, SimSun] Creating xml font file... Creating CID encoded metrics... Writing xml font file ./simsun.xml... This font contains no embedding license restrictions. XML font metrics file successfully created.
copy fop 官方发布包的 conf/fop.xconf 到本目录，在此基础上改
<font metrics-url="/export/m1/luoyi/asciidoc/simsun.xml"
embed-url="/export/m1/luoyi/src/fop/fonts/simsun.ttc"
kerning="yes">
<font-triplet name="SimSun" style="normal" weight="normal"/>
<font-triplet name="SimSun" style="normal" weight="bold"/>
<font-triplet name="SimSun" style="italic" weight="normal"/>
<Font-triplet name="SimSun" style="italic" weight="bold"/>
</font>
将 docbook 的 fo.xsl 3 种（body、title、monospace）字体均改成 SimSun：
luoyi@skyking: asciidoc$ grep 'SimSun' ./asciidoc-8.2.6/docbook-xsl/fo.xsl <xsl:param name="body.font.family" select="'SimSun'"/> <xsl:param name="title.font.family" select="'SimSun'"/> <xsl:param name="monospace.font.family" select="'SimSun'"/> luoyi@skyking: asciidoc$
这样 xsltproc 用 fo.xsl 生成 ssh.fo 的时候，会将所有的 font-family 都设为 SimSun ，而 fop 执行的时候由于我们提供了字体配置，因此，能将对应的 ttf 内嵌入最终的 pdf 文档中。
- 如果一个 txt 文档 只有 一级标题 没有 二级标题 则 fop 处理会出错
