DocBook学习(v1.6.7)
DocBook学习
修订版本 1.6.7(http://www.xiaowang.net/doc/docbook/)
版权 © 2005 limodou
本文档还在不停地写作、完善中，如果你有什么建议请与limodou联系。
本教程提供源码下载，大家可以下载源码在你的机器上进行测试。关于下载及转换见附录 A, 关于本教程。
本文档版权所有者为limodou。你可以自由发布，引用，拷贝，但要保留此版权声明。
感谢 leasun 指出2.5节和2.16的错误。
特别感谢 1.6.6 版是在老康的帮助下完成的，不仅有好的建议，还帮助我改进了许多地方。
感谢 xuejm 指出2.5节的错误。
感谢 jxb 指出2.5节的错误。
感谢 Alex Dong 指出3.1节的错误。
目录
从这里开始学习DocBook
DocBook是什么？有什么用？我不想在这方面过多地叙述了。从现在开始，我只是想和大家一起来学习如何使用DocBook来进行写作。我会通过如何写一个Book来和大家一起学习。我会一点点地增加使用的element(元素)，从而使这个Book丰富起来。因此这篇文档是在不停的写作中，如果想要了解最新的内容，请访问我的Blog：limodou的学习记录。
这里所讨论的DocBook都是以XML为前提的，关于SGML的内容在这里不涉及。同时有关XML的知识如果可能我会加以说明，一些基础知识还请大家看一下有关资料。因此学习本教程希望你有一些XML的知识。
对于DocBook我经验也不丰富，之所以写这个教程主要是想把我所学过的东西拿出来与大家分享。因此这个教程一定有不足和错误的地方，希望大家指出来，以便我进行改正，从而使本教程变得实用。
第 1 章 DocBook Book 结构
目录
1.1. 一个Book示例
例 1.1. 一个Book示例
<?xml version="1.0" encoding="gb2312"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book>
<bookinfo>
<title>DocBook 学习</title>
<author>
<othername>limodou</othername>
</author>
</bookinfo>
<chapter>
<title> ... </title>
<sect1> ... </sect1>
</chapter>
<chapter>
<title> ... </title>
<sect1> ... </sect1>
</chapter>
</book>
XML文档声明。encoding为xml文档所用编码。一个XML文档必须要有声明，而且这个声明必须是文档的开始。即声明前不能有任何内容，包括空白。
DTD声明。DTD是用于对XML文档合法性进行检查用的，全称是Document Type Definition。这里大家照猫画虎即可。不过要注意地是DOCTYPE后面跟着的是XML文档的根元素，这里就是book了。
XML文档的根元素。从这里开始进入内容部分。前面的内容可以叫作“引言”。
关于Book的Meta信息。如：title、author等。这个例子中，只用到了title和author。其中，作者的名字使用了othername，这是因为我不想把名和姓分开的缘故。
第一章开始。DocBook对于象chapter、example之类可以自动编号。
章的标题。
许多element都有title，如：book、chapter等。
第一章的第一节。也是可以自动编号。
上面就是一个Book的简单样子，我会逐步改造它，使它变得越来越丰富。
1.2. 多个物理文档
XML文档允许你将一个大文档拆分成多个文档。你看到的本教程就是一个例子。下面给出一个分成两个文件的例子。
例 1.2. 多文件示例
这是主文件，起名为main.xml
<?xml version="1.0" encoding="gb2312"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY chapter1 SYSTEM "chapter1.xml">
]>
<book>
<bookinfo>
<title>DocBook 学习</title>
<author>
<othername>limodou</othername>
</author>
<para>这是一个演示多文档的示例。</para>
</bookinfo>
&chapter1;
<chapter id="chapter.2">
<title>标题</title>
<sect1> ... </sect1>
</chapter>
</book>
通过定义一个entity(实体)来引入一个外部文件。
在book中的bookinfo元素中也可以有para内容。
在此处插入chapter1.xml的内容。在使用一个实体时，前面是一个&，然后是实体名字，后面跟着分号(;)。
其本上所有的元素都有id属性。这个id属性可以被其它element进行引用。
下面是次文件，文件名为chapter1.xml
<?xml version="1.0" encoding="gb2312"?>
<chapter id="bookstru">
<title>标题</title>
<sect1> ... </sect1>
</chapter>
chapter1.xml文件不需要也不可以包含DTD声明。
以上就是一个多文档的例子，你可以将内容安排在不同的文档中，然后通过一个主文档将它们组织起来。
1.3. 块元素 vs. 环境
块元素(Block element)是一个容器，它可以包含其它的子元素和块元素(当然有些是有限制的)。关于块元素可以包含哪些子元素和块元素，这些都在DTD中有介绍。
环境不是DocBook的概念，是我的创造。因为块元素这个概念给人一种大小上的感觉。因此为了突出块元素在上下文环境中的作用和所代表的语义概念，我提出了环境这一说法，按我的定义就是：环境是在上下文中具有特定语义的块元素及其子元素的集合。这样提到环境时，就不再孤立地只提到某种块元素，同时还包括了它的语义，和它所包含的内容。
第 2 章 常见环境介绍
目录
2.1. 章、节、段
chapter(章)
可以带一个title子element，用来书写章的标题。
section(节)
可以带一个title子element，用来书写节的标题。
section可以有多种形式：
· 带序号的section：sect1...sect5
· 不带序号的section：section
· 其它几种形式
para(段)
用来书写内容。
上面三种环境是依次包含的。
例 2.1. chapter,section,para举例
<chapter id="bookstru">
<title>&docbook; Book 结构</title>
<sect1 id="sect.1.1">
<title>一个Book示例</title>
<para>内容放在这里</para>
</sect1>
</chapter>
2.2. 使用entity做为宏替换
在写作过程中，有一些单词可能要经常输入，那么你可以使用entity来表示它们。这样在需要的地方使用entity就可以方便地输入这些内容了。如果以后对内容修改，只要修改实体定义部分即可，不用全文替换，很方便。
其实关于entity的定义，在第 1.2 节 “多个物理文档”中已经用过了，不过那个定义是引用外部文件。一般entity的定义可以象：
<!ENTITY xml "<acronym>XML</acronym>">
这里定义了一个entity，叫xml，它的值为"<acronym>XML</acronym>"。使用这个实体时可以将&xml;插入到任何想要输入"<acronym>XML</acronym>"的地方。xslt处理器对entity的处理相当于先要进行替换操作，然后再进行分析。因此如果想在entity中使<被处理成字符，而不是XML中标记的开始字符，那么要用<的实体形式<。
例 2.2. 使用entity的例子
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[
<!ENTITY % entities SYSTEM "entities.xml">
%entities;
<!ENTITY xml "<acronym>XML</acronym>">
<!ENTITY ent "<acronym>XML</acronym>">
]>
<article>
<para>use &xml;(&xml;)</para>
<para>use &ent;(&ent;)</para>
</article>
输出结果为：
use &xml;(XML)
use &ent;(<acronym>XML</acronym>)
如果你仔细地话，你还会看到上面DTD声明中有些特殊的entity定义。
<!ENTITY % entities SYSTEM "entities.xml">
%entities;
在entity名entities前有一个百分号(%)，并且后面还使用了SYSTEM定义。下面紧接着对这个entity的引用，不过前面不是&而是%。这个有点象在DocBook正文里面使用的引用文件的entity，它与正文中使用的entity的区别在于：
上面的entity定义表示引用外部entity集(属于DTD的一部分)。使用时用%entities;。而在正文中引用的是正文片断，不是DTD片断。
这样我们可以将entity定义放在单独的文件中统一进行维护。
2.3. 例子
在写文章时，我们经常要举例，这时我们要使用example环境。
例 2.3. 如何生成一个例子
<example>
<title>例子标题</title>
<para>内容</para>
</example>
一个例子的块元素是example，一般要有一个title，然后是它的内容。
例子在使用时会自动根据所处的章节进行编号。
2.4. 图形
2.4.1. 使用figure环境
使用figure环境可以自动进行编号。
例 2.4. 使用了graphic元素的figure
<figure><title>图形示例</title>
<graphic fileref="figures/test.png"/>
</figure>
这里使用了graphic子元素。在DocBook: The Definitive Guide中介绍此元素将在DocBook DTD 5.0版中被mediaobject所代替。
例 2.5. 使用了mediaobject元素的figure
<figure><title>图形示例</title>
<mediaobject>
<imageobject>
<imagedata fileref='figures/test.png'/>
</imageobject>
</mediaobject>
</figure>
2.5. 代码片段
使用programlisting环境。你可以在文章中引用代码片段，片段的显示是采用等宽字体来显示的。
例 2.6. 引入代码片段
<programlisting>
#include <stdio.h>
int main()
{
printf("hello, world.\n");
}
</programlisting>
象上面，如果要使用<，则应该使用它的实体形式<。>可以不进行转换。
如果你不想进行转换，还有一种方式是使用CDATA节[1]。
<programlisting><![CDATA[
#include <stdio.h>
int main()
{
printf("hello, world.\n");
}]]>
</programlisting>
[1] CDATA中的内容，如<, >, ", ', &等全部被当作字符来看来，XML处理器不会对它们进行解释。一个CDATA节以“<![CDATA[”开始，以“]]>”结束。
2.6. 屏幕输出
使用screen环境。当你需要显示屏幕文本输出时，可以使用这一环境。
例 2.7. 文本屏幕输出
<screen>
Volume in drive C is SYSTEM Serial number is 2350:717C
Directory of C:
10/17/97 9:04 <DIR> bin
10/16/97 14:11 <DIR> DOS
10/16/97 14:40 <DIR> Program Files
10/16/97 14:46 <DIR> TEMP
10/17/97 9:04 <DIR> tmp
10/16/97 14:37 <DIR> WINNT
10/16/97 14:25 119 AUTOEXEC.BAT
2/13/94 6:21 54,619 COMMAND.COM
10/16/97 14:25 115 CONFIG.SYS
11/16/97 17:17 61,865,984 pagefile.sys
2/13/94 6:21 9,349 WINA20.386
</screen>
这里对'<'之类的符号的处理同programlisting。
如果想要显示屏幕截屏，则可以使用screenshot环境。
<screenshot>
<graphic fileref="test.gif"/>
</screenshot>
在screenshot环境中可以包含graphic和mediaobject元素。
2.7. 编号图形
你在本教程的例 1.1 “一个Book示例”中可以看到，在某些代码行前面有一个编号的小图形，同时在下面有对这些点的解释。如果在你的文档中想使用这种效果，要使用calloutlist环境。
例 2.8. 编号图形示例
<programlisting>
<co id="co.1.1.1"/><?xml version="1.0" encoding="gb2312"?>
<co id="co.1.1.2"/><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<co id="co.1.1.3"/><book>
<co id="co.1.1.4"/><bookinfo>
<title>DocBook 学习</title>
<author>
<othername>limodou</othername>
</author>
</bookinfo>
<co id="co.1.1.5"/><chapter>
<co id="co.1.1.6"/><title> ... </title>
<co id="co.1.1.7"/><sect1> ... </sect1>
</chapter>
<chapter>
<title> ... </title>
<sect1> ... </sect1>
</chapter>
</book>
</programlisting>
<calloutlist>
<callout arearefs="co.1.1.1">
<para>&xml;文档声明。<literal>encoding</literal>为xml文档所用编码。一个&xml;文档必须要有声明，而且这个声明必须是文档的开始。即声明前不能有任何内容，包括空白。</para>
</callout>
</calloutlist>
programlisting环境开始。
使用co元素来定义一个小图形的插入点。图形上的数字会依次递增。要定义id属性。
calloutlist环境开始。
定义一个解释。需要在arearefs属性中对前面定义的编号进行引用。
对此编号的解释。
2.8. 脚注
使用脚注要使用footnote环境。
在footnote环境下不能直接输入文本，要加入para元素才可以。
例 2.9. 脚注示例
<para>这是一个脚注的示例<footnote><para>在footnote中不能直接输入文本，
要在para元素中输入。</para></footnote>。</para>
2.9. 列表
列表是按顺序列出某些条目，分为有序与无序。
2.9.1. 无序列表
无序列表的每一项前有一个圆点或圆圈。使用itemizedlist环境。
例 2.10. 无序列表
<itemizedlist>
<listitem><para>项目一</para></listitem>
<listitem><para>项目二</para></listitem>
</itemizedlist>
每项内容放在listitem元素中。
listitem元素中不能直接输入文本，可以使用para元素。
输出结果为：
· 项目一
· 项目二
itemizedlist元素的mark属性可以指定几种项前的符号[2]：opencircle, bullet, box。
如果在listitem中指定override属性为上面的取值，可以修改当前项的符号。
例 2.11. 改变项前的符号
<itemizedlist mark="opencircle">
<listitem><para>项目一</para></listitem>
<listitem override="bullet"><para>项目二</para></listitem>
<listitem override="box"><para>项目三</para></listitem>
</itemizedlist>
输出结果为：
o 项目一
· 项目二
§ 项目三
2.9.2. 有序列表
有序列表使用的是orderedlist环境。
例 2.12. 有序列表示例
<orderedlist numeration="lowerroman">
<listitem>
<para>One</para>
</listitem>
<listitem>
<para>Two</para>
</listitem>
</orderedlist>
输出结果为：
i. One
ii. Two
orderedlist元素的numeration属性可以选择：lowerroman(小写罗马数字), upperroman(大写罗马数字), loweralpha(小写字母), upperalpha(大写字母), arabic(阿拉伯数字)以显示不同的编号。
2.9.3. 定义列表
用于描述一系列的名词解释。
例 2.13. 定义列表示例
<variablelist>
<varlistentry>
<term><filename>TTF</filename></term>
<listitem><para>TrueType fonts.</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>PFA</filename></term>
<term><filename>PFB</filename></term>
<listitem><para>PostScript fonts. <filename>PFA</filename> files are common on
<acronym>UNIX</acronym> systems, <filename>PFB</filename> files
are more common on Windows systems.</para></listitem>
</varlistentry>
</variablelist>
输出结果为：
TTF
TrueType fonts.
PFA , PFB
PostScript fonts. PFA files are common on UNIX systems, PFB files are more common on Windows systems.
[2] 这里我只是生成HTML时是可用的，别的没试。
2.10. 表格
生成一个表格要使用table环境。
2.10.1. 表格基础
例 2.14. 一个表格例子
<table frame="topbot" align="left">
<title>表格标题<title>
<tgroup cols="2">
<colspec colname="c1"/>
<colspec colname="c2"/>
<thead>
<row>
<entry>属性</entry>
<entry>取值</entry>
</row>
</thead>
<tbody>
<row>
<entry>frame</entry>
<entry><para>边框</para></entry>
</row>
<row>
<entry>c1</entry>
<entry>c4</entry>
</row>
<row>
<entry>d1</entry>
<entry>d4</entry>
</row>
</tbody>
</tgroup>
</table>
表格开始元素。table元素有许多的属性，常用属性如下：
frame
frame用于指明表格四周的边框。不包括单元格的边框。
属性值
含义
all
显示表格的四条边。
bottom
只显示表格的底边。
none
不显示表格边框。
top
只显示表格的上框。
topbot
只显示表格的上框和底框。
align
指定整个表格文本的对齐方式。取值可以为：left(左对齐), center(居中), right(右对齐)。
表格内容的封装体。它的属性值cols用来表示表格有多少列。它有thead, tbody, tfoot三个子元素，分别表示表头，表体和表尾。
用于指明每列的属性。常用属性如下：
colsep
用于指定每列之间是否有分隔线。如果为"0"则无分隔线，为"1"有分隔线。
colname
为当前列起一个名字。
colnum
为当前列编一个号。
colwidth
为当前列指定宽度。一般的形式是数字加"*"号。"1*"表示基准宽度。"n*"表示是基准宽度的n倍。
rowsep
用于指定本列的单元格间是否有分隔线。如果为"0"则无分隔线，为"1"有分隔线。
align
用于指定本列的文本对齐方式。属性值有：left, center, right。
thead用于指明表头。常用属性为：
valign
用于指定表头文本的垂直对齐方式。属性值有：bottom, middle, top。
row表示一行数据。还有一种与HTML兼容的tr。
当前行的一个单元格数据。常用属性如下：
rowsep, colsep
rowsep指定此单元格与下一个单元格之间是否有分隔线。colsep指定此单元格与右一单元格之间是否有分隔线。如果为"0"则无分隔线，为"1"有分隔线。
spanname
按spanname定义的跨度将单元格进行融合。spanname是在spanspec中定义。后面将会有解释。
align, valign
单元格文本的水平、垂直对齐方式。取值同上面。
namest, nameend
两者合起来表示单元格的横向融合。namest用来指明融合的开始列的名字，nameend指用融合的结束列的名字。
是名字而不是编号。
morerows
用于单元格的融合，表示将当前单元格与其下单元格按指定行数进行融合。如：morerows为2，则会将当前单元格与下两行单元格进行融合，也就是三个变成了一个。
表格体。
2.10.2. 横向融合
例 2.15. 横向融合示例
<table frame="all">
<title/>
<tgroup cols="3" align="left">
<colspec colnum="1" colname="c1" colwidth="1*"/>
<colspec colnum="2" colname="c2" colwidth="3*"/>
<colspec colnum="3" colname="c3" colwidth="8*"/>
<thead>
<row>
<entry>a</entry>
<entry>b</entry>
<entry>c</entry>
</row>
</thead>
<tbody>
<row>
<entry>d</entry>
<entry namest="c2" nameend="c3">e</entry>
</row>
<row>
<entry>g</entry>
<entry>h</entry>
<entry>i</entry>
</row>
<row>
<entry>g</entry>
<entry>k</entry>
<entry>l</entry>
</row>
</tbody>
</tgroup>
</table>
输出结果：
a
b
c
d
e
g
h
i
j
k
l
通过在单元格中指定namest和nameend属性将单元格进行横向融合。
2.10.3. 纵向融合
例 2.16. 纵向融合示例
<table frame="all">
<title/>
<tgroup cols="3" align="left">
<colspec colnum="1" colname="c1" colwidth="1*"/>
<colspec colnum="2" colname="c2" colwidth="3*"/>
<colspec colnum="3" colname="c3" colwidth="8*"/>
<thead>
<row>
<entry>a</entry>
<entry>b</entry>
<entry>c</entry>
</row>
</thead>
<tbody>
<row>
<entry>d</entry>
<entry morerows="1">e</entry>
<entry>f</entry>
</row>
<row>
<entry>g</entry>
<entry>i</entry>
</row>
<row>
<entry>g</entry>
<entry>k</entry>
<entry>l</entry>
</row>
</tbody>
</tgroup>
</table>
处理结果为：
a
b
c
d
e
f
g
i
j
k
l
这里使用morerows属性。
2.11. 处理过程
使用procedure环境。处理过程表示一系列的操作步骤，如表示软件的安装过程。
例 2.17. 处理过程例子
<procedure><title>处理过程例子</title>
<step>
<para>第一步</para>
</step>
<step>
<para>第二步</para>
<substeps>
<step>
<para>子步骤可以任意嵌套。</para>
</step>
</substeps>
</step>
<step>
<para>最后一步</para>
</step>
</procedure>
输出结果为：
过程 2.1. 处理过程例子
1. 第一步
2. 第二步
a. 子步骤可以任意嵌套。
3. 最后一步
2.12. 链接
链接是表示一个连接到其它文档的一个点。它有几种形式。
ulink
一般要使用它的url属性。
例 2.18. ulink举例
<ulink url="http://pyrecord.freezope.org/docbook/index.html"><citetitle>DocBook学习</citetitle></ulink>
<ulink url="http://diveintopython.org"/>
结果如下：
引用文档：DocBook学习。链接站点： http://diveintopython.org
此处还使用了citetitle标记，它表示引用一个标题。一般产生的效果就是斜体。引用文档可以使用这种方式。
ulink中没有包括任何文字。因此会将url属性值作为包括的内容。
link
通用的链接元素。
例 2.19. link举例
<link linkend="bookstru">引用第一章</link>
<link linkend="bookstru" endterm="sect.1.1.title"/>
结果如下：
linkend属性表示链接到哪个元素的id上去。因为id要求是唯一的，每个元素的id必须不同。link所包含的文字会显示为链接。本例为链到第一章的链接。
endterm表示链接文字用那个id的元素内容进行显示。这样做的效果就是把指定id的元素的内容显示为链接文本。本例为链到第一章的链接，但链接文字使用了第一章第一节的标题。
如果不想使用某个元素定义的id，而是想引用任意位置该怎么办呢？可以使用anchor元素，在其中设置它的id属性即可。
例 2.20. 设置锚点(链接点)
<para>这是一个测试用例。这里<anchor id="anchor.1"/>是一个anchor。</para>
这样就设置了一个anchor，在后面就可以使用link对其进行链接了。
xref
它与link类似，不同之处它是一个空元素[3]。它的链接文本是通过处理器根据指定id元素的内容生成的。
例 2.21. xref示例
<xref linkend="bookstru" endterm="sect.1.1.title"/>
运行结果为：一个Book示例
[3] 空元素不是成对的，它只有属性，不包含内容。形如：<anchor id="id.1"/>。
2.13. 块引用
块引用使用blockquote环境。用来引述别人的内容。如果加入attribution元素，则可以表示引述他人说过的话。
例 2.22. 块引用
<blockquote>
<attribution>Richard Dawkins</attribution>
<para>The universe that we observe has precisely the properties we should
expect if there is, at bottom, no design, no purpose, no evil and
no good, nothing but pitiless indifference.</para>
</blockquote>
运行结果：
The universe that we observe has precisely the properties we should expect if there is, at bottom, no design, no purpose, no evil and no good, nothing but pitiless indifference.
--Richard Dawkins
2.14. 常见inline元素
inline元素是指不会引起换行的元素，它主要是指定一个单词或一个短语的特殊含义，通常的效果是引起字体发生变化，当然也可能没有变化。下面列出常见的inline元素，大家可以选择性的使用。有些inline元素还带有属性，请大家参考DocBook:The Definitive Guide。
元素名
含义
示例
abbrev
略写，一般后面带有一个点('.')
i.e.
emphasis
强调
强调
phrase
短语
短语
quote
用引号引起来
“文字”
trademark
注册商标
Intel™
literal
文字的字面含义
tag
sgmltag
sgml标记
table
prompt
提示符
c:>
userinput
用户输入
build.bat
subscript
下标
H2O
superscript
上标
x2
application
软件名
python
command
命令
rm
envar
环境变量
PATH
filename
文件名
autoexec.bat
database
数据库
Informix
电子邮件
2.15. 附录
生成附录要使用appendix环境。一个附录包含title，还包含内容。内容可以有很多，如：一般性文字，术语表，参考书目等。
2.15.1. 术语表
术语表一般使用glossary环境，它需要单独的title。在附录中使用它并不需要定义它，只需直接使用glossentry元素即可。
例 2.23. 术语表例子
<glossentry id="xml">
<glossterm>XML</glossterm>
<glossdef><para>可扩展标记语言。</para>
</glossdef>
</glossentry>
一个术语项定义。属性id可以用来作为引用点。在文章中可以使用glossterm来定义一个术语引用项，如：<glossterm linkend="xml">xml</glossterm>。这样就生成一个指向xml定义的一个链接。
术语名称
术语的解释。
2.15.2. 参考书目
参考书目一般使用bibliography环境，它需要单独的title。在附录中使用时不需要定义它，只需直接使用biblioentry元素即可。
例 2.24. 参考书目例子
<biblioentry>
<title>DocBook:The Definitive Guide</title>
<publisher>
<publishername>O'Reilly & Associates, Inc.</publishername>
</publisher>
<authorgroup>
<author><othername>Norman Walsh</othername>
</author>
<author><othername>Leonard Muellner</othername>
</author>
</authorgroup>
</biblioentry>
书名。
出版者信息。
作者
本例所举的环境中，还有许多元素，这里不过是简化了。
2.15.3. 修订历史
修订历史用来记录对信息修改的历史。它使用revhistory环境。
例 2.25. 修订历史例子
<revhistory>
<revision>
<revnumber>1.0</revnumber>
<date>2004-03-17</date>
<revdescription>
<itemizedlist>
<listitem><para>增加 <xref linkend="sect.2.10"/></para></listitem>
<listitem><para>增加 <xref linkend="sect.2.11"/></para></listitem>
</itemizedlist>
</revdescription>
</revision>
</revhistory>
一个修订记录。
修订版本号
修订日期
本修订的描述。这里使用了无序列表来列出每个修改点。
2.16. 警告信息
在DocBook中有许多的警告类的信息，它们被用在不同的场合，都是表示一种警告性的信息。它们的格式都一样，就是元素名不同。有： important, caution, tip, note, warning等。
例 2.26. tip示例
tip一般表示一个技巧，窍门。其它警告信息格式与此相同。
<tip><title>标题</title><para>内容</para></tip>
标题是必须的，但可以为空。如果为空则一般会显示相应的警告种类 [4]。本例可能为：tip。
各种警告的图形显示结果：
tip
caution
important
note
warning
[4] 不过如果警告是以图形方式显示的，则标题不会显示出来。
第 3 章 输出HTML
目录
本章用来介绍如何将DocBook转换成HTML的过程。本人只使用过Saxon，因此目前只有关于Saxon的使用说明。有些内容在我以前所写的Saxon实践中有所提及，但某些技术的使用已经有所不同（指本人所使）。因此建议大家使用本教程中所运用的技术。
本人所使用的环境是在windows下，请大家注意根据各自的环境做相应的调整。
3.1. 环境准备
过程 3.1. 环境准备
1. 软件下载
· Java JDK 1.4.2或者更高下载。因为Saxon是Java程序，因此建议大家安装最新的JDK工具。大家可以去http://java.sun.com/getjava/下载。
· Saxon下载。可以从http://saxon.sourceforge.net下载。我使用的Saxon版本为6.5.1开发版本。(老康已经在6.5.3上测试通过)
· DocBook DTD。可以从http://www.oasis-open.org/docbook/xml/下载。现在用得最多的是4.2版本。可以使用最新的4.5b1版，5.0版DTD正在制定中。
· DocBook XSLT。可以从http://sourceforge.net/projects/docbook/下载。可以使用最新的xsl-1.69版。
2. 软件安装
· Java安装没什么可说的。执行安装文件即可。然后要在环境变量PATH中增加Java JDK 1.4.2或者更高/bin目录，以便在命令行执行时能够找到Java程序。
· 建立工作环境。在我的机器上，我建立了一个子目录d:\docbook，所有相关的东西全放在这个目录下。然后建立工作子目录src，用于存放我的XML文件。
· 安装Saxon。将Saxon解压在d:\docbook下，目录名改为saxon即可。
· 安装DocBook DTD 4.2。将压缩包解压在d:\docbook下，目录名改为docbook-xml即可。
· 安装DocBook XSLT。将压缩包解压在d:\docbook下，目录名改为docbook-xsl即可。
· 在d:\docbook下建立批处理文件：build.bat。
最后的目录结构图如下：
d:\docbook
|-docbook-xml
|-docbook-xsl
|-saxon
|-src
批处理文件(build.bat)内容为：
set CLASSPATH=..\saxon\saxoncatalog.jar
set CLASSPATH=%CLASSPATH%;..\saxon\saxon.jar
set CLASSPATH=%CLASSPATH%;..\docbook-xsl\extensions\saxon651.jar
java -classpath %CLASSPATH% -Dxml.catalog.files=catalog
com.icl.saxon.StyleSheet -x cz.kosek.CatalogXMLReader
%1 %2 %3 %4 %5 %6
第三行是用来设置xslt扩展功能的。这个 saxon651.jar不是安装Saxon包所带的，而是docbook-xsl自带的。在docbook-xsl的extensions目录下你会看到好多扩展包，光Saxon的就好几个，我使用了 saxon651.jar这个版本。
3. 其它东西
在build.bat中有一个saxoncatalog.jar[5]文件。这是用来将公共DTD映射成本地DTD的一个Java包。因为我的文档都使用了公共DTD，因此在转换时需要它。使用时还需要一个CATALOG文件。如果你需要saxoncatalog.jar，可以从这里下载。下载后的文件放在Saxon目录中即可。
我的CATALOG文件内容如下：
PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "../docbook-xml/docbookx.dtd"
PUBLIC "-//OASIS//DTD DocBook CALS Table Model V4.2//EN"
"../docbook-xml/calstblx.dtd"
最后一行过长处理为两行，其实应该是一行。
这里本地文件名都使用了URI的写法。在你的机器上改成相应的内容即可。此文件在我的环境下是放在d:\docbook目录下的。
这样我们就可以开始我们的工作了。
[5] 这里有一篇文章是关于如何在Saxon中使用CATALOG的。Adding catalog support into Saxon
3.2. xslt参数的使用
param(参数)在xslt转换样式表中用得很多，它的主要作用相当于函数中的参数一样，在xslt样式表中做为template(模板)过程的参数。在模板处理时，可以指定参数值，从而改变模板过程输出的结果。你不太明白没关系，只要知道，在DocBook的转换中(即将XML转换为其它格式)，通过指定参数就可以改变输出结果。在解开的docbook-xslt压缩包中的doc子目录下就有详细的参数说明，详细列出了在xslt中用到的参数的说明。在这里只介绍我用过的一些参数，请参阅xslt的文档以了解更多关于参数的信息，从而调整你的输出结果。
3.2.1. 在命令行中指定参数
参数可以在命令行中指定
例 3.1. 命令行中指定参数
java -classpath %CLASSPATH% com.icl.saxon.StyleSheet -o myfile.html
myfile.xml myfile.xsl use.extensions=1
其中use.extensions=1就是我们所指定的参数。等号前是参数名，等号后是参数值。如果有多个参数则依次列出来即可，中间用空格分开。
那么当参数很多时，都放在命令行上就不方便了，那么这时我们可以使用驱动样式表文件。把要用的参数放在这个样式表中就很方便了。
3.2.2. 在驱动样式表中使用参数
为什么叫驱动样式表，因为它不是真正包含转换信息的xslt样式表，而是一个封装。比如我们要将XML文档转换成多个HTML文件，那么我们就要用过下载的docbook-xslt中的html/chunk.xsl转换样式表。可是我们还有一些特殊的要求，因此要用到参数。因为docbokk样式表是一个标准，所以不能修改它，那么我们可以自已写一个样式表，在其中调用它，然后再加入我们要用到的参数即可。因此它的作用只是起到一个引导的作用，所以叫驱动样式表。
下面是我为了生成本教程所用到的驱动样式表内容，看不懂没关系，一会儿我们就会讲到它：
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="../docbook-xsl/html/chunk.xsl"/>
<xsl:param name="saxon.character.representation" select="'native'"/>
<xsl:param name="l10n.gentext.language" select="'zh_cn'"/>
<xsl:param name="admon.graphics" select="1"/>
<xsl:param name="base.dir" select="'html/'"/>
<xsl:param name="chunker.output.indent" select="'yes'"/>
<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="section.label.includes.component.label" select="1"/>
<xsl:param name="html.stylesheet" select="'docbook.css'"/>
<xsl:param name="table.borders.with.css" select="1"/>
<xsl:param name="use.extensions" select="1"/>
<xsl:param name="tablecolumns.extension" select="1"/>
<xsl:param name="bibliography.numbered" select="1"></xsl:param>
<xsl:param name="generate.toc">
appendix toc
article/appendix nop
article toc,title
book toc,title
chapter toc,title
part toc,title
preface toc,title
qandadiv toc
qandaset toc
reference toc,title
sect1 toc
sect2 toc
sect3 toc
sect4 toc
sect5 toc
section toc
set toc,title
</xsl:param>
</xsl:stylesheet>
请注意前面第4行的 xsl:import命令，它将导入真正用来处理XML的xsl文件名，请按你实际的目录情况进行修改。
3.3. 使用Saxon进行转换
如果前面的工作全部做完了，那么我们就可以开始进行转换处理了。如果你没有现成的XML文档，那么下面是一个简单的文档，可以用来测试。
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<title>测试</title>
<sect1 id="sect.1">
<title>第一节</title>
<para>这是内容</para>
</sect1>
</article>
请注意，使用这个例子文档时，在保存时一定要是utf-8的编码，否则会报错。这是因为这个XML文档在开始时声明为utf-8的编码，解释器会对XML文档进行编码检查。
在这里我们没有使用驱动文件，而是直接使用docbook的xslt文件。
build.bat -o test.html test.xml ..\docbook-xsl\html\docbook.xsl
如果顺利的话，应该可以成功。
命令行选项 [6]-o test.html表示输出结果文件名。在选项之后是：XML源文件和xslt转换文件。
对于复杂的情况，只要将xslt文件名改成你的驱动文件名即可。
其实在我实际的工作中，因为我只在处理一个文档，因此并没有将build.bat写成一个通用的模式，而是将相应的选项直接写在了文件里，这样只要敲入 build.bat就可以了。
[6] 关于详细的命令行选项请查看Saxon所带的文档。
3.4. docbook.xsl 还是 chunk.xsl
docbook.xsl可以将XML转换成单一的HTML文档。而chunk.xsl可以将XML转换多文件的HTML文档。至于使用哪个样式表要看你实际的需要。
它们之间还有一个差别就是chunk.xsl有许多参数，而docbook.xsl没有。象chunk.xsl有输出编码选项，而docbook.xsl没有。
3.5. 本教程所用样式表参数解释
关于本教程所用到的样式在第 3.2.2 节 “在驱动样式表中使用参数”中有完整的内容。在这里只是介绍我用到的参数，更详细的信息请查看docbook-xslt的带的文档。
参数
取值
说明
saxon.character.representation
'native'
对于非ASCII码，按本地字符形式显示。缺省为decimal，这样会把非ASCII码显示为数字实体的形式。此参数是saxon针对chunk.xsl才有的。
l10n.gentext.language
'zh_cn'
对于某些标准信息（如目录名、导航文字等这些已经在系统中定义的文字）使用相应的语言版本。'zh_cn'表示选取中文。因此你会看到是“目录”而不是"Table of Content"。
admon.graphics
1
对于警告类信息是否使用图形。
base.dir
'html/'
生成的HTML文件存放的起始目录。
chunker.output.indent
'yes'
对于生成的HTML文件内容是否进行缩排。缩排会使内容阅读起来方便，但增加了许多空格。
section.autolabel
1
给节编号。
section.label.includes.component.label
1
节的编号是否包含章的编号。
html.stylesheet
'docbook.css'
通过此参数指定生成的HTML文件所用的CSS文件。
table.borders.with.css
1
表格边框的属性是否使用CSS来指定。这里的CSS是预先设好的。如果不使用这个参数，你会发现生成的表格会很难看。
use.extensions
1
是否使用扩展方式。这个参数对表格宽度的生成有影响。
tablecolumns.extension
1
允许表格列扩展函数。
bibliography.numbered
1
参考书目要进行编号。
generate.toc
略
索引信息调整。比如例子列表要不要在目录页中出现；附录中要不要再显示附录的标题。
3.6. 中文处理
3.6.1. 编码
如果你看过我写的文章 《saxon实践(二)》，从上面可以看到我使用了gb2312编码。但是，Saxon本身不支持gb2312，因此必须要修改Saxon的源码才可以。使用这种方法需要一些Java的经验。
我现在的处理方法是：使用utf-8编码。Saxon直接支持utf-8编码，因此这种方法不用修改源码，而且经过我测试没有问题。也许存在的唯一问题是，你需要一个可以打开和另存为utf-8编码的编辑器。我使用的是 EditPlus。 这样我们在写完文档时注意保存成utf-8编码就可以了。以后输出的HTML文档也将会是utf-8编码的。
3.6.2. 调整相关xslt参数
需要调整下面参数：
<xsl:param name="saxon.character.representation" select="'native'"/>
<xsl:param name="l10n.gentext.language" select="'zh_cn'"/>
加入这样的参数到驱动样式表中后就可以很好的处理中文了。
在前面你看到了我用的样式表说明，已经加入了这些参数。
3.7. 编辑DocBook文档
现在有没有合适的编辑器可以生成DocBook文档呢？
· emacs有插件可以帮助我们做这件事，不过我没有用过。
· xml spy可以输入DocBook文档，不过，因为DocBook格式很灵活，所以可能有些麻烦。但xml spy的文本编辑有一个好处就是：它可以自动填充标记。比如你敲入： <para>时，它会自动将 </para>补上，多少方便一些。而且还有一个代码缩排功能，可以把代码排得很整齐。
· EditPlus支持xml的语法高亮，可以识别出标记，注释等内容。还有就是可以自定义的自动完成功能，这个功能有些简单但也可以应付了。
xml spy和EditPlus都可以自动识别出utf-8编码，也可以保存为utf-8编码，这一点对于我使用中文很重要（因为我使用的是utf-8编码）。对于我来说，常用的DocBook的元素可能没有想象得那么多，因此我只需要一些简单的能够支持xml功能的编辑器就可以了。于是我选择了EditPlus。我利用EditPlus的自动完成功能定制了我常用的一些环境，这样当我敲入某些环境的开始元素串时，EditPlus会自动补全，用起来还是比较方便的。
如果有其它的好用的编辑器大家可以介绍给我。
3.8. 关于输出要注意的其它问题
3.8.1. images目录
如果你使用编号图形或设置警告信息输出为图形时要注意，在生成的HTML文件下并不带这些图形。那么从哪里可以得到它们呢？它们就在docbook-xsl目录下。它的下面有一个images目录，里面就是这些环境所要用到的图片。你要做的就是把images目录拷贝到输出HTML的目录下，作为一个子目录。
再用浏览器看一看你生成的结果文件，图形显示正常了。如果你还有自已的一些图片，把它们放也在HTML的输出目录下即可。
3.8.2. 常见的问题
1. 格式不正确
比如一个标记只有开始，没有结束，即不成对。对于空元素在 '>'前一定要有 '/'字符。对于正文中出现的 '<'一定要使用实体形式 <。
2. 不符合DTD
只要你使用了DTD声明，解释器就会对你的XML文档进行相应的内容验证，因此你写的XML文档的内容一定要符合相应的DTD的要求。比如说：footnote元素的内容不能直接为文本，要使用其它的元素，如para环境才可以。因此： <footnote>正文</footnote>就是错的，而 <footnote><para>正文</para></footnote>就是正确的。再如 sect1只能有一个title子元素，如果你写了两个就是错的。如果出现这样的问题，首先看错误信息是什么意思，然后再参考相应的文档看是如何规定的应该就可以了。
3.8.3. CSS文件
如果你自已生成了CSS，并且在参数中指定使用CSS(参见 第 3.5 节 “本教程所用样式表参数解释” )，那么需要将其拷贝到HTML的输出目录下。
3.8.4. UTF-8编码
如果输入了中文，又没有使用GB2312码，请注意保存时要使用utf-8编码。否则解释器会报错。
附录 A. 关于本教程
关于本教程的源码可以在 这里下载。
过程 A.1. 转换方法
1. 建立环境
按 第 3.1 节 “环境准备”建立环境。
2. 解压
将源码包解压放在src目录下。
3. 转换
执行 build.bat。结果会放在html目录下。
附录 B. 文档修订历史
修订历史
修订 1.6.7
2005-10-20
· 修改 两处错误。感谢leasun。
修订 1.6.6
2005-10-3
· 修改 多处错误。感谢老康的劳动。
修订 1.6.5
2005-04-07
· 修改 第 2.10 节 “表格”中的“一个表格例子”，加上漏掉的'/'。感谢xdsnet指出。
修订 1.6.4
2004-11-29
· 修改 第 2.4 节 “图形”中的imageobject例子，加入mediaobject标签。感谢Fred Lin指出。
修订 1.6.3
2004-10-17
· 修改 第 2.5 节 “代码片段”中的programlist例子中<programlist>标记放错位置的错误
修订 1.6.2
2004-08-20
· 修改 第 3.1 节 “环境准备”中的saxon地址错。感谢Alex Dong的指出
修订 1.6.1
2004-06-25
· 修改 第 2.5 节 “代码片段”中的programlist例子中CDATA标记未结束的错误。
修订 1.6
2004-03-20
· 增加 附录 A, 关于本教程
修订 1.5
2004-03-19
· 增加 第 2.15.3 节 “修订历史”
· 增加 第 2.16 节 “警告信息”
· 增加 第 3 章 输出HTML
· 增加 第 3.1 节 “环境准备”
· 增加 第 3.2 节 “xslt参数的使用”
· 增加 第 3.4 节 “docbook.xsl 还是 chunk.xsl”
· 增加 第 3.6 节 “中文处理”
修订 1.4
2004-03-17
· 增加 第 2.10 节 “表格”
· 增加 第 2.11 节 “处理过程”
· 增加 第 2.12 节 “链接”
· 增加 第 2.13 节 “块引用”
· 增加 第 2.15 节 “附录”
修订 1.3
2004-03-13
· 增加 第 2.10 节 “表格”
修订 1.2
2004-03-11
· 增加 第 2.3 节 “例子”
· 增加 第 2.4 节 “图形”
· 增加 第 2.5 节 “代码片段”
· 增加 第 2.6 节 “屏幕输出”
· 增加 第 2.7 节 “编号图形”
· 增加 第 2.8 节 “脚注”
· 增加 第 2.9 节 “列表”
修订 1.1
2004-03-10
· 增加 从这里开始学习DocBook
· 增加 第 1.1 节 “一个Book示例”
· 增加 第 1.2 节 “多个物理文档”
· 增加 第 2 章 常见环境介绍
· 增加 第 2.1 节 “章、节、段”
附录 C. 常用术语
XML
可扩展标记语言。
附录 D. 参考书目
[1] 《DocBook:The Definitive Guide》. O'Reilly & Associates, Inc.. Norman Walsh和Leonard Muellner.
[2] 《DocBook XSL: The Complete Guide》. Second Edition. Sagehill Enterprises. Bob Stayton.
[3] 《Adding catalog support into Saxon》. Jirka Kosek.
