1. 制作Docbook文檔需要了解的知識：

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

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

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

2.1. 編輯XML文件

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

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

讓我們先來看一個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， 所有的內容都包含在book元素中，bookinfo元素包含書名（title）、作者（author）、出版社（publisher）、書號 （isbn）和版權（copyright）。接著part元素包含的內容是該書的一個部分，下面有一章，接著有一節（sect1），當然都有各自的標題。

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

在上面的例子里面，有些元素不是必須的。譬如bookinfo，可以沒有或者有一個，看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">

這個聲明表明，文檔的根元素是<article>，使用外部DTD，該DTD用一個公共標識符"-//OASIS//DTD DocBook XML V4.2//EN"標識，該DTD位于網絡的某處。標識符必須是全球唯一的，其形式為：

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

第一個prefix為“+/-”，“+”表示是已注冊的標識，“-”則相反。其他各部分的含義自己對照。

接著就可以添加內容了。首先是根元素：

<article>

</article>

article必須有一個標題：

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

標題之后必須有內容，不可能有無內容的文章：

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

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

與article相同，sect1也必須有標題：

<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>元素封裝，para即段落（paragraph）的意思。

現在就有了一個最簡單的Docbook文檔。list 2是完整的代碼。

??????????? 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>

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

2.2 生成HTML

關于如何安裝配置工具，參見“安裝配置Docbook”。

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

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

--nonet表示我不希望從網絡獲取DTD，這樣可以節省時間。

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

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

最后是要處理的Docbook文檔。

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

2.3 生成PDF文件

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

在控制臺輸入命令：

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

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

-xml指定需要轉換的docbook文檔。

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

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

在FOP處理過程中，會輸出許多諸如

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

的信息。不用理會，這是因為FOP還在開發中，許多XSL-FO的特性都不支持。這樣的問題并不影響最終文檔的生成。

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

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

3. 定制自己的XSL樣式單

當你開始正式制作自己的docbook文檔之后，你會發現生成的文檔并不能完全滿足你對格式的要求，譬如章節號、頁碼、字體等等。這一節就告訴你如何定制自己的XSL樣式單，生成滿足特定需求的文檔。下面的內容會涉及XSL和XSL-FO。

有人可能會想通過修改Docbook DTD達到定制目的，但是這種方式是不建議采用的，因為修改Docbook DTD之后，你的文檔就不再是Docbook文檔。

因為Docbook把內容與樣式完全分開，所以修改XSL樣式單，就能夠改變輸出結果。

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

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

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

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

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

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

3.1 修改樣式單參數

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

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

參數的名字是“section.autolabel”，值為“0”。這個參數的作用是控制生成文檔的時候是否對小節自動編號，譬如“1”，“1.1”等等。“0”表示關閉自動編號。你可以看一下前面生成的文檔，是不是沒有章節號？

要打開自動編號，只需要這樣修改：

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

你不是直接在param.xsl里面改的吧？如果是的話，趕緊改回來！千萬記得，所有的修改都寫在前面生成的customization.xsl。現在重新生成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

注意，這個參數對HTML和XSL-FO都有效，但是你必須在customization.xsl中用<xsl:import>引入對應的起點文件，否則會報錯。現在新的文檔是不是出現章節號了？

再來一個。看你的PDF文檔，肯定沒有bookmark，因為在fo/param.xsl中，bookmark的功能被關閉了。在customization.xsl里添加：

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

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

再來一個復雜點的：

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

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

3.2 修改模板

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

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

對于這樣的情況，FOP的FAQ告訴你的就是，“對不起，我們還沒有實現”，至于什么時候實現，“你別問，我也不知道”。

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

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

重新生成PDF文件：

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

你會發現所有<sect2>的內容沒有標題與內容斷開在兩頁上的情況了。

4. 總結

到此為止，你已經了解制作Docbook的完整過程：

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

定制XSL樣式單不能直接修改Docbook XSL樣式單，需要創建一個新的XSL文件作為定制層。

XSL樣式單定制有兩類：

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

總之Docbook是十分強大的工具，可以用來制作非常專業漂亮的技術文檔，甚至是其他文檔。

參考文章：

Docbook簡介

安裝配置Docbook

DocBook XSL: The Complete Guide