Docbook简介

Docbook简介

熊 伟
Senior R&D Engineer Linux

< netx@turbolinux.com.cn>

Abstract

本文介绍了docbook的基本概念，使用方法，Docbook的组织结构，文档解析过程，以及相关的XML知识。

背景知识

什么是docbook

简单说，docbook就是一组对于xml文档进行解析的规范。也就是说，对于一个按照docbook格式写好的xml文件，使用docbook的一些相关工具，就可以按照用户的要求生成各种各样的输出。顾名思义，docbook显然是主要针对book类型进行设计的，也就是说，专门为写书籍或者类似书籍的文档所设计的。当然，由于设计的灵活性，我们也可以使用docbook来制作其它的文档，例如网页。

既然通常是要用docbook来写一本书，那么书籍所具有的目录，索引，词条解释，附录，参考书目，甚至出版社，ISBN号码等等，在docbook中都有非常详细的规定。只需要在xml文件中引用这些规定好的条条框框，那么剩下的事情就是解析程序的事情了。

由于docbook采取了存储格式与显示格式的分离，因此，它具有下面几点显著的特色。

节省了排版等的时间，加快写作速度。
一次输入，多种输出。
便于多人同时进行编辑。

SGML,XML,DTD,StyleSheet和Docbook

通常介绍docbook都会牵涉到一大堆的概念，符号，术语，因此也较为难于理解。通常我们会遇到SGML,XML,DTD,StyleSheet等这样的词汇。本节会简要介绍一下这些相关的概念。

实际上，docbook和SGML,XML并不是直接相关的，它只是一个规范的集合，这个规范定义了怎么检查一个文档各个层次之间关系的合法性。例如：一本书的章节应该是累进的，举一个例子来说：显然任何一本书的第1.1小节应该包含在第1节的内部，显然不可能出现第1节包含在第1.1小节的情况发生，那么docbook规范中就采取了一些措施来保证你的文章不会出现上述的情况，如果出现上述情况的文档，在编译成为其它格式的文件，例如html,pdf等的时候，系统就会提示文档写的有错误。

另外，一本书，一篇文章，要让读者看起来很舒服，无论是转换成为什么格式，总是会有一定的排版格式的，当然，对于一本书，用html排版和使用pdf排版，无论是从外观上看，还是从技术的角度看，都是差别很大的，docbook对于文档转换成不同格式的文件时的排版格式也做了详细的规定。其实归结起来就是一句话：docbook规定了文档最后长什么样！

一本书的出版过程可以分为三步，下表列出了这些步骤以及每个步骤所相关联的工具：

写作—>纸、笔
校对—>校对人员
排版印刷—>排版软件

同样，从上面对于docbook规范的介绍来看，一个docbook的形成，也同样要经历相类似的三个阶段。只不过，在这些阶段中，相关联的工具不同罢了。

写作—>SGML,XML
校对—>DTD
排版印刷—>StyleSheet

从上面的类比可以看出来，一个完整的docbook的书写过程，应该是按照下面的过程来进行。

使用各种编辑器编辑SGML,XML文件。
使用DTD来对编写的XML文件进行检查。
使用StyleSheet从XML中生成所需要的文档格式。

SGML,XML简介

SGML和XML很相似，实际上，XML就是SGML改进版本，由于所有文档都由XML写成，这里就仅仅介绍XML了。XML包含四种基本的元素

<和>
element：项目
attributes：属性
entities：实体

对于前三项，一个简单的例子就可以说明全部的问题：

<sect1 id="analysis">

上面的例子中的sect1就是element，而id=“analysis”就是附着于sect1的一个attributes。关于entities，则情况要复杂一些。entities的定义如下所示：

<!ENTITY iw "I want dillon to raise my salary every month">

通常一个entities所表示的意义给一段的数据指定一个名称。那么在以后的使用中，如果遇到需要这个数据单元的时候，则只需要简单的使用&iw;就可以了。

这就是XML文件定义的全部了，由于XML定义的随意性，因此，XML具有很好的灵活性。只要符合XML的通用的几个规范，那么这个XML文件就是合法的。但是，如果一个XML仅仅具有灵活性而没有相应的约束，或者换一句话说，没有一定的格式来解释、检查XML文件的格式，那么显然这个XML是没有意义的。对于Docbook来说，现有的XML检查解释器就是DTD。

DTD简介

DTD的全称是Document Type Definitions。DTD通常是一组说明文件，这些文件内部包含了描述了一个XML文件内部的层次和分类的说明。一个典型的DTD文件组的结构图如下所示： Figure 1. DTD文件组织结构图 DTD文件组织结构图

对于T10D系统来说，可以在 /usr/share/sgml/docbook/xml-dtd-4.2-1.0-3 目录下找到类似图上的文件与目录结构，只不过所有的文件名称都增加了一个x，同时多了一个catalog文件。

这些不同的dtd和mod文件之间的组合，就可以保证对一个XML文件的检查，来确定这个文件是否符合docbook的规范。在这些文件集合中，有一个 ISO entity Sets，在T10D表现为一个目录ent，这里面存放这ISO定义的各种entity。所谓的entity就是对于不同的字符的一个全球统一的编号。在 ent目录下，任意打开一个文件，就可以看到这些定义。对于其它的文件，简要的举几个例子来进行说明。 docbook.dtd

这个文件是一个总控文件，用来集合其他的mod文件

*dbhier.mod 这个文件中定义了描述docbook中层次结构的各种规定，例如规定了book，sect，artical，chapter等等，同时也规定了各种层次之间的关系，例如book一定是sect和artical的外层等等一系列的关系。这些规定就将原来没有层次概念的xml文件进行了分层。 dbpool.mod 这个文件中定义了描述docbook中各种参考文献，注释，脚注等等的规格。 dbcent.mod**

这个文件中指定了docbook用到的各种ISO定义的entity。

对于这些DTD文件，其本身具有一套较为复杂的格式，(fix me)。由于本身XML就有很强的描述能力，因此，现在有一种新的项目是使用XML来重新定义DTD所定义的规则，同时对DTD进行扩充，这就是经常说的Schema（？）。

各种Docbook的工具对XML文件进行处理的时候，就是到相应的DTD目录下来寻找这些规则来对XML文件进行解析的。如果使用这些规则对于XML文件的解析没有问题，证明这个XML是符合docbook规范的，那么下一步就是将一定的StyleSheet指定给这个XML，用来将XML文件转换成为易于为读者阅读的格式。这就需要得到StyleSheet的各种规范了。

StyleSheet简介

StyleSheet?通常被成为样式表。可以想象，StyleSheet其实也和DTD类似，是一组规范，只不过，它是用来描述将XML转换成为什么形式的文档而已。以最终转换成为html为例，那么初始的XML文件内部必须加上<html>这样的标签，因为这是每一个html页面都必须这样作的。因此，对于不同的最终类型，都应该有一组规范。也就是说，对于html和man类型的转换，其规范显然也是不一样的。各种组织都提供不同的 StyleSheet?。通常使用的是从http://docbook.sourceforge.net/得到的StyleSheet。例如在T10D上，所有的StyleSheet都存储在 /usr/share/sgml/docbook/xsl-stylesheets 目录中。该目录的基本结构如下表所示：

Table 1.

common	公用的StyleSheet以及语言选择等
doc	文档
extensions	扩展的格式，以便供不同的解析器使用
fo	产生xlt-fo输出，便于生成pdf格式的输出
html	产生html格式输出的StyleSheet
manpages	产生man格式输出的StyleSheet
img	存储图表文件
lib	公用库

因此，需要什么样的输出，就可以到不同的目录中去寻找相匹配的StyleSheet。例如：如果需要从一个XML文件生成html的文件的话，就可以使用 html目录下的docbook.xsl样式表来帮助进行输出。当选定了样式表以后，就剩下最后的一步，选取一个合适的解析器，也就是一个程序，能够真正将上述的步骤一一实现，真正将一个XML文件变成我们所要的文档。解析器的选取

经常使用的对于XML格式进行解析的工具有三种：

Saxon：用java写成
Xalan：用java和C++写成
xsltproc：用C写成，最快

我们的文档系统都使用xsltproc进行转换，这个工具使用很方便，也很简洁，也就订立为我们的标准工具。xsltproc在T10D上是包 libxslt-1.0.33-1的一部分。这里要提醒的一点是，通常大家所熟悉的docbook2html等等系列工具都是为SGML格式文件转换所准备的，用他们来转换XML文件会出现很多的问题。到现在已经介绍了全部的XML类型的docbook相关的知识，再精彩的描述也不及一个简单的例子来的容易理解。下一节会用一个例子作为引子逐步讲解docbook的写法与生成方法。

制作docbook

hello, world

没有什么比hello,world更简单的例子了。首先第一步需要编辑一个XML文件，这个XML文件就是docbook的起点。这里特别要提醒的一点是编码的选择。 Note

由于docbook采用的unicode编码，所以要使用统一的UTF-8编码，这样才能保证在XML文件中输入的中文可以被解析，同时输出的时候不会出现乱码。切记，否则，敲打了半天的工作可能会浪费了。

下面是这个最简单例子的程序与部分的解释。

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article>
<articleinfo>
  <title>Hello World!</title>
</articleinfo>
<sect1><title>Hello World!</title>
  <para>
  Hello world! 这是我的第一个 DocBook 文档。
  </para>
</sect1>
</article>

首先要声明使用什么类型的DTD来对文件进行格式、合法性等的检查。同时指明XML文档的根标签。在这个例子中是article作为根标签。
每一个docbook都有一个根标签，docbook的所有实质性的内容都需要放置到这个根标签之中。常用的根标签有book，chapter，article等类型。最为常用的就是article类型的。
XML文件对于层次来说，最为重要与常用的就是<sect*>标签，这个标签标志了通常的‘节’的概念。一共可以有5个节，它们依次是sect1到sect5。其使用的层次结构也是嵌套的。
XML文件中最为常用的一个标签就是para，也就是平时所说的‘段落’。段落里面通常包含的就是文章的正文，但也可以包含表，图等信息。

有了上面的概念，那么剩下的事情就是将这个XML格式的docbook真正的输出成为可以为大家看到的一种格式了。例如要输出成为html格式的文档。首先保存这个xml文件，假设文件名为my.xml。如果在T10D环境下，则输入下面的命令行。

xsltproc /usr/share/sgml/docbook/xsl-stylesheets/html/docbook.xsl.xml my.xml > my.html

如果系统不提示任何的信息，则命令运行成功，可以用浏览器看看生成的my.html是什么样子 my.html。但是在这里，xsltproc命令并没有使用什么DTD信息，仅仅是给定了样式表就生成了所需要的文件，那么DTD到底是怎么作用到XML文件上的呢？对于不同的系统，这个DTD的解析过程可能会有所不同，但大体的过程应该是类似的，现在就以T10D的解析过程来作一个讲解。

xslpproc会使用环境变量XML_CATALOG_FILES来寻找自己DTD，如果这个环境变量没有设置的话，就会到 /etc/xml 目录下寻找catalog文件。通常环境变量XML_CATALOG_FILES是没有被设置的，因此，catalog就是xsltproc所依赖的寻找DTD的地图。catalog本身就是一个XML格式的文件，它指定了这个机器上所有DTD所在的位置。实际上，“位置”这个词并不是很准确，catalog中的内容指向的实际上是另外的一个地图。例如对于XML格式的docbook，catalog中指向的是一个文件/usr/share/sgml/docbook/xmlcatalog。下面是文件中的片段:

<delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML" catalog="file:///usr/share/sgml/docbook/xmlcatalog"/>

实际上xmlcatalog也是一个catalog文件，仍然是一个“地图”。在这个文件中，有下面的两行：

<public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" uri="xml-dtd-4.1.2-1.0-3/docbookx.dtd"/>
<public publicId="-//OASIS//DTD DocBook XML V4.2//EN" uri="xml-dtd-4.2-1.0-3/docbookx.dtd"/>

现在，对照一下my.xml的第一行，所有的过程就一目了然了。有了上面的介绍，大部分的docbook都应该可以看懂了。一些注意点

docbook的书写还是很简单的，在很短的时间内就可以掌握，如果想作的很好，当然有很多东西需要阅读，但是对于写一些技术文档，一些基本的标签就够了。下面就对一些常用的标签以及注意事项做一个简要的介绍。特殊符号

在docbook的定义中，有四个字符是特殊的字符，必须配合转义字符才能被使用的。

Table 2.

特殊字符	转义字符组
&	&mp;
<	<
>	>
”	"

消除特殊字符功能

特殊字符存在主要是为了规避和XML文件中标签等定义的冲突，但是，如果想引用一段诸如html文件的内容，如果要一个个去用转义字符组去替换特殊字符，则太麻烦了，因此有一种消除特殊字符功能的标签可以做到。如下面的例子：

  <literallayout>
   <![CDATA[
     <chapter><title>标题</title>
      <para>段落</para>
     </chapter>
  ]]>
  </literallayout>

其运行结果是：

<chapter><title>标题</title>
<para>段落</para>
</chapter>

标签简表

Table 3.

实现的功能	相关标签
表格	table,tgroup,thread,tbody,row,entry
图形	graphic,figure
链接，邮箱，书签等	link,olink,ulink,xref
脚注	footnote,footnoteref
程序相关	programlisting，funcdef
其他常用的标签	screen

参考资料

请不断进行充实网上的资料