一个简单的Docbook 5.0例子

一个简单的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编译环境的搭建 ]

1. 下载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格式的样式表。

2. 下载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

   其实windows下配置docbook是相当的容易，以上四个工具缺一不可

   下载后，把这些包解压到同一个目录里，假设解压到C:\docbook\xsltproc目录，解压后，你可以看到在C:\docbook\xsltproc\下多了三个目录：bin，include和lib。现在需要在环境变量PATH中增加C:\docbook\xsltproc\bin，设置后，再打开一个DOS窗口，可以直接输入xsltproc命令，不需要输入使用全路径了。

3. 安装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源文档了。