製作Docbook文檔

製作Docbook文檔

[轉] 自 mickeyrat 的 Blog  

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

關於如何安裝組態工具，參見http://blog.csdn.net/mickeyrat/archive/2005/02/06/283471.aspx。

我使用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。