一个简单的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的编译环境就建好了。相比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='https://blog.easwy.com/'>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的话，忽略告警即可，这些告警并不影响使用。

如果嫌每次输入转换命令太麻烦，可以把上面的命令保存为一个批处理文件。我在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源文档了。