一个简单的Docbook 5.0例子
我使用Docbook写文档大约才一两个月的时间，但关注Docbook已经很久了，在网上也阅读了很多中文及英文的Docbook文档。一直没用 Docbook的主要原因是Docbook 4.2的编译环境配置看起来很繁琐。我曾经尝试配置过一次，但看到一大堆catalog配置、SGML配置、OpenJade配置，最终放弃了。
直到有一天，我看到benr写的Playing With DocBook 5.0 ，才第一次真正书写Docbook文档。Docbook 5.0不再使用旧的SGML DTD，转而使用XML，编译环境配置简单多了。
下面我先介绍Windows下如何搭建Docbook 5.0编译环境，然后再以一个简单的Docbook 5.0文档为例，讲一下如何把Docbook文档转换成其它格式。
[ Windows下Docbook编译环境的搭建 ]
- 下载Docbook XSL样式表
首先下载Docbook XSL转换样式表 。我们只需要下载docbook-xsl-ns即可，目前的最新版本是1.74.3。下载后，把它解压到一个目录中，我这里假设解压到C:/docbook目录，也就是说，Docbook XSL所在的目录是: C:/docbook/docbook-xsl-ns-1.74.3/ 。
在Docbook介绍 一文中我讲过Docbook是”内容与格式分离”的，我们写Docbook文档时只关注文档的内容，而Docbook如何转换成其它文档类型，则由Docbook XSL转换样式表来定义。我们最常用的是转换到HTML格式的样式表，以及转换到FO格式的样式表。
- 下载xsltproc转换程序
接下来，需要下载XML语言转换工具。我喜欢用的转换工具是xsltproc ，这是一个由C语言写成的XML转换工具，它的特点是转换速度很快，并且同时支持Windows和Linux。除了这个转换工具外，还有很多Java写的转换工具，例如Saxon , Xalan 。
我们到这里下载Windows版本的xsltproc ，需要下载下面几个包：
- iconv-1.9.2.win32.zip - 编码转换工具
- zlib-1.2.3.win32.zip - 压缩工具
- libxslt-1.1.24.win32.zip - XSL和EXSL转换工具，xsltproc程序就在此包中
- libxml2-2.7.3.win32.zip - XML解析工具和处理工具，同时提供了验证工具xmllint和xmlcatalog
下载后，把这些包解压到同一个目录里，假设解压到C:/docbook/xsltproc 目录，解压后，你可以看到在C:/docbook/xsltproc/下多了三个目录：bin，include和lib。现在需要在环境变量PATH中增加C:/docbook/xsltproc/bin ，设置后，再打开一个DOS窗口，可以直接输入xsltproc命令，不需要输入使用全路径了。
- 安装FOP
安装了上面的两个工具，你就可以把Docbook文档转换成HTML格式了。如果你需要把Docbook文档转换成PDF格式，还需要安装把XSL-FO格式转换为PDF格式的转换工具，Apache FOP 是一个不错的选择。不过我现在没有这方面的需求，暂时没有安装。据说配置Apache FOP支持中文比较繁琐，改天我试过再把经过写出来。(2009/04/11更新，关于Apache FOP的配置，参见文章使用Apache FOP将Docbook文档转换成PDF (一)
现在，Docbook的编译环境就建好了。相比Docbook 4.2，编译环境的搭建容易了很多，你不必再去配置catalog这些东西，因为Docbook 5.0已经不再需要文档类型定义了。
接下来，我们写一个简单的Docbook文档。
[ 编写Docbook文档 ]
你可以在这里 下载本例中用到的文件，包括docbook.xml、docbook_easwy.xsl和Easwy的Makefile。
下面是一个简单的Docbook 5.0文档，把这段内容保存一下，例如，存为文件docbook.xml。
<?xml version='1.0' encoding="utf-8"?>
<article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="zh-CN"
xmlns:xlink='http://www.w3.org/1999/xlink'>
<articleinfo>
<title>我的第一篇Docbook 5.0文档</title>
<author>
<firstname>Easwy</firstname>
<surname>Yang</surname>
</author>
</articleinfo>
<section>
<title>文档介绍</title>
<para>
这是我的第一篇Docbook 5.0文档，欢迎你来到<link xlink:href='http://easwy.com/blog/'>Easwy的博客</link>。
</para>
</section>
</article>
[ 将文档转换成HTML格式 ]
在转换之前，要先把输出编码设置为UTF-8。docbook-xsl-ns的缺省输出编码是ISO-8859-1，但对于中文字符，我们应该把输出编码设置为UTF-8，否则输出的文件会显示为乱码。
更改输出编码很简单，你可以直接修改你的C:/docbook/docbook-xsl-ns-1.74.3/html/docbook.xsl文件，在文件中找到
<xsl:output method="html"
encoding="ISO-8859-1"
indent="no"/>
把它改成
<xsl:output method="html"
encoding="UTF-8"
indent="no"/>
我一般是另外写一个xsl文件，在这个文件中包含标准的docbook-xsl，然后重新定义自己的编码为UTF-8。把下面的文件保存为docbook_easwy.xsl：
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version='1.0'>
<xsl:include href="C:/docbook/docbook-xsl-ns-1.74.3/html/docbook.xsl"/>
<xsl:output method="html"
encoding="UTF-8"
indent="no"/>
</xsl:stylesheet>
接下来，我们把上面的Docbook文档转换成HTML格式，使用下面的命令：
xsltproc -o docbook.html docbook_easwy.xsl docbook.xml
如果你看到类似下面的提示，那么你的xsl不是docbook-xsl-ns，而是docbook-xsl。如果不想下载docbook-xsl-ns的话，忽略告警即可，这些告警并不影响使用。
1: Note: namesp. cut : stripped namespace before processing 我的第一篇Docbook 5.0文档
2: WARNING: cannot add @xml:base to node set root element. Relative paths may not work.
3: Note: namesp. cut : processing stripped document 我的第一篇Docbook 5.0文档
如果嫌每次输入转换命令太麻烦，可以把上面的命令保存为一个批处理文件。我在Windows里安装了Cygwin (参考这篇文章 安装cygwin)，所以一般用Makefile来转换Docbook源文件。我的Makefile内容如下：
# Docbook Makefile
# Easwy Yang
XSLFILE=docbook_easwy.xsl
XML_FILE=$(wildcard *.xml)
HTML_FILE=$(XML_FILE:.xml=.html)
.PHONY: html clean
html : $(HTML_FILE)
%.html : %.xml
xsltproc -o $(@F) $(XSLFILE) $<
clean:
rm *.html
现在，我在vim里可以直接使用:make 命令转换我的Docbook源文档了。