[轉]制作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。