用docbook写文档

abloz 2012-12-27
abloz 2012-12-27

周海汉 2012.12.27

在翻译HBase官方文档中文版时遇到一个困难,就是原文进行大量章节变动后,对章节号和注解号跟踪非常困难。在usenet上询问,HBase官方文档作者之一Stack告诉我是采用DocBook来写xml,然后再通过maven来编译生成html的。自己又土了一把,直接下载html翻译的。为什么很多开源软件的文档不是直接编写html呢? html和word文档都有一个问题,就是内容和排版是搅合在一起的。word文档最大的毛病是不适合版本管理和多人合作。html还通过css进行了一部分分离,但相对而言,还是有很多排版标签。而docbook则仅需很少的xml标签,用户可以直接面向内容,至于如何展示,再用独立的xsl等来规定。

docbook网站:http://docbook.org 对于如何使用docbook规范来写文档,windows下有一篇很好的文档《一个简单的Docbook 5.0例子》,本文也基本按照该文来操作的。linux下面由于我操作系统比较旧,相关依赖库比较麻烦,所以没有完成。

以下操作都是在win7下完成的。

## 下载:

docbook xml dtd下载 http://sourceforge.net/projects/docbook/files/ 下载xsl http://superb-dca2.dl.sourceforge.net/project/docbook/docbook-xsl-ns/1.78.0/docbook-xsl-ns-1.78.0.tar.bz2

下载libxml和文档生成相关工具 ftp://ftp.zlatkovic.com/libxml/ 里有libxml相关库的windows编译版本,感谢! 将下面这些库从上面的网址下载下来,解压 iconv-1.9.2.win32.zip1.3 MB

libxml2-2.7.8.win32.zip2.6 MB

libxmlsec-1.2.18.win32.zip967 kB

libxmlsec-nounicode-1.2.18.win32.zip951 kB

libxslt-1.1.26.win32.zip398 kB

openssl-0.9.8a.win32.zip2.4 MB

xsldbg-3.1.7.win32.zip688 kB

zlib-1.2.5.win32.zip169 kB

如要生成pdf,下载apache fop

http://xmlgraphics.apache.org/fop/

http://labs.mop.com/apache-mirror/xmlgraphics/fop/binaries/ http://labs.mop.com/apache-mirror/xmlgraphics/fop/binaries/fop-1.1-bin.zip

解压后将所有bin目录内容复制到一个目录下,我将其复制到D:docbookbin,并将该目录加入到系统的Path中。

在cmd中执行xsltproc如果没有报错,则环境准备正确。

写文档

建一个book.xml,这是文档内容。

用Docbook 5.0自动生成文档 Andy Zhou http://abloz.com
欢迎 欢迎您来到瀚海星空</link>。
HBase 0.95官方文档中文版 HBase 0.95官方文档中文版</link>有望放到HBase官方网站的链接中,期望更多的朋友加入翻译。 该文档也是Docbook写的,然后再编译成html或pdf版本的。

编辑docbook_zhh.xsl,这是html生成的样式规范

生成命令

D:docbookexample>xsltproc -o book.html docbook_zhh.xsl book.xml

book.html源码:

</tbody> </table> **html内容:** ## 用Docbook 5.0自动生成文档 ### Andy Zhou ### http://abloz.com * * * **目录** [欢迎](file:///D:/docbook/example/book.html#id532049) [HBase 0.95官方文档中文版](file:///D:/docbook/example/book.html#id531993) ## 欢迎 欢迎您来到[瀚海星空](http://abloz.com/)。 ## HBase 0.95官方文档中文版 [HBase 0.95官方文档中文版](http://abloz.com/hbase/book.html)有望放到HBase官方网站的链接中,期望更多的朋友加入翻译。 该文档也是Docbook写的,然后再编译成html或pdf版本的。

</td> </tr>
</td> </tr>
用Docbook 5.0自动生成文档
</head>
</td> </tr>
</td> </tr>
</td> </tr>

</td> </tr>

用Docbook 5.0自动生成文档</h2></div>

</td> </tr>

Andy Zhou
</h3></div></div>

http://abloz.com

</div>

</div>
</td> </tr>

目录

</td> </tr>
欢迎
HBase 0.95官方文档中文版
</dl>
</div>
</td> </tr>

</td> </tr>

欢迎</h2></div></div></div>

</td> </tr>

欢迎您来到瀚海星空
</p>
</div>
</td> </tr>

</td> </tr>

HBase 0.95官方文档中文版</h2></div></div></div>

</td> </tr>

HBase 0.95官方文档中文版有望放到HBase官方网站的链接中,期望更多的朋友加入翻译。
该文档也是Docbook写的,然后再编译成html或pdf版本的。
</p>
</div>
</div></body>
</html>

如非注明转载, 均为原创. 本站遵循知识共享CC协议,转载请注明来源