DocBook学习(v1.6.7)

DocBook学习

修订版本 <chsdate year="1899" month="12" day="30" islunardate="False" isrocdate="False" w:st="on">1.6.7(<a href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/">http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/</a><a href="http://www.xiaowang.net/doc/docbook/"></a>)</chsdate>

版权 © 2005 limodou

本文档还在不停地写作、完善中，如果你有什么建议请与limodou联系。

本教程提供源码下载，大家可以下载源码在你的机器上进行测试。关于下载及转换见附录A, 关于本教程。

本文档版权所有者为limodou。你可以自由发布，引用，拷贝，但要保留此版权声明。

感谢 leasun 指出2.5节和2.16的错误。

特别感谢 <chsdate year="1899" month="12" day="30" islunardate="False" isrocdate="False" w:st="on">1.6.6</chsdate>版是在老康的帮助下完成的，不仅有好的建议，还帮助我改进了许多地方。

感谢 xuejm 指出2.5节的错误。

感谢 jxb 指出2.5节的错误。

感谢 Alex Dong 指出3.1节的错误。

---

目录

从这里开始学习DocBook

1. DocBook Book 结构

1.1. 一个Book示例

1.2. 多个物理文档

1.3. 块元素 vs. 环境

2. 常见环境介绍

2.1. 章、节、段

2.2. 使用entity做为宏替换

2.3. 例子

2.4. 图形

2.4.1. 使用figure环境

2.5. 代码片段

2.6. 屏幕输出

2.7. 编号图形

2.8. 脚注

2.9. 列表

2.9.1. 无序列表

2.9.2. 有序列表

2.9.3. 定义列表

2.10. 表格

2.10.1. 表格基础

2.10.2. 横向融合

2.10.3. 纵向融合

2.11. 处理过程

2.12. 链接

2.13. 块引用

2.14. 常见inline元素

2.15. 附录

2.15.1. 术语表

2.15.2. 参考书目

2.15.3. 修订历史

2.16. 警告信息

3. 输出HTML

3.1. 环境准备

3.2. xslt参数的使用

3.2.1. 在命令行中指定参数

3.2.2. 在驱动样式表中使用参数

3.3. 使用Saxon进行转换

3.4. docbook.xsl 还是 chunk.xsl

3.5. 本教程所用样式表参数解释

3.6. 中文处理

3.6.1. 编码

3.6.2. 调整相关xslt参数

3.7. 编辑DocBook文档

3.8. 关于输出要注意的其它问题

3.8.1. images目录

3.8.2. 常见的问题

3.8.3. CSS文件

3.8.4. UTF-8编码

A. 关于本教程

B. 文档修订历史

C. 常用术语

D. 参考书目

---

从这里开始学习DocBook

DocBook是什么？有什么用？我不想在这方面过多地叙述了。从现在开始，我只是想和大家一起来学习如何使用DocBook来进行写作。我会通过如何写一个Book来和大家一起学习。我会一点点地增加使用的element(元素)，从而使这个Book丰富起来。因此这篇文档是在不停的写作中，如果想要了解最新的内容，请访问我的Blog：limodou的学习记录。

这里所讨论的DocBook都是以XML为前提的，关于SGML的内容在这里不涉及。同时有关XML的知识如果可能我会加以说明，一些基础知识还请大家看一下有关资料。因此学习本教程希望你有一些XML的知识。

对于DocBook我经验也不丰富，之所以写这个教程主要是想把我所学过的东西拿出来与大家分享。因此这个教程一定有不足和错误的地方，希望大家指出来，以便我进行改正，从而使本教程变得实用。

---

第1章DocBook Book 结构

目录

1.1. 一个Book示例

1.2. 多个物理文档

1.3. 块元素 vs. 环境

1.1.一个Book示例

例1.1.一个Book示例

<shapetype id="_x0000_t75" coordsize="21600,21600" o:spt="75" o:preferrelative="t" path="m@4@5l@4@11@9@11@9@5xe" filled="f" stroked="f"><font face="宋体" size="3"> <stroke joinstyle="miter"></stroke></font><formulas><font face="宋体" size="3">  <f eqn="if lineDrawn pixelLineWidth 0"></f><f eqn="sum @0 1 0"></f><f eqn="sum 0 0 @1"></f><f eqn="prod @2 1 2"></f><f eqn="prod @3 21600 pixelWidth"></f><f eqn="prod @3 21600 pixelHeight"></f><f eqn="sum @0 0 1"></f><f eqn="prod @6 1 2"></f><f eqn="prod @7 21600 pixelWidth"></f><f eqn="sum @8 21600 0"></f><f eqn="prod @7 21600 pixelHeight"></f><f eqn="sum @10 21600 0"></f></font></formulas><font face="宋体" size="3"> <path o:extrusionok="f" gradientshapeok="t" o:connecttype="rect"></path><lock v:ext="edit" aspectratio="t"></lock></font></shapetype><shape id="_x0000_i1028" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="1"><font face="宋体" size="3"> <imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/1.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image001.gif"></imagedata></font></shape><?xml version="1.0" encoding="gb2312"?>

<shape id="_x0000_i1029" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="2"><font face="宋体" size="3"> <imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/2.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image002.gif"></imagedata></font></shape><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<shape id="_x0000_i1030" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="3"><font face="宋体" size="3"> <imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/3.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image003.gif"></imagedata></font></shape><book>

<shape id="_x0000_i1031" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="4"><font face="宋体" size="3"> <imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/4.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image004.gif"></imagedata></font></shape><bookinfo>

<title>DocBook 学习</title>

<author>

<othername>limodou</othername>

</author>

</bookinfo>

<shape id="_x0000_i1032" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="5"><font face="宋体" size="3"> <imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/5.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image005.gif"></imagedata></font></shape><chapter>

<shape id="_x0000_i1033" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="6"><font face="宋体" size="3"> <imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/6.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image006.gif"></imagedata></font></shape><title> ... </title>

<shape id="_x0000_i1034" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="7"><font face="宋体" size="3"> <imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/7.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image007.gif"></imagedata></font></shape><sect1> ... </sect1>

</chapter>

<chapter>

<title> ... </title>

<sect1> ... </sect1>

</chapter>

</book>

<shape id="_x0000_i1035" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="1" href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/bookstructure.html#co.1.1.1#co.1.1.1" o:button="t"><imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/1.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image001.gif"><font face="宋体" size="3"></font></imagedata></shape>	XML文档声明。encoding为xml文档所用编码。一个XML文档必须要有声明，而且这个声明必须是文档的开始。即声明前不能有任何内容，包括空白。
<shape id="_x0000_i1036" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="2" href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/bookstructure.html#co.1.1.2#co.1.1.2" o:button="t"><imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/2.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image002.gif"><font face="宋体" size="3"></font></imagedata></shape>	DTD声明。DTD是用于对XML文档合法性进行检查用的，全称是Document Type Definition。这里大家照猫画虎即可。不过要注意地是DOCTYPE后面跟着的是XML文档的根元素，这里就是book了。
<shape id="_x0000_i1037" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="3" href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/bookstructure.html#co.1.1.3#co.1.1.3" o:button="t"><imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/3.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image003.gif"><font face="宋体" size="3"></font></imagedata></shape>	XML文档的根元素。从这里开始进入内容部分。前面的内容可以叫作“引言”。
<shape id="_x0000_i1038" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="4" href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/bookstructure.html#co.1.1.4#co.1.1.4" o:button="t"><imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/4.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image004.gif"><font face="宋体" size="3"></font></imagedata></shape>	关于Book的Meta信息。如：title、author等。这个例子中，只用到了title和author。其中，作者的名字使用了othername，这是因为我不想把名和姓分开的缘故。
<shape id="_x0000_i1039" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="5" href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/bookstructure.html#co.1.1.5#co.1.1.5" o:button="t"><imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/5.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image005.gif"><font face="宋体" size="3"></font></imagedata></shape>	第一章开始。DocBook对于象chapter、example之类可以自动编号。
<shape id="_x0000_i1040" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="6" href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/bookstructure.html#co.1.1.6#co.1.1.6" o:button="t"><imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/6.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image006.gif"><font face="宋体" size="3"></font></imagedata></shape>	章的标题。 <shape id="_x0000_i1041" style="WIDTH: 18pt; HEIGHT: 18pt" type="#_x0000_t75" alt="[Note]"><imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/note.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image008.gif"></imagedata></shape> 许多element都有title，如：book、chapter等。
<shape id="_x0000_i1042" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="7" href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/bookstructure.html#co.1.1.7#co.1.1.7" o:button="t"><imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/7.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image007.gif"><font face="宋体" size="3"></font></imagedata></shape>	第一章的第一节。也是可以自动编号。

上面就是一个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" [

<shape id="_x0000_i1044" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="1"><font face="宋体" size="3"> <imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/1.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image001.gif"></imagedata></font></shape> <!ENTITY chapter1 SYSTEM "chapter1.xml">

]>

<book>

<bookinfo>

<title>DocBook 学习</title>

<author>

<othername>limodou</othername>

</author>

<shape id="_x0000_i1045" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="2"><font face="宋体" size="3"> <imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/2.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image002.gif"></imagedata></font></shape><para>这是一个演示多文档的示例。</para>

</bookinfo>

<shape id="_x0000_i1046" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="3"><font face="宋体" size="3"> <imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/3.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image003.gif"></imagedata></font></shape>&chapter1;

<shape id="_x0000_i1047" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="4"><font face="宋体" size="3"> <imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/4.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image004.gif"></imagedata></font></shape><chapter id="chapter.2">

<title>标题</title>

<sect1> ... </sect1>

</chapter>

</book>

<shape id="_x0000_i1048" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="1" href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/multifiles.html#co.1.2.1#co.1.2.1" o:button="t"><imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/1.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image001.gif"><font face="宋体" size="3"></font></imagedata></shape>	通过定义一个entity(实体)来引入一个外部文件。
<shape id="_x0000_i1049" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="2" href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/multifiles.html#co.1.2.2#co.1.2.2" o:button="t"><imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/2.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image002.gif"><font face="宋体" size="3"></font></imagedata></shape>	在book中的bookinfo元素中也可以有para内容。
<shape id="_x0000_i1050" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="3" href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/multifiles.html#co.1.2.3#co.1.2.3" o:button="t"><imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/3.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image003.gif"><font face="宋体" size="3"></font></imagedata></shape>	在此处插入chapter1.xml的内容。在使用一个实体时，前面是一个&，然后是实体名字，后面跟着分号(;)。
<shape id="_x0000_i1051" style="WIDTH: 9pt; HEIGHT: 9pt" type="#_x0000_t75" alt="4" href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/multifiles.html#co.1.2.4#co.1.2.4" o:button="t"><imagedata o:href="http://www.woodpecker.org.cn:9081/doc/XML/docbook_step_1.6.6/src/html/images/callouts/4.png" src="file:///C:%5CDOCUME~1%5CSnaill%5CLOCALS~1%5CTemp%5Cmsohtml1%5C01%5Cclip_image004.gif"><font face="宋体" size="3"></font></imagedata></shape>	其本上所有的元素都有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中有介绍。

<font