制作Docbook文档
1. 制作Docbook文档需要了解的知识Q?/p>
1) XML - q是最基本的，如果q个都不懂的话，最好先找本入门U的书看看；
2) DTD - 有助于你理解Docbook的结构；
3) XSL - 有助于定制自qDocbookQ?br />4) XSL-FO - 最好了解一点，有助于更好的定制自己的PDF输出?/p>
2. 制作Docbook文档的最单的q程包括以下的步骤：
1) ~辑XML文g;
2) 对XML文gq行处理Q生成HTML或者PDF文档?/p>
2.1. ~辑XML文g
如果使用U文本编辑器来完成这工作，我敢打赌一天之后你做不下MQ直接编辑XML可是一件苦差事。用类似XMLSPYq样的工P提供自动填充功能Qƈ且随时可以进行有效性检查，不容易出错，可以让工作轻松不?/p>
Docbook文档分两c：书（bookQ和文章QarticleQ。article是一般的文章Q不包含章（chapterQ，只有? QsectionQ。book比较完整Q可以包含前aQprefaceQ，部分QpartQ，章（chapterQ，文章QarticleQ等{。以上描 q的都是Docbook DTD定义的元素，q里不可能给l的说明Q具体每个元素的l构参见Docbook DTD?/p>
让我们先来看一个bookcd文档的典型定义：
list 1. 典型的bookcd文档
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book>
<bookinfo>
<title>My Book</title>
<author>
<firstname>My First Name</firstname>
<surname>My Last Name</surname>
</author>
<publisher>
<publishername>CSDN</publishername>
</publisher>
<isbn>ISBN#</isbn>
<copyright>
<year>2005</year>
</copyright>
</bookinfo>
<part>
<title>My Part</title>
<chapter>
<title>My Chapter</title>
<sect1>
<title>My Section1</title>
<para>This is a demo of a book.</para>
</sect1>
</chapter>
</part>
</book>
该文档声明用的DTD?a >http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtdQ? 所有的内容都包含在book元素中，bookinfo元素包含书名QtitleQ、作者（authorQ、出版社QpublisherQ、书? QisbnQ和版权QcopyrightQ。接着part元素包含的内Ҏ该书的一个部分，下面有一章，接着有一节（sect1Q，当然都有各自的标题?/p>
怎么P各个元素的含义是不是很显而易见，Ҏ元素的名Uͼ你就能知道自q内容该包含在什么元素里面?/p>
在上面的例子里面Q有些元素不是必ȝ。譬如bookinfoQ可以没有或者有一个，看Docbook DTD可以知道?/p>
下面我以articlecd的文档ؓ例子Q说明Docbook文档的制作过E?/p>
首先是XML声明Q说明文档的一些基本信息：
<?xml version="1.0" encoding="UTF-8"?>
紧接着是文档的DTD声明Q说明文档用的DTDq有根元素。典型的docbook文档的DTD声明如下Q?/p>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
q个声明表明Q文档的根元素是<article>Q用外部DTDQ该DTD用一个公共标识符"-//OASIS//DTD DocBook XML V4.2//EN"标识Q该DTD位于|络的某处。标识符必须是全球唯一的，其Ş式ؓQ?/p>
prefix//owner-identifier//text-class text-description//language//display-version
W一个prefix为?/-”，?”表C是已注册的标识Q?”则相反。其他各部分的含义自己对照?/p>
接着可以添加内容了。首先是根元素：
<article>
</article>
article必须有一个标题：
<article>
<title>My Article</title>
</article>
标题之后必须有内容，不可能有无内容的文章Q?/p>
<article>
<title>My Article</title>
<sect1>
</sect1>
</article>
q里我们d一个小节，“sect1”是节的最层元素Q其~排方式与MS Word的“heading 1”类伹{?/p>
与article相同Qsect1也必L标题Q?/p>
<article>
<title>My Article</title>
<sect1>
<title>My Section</title>
</sect1>
</article>
sect1也不允许无内容：
<article>
<title>My Article</title>
<sect1>
<title>My Section</title>
<para>This is my first article.</para>
</sect1>
</article>
正文的内容一般用<para>元素装Qparax落（paragraphQ的意思?/p>
现在有了一个最单的Docbook文档。list 2是完整的代码?/p>
list 2. 一个简单的article文档
<?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>My Article</title>
<sect1>
<title>My Section</title>
<para>This is my first article.</para>
</sect1>
</article>
~辑完成之后Q保存ؓmyarticle.xmlQ接着可以生成HTML或者PDF了?/p>
2.2 生成HTML
关于如何安装配置工具Q参见“安装配|Docbook”?/p>
我用cygwin下的xsltproc来生成HTMLQ在cygwin的shell中输入命令：
xsltproc --nonet --output myarticle.html c:/docbook-xsl-1.67.2/html/docbook.xsl myarticle.xml
--nonet表示我不希望从网l获取DTDQ这样可以节省时间?/p>
--output指定我希望输出的文g名，q里指定的是myarticle.html?/p>
紧接着是用来{换XML文g的XSL样式单，需要注意，使用的是html目录下的XSL样式单?/p>
最后是要处理的Docbook文档?/p>
没有意外的话Q现在你可以用览器打开myarticle.html看看效果了?/p>
2.3 生成PDF文g
下面使用FOP生成PDF文g。关于如何安装配|FOPQ参?a >http://blog.csdn.net/mickeyrat/archive/2005/02/06/283471.aspx?/p>
在控制台输入命oQ?/p>
fop -xml myarticle.xml -xsl C:\docbook-xsl-1.67.2\fo\docbook.xsl myarticle.pdf
Linux的命令类|注意docbook.xsl的\径?/p>
-xml指定需要{换的docbook文档?/p>
-xsl指定使用的样式单Q注意，q里使用的fo目录下的样式单，q是专ؓ转换XSL-FO开发的?/p>
最后是输出文档的文件名?/p>
在FOP处理q程中，会输多诸?/p>
property - "background-position-horizontal" is not implemented yet.
的信息。不用理会，q是因ؓFOPq在开发中Q许多XSL-FO的特性都不支持。这L问题q不影响最l文档的生成?/p>
快打开myarticle.pdf看看效果吧，是不是很专业的PDF文档Q?/p>
是不是觉得制作docbook文档很简单呢Q这么想可就错了Q本文剩余的部分介绍制作Docbook文档的高U技巧?/p>
3. 定制自己的XSL样式?/p>
当你开始正式制作自qdocbook文档之后Q你会发现生成的文档q不能完全满你Ҏ式的要求Q譬如章节号、页码、字体等{。这一节就告诉你如何定制自qXSL样式单，生成满特定需求的文档。下面的内容会涉及XSL和XSL-FO?/p>
有h可能会想通过修改Docbook DTD辑ֈ定制目的Q但是这U方式是不徏议采用的Q因Z改Docbook DTD之后Q你的文档就不再是Docbook文档?/p>
因ؓDocbook把内容与样式完全分开Q所以修改XSL样式单，p够改变输出结果?/p>
Z修改样式单，你需要有自己的定制层Q也是ZDocbook XSL样式单之上开发自q样式单。千万不要直接修改Docbook XSL样式单，q样做有两个~点Q?/p>
1) 不易l护Q你的修改可能会分散在几十个文g中，q几天，你就会忘记自׃改过的地斏V?/p>
2) 不易升Q如果你惛_U样式到新的版本Q你不得不把你所做的所有修改合q到新的版本中，合ƈ的过E中肯定要处理大量的冲突Qƈ且容易出错?/p>
我想你应该知?lt;xsl:include>?lt;xsl:import>的区别：使用<xsl: include>引入的元素，如果有重复定义的Q第一ơ出现的有效Q?lt;xsl:import>引入的元素，最后一个有效。定制层? 实是依赖于XSLq样的一个特性，使用<xsl:import>引入Docbook XSL样式单的L文gQ然后添加自q修改。list 3l出一个定制层文g的框架?/p>
list 3 customization.xsl
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="html/docbook.xsl"/>
...
modifications
...
</xsl:stylesheet>
定制层是XSL文gQ因此需要引入xsl的名字空间。在W三行，引入转换HTML的XSL样式单的L文gdocbook.xslQ如果是XSL-FO的定制层QvҎ件在fo目录下。然后就可以d自己的修改了?/p>
定制分ؓ两类Q一cL修改样式单参敎ͼ一cL修改模板?/p>
3.1 修改样式单参?/p>
打开html/param.xsl或者fo/param.xslQ可以找到所有的样式单参数。看下面q个例子
<xsl:param name="section.autolabel" select="0"/>
参数的名字是“section.autolabel”，gؓ?”。这个参数的作用是控制生成文档的时候是否对节自动~号Q譬如?”，?.1”等{。?”表C关闭自动编受你可以看一下前面生成的文档Q是不是没有章节P
要打开自动~号Q只需要这样修改：
<xsl:param name="section.autolabel" select="1"/>
你不是直接在param.xsl里面改的吧？如果是的话，赶紧改回来！千万记得Q所有的修改都写在前面生成的customization.xsl。现在重新生成HTMLQ?/p>
xsltproc --nonet --output myarticle.html c:/docbook-xsl-1.67.2/customization.xsl myarticle.xml
或生成PDF
fop -xml myarticle.xml -xsl C:\docbook-xsl-1.67.2\customization.xsl myarticle.pdf
注意Q这个参数对HTML和XSL-FO都有效，但是你必dcustomization.xsl中用<xsl:import>引入对应的vҎӞ否则会报错。现在新的文档是不是出现章节号了Q?/p>
再来一个。看你的PDF文档Q肯定没有bookmarkQ因为在fo/param.xsl中，bookmark的功能被关闭了。在customization.xsl里添加：
<xsl:param name="fop.extensions" select="1"/>
q样FOP在处理的时候就会生成bookmark。注意这个参数的名字Q“fop.extensions”，表示q个参数属于FOP的扩展，只对FOP有效。如果你使用PassiveTeXQ那么需要设|“passivetex.extensions”?/p>
再来一个复杂点的：
<xsl:param name="formal.title.placement">
figure after
example before
equation before
table before
procedure before
task before
</xsl:param>
q个参数作用于文章中的图、表{等元素的标题，控制标题的位|在前面QbeforeQ还是后面（afterQ，param.xsl预定义的都是 “before”，q里把figure的标题放在图的后面。这个参数对HTML和XSL-FO都有效。在你的文档中添?lt;figure>? 素，重新生成文档Q就可以看到效果?/p>
3.2 修改模板
Docbook XSL提供很多的参数控制输出的效果。但是有时候，仅仅修改参数q不能满x有的要求Q这Ӟ你就需要修Ҏѝ?/p>
我们来看一个很现实的例子。XSL-FO定义了一cM“keep-”开头的属性，譬如“keep-with-next”，表示前面的内容与后面的内容必d同一，不能断开在两上。但是除了tableQ?br />FOP目前不支持这L属性。所以当文档比较长的时候，在FOP生成的PDF文档中，你会发现有某些小节的标题在一늚底部Q而内容却在下一，其他有标题的内容Q譬如图Q都会出现这L情况。这当然是不合理的，可是无论你怎么d“keep-”类的参敎ͼ都无于事?/p>
对于q样的情况，FOP的FAQ告诉你的是Q“对不vQ我们还没有实现”，至于什么时候实玎ͼ“你别问Q我也不知道”?/p>
所以只能采取一个变通的方式。前面我说过QFOP对于table支持q样的属性，那么是否可以考虑把这L内容攑֜table里面呢？当然可以Q?
FOP有一个“blind table”的概念Q这L表除了其中的内容是不可见的，正符合我们的要求。现在的问题是QDocbook
XSL样式单生成的是通用的XSL-FO文gQ不会把?lt;sect2>q种元素的内Ҏ到“blind
table”里面。那只剩一条\了（其实q有一条，用商业品^_^QRenderX的XEP支持“keep-”类属性）Q修Ҏ式单模板。list
4的代码把<sect2>的内ҎC个“blind table”里面?br />
list 4. blindtable.xsl
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version="1.0">
<xsl:import href="docbook.xsl"/>
<xsl:template match="sect2">
<xsl:variable name="id">
<xsl:call-template name="object.id"/>
</xsl:variable>
<fo:table table-layout="fixed" width="100%">
<fo:table-column column-number="1"/>
<fo:table-body>
<fo:table-row keep-with-next="always">
<fo:table-cell id="{$id}" xsl:use-attribute-sets="section.level2.properties">
<xsl:call-template name="sect2.titlepage"/>
</fo:table-cell>
</fo:table-row>
<xsl:variable name="toc.params">
<xsl:call-template name="find.path.params">
<xsl:with-param name="table" select="normalize-space($generate.toc)"/>
</xsl:call-template>
<xsl:if test="contains($toc.params, 'toc') and $generate.section.toc.level >= 2">
<xsl:call-template name="section.toc"/>
<xsl:call-template name="section.toc.separator"/>
</xsl:if>
</xsl:variable>
<fo:table-row>
<fo:table-cell>
<xsl:apply-templates select="*[2]"/>
</fo:table-cell>
</fo:table-row>
</fo:table-body>
</fo:table>
<xsl:apply-templates select="*[position() > 2]"/>
</xsl:template>
</xsl:stylesheet>
对于q段代码׃多做解释了，ȝ来说其作用就是覆盖了sections.xsl中定义的名ؓ“sect2”的模板Q在生成XSL-FO文g的时 候，?lt;sect2>的标题和内容分别攑ֈ一个单列表的两行。因里用Cfo名字I间Q所以在开始要引入fo名字I间?/p>
重新生成PDF文gQ?/p>
fop -xml yourarticle.xml -xsl C:\docbook-xsl-1.67.2\blindtable.xsl yourarticle.pdf
你会发现所?lt;sect2>的内Ҏ有标题与内容断开在两上的情况了?/p>
4. ȝ
到此为止Q你已经了解制作Docbook的完整过E：
1) ~辑XML文档Q?br />2) 生成HTML/PDFQ?br />3) 定制XSL样式单?/p>
定制XSL样式单不能直接修改Docbook XSL样式单，需要创Z个新的XSL文g作ؓ定制层?/p>
XSL样式单定制有两类Q?/p>
1) 修改XSL参数Q?br />2) 修改XSL模板?/p>
MDocbook是十分强大的工具Q可以用来制作非怸业漂亮的技术文档，甚至是其他文档?/p>
参考文章：
DocBook XSL: The Complete Guide
]]>
安装配置Docbook工具
使用Docbook发布文档Q需要安装以下的工具Q?br /> *DocBook DTD
*DocBook XSL 样式?br /> *XSLT处理E序
*XSL-FO处理E序
下面详细介绍各个工具的安装?/p>
1.安装DocBook DTD
Docbook DTD可以到OASIS的网站上下蝲Q在q里你可以找到zip格式的压~包。目前的最新版本是4.2?/p>
事实上可以不下蝲Docbook DTD。如果你的文档DTD声明q样写：
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" " Ҏq样的定义，大部分XML处理器能够从|络上获取DTD。这样做的好处是~辑的Docbook文档UL性好Q可以在没有安装Docbook
DTD的机器上使用。不q由于Docbook DTD比较庞大Q通过|络获取DTD会媄响处理速度Q在低速网l或者网l比较糟p的情况下，影响ؓ显著?/p> 如果选择使用本地DTDQ文档的DTD引用应该q样写： Linux: Windows: Docbook提供了一U方式，让用户可以用相同的DTD声明Q但可以在用网l获取DTD和用本地DTD之间切换Q同时拥有两者的优势。这是catalog文g的作用。典型的catalog的声明如下： <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> q个声明把网lDTD映射到本地DTD。如果用支持Catalog的XSLT ProcessorQ它首先会查找本地文Ӟ如果本地文g不存在，再查扄l?/p> 2.安装Docbook XSL样式?/p> ?a >http://docbook.sourceforge.net
<!DOCTYPE book SYSTEM "/usr/share/docbook-4.2/docbookx.dtd">
<!DOCTYPE book SYSTEM "file:///C:/xml/docbook42/docbookx.dtd">
<group id="DocbookDTD" prefer="public">
<system
systemId="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
uri="file:///usr/share/xml/docbook42/docbookx.dtd"/>
</group>
</catalog>
解压之后Q有几个比较主要的目录：
*common - 包含的是公用的模块，诸如语言之类的文仉在这里?br /> *extensions - 针对特定的XSLT Processor~写的扩展代码?br /> *fo - 生成XSL-FO文g所需的XSL样式单?br /> *html - 生成HTML文g所需的XSL样式单?br /> *images - 生成文档时所需要的囄?br /> *doc - 有关XSL样式单的文档Q同hDocbook文档?/p>
其他q有像htmlhelp之类的目录，但不是生成HTML或XSL-FO所必须的?/p>
3.安装XSLT Processor
目前有许多免费的XSLT ProcessorQ最常用的是
*Saxon - 使用Java实现Q?a >http://saxon.sourceforge.net/?br /> *Xalan - 有Java和C++版本Q?a >http://xml.apache.org/xalan-j/index.html?br /> *xsltproc - 使用C实现Q是最快的处理E序Q?a >http://xmlsoft.org/XSLT/
因ؓSaxon和Xalan都有Java版本Q所以按照一般的JavaE序的安装方式安装即可。下面介lxsltproc的安装，因ؓ它速度快，是我比较喜欢的处理程序?/p>
如果你用windowsq_Q那么你有两个方法可选：
1) 直接下蝲为windowsq_预编译的版本。你需要下载libxml, libxslt, 和iconvQ它们都是zip格式Q解压之后，在环境变量PATH中添加xsltproc.exe?dll文g的\径?br />
如果你不想编辑环境变量，一个简单的办法是把下面q些文g复制到C:\Windows\System32Q?br />
libxslt.dll
libxml2.dll
libexslt.dll
iconv.dll
xsltproc.exe
q样在命令行可以直接找到这些文件了。完成之后，q行
xsltproc -version
打印出版本号则表明完成安装?br />
2) 在Cygwin下安装，q是我选择使用的方式。Cygwin是一个在Windows下模拟Linux Shell的应用程序。如果你喜欢以Linux命o的方式来使用xsltprocQ?a >下蝲Cygwin安装E序。Cygwin的是通过|络安装的，首先你从它提供的包列表中选择libxsltQ然后安装程序会Ҏ依赖关系自动选择libxml2Q确定之后，安装E序下蝲q安装xsltproc。完成安装之后，你就可以q行
xsltproc -version
来检查是否安装成功?br />
3) 如果使用LinuxQ很有可能系l已l安装了xsltproc。运?br />
xsltproc -version
查一下是否已l安装。如果运行命令失败，或者版本太老，那么讉K下面两个URL获取最新的RPM包：
http://rpmfind.net/linux/rpm2html/search.php?query=libxml2
http://rpmfind.net/linux/rpm2html/search.php?query=libxslt
然后切换到root权限Q安装新的包Q?br />
rpm -Uv libxml2-2.6.17-2.i386.rpm
rpm -Uv libxslt-1.1.12-4.i386.rpm
完成之后Q就可以q行
xsltproc -version
查安装是否完成?/p>
安装之后Q就可以使用xsltproc来生成HTML或者XSL-FO文g?/p>
譬如Q生成HTMLQ?br />
xsltproc --output myfile.html docbook-xsl/html/docbook.xsl myfile.xml
或者生成XSL-FO文档Q?br />
xsltproc --output myfile.fo docbook-xsl/fo/docbook.xsl myfile.xml
?a >http://xmlsoft.org/XSLT/xsltproc2.html上列Z所有xsltproc的命令行参数Q直接运?br />xsltproc也会打印出参数列表?/p>
如果你只要发布HTML文档Q那么到此ؓ止。如果你q想发布PDF或是PS文档Q那么需要安装XSL-FO处理E序?/p>
4. 安装XSL-FO处理E序
XSL-FO处理E序ҎXSLT处理E序生成的XSL-FO文g生成PDF或者PS文g。目前可供选择的XSL-FO处理E序q不如XSLT处理E序那么多，q是因ؓQ?br />
a. XSL-FO标准比XSLT标准的制订晚两年Q?br />
b.XSL-FO标准及其庞大而复杂，该标准的作者也发现其实C的难度，从而将该标准分为基本、扩展和完整三个U别?/p>
现在可用的免费的XSL-FO处理E序有：
*FOP - 来自Apache XML目。目前最新的版本?.20.5Q还在开发当中，q有很多Ҏ不支持Q不q已l可以满一般的使用?br />
*PassiveTeX - 来自Sebastian Rahtz (http://www.tei-c.org.uk/Software/passivetex/)一Ƒ֟于TeX的XSL-FO处理E序。同样也在开发中Q较FOP要复杂的多?/p>
另外有一些商业品可供选择Q可能生成的文档质量要比开源代码好Q譬如：
*XEP
下面介绍如何安装FOP?/p>
4.1.首先需要安装JDKQ这个不用多说?/p>
4.2. 下蝲FOPQ可以选择tar或者zip压羃包。下载之后解压到本地?/p>
4.3. 下蝲囑Ş代码库。FOP自己不支持PNG之类的图片，如果在你的文档里会涉及到囄Q那么需要下载额外的代码库。可以选择JAIQ或?a >Jimi?.20.5之前的版本只能用Jimi。下载之后，jai_core.jar和jai_codec.jarQJAI)Q或者JimiProClasses.jarQJimiQ复制到FOP安装目录的lib目录下，然后在fop.batQWindowsq_Q中d
set LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\jai_core.jar
set LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\jai_codec.jar
或是
set LOCALCLASSPATH=%LOCALCLASSPATH%;%LIBDIR%\JimiProClasses.zip
如果使用fop.shQLinuxq_Q，会自动搜索?/p>
4.4. d扩展代码。如果Docbook XSL样式单有针对FOP的扩展代码（目前没有Q，像上面一h它们d到FOP安装目录下lib目录?/p>
现在可以用FOP来生成PDF文档了。FOP提供两个脚本fop.batQWindowsq_Q和fop.shQUnix和Linuxq_Q以方便使用。生成PDF的命令行如下Q?br />
Linux或UnixQ?br /> fop.sh -xsl /docbook-xsl/fo/docbook.xsl -xml myfile.xml -pdf myfile.pdf
WindowsQ?br /> fop.bat -xsl /docbook-xsl/fo/docbook.xsl -xml myfile.xml -pdf myfile.pdf
在处理过E中Q可能会提示某些属性不支持或尚未实玎ͼ不用理会q些提示Q因为FOP仍处于开发中Q这q不影响生成PDF文档?/p>
到此Q一个Docbook发布pȝ配置完成Qƈ可以用来发布文档了。你完全可以在Linux上编写Q务，通过该系l自动发布技术文档?/p>
参考文章：
Docbook?/a>
制作Docbook文档
DocBook XSL: The Complete Guide
]]>
]]>