一个简单的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

    下载后,把这些包解压到同一个目录里,假设解压到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='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的话,忽略告警即可,这些告警并不影响使用。

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源文档了。

“一个简单的Docbook 5.0例子”的24个回复

  1. Pingback: 用docbook写文档
  2. 请教个问题,写了一个article的docbook,里边有para标签,显示的时候,段落没有首行缩进,请问应该怎样设置。是不是查找对应的xsl文件,找到元素然后重写,但是xsl里边好复杂,找了好几天根本找不到。
    有说修改docbook.xsl里的indent参数为yes就行,但是也不行的。

  3. 能否有其他方式可以直接联系您,我这个真的很急,我在评论中留的是qq邮箱,您可以直接跟我联系,非常感谢!

  4. 谢谢博主,问题我已经解决了。不过现在又有新的问题了,我不知道怎样转成pdf文件,你能介绍的详细些吗?我看了“使用Apache FOP将Docbook文档转换成PDF”这篇文章,还是不知道该怎样弄,能知道一下吗?急!急!急!!!!!

  5. 首先谢谢你一个简单的Docbook 5.0例子提供的这个帖子,但是我按照你所说步骤进行设置了,但是总是提示我:warning:failed to load external entity “docbook_easwy.xsl”cannot parse docbookdocbook_easwy.xsl,请问这是哪里出了问题,谢谢!急!急!急!

  6. 请教两个问题:
    最新版的docbook-xsl-ns找不到docbook.xsl文件,好像你这个版本的也没有,另,编译的时候写的XML等文件放在哪里?
    先谢谢了。

  7. @湘倪~!
    你没把xsltproc所在的目录加到你的路径里。你要在环境变量PATH里加上xsltproc所在的目录,或者使用完整的路径来调用xsltproc。
    或者,你把xsltproc写成了sxltproc ^_^

  8. 弄了好久,就是不对,在cmd输入sxltproc,显示的是‘sxltproc’不是内部或外部命令,也不是可运行的程序或批文件处理。下面的就没办法继续下去,请问是哪里出了问题。谢谢···

  9. 看了两个小时终于把楼主的东西实现了,感觉挺有意思的。不过按楼主讲述的 以后编写文档那都应该得些两个文件的 xsl 和 xml, xml文件中包含自己想书写的文档内容吧?xsl 就是文档所要生成的样式?要是这样写文档就得了解xml 和 xsl了,对吧?

发表回复

您的电子邮箱地址不会被公开。 必填项已用 * 标注