1. 制作Docbook文檔需要了解的知識(shí)：

1) XML - 這是最基本的，如果這個(gè)都不懂的話，最好先找本入門級(jí)的書看看；
2) DTD - 有助于你理解Docbook的結(jié)構(gòu)；
3) XSL - 有助于定制自己的Docbook；
4) XSL-FO - 最好了解一點(diǎn)，有助于更好的定制自己的PDF輸出。

2. 制作Docbook文檔的最簡單的過程包括以下的步驟：

1) 編輯XML文件;
2) 對(duì)XML文件進(jìn)行處理，生成HTML或者PDF文檔。

2.1. 編輯XML文件

如果使用純文本編輯器來完成這項(xiàng)工作，我敢打賭一天之后你就做不下去了，直接編輯XML可是一件苦差事。使用類似XMLSPY這樣的工具，提供自動(dòng)填充功能，并且隨時(shí)可以進(jìn)行有效性檢查，不容易出錯(cuò)，可以讓工作輕松不少。

Docbook文檔分兩類：書（book）和文章（article）。article就是一般的文章，不包含章（chapter），只有節(jié) （section）。book比較完整，可以包含前言（preface），部分（part），章（chapter），文章（article）等等。以上描 述的都是Docbook DTD定義的元素，這里不可能給出詳細(xì)的說明，具體每個(gè)元素的結(jié)構(gòu)參見Docbook DTD。

讓我們先來看一個(gè)book類型文檔的典型定義：

??????????? list 1. 典型的book類型文檔
<?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為http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd， 所有的內(nèi)容都包含在book元素中，bookinfo元素包含書名（title）、作者（author）、出版社（publisher）、書號(hào) （isbn）和版權(quán)（copyright）。接著part元素包含的內(nèi)容是該書的一個(gè)部分，下面有一章，接著有一節(jié)（sect1），當(dāng)然都有各自的標(biāo)題。

怎么樣，各個(gè)元素的含義是不是很顯而易見，根據(jù)元素的名稱，你就能知道自己的內(nèi)容該包含在什么元素里面。

在上面的例子里面，有些元素不是必須的。譬如bookinfo，可以沒有或者有一個(gè)，看Docbook DTD就可以知道。

下面我以article類型的文檔為例子，說明Docbook文檔的制作過程。

首先是XML聲明，說明文檔的一些基本信息：

<?xml version="1.0" encoding="UTF-8"?>

緊接著是文檔的DTD聲明，說明文檔使用的DTD還有根元素。典型的docbook文檔的DTD聲明如下：

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
?????????????? "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

這個(gè)聲明表明，文檔的根元素是<article>，使用外部DTD，該DTD用一個(gè)公共標(biāo)識(shí)符"-//OASIS//DTD DocBook XML V4.2//EN"標(biāo)識(shí)，該DTD位于網(wǎng)絡(luò)的某處。標(biāo)識(shí)符必須是全球唯一的，其形式為：

prefix//owner-identifier//text-class text-description//language//display-version

第一個(gè)prefix為“+/-”，“+”表示是已注冊(cè)的標(biāo)識(shí)，“-”則相反。其他各部分的含義自己對(duì)照。

接著就可以添加內(nèi)容了。首先是根元素：

<article>

</article>

article必須有一個(gè)標(biāo)題：

<article>
??? <title>My Article</title>
</article>

標(biāo)題之后必須有內(nèi)容，不可能有無內(nèi)容的文章：

<article>
???? <title>My Article</title>
???? <sect1>
????? </sect1>
</article>

這里我們添加一個(gè)小節(jié)，“sect1”是小節(jié)的最頂層元素，其編排方式與MS Word的“heading 1”類似。

與article相同，sect1也必須有標(biāo)題：

<article>
???? <title>My Article</title>
???? <sect1>
??????? <title>My Section</title>
????? </sect1>
</article>

sect1也不允許無內(nèi)容：

<article>
???? <title>My Article</title>
???? <sect1>
??????? <title>My Section</title>
??????? <para>This is my first article.</para>
????? </sect1>
</article>

正文的內(nèi)容一般用<para>元素封裝，para即段落（paragraph）的意思。

現(xiàn)在就有了一個(gè)最簡單的Docbook文檔。list 2是完整的代碼。

??????????? list 2. 一個(gè)簡單的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>

編輯完成之后，保存為myarticle.xml，接著就可以生成HTML或者PDF了。

2.2 生成HTML

關(guān)于如何安裝配置工具，參見“安裝配置Docbook”。

我使用cygwin下的xsltproc來生成HTML，在cygwin的shell中輸入命令：

xsltproc --nonet --output myarticle.html c:/docbook-xsl-1.67.2/html/docbook.xsl myarticle.xml

--nonet表示我不希望從網(wǎng)絡(luò)獲取DTD，這樣可以節(jié)省時(shí)間。

--output指定我希望輸出的文件名，這里指定的是myarticle.html。

緊接著是用來轉(zhuǎn)換XML文件的XSL樣式單，需要注意，使用的是html目錄下的XSL樣式單。

最后是要處理的Docbook文檔。

沒有意外的話，現(xiàn)在你就可以用瀏覽器打開myarticle.html看看效果了。

2.3 生成PDF文件

下面使用FOP生成PDF文件。關(guān)于如何安裝配置FOP，參見http://blog.csdn.net/mickeyrat/archive/2005/02/06/283471.aspx。

在控制臺(tái)輸入命令：

fop -xml myarticle.xml -xsl C:\docbook-xsl-1.67.2\fo\docbook.xsl myarticle.pdf

Linux的命令類似，注意docbook.xsl的路徑。

-xml指定需要轉(zhuǎn)換的docbook文檔。

-xsl指定使用的樣式單，注意，這里使用的fo目錄下的樣式單，這是專為轉(zhuǎn)換XSL-FO開發(fā)的。

最后是輸出文檔的文件名。

在FOP處理過程中，會(huì)輸出許多諸如

property - "background-position-horizontal" is not implemented yet.

的信息。不用理會(huì)，這是因?yàn)镕OP還在開發(fā)中，許多XSL-FO的特性都不支持。這樣的問題并不影響最終文檔的生成。

快打開myarticle.pdf看看效果吧，是不是很專業(yè)的PDF文檔？

是不是覺得制作docbook文檔很簡單呢？這么想可就錯(cuò)了，本文剩余的部分介紹制作Docbook文檔的高級(jí)技巧。

3. 定制自己的XSL樣式單

當(dāng)你開始正式制作自己的docbook文檔之后，你會(huì)發(fā)現(xiàn)生成的文檔并不能完全滿足你對(duì)格式的要求，譬如章節(jié)號(hào)、頁碼、字體等等。這一節(jié)就告訴你如何定制自己的XSL樣式單，生成滿足特定需求的文檔。下面的內(nèi)容會(huì)涉及XSL和XSL-FO。

有人可能會(huì)想通過修改Docbook DTD達(dá)到定制目的，但是這種方式是不建議采用的，因?yàn)樾薷腄ocbook DTD之后，你的文檔就不再是Docbook文檔。

因?yàn)镈ocbook把內(nèi)容與樣式完全分開，所以修改XSL樣式單，就能夠改變輸出結(jié)果。

為了修改樣式單，你需要有自己的定制層，也就是基于Docbook XSL樣式單之上開發(fā)自己的樣式單。千萬不要直接修改Docbook XSL樣式單，這樣做有兩個(gè)缺點(diǎn)：

1) 不易維護(hù)：你的修改可能會(huì)分散在幾十個(gè)文件中，過幾天，你就會(huì)忘記自己修改過的地方。

2) 不易升級(jí)：如果你想升級(jí)樣式到新的版本，你不得不把你所做的所有修改合并到新的版本中，合并的過程中肯定要處理大量的沖突，并且容易出錯(cuò)。

我想你應(yīng)該知道<xsl:include>與<xsl:import>的區(qū)別：使用<xsl: include>引入的元素，如果有重復(fù)定義的，第一次出現(xiàn)的有效；使用<xsl:import>引入的元素，最后一個(gè)有效。定制層其 實(shí)是依賴于XSL這樣的一個(gè)特性，使用<xsl:import>引入Docbook XSL樣式單的起點(diǎn)文件，然后添加自己的修改。list 3給出一個(gè)定制層文件的框架。

???????????????????????????? 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文件，因此需要引入xsl的名字空間。在第三行，引入轉(zhuǎn)換HTML的XSL樣式單的起點(diǎn)文件docbook.xsl，如果是XSL-FO的定制層，起點(diǎn)文件在fo目錄下。然后就可以添加自己的修改了。

定制分為兩類，一類是修改樣式單參數(shù)，一類是修改模板。

3.1 修改樣式單參數(shù)

打開html/param.xsl或者fo/param.xsl，可以找到所有的樣式單參數(shù)。看下面這個(gè)例子

<xsl:param name="section.autolabel" select="0"/>

參數(shù)的名字是“section.autolabel”，值為“0”。這個(gè)參數(shù)的作用是控制生成文檔的時(shí)候是否對(duì)小節(jié)自動(dòng)編號(hào)，譬如“1”，“1.1”等等。“0”表示關(guān)閉自動(dòng)編號(hào)。你可以看一下前面生成的文檔，是不是沒有章節(jié)號(hào)？

要打開自動(dòng)編號(hào)，只需要這樣修改：

<xsl:param name="section.autolabel" select="1"/>

你不是直接在param.xsl里面改的吧？如果是的話，趕緊改回來！千萬記得，所有的修改都寫在前面生成的customization.xsl。現(xiàn)在重新生成HTML，

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

注意，這個(gè)參數(shù)對(duì)HTML和XSL-FO都有效，但是你必須在customization.xsl中用<xsl:import>引入對(duì)應(yīng)的起點(diǎn)文件，否則會(huì)報(bào)錯(cuò)。現(xiàn)在新的文檔是不是出現(xiàn)章節(jié)號(hào)了？

再來一個(gè)。看你的PDF文檔，肯定沒有bookmark，因?yàn)樵趂o/param.xsl中，bookmark的功能被關(guān)閉了。在customization.xsl里添加：

<xsl:param name="fop.extensions" select="1"/>

這樣FOP在處理的時(shí)候就會(huì)生成bookmark。注意這個(gè)參數(shù)的名字，“fop.extensions”，表示這個(gè)參數(shù)屬于FOP的擴(kuò)展，只對(duì)FOP有效。如果你使用PassiveTeX，那么需要設(shè)置“passivetex.extensions”。

再來一個(gè)復(fù)雜點(diǎn)的：

<xsl:param name="formal.title.placement">
? figure after
? example before
? equation before
? table before
? procedure before
? task before
?</xsl:param>

這個(gè)參數(shù)作用于文章中的圖、表等等元素的標(biāo)題，控制標(biāo)題的位置在前面（before）還是后面（after），param.xsl預(yù)定義的都是 “before”，這里把figure的標(biāo)題放在圖的后面。這個(gè)參數(shù)對(duì)HTML和XSL-FO都有效。在你的文檔中添加<figure>元 素，重新生成文檔，就可以看到效果。

3.2 修改模板

Docbook XSL提供很多的參數(shù)控制輸出的效果。但是有時(shí)候，僅僅修改參數(shù)并不能滿足所有的要求，這時(shí)，你就需要修改模板。

我們來看一個(gè)很現(xiàn)實(shí)的例子。XSL-FO定義了一類以“keep-”開頭的屬性，譬如“keep-with-next”，表示前面的內(nèi)容與后面的內(nèi)容必須在同一頁，不能斷開在兩頁上。但是除了table，
FOP目前不支持這樣的屬性。所以當(dāng)文檔比較長的時(shí)候，在FOP生成的PDF文檔中，你會(huì)發(fā)現(xiàn)有某些小節(jié)的標(biāo)題在一頁的底部，而內(nèi)容卻在下一頁，其他有標(biāo)題的內(nèi)容，譬如圖，都會(huì)出現(xiàn)這樣的情況。這當(dāng)然是不合理的，可是無論你怎么添加“keep-”類的參數(shù)，都無濟(jì)于事。

對(duì)于這樣的情況，F(xiàn)OP的FAQ告訴你的就是，“對(duì)不起，我們還沒有實(shí)現(xiàn)”，至于什么時(shí)候?qū)崿F(xiàn)，“你別問，我也不知道”。

所以只能采取一個(gè)變通的方式。前面我說過，F(xiàn)OP對(duì)于table支持這樣的屬性，那么是否可以考慮把這樣的內(nèi)容放在table里面呢？當(dāng)然可以， FOP有一個(gè)“blind table”的概念，這樣的表除了其中的內(nèi)容是不可見的，正符合我們的要求。現(xiàn)在的問題就是，Docbook XSL樣式單生成的是通用的XSL-FO文件，不會(huì)把像<sect2>這種元素的內(nèi)容放到“blind table”里面。那就只剩一條路了（其實(shí)還有一條，用商業(yè)產(chǎn)品^_^，RenderX的XEP支持“keep-”類屬性），修改樣式單模板。list 4的代碼把<sect2>的內(nèi)容放到一個(gè)“blind table”里面。
?
?????????????????????? 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 &gt;= 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>

對(duì)于這段代碼就不多做解釋了，總的來說其作用就是覆蓋了sections.xsl中定義的名為“sect2”的模板，在生成XSL-FO文件的時(shí) 候，把<sect2>的標(biāo)題和內(nèi)容分別放到一個(gè)單列表的兩行。因?yàn)檫@里用到了fo名字空間，所以在開始要引入fo名字空間。

重新生成PDF文件：

fop -xml yourarticle.xml -xsl C:\docbook-xsl-1.67.2\blindtable.xsl yourarticle.pdf

你會(huì)發(fā)現(xiàn)所有<sect2>的內(nèi)容沒有標(biāo)題與內(nèi)容斷開在兩頁上的情況了。

4. 總結(jié)

到此為止，你已經(jīng)了解制作Docbook的完整過程：

1) 編輯XML文檔；
2) 生成HTML/PDF；
3) 定制XSL樣式單。

定制XSL樣式單不能直接修改Docbook XSL樣式單，需要?jiǎng)?chuàng)建一個(gè)新的XSL文件作為定制層。

XSL樣式單定制有兩類：

1) 修改XSL參數(shù)；
2) 修改XSL模板。

總之Docbook是十分強(qiáng)大的工具，可以用來制作非常專業(yè)漂亮的技術(shù)文檔，甚至是其他文檔。

參考文章：

Docbook簡介

安裝配置Docbook

DocBook XSL: The Complete Guide