cuijiemin

浏览: 263923 次
性别:
来自: 杭州

最近访客更多访客>>

hyc1991

tpwulawula

love1238

gcp1992

博主相关

博客

微博

相册

留言

关于我

文章分类

社区版块

存档分类

DocBook 文件寫作入門

Linux XML 出版 HTML Unix

DocBook 文件寫作入門

作者. 老貢生

Edited by

總編. 老貢生

台灣企鵝寶寶工作隊

Revision History

Revision 1.2	2004/01/01 15:10:15
第一次正式公開發佈
Revision 1.1.1.1.2.1	2004/01/01 09:25:51
第一次草稿

這是一本幫助以前沒接觸過 DocBook 格式文件的新手，一個基礎導覽的技術小手冊。本手冊並未包含所有 DocBook 標籤，及其詳細解說。本手冊只挑選 DocBook DTD 定義中最常為使用者利用的標籤做最基礎的解說，尤其會和 HTML 的相類似格式資料做比對。所以不應該希望本手冊為你解答所有 DocBook 的疑惑，這只是一個墊腳石和敲門磚，幫助你更快的向 DocBook 的殿堂邁進。

本文採用 GNU 組織的 GPL公開版權宣告，歡迎複製,改寫,散佈，並要求你應該以同樣的權利條款，授予文件的使用人。對 GPL 的進一步的解釋，請參考GNU 通用公共許可證。

我的感謝

首先我要感謝 James Clark 先生，沒有他，我們就缺少了一個執行 DocBook 文件解析轉譯的自動執行工具。他的 OpenJade 工具組，是一切 SGML 文件處理的心臟和引擎。由於他的慷慨，使得我們不必花一毛錢，就能擁有商業軟體同樣的服務和效能。

我們也要感謝 Norman Walsh 先生，要不是他耗費心力製作 docbook-dsssl 轉換輸出樣式表，DocBook 將只是又一個意義分類結構標記語言的實驗，一種理論性的教材而已。有了配套的 DSSSL 樣式表，DocBook 才能轉換成 text,rtf,ps,html 各種文件，真正達成一次輸入，多種輸出，各種格式文件交換中介的有力工具。

Norman Walsh 先生不只提供 DocBook-DSSSL ，他本身也是 OASIS DocBook 委員會的主要成員。藉由早期的 Davenport 討論組，到現在 DocBook Committees 參與成員的不斷努力，所謂分類意義的結構化文件格式的使用，已經不再只是個目標而已，它已經開始在我們的電子文件處理中日漸擔負起重要的使命。

最後，照慣例，要感謝我已七六高齡的老母親，要不是他打理我生活的一切，我一定連三餐都成問題，還提什麼奉獻呢？我知道這世間就算沒了我們母子，一樣陽光燦爛，生氣蓬勃，但至少這篇文章是不會問世了。所以如果你覺得從這篇文章多少得到益處，請和我一樣，多少感謝我娘及自己的娘一些。

Table of Contents

導論

1.1. 無用之用

1.2. 文件型態宣告

1.3. 根標籤

1.4. 常用的根標籤介紹

1.5. DocBook 最基本的文件結構 -- Sect

1.6. 基本的根標籤結構

1.7. 條列資料表示法

1.8. 表格資料表示法

1.9. 外部其他媒體格式檔案表示法

1.10. 書籤與聯結的表示法

1.11. 其他區塊資料的表示法

1.12. 字串強調表示法

1.13. 其他標籤使用方法

2. 特殊資料格式的標籤

2.1. 出版訊息表示法

2.2. 作者序言表示法

2.3. 目錄索引表示法

2.4. 詞彙解釋表示法

2.5. 參考書目表示法

2.6. 問題解答集表示法

2.7. 結語

A. 附錄

List of Tables

1-1. mediaobject 主要組成列表

1-2. 特殊意義的區塊標籤

1-3. DocBook 特殊字元表

A-1. 單純標籤次序規則敘述表

A-2. 綜合標籤次序規則敘述表

List of Figures

1-1. DocBook DTD 文件組成結構圖

List of Examples

1-1. SGML 的備註表示法

1-2. SGML 的文件型態宣告

1-3. XML 的文件型態宣告

1-4. sect 的基本結構

1-5. sect 的層級結構

1-6. chapter 基本的層級結構

1-7. book 基本的層級結構

1-8. book 的 SGML 文件模型

1-9. book 的 XML 文件模型

1-10. HTML 的編號列示資料表示法

1-11. DocBook 的編號列示資料表示法

1-12. HTML 的兩段條列式資料表示法

1-13. DocBook 的兩段條列式資料表示法

1-14. DocBook 的簡單列示資料表示法

1-15. DocBook 單一形式表格

1-16. DocBook 跨行列表格

1-17. DocBook 附加說明訊息表格

1-18. DocBook 的圖形資料顯示

1-19. DocBook 的外部多媒體資料顯示

1-20. DocBook inline 標籤的使用

1-21. HTML 的書籤表示法

1-22. DocBook 的書籤表示法(1)

1-23. DocBook 的書籤表示法(2)

1-24. DocBook 的聯結表示法

1-25. xref 與 link 輸出結果比較

1-26. 鄭愁予詩選

1-27. DocBook 註腳連結表示法

1-28. 引用資料表示法

1-29. 圖解說明的表示法

1-30. 範例說明的表示法

1-31. tip 區塊表示法

1-32. 字串強調表示法

1-33. 字串下標表示法

1-34. 字串上標表示法

1-35. 版面格式表示法

1-36. 特殊字元除能表示法

2-1. Book 的特殊資料區段位置

2-2. bookinfo 出版訊息表示法

2-3. dedication 作者序言表示法

2-4. index 目錄索引表示法

2-5. glossary 詞彙解釋表示法

2-6. bibliography 參考書目表示法

2-7. 問題解答集（qandaset)範例

導論

本手冊希望協助一些還不熟悉 DocBook 文件格式的新手，學習基本的語法，並能快速而容易的開始觸類旁通，把 DocBook 這種格式的組織方法，用到自己文件的開發上。當然，在你學習一項新事務前，總希望知道一些新東西特性，大概的用途，以及最重要的，學會了有何好處？所以我們一開始先來談談 DocBook 是什麼？

1. DocBook 是什麼

談到 DocBook ，有人喜歡以標記語言出發，先解說一大堆 SGML 和 XML 的概念。另些人則著重在表形文件格式與表意文件格式的分別，強調所謂邏輯結構和意義分類在文件組織的重要性。這些都對，也都是組成 DocBook 的重要概念，但是這些概念本身比 DocBook 更難理解，結果是用一個不明白解釋了另一個不明白。為了避免花了大半篇幅，還是讓你一頭霧水，我不企圖讓你明白什麼叫標記語言的結構邏輯，也不一再舉例表形和表意格式文件的差別，我只向大家說明一個重點，那就是 DocBook 文件能做怎樣的利用，你能從 DocBook 的格式安排上得到什麼樣的好處。

1.1. 寫一份學術著作

從望文生義來做最直接的了解，DocBook 的 Book 就是書，DocBook 的種種格式就是幫助你很方便的去寫作一本書。而且這本書是指具有理論性，嚴謹性的學術著作，所以舉凡目錄,索引,參考書目,詞彙解釋,備註解釋.....，乃至作者,出版商,書籍國際編碼等等，舉凡一本我們在書店買到很正式像樣的書中所能找到的各種資料分類，DocBook 都做了相對應的格式規劃。只要你按照 DocBook 規定填入各部份資料，透過翻譯轉換器及樣式表的自動處理，還可以為你自動編輯版面和補充資料，而且你的書寫得愈大愈多，你就會發覺 DocBook 幫你省下的編排功夫也愈多。

DocBook 並不是只適用大部頭的書籍寫作，單一主題的討論文章，或是問題解答集也很合適。但基本上 DocBook 是為學術或技術性等論理文章設計的，而不是為詩詞歌賦這種文藝文章設計的。

1.2. 一次輸入多種輸出

DocBook 格式文件的最大特色就是沒有可閱讀的版面樣式，這並不是說 DocBook 文件無法閱覽，剛好相反，任何一個能處理純文字的編輯器和瀏覽器都能開啟 DocBook 格式文件。問題是那只是字元一個挨著一個，你完全看不出來那個字串該使用什麼字體字型，要多大多小，要置左置右置中，那個要縮排，那個要凸排，那個要單獨另成一段，那個要折行，又那個要緊跟前面，不分段落。凡此種種，你常在各種排版軟體上使用的版面設定和功能，在 DocBook 裡一樣也找不到。

DocBook 做為一個標記文件，一樣有標記設定，以及將文章加以分類的方法。不過他是將文章分為章,節,段,落，作者，出版商...等等，至於作者,出版商,章,節,標題等該用什麼字型字體，成個什麼段落，在 DocBook 格式定義裡完全沒有這些訊息。DocBook 把這些設定留給樣式表去規定[1]。所以只要樣式表一變，DocBook 最終轉換輸出的結果就會改變，而完全不需改動到原有的 DocBook 文件內容。利用標記語言中資料文件本體與輸出樣式表分開的概念，我們只要按 DocBook 格式規定，輸入一次資料，就可以利用樣式表的設定及改換，可以轉換輸出成 HTML,RTF,PS,MAN...等等其他閱覽格式的文件，並且可以設定個人或組織專屬的特殊風格，這就是所謂的一次輸入，多種輸出。

1.3. 建立可搜尋的文字庫

DocBook 另一個被稱頌的功能就是他的分類細膩而週延，結構完整，並且有搜尋次序上的意義。由於這些特性，凡遵照 DocBook 格式規定製作出來的文件，有如一個資料庫一般，有完整的紀錄次序，欄位分隔，可供條件查詢及檢索。所以不只把 DocBook 文件轉換成其他格式文件，是有效的利用，就是把 DocBook 原始文件放在網路上供查詢檢索，也比任何其他的排版格式文件更為適合。

1.4. 共同文件寫作

DocBook 是非常靠近 SGML 原始型態及功能的格式文件，透過對 SGML 中模組化的文件型態定義，條件編譯選項，外部插入檔案等等功能的繼承，使得 DocBook 非常適合擔任團體共同寫作文件的重任。經由根文件的適當設定，每個寫作團隊成員都可以分頭獨立寫作部份文件，最後再透過 DocBook 的自動編排功能，把獨立的部份文件串成一個整體文件，宛如一個人寫作一般。

由於這個共同寫作的強大功能，在 Unix 系統下許多軟體開發專案團隊，都漸漸採用 DocBook 作為他們共同寫作的解決方法，最有名的例證就是 Linux 的 HOWTO 文件的組織整理，已經將 DocBook 做為推薦的標準寫作格式。[2]

2. DocBook 的源流

尋找一個共通的，可以在不同的工作平台及作業系統中，在不同的排版軟體中，交換彼此資料的文件格式，一直是許多機關組織，工作團隊，在製作流通文件上的基本需求。尤其在 Unix 的 Open source 軟體開發團隊運作上，更是不停的在尋求更理想的運作模式。這其中尤以 The Linux Document Project [3] 這個專案計畫最具指標意義，因為 TLDP 匯集了 Linux 作業系統下各個層面的軟體使用者及發展者，所以 TLDP 網站採用的文件格式，幾乎就可以說是 Linux 社區的標準資料格式了。所以，現在我們就來看看 TLDP 文件格式的演化過程。

2.1. HTML

作為 Wild World Web 的一分子，大概主要的顯示文件都是 HTML 文件吧。在所謂意義分類的結構文件概念尚不發達，來源資料與版面顯示分開處理的技術尚未開展時，HTML 格式，既是資料來源的組成，也是最終的顯示樣式，一肩挑起所有的大梁。

2.2. LinuxDoc

HTML 雖然在網路資料的交換顯示上，有其不可忽視的貢獻，但卻有他另一面不足的地方。第一：HTML 只適合在網頁瀏覽器中顯示，如果要把他列印，或用別的排版軟體開啟，顯示的結果都會格格不入，無法配合。這時同樣的內容，換種利用方式，就要對文件做重新編排，導致編輯時間浪費及版本混亂。

其次 HTML 並不會對文件內容加以歸類，他的標記只是表明那個字串或區段該如何排列顯示而已，並不會有任何指示，告訴你那一段文字，他代表了什麼意義。這對網路資料的搜尋與統整毫無任何幫助，他無法達成一份文件，既能顯示，又方便檢索查詢的資料庫功能。

為了尋求更符合需求的文件格式，大家不約而同的都尋求 SGML 這個標記語言的幫忙[4]。首先是 Tom Gordon 利用 SGML 語法制定了一個 QWERTZ DTD ，目的是為了方便輸入資料，然後自動化產生 LaTex 排版格式文件。

接著是 Matt Welsh，他覺得 QWERTZ DTD 既可以將一般文字轉換成 Latex 格式文件，那同樣的原理，應該也可以產生其他種格式文件。正巧他的工作，需要大量產生各種不同格式的文件，例如像plain text, html, and PS 等等，因此他修正了一下 QWERTZ DTD，作為他 Linuxdoc-SGML document processing system(Linux SGML 格式文件處理系統) 的核心部份。由於 Linuxdoc 格式的產生，確實能解決一次輸入，多種輸出的功能，以及將文件做良好有意義的分類，以方便檢索的功能，因此被 TLDP 採用為交換文件標準。從此所謂的 Linux SGML 文件變成 Linux 系統中，非列印顯示，而是以意義分類為標記的格式文件統稱[5]，而 Linuxdoc 格式就是第一代的 Linux SGML 文件。

2.3. DocBook

TLDP 所屬的不少人曾用 Linuxdoc 格式寫作 HOWTO 文件，但 Linuxdoc 本身的發展演進卻不令人滿意。在 Matt Welsh 繼續發展了幾年沒有很好的成效後，Cees de Groot 用 perl 這套程式重新改寫了 Linuxdoc 系統，改名為 SGML-tools ，但 DTD 仍用的是 Linuxdoc 的標準。最後 SGML-tools 又被用 python 程式語言全新改寫了一次，但這次，Linuxdoc 卻讓出了龍頭寶座，而把文件製作的格式標準，讓給了另一個由 SGML 語言定義出來的 DocBook 格式文件。

DocBook 並非由 Linuxdoc 衍生出來的，它有它自己的故事。早在 1991 年 HaL Computer Systems 和 O'Reilly & Associates 這兩個組織為了達成 Unix 作業系統下 groff 文件系統轉換問題，特別用 SGML 設計了 DocBook V1.1 這個格式文件。

在 DocBook V1.1 推出的同時，O'Reilly 開闢了一個討論園地，稱為 Davenport 討論組。參與 Davenport 討論的成員非常投入，貢獻良多，因此到了 1994 年他們得到正式的授權，成為 DocBook 格式標準的正式維護組織，並同時推出 DocBook V1.2.2。

DocBook 交到 Davenport 手上後，快速的成長蓬勃，不只包含的企圖與收納更多，並且擺脫 groff 工具的限制，直接使用 sgml 解譯器程式來處理文件轉換，並嘗試直接做列印格式輸出。這時期 Novell 和 Sun 兩大資訊公司對 DocBook 風格的形成，有很大的影響。

到了 1997 年 1 月，Davenport 推出 V3.0 後的不久，一些 Davenport 的主要發展者開始討論怎樣把 DocBook 格式文件從原來的 SGML 標記語言推展到 XML 標記語言，從而能在 DocBook 中使用 XML 發展蓬勃的應用工具軟體。它們取得了一些進展，但在 Davenport 時期，並未完成這件工作。

1998 年 7 月，在 Davenport 原有的贊助者結束贊助的情況下，由綠洲組織(OASIS)接手 DocBook 發展計畫，成立了 The DocBook Technical Committee 組織負責推展及研發 DocBook 。目前 DocBook 已推出 V4.2 ，並且完成了 XML 的格式定義檔案，變成可選擇由 SGML 或 XML 兩種轉譯方式的處理。DocBook Technical Committee 的發展人員正著手規畫推出 DocBook 5.0 ，正逐步健全發展，也成為 KDE,Gnome 以及 TLDP 等數十個公私組織的標準文件交換格式，勢必在將來日增其影響力，成為普遍的文件標準。

3. 開始寫作前的準備工作

如果 DocBook 格式文件已經挑起你的興趣，而你以前又從未製作過 DocBook 格式文件，那麼可以考慮跟隨著本手冊的章節，從最基本的開始。雖然 DocBook 文件唯一需要的工具只是一個簡單的文字編輯器即可，Unix OS 下的 vi ，MS Windows 下的 notepad 都可勝任愉快。但能夠邊編寫邊解析轉換，校正標籤使用的合法性及觀視閱覽格式輸出的結果，都是你在學習製作 DocBook 文件時不可或缺的。所以一些解析轉換 DocBook ，及檢視輸出結果的工具，也是我們在製作 DocBook 文件前要先準備好的。先了解一下 DocBook 文件運作流程，有助於我們了解要做那些準備工作。

Table 1. DocBook 文件運作流程表

流程名稱使用工具準備方法

依 DTD 定義編寫文件	任何的文字編輯器皆可	使用系統中的原有編輯工具
將寫好的文件加以解析，並檢查是否符合文法。	DocBook 的 DTD 文件模組	在系統中安裝 DTD 文件模組
OpenSP 文件解析程式工具	在系統中安裝 OpenSP 程式工具
將解析過的文件，依照樣式表文件模組轉換成別種格式文件。	DocBook 的 DSSSL 文件模組	在系統中安裝 DSSSL 文件模組
OpenJade 文件轉換程式工具	在系統中安裝 OpenJade 程式工具
將轉換過的文件，用適合的瀏覽器觀視檢查。	依轉換格式選擇瀏覽工具	使用系統中適合的瀏覽器

由上表可知，學習 DocBook 文件編寫的必要工具是：

純文字編輯器
DocBook 的 DTD 文件模組
DocBook 的 DSSSL 文件模組
SGML 的解析器 OpenSp
SGML 的轉譯器 OpenJade
輸出格式文件的瀏覽器

如本手冊前面所言，文字編輯器任何一個都可以，系統中現有的，習慣使用的即可。DTD,DSSSL,OpenSp,OpenJade 等工具的安裝及設定，在 Linux 系統下，可以使用 docbook-utils or sgml-tools 套件，或者你也可以參考本人的另一篇譯文 DocBook XML/SGML Processing Using OpenJade 從原碼來自己編譯建立 DocBook 的轉譯輸出系統。至於輸出格式的瀏覽器，本手冊的輸出是採用 HTML 格式，所以不管你使用 IE,Netscape or Mozilla ，都是很適合的瀏覽器。

4. DocBook 編寫的注意事項

4.1. 標記語法的規則

DocBook 使用的標記語法和 SGML 預設值相同，如果你會使用 HTML or XML 的標記語法，那麼可以說也就會了 DocBook 標記語法。但如果你不曾接觸過 SGML 的標記語法，不妨看看下面標記語法的簡短介紹。

要在文件中加入分類標籤，一定要有些字符負責當作分隔字符，把標籤資料和文件原始內容分開。SGML 是以 '<' 字符當作標籤開始字符，把 '>' 當標籤的結束字符，所以一個資料內容的開始標籤，它的語法是 <標籤名稱屬性名稱A="屬性值" 屬性名稱B="屬性值" ...> ，< 和 > 字符之間是標記資料。

至於一個資料內容的結束標籤就比較簡單，他的語法是 </標籤名稱>，分隔字符和開始標籤完全相同，標籤名稱前要有 '/' 前置字符，至於屬性值字串，結束標籤是不需要屬性設定的。

最後開始標籤字串和結束標籤字串間包夾的就是文件的分類資料內容了，譬如：

<emailid="mymail">abc@def.idv.tw</email>

<email id="mymail"> : 開始標籤

email : 標籤名稱

id="mymail" : 標籤屬性設定

ibc@def.idv.tw : 資料內容

</email> : 結束標籤

標記語言對標籤的格式有嚴格的要求，除了分隔字符，標籤名稱，屬性名稱不能有絲毫錯誤外，尤其是 XML 語法定義的 DocBook 格式，不可任意簡省結束標籤，或採取像

<emailid="mymail"/abc@def.idv.tw/

這樣的簡省敘述。請一定照規矩打足開始標籤與結束標籤，空標籤沒有結束標籤，所以他的開始標籤結尾要加 '/' 字符，如 <xref linkend="address" />。

4.2. 特殊字符的表示法

如同前一小節敘述，'<' 和 '>' 字符被 DocBook 拿來當作標籤分隔字符用，那萬一我們要顯示 '<' 和 '>' 字符符號，而不是要他發揮分隔字串功能的時候該怎麼辦呢？這時就要有個 '<' 和 '>' 字符的代名來表示要顯示他們原來字元的意思。'<' 的代名是 lt(little) ，'>' 的代名是 gt(great) 。使用代名時要在代名前加個 '&' 字符當前置字，';' 當收尾字。< 表示 lt 這裡不是代表 "lt" 字串，而是表示 '<' 字元顯示的意思。

這裡為了特殊字元表示把 '&' 字符借去當前置字，那麼 '&' 字元本身也成了特殊字元，所以也有個 '&' 的代名是 amp ，表示式是 & 。

DocBook 特殊字元列表請參考後面章節的 DocBook 特殊字元表> 。

4.3. 放棄版面編排的習慣

百分之九十以上的人在製作文件時，都會考慮到版面編排的問題，因為重視文件閱覽的感受和效果，被認為是一個文件撰寫人應當負起的責任。但這在 DocBook 文件撰寫時，卻是你應該極力屏除的心理障礙，理由如下：

不管是 XML 或 SGML 標記語言定義的格式文件，都是忽略格式字元處理的，所以不管你在一行文字前塞入多少空白，在行與行間按下多少個分段按鍵，DocBook 一概忽略不理，所以就算你費盡心力去排，也是枉然，對 DocBook 來說，只有標籤的改變才是有意義的。

DocBook 的功能就是要將資料塞到各種顯示格式文件裡，唯有他毫無任何固定格式，才能隨時被捏塑成各種格式。任何單一的版面考慮，不管是對 HTML,RTF or Tex/Latex ，當他換成另一種顯示時，原來的版面設定肯定會成為搗蛋鬼和麻煩的來源。所以 DocBook 文件本身不該包含版面設定資料，決定輸出成什麼樣子，應該留給樣式表來決定。在 XML 中是 XSL 和 XSLT ，在 SGML 中是 DSSSL 。

在 DocBook 中重視的是大量文件的自動編排轉換，和統一風格的建立，單一文件版面細部的修整設定，不是 DocBook 所擅長的。

我們常在 DocBook 文件中，把子標籤前多塞幾個空格，好表示他是父標籤的下一個層級。這純粹是方便文件撰寫者檢視文件語法用的，與輸出格式完全無關，一個標籤是否是另一個標籤的子標籤，端看他是否處在別人的開始標籤與結束標籤中，與他是否縮排或凸排完全無關。

4.4. 其他注意事項

本手冊以 SGML-DTD-V4.2 為標準，所以你至少需下載 DocBook sgml-dtd-4.2 DTD 模組文件。

本手冊只觸及 DocBook 所有標籤的一小部份而已，如果有任何疑問或懷疑，請以 DocBook: The Definitive Guide 記載為準。

本手冊的各範例希望你都能試作一遍，並把他們轉換成 HTML 文件，在網頁瀏覽器上觀視。這樣做有兩個好處；一：校正自己的語法錯誤(我使用 DocBook 到如今，沒有一次不用錯語法的。)二：知道 DocBook 這樣安排的意義所在。

留心轉譯器所顯示的錯誤訊息，像：

jade:preface.sgml:134:112:E:endtagforelement"LISTITEM"whichisnotopen
jade:docwrite.sgml:33:12:E:endtagfor"APPENDIX"whichisnotfinished

它會告訴你原因及詳細的錯誤所在，別偷懶，一一去改正你文件中的錯誤。

Chapter 1. 基礎標籤的運用

本章將介紹 DocBook 格式文件寫作時，最基本而且常用的標記名稱及使用方法。尤其是把重點放在與 HTML 相對應功能的標記上，希望你學會這些標記後，至少能做到把 DocBook 文件資料，轉換成 HTML 網頁，供人網路閱覽無礙。至於其他比 HTML 更進一步的功能，我們在製做其他文件常用的，將會分別以專章討論。至於一些十分細碎的，特殊用途的標記，則不是本手冊能包含的內容，請到 DocBook 官方網站查詢官方版的線上手冊。

1.1. 無用之用

在介紹任何其他有分類意義的標籤前，先要介紹這個不代表任何分類意義，也對文件內容或輸出格式無任何影響的標籤，就是備註標籤。不管 HTML,DocBook or XML ，他們的備註標籤格式都一樣，以 "" 字串結尾的一個空標籤，凡在 "" 間包夾的所有字元字串都被忽略，一律不予處理，這是 SGML 標記語言的預設備註表示法。

Example 1-1. SGML 的備註表示法

<!DOCTYPEbookPUBLIC"-//OASIS//DTDDocBookV4.2//EN">
<book>

......

</book>

上例可知，"" 間的所有文字敘述，都只是對本文的附加說明而已，使用與不使用都對該文件沒有影響[6]，本手冊一開始就介紹這標籤的目的是，後面很多的解釋段落要用到他，你及早知道這樣表示法的含意，才不會不知所云。

1.2. 文件型態宣告

不管是 SGML 或 XML ，除了註解之外，開頭的第一或第二個標記，一定是用一個文件型態宣告的標記，來標明整份 SGML 文件，是遵守那種 DTD 格式規範所製作的。他的目的是通知負責處理此份文件的軟體程式，使用適合的 DTD 規定，來解譯和處理。這是一切 SGML 文件製作法則的依據，也是 DocBook 在完成以後，能夠順利轉換成別種顯示格式文件的根本，雖然他不是文件要顯示的內容，卻是決定並掌管了整份文件的規則，所以必須清楚明確而不可少。

Example 1-2. SGML 的文件型態宣告

<!DOCTYPE	book	PUBLIC	"-//OASIS//DTD DocBook V4.2//EN">
註1	註2	註3	註4

註1, 文件型態表示詞

'!' 字符加上大寫 "DOCTYPE" 字串，表示這個標籤作為宣告文件型態之用。

註2, 根標籤名稱

指定本文件要用那個 DocBook DTD 定義的標籤當根標籤。原則上 DocBook 並未嚴格指定限用那些標籤做根標籤，所以不只 book ，像 article,chapter,grossary.appendix 都可以當根標籤。但很重要的一點就是，根標籤是一份文件最上層的標籤，不可以有比他更高層的標籤出現在文件中，所以一旦你選定了根標籤，也同時決定了這份文件能使用那些類別的子標籤和階層結構。這點是和 HTML 大不相同的，HTML 的根標籤永遠是 <html>，能使用的標籤名稱和結構也永遠不變，但 DocBook 的文件的風格，會跟著根標籤的不同而改變。

註3, 公共識別表示詞

大寫 "PUBLIC" 字串是表示它後面跟了個公共識別字串，又稱作 PUBLIC IDENTIFIER 。DocBook 有個龐大的 DTD 定義，通常都不會直接和本文寫在一起，而採外部文件形式，把 DTD 敘述儲存成單獨的檔案，在解譯轉譯 DocBook 文件時，再由解譯器載入外部 DTD 檔案，以分析 DocBook 文件。那為何不直接寫 DTD 的檔案路徑名稱就好，而要拐彎抹角，搞個又臭又長的 public ID 字串呢？這是因為 DocBook 是一個供不同平台交換資料訊息用的文件。當一份文件由作者的主機傳到閱覽者主機上時，怎能保證彼此的 DTD 定義檔路徑會一樣呢？所以為了避免因閱覽者與文件作者主機系統配置不同而指定錯誤，就用 public ID 的辦法。經由 DocBook 使用者在自己機器上放置一份對照表，紀錄各 public ID 的 DTD 相對應檔案路徑，就不必耽心因為彼此 DTD 檔案放置路徑的不同，而無法成功轉譯。

註4, 公共識別字串

任何一個格式標準的發佈者，都應該設定其與眾不同，獨一無二的識別字串，來公佈周知。如果在文件開頭看到這個識別字串，就表示此文件使用該發佈者制定的格式，應該依據發佈者規定的方式處理。這個識別字串的組成可翻閱參考字典的 Public Identifier，查看標準的組成方式。但縱使不依據此規則，仍無損其效力，因為識別字串的關鍵是獨特與唯一。而 DocBook 的每一版本都有其唯一的公共識別字串，你必須完全照抄，不能任意增減，所以寫作前請先參考相關 DTD 下載群組的 catlog or docbook.cat ，看看他要求的識別字串是怎麼下的，然後複製貼上，成為你 DocBook 文件的第一行。

Example 1-3. XML 的文件型態宣告

<?xmlversion='1.0'?>
<!DOCTYPEbookPUBLIC"-//OASIS//DTDDocBookXMLV4.1.2//EN"
"http://docbook.org/xml/4.1.2/docbookx.dtd">

XML 文件表示標籤：W3 組織制定 XML 標準時的規定，凡使用 XML 標記語法的文件，開頭第一行要做這樣的表示。如果你是採用 SGML ，當然就不能加這個。

除了public ID 加上 XML 字樣外，其他完全和 SGML 的 DOCTYPE 標籤用法一樣。

SYSTEM ID 路徑字串：這也是只有 XML 才有的要求，通常是指向外部 DTD 規格檔的所在路徑。由於 XML 標榜的是網路運作交換，所以通常這裡都是 DTD 檔的 URL 位址。不管是 SGML 還是 XML ，當設定產生競合衝突時，文件設定高於系統設定，所以解譯器在處理時，是會跨過系統指定的 DTD ，而到網路上去找指定的 DTD 檔。但這也同時容易在網路位址錯誤或更動時，引起找不到 DTD 檔的錯誤而導致解譯轉換失敗，所以 SGML 和 XML 文件宣告方式的差異，可說各有利弊。

1.3. 根標籤

根標籤表示一個文件的定義宣告區段結束，文件分類編輯區正式開始。除此之外，根標籤有下列規則必須遵守：

根標籤的法則

任何一份 DocBook 文件都不能缺少根標籤。
根標籤的起始標籤必須緊接著定義宣告區段，作為本文的第一個標籤，而他的結束標籤必須在結尾的最後一個，包含著整個本文的其他標籤及文字區段。
根標籤必須與 DOCTYPE 宣告的根標籤名稱一致。
根標籤不得包含在 DTD 定義中的上層結構標籤，也就是一份文件只可以出現及使用根標籤的子標籤。
根標籤在同一份文件上只可以出現一次，不得出現兩次以上。這包括根標籤內含根標籤的階層結構，或兩者前後排列的平行結構。
空標籤不得作為根標籤。

1.4. 常用的根標籤介紹

就如前面章節所言，DocBook 並不限制根標籤要用那個。但依據一般我們日常的使用習慣，也考慮到最後輸出格式的樣式表是否支援，還是有些比較標準化的根標籤可供依循。一般比較常用的根標籤有：

book, 書籍, 手冊

這並無一定大小的區別，與一般我們對書籍觀念類似，集合幾個章節，談些相關但分門別類的主題。

chapter, 章

雖然 chapter 本身在 DocBook DTD 定義中是 book 的子標籤，但一般也常拿他當討論某個單一主題文件的根標籤。導致和下面要講的 article 標籤，反而有異曲同工的感覺。

article, 主題文章

這是一個和 chapter 平行的標籤，在使用習慣上，article 比 chapter 更常被用來當根標籤，他代表單一主題的單一文章，與動用數個 chapter 去描述一個主題的使用習慣不同，所以在 Linux Document Project 上的 HOWTO 文章，用得最多的根標籤就是 article。

這純粹是種使用習慣，而非 DocBook 的 DTD 限制，沒人規定你不可以用數個 article 來談單一主題，以及只用一個 chapter 談一個主題。

當然 DocBook 不只這幾個上層標籤而已，如 set 標籤，相當於叢書，是 book 的上層標籤，而介於 book 和 chapter 之間還有個 part ，就好像我們說書的上篇下篇一樣。此外像 preface (序言，導論) ， appendix (附錄)，其實把他們看成第一個 chapter 及最後一個 chapter ，並沒什麼分別。所以熟悉 book,chapter,article 結構，就同理可推了。

此外 DocBook 也提供了一些非一般章節的，特殊格式的標籤組可以當根標籤，也可以內涵於 book 當子標籤，譬如：

index: 目錄索引

bibliography: 參考書目

glossary: 詞彙解釋

qandaset: 問答集(Q & A)

這些都是比較複雜的書籍會有的文件結構，由於他們不同於一般章節的內容，所以我們將另闢一章來講解如何製作這些特殊格式標籤組。至於本章，我們將著重在 DocBook 最基本的結構 book,chapter,article ，以及如何使用 DocBook 標籤，做出類似 HTML 表現方式的結構出來。

1.5. DocBook 最基本的文件結構 -- Sect

在進入 book,chapter,article 這三種最常用根標籤附屬結構的討論前，我們先來談談這三個根標籤共同擁有，也是 DocBook 格式文件最常被使用的子結構，sect。

sect 是 section 的縮寫，通常我們中譯成段落。在 DocBook 中他的基本結構是：

Example 1-4. sect 的基本結構

<sect[n]>
<title>段落標題</title>
<para>第一段文字......</para>
<para>第二段文字......</para>
......
[子標籤結構]
......
</sect[n]>

從 HTML 表現格式的觀念來類比，就如同一個 <Hn> 的橫幅，配上一個 <div>，<div> 裡可能是文字區段 <p>，也可能是其他的標記。所以一個標題，加上一個資料區塊，就是 sect 基本上的樣貌。

HTML 的 title 標籤和 DocBook 的 title 標籤，在意義和最後顯示格式上不大一樣，HTML 的 title 一個 page 只能有一個，而且通常顯示在瀏覽器的標題列，但 DocBook 的 title 則大部分的區段標籤都有，表現形式比較像分隔區段與區段的醒目橫列文字(like HTML <Hn>)。

至於 sect 的區塊部份，一個 DocBook 各種標籤都少不了他的就是 para。para 是 paragraph 的縮寫，中譯也是區域段落，老實說光從字義看，好像和 sect 沒啥區別，但依據 DocBook DTD 的定義，真正文字敘述是放在 para 裡面，也就是 sect[n] 是要靠 para 來收納他的文字串列的。一個 sect[n] 最少要有一個 para，但可依需要增加 para 使用數量。[7]

最後是包含子標籤，這是選項，可要，可不要。sect[n] 表示是有層級分別的，目前 DocBook DTD 的定義是 sect1 到 sect5五個層級，而且必須按層級逐階隸屬，也就是你不可以不透過 sect2 就直接把 sect3 塞到 sect1 裡。 [8] 同理，如果你堅持要使用 sect5 ，那就必須：

Example 1-5. sect 的層級結構

上面的結構範例請你再多看兩眼，因為把它記熟了，你就已經會了百分之六十的 DocBook 基本結構[9]。而且不要懷疑，光靠這幾個標記，已經夠寫出個陽春型的 DocBook 文件來了。

1.6. 基本的根標籤結構

首先我們談 chapter 和 article ，這兩種根標籤結構大同小異。以 chapter 為例，套用上節的 sect 結構理念，一個標題配一個資料區塊，那 chapter 的基本結構就是：

Example 1-6. chapter 基本的層級結構

article 的根標籤基本結構，就是把那根標籤名稱從 chapter 換成 article 就成了。

至於 book 這個很有份量的根標籤是由數個 chapter 或 article 組成，所以book 根標籤的結構應該是類似這樣：

Example 1-7. book 基本的層級結構

有了基本根標籤結構還不能稱為完整的 DocBook 文件，我們還要為它們加上 SGML 標記語言規則所要求的文件型態定義宣告。依 DocBook 是採用 SGML or XML 宣告方式，一個完整 DocBook 文件模型應該是：

Example 1-8. book 的 SGML 文件模型

<!DOCTYPEbookPUBLIC"-//OASIS//DTDDocBookV4.2//EN">
<book><title>書籍名稱</title>
<chapter><title>章標題</title>
<para>章引言...</para>
......
</chapter>
......
</book>

Example 1-9. book 的 XML 文件模型

<?xmlversion="1.0"?>
<!DOCTYPEbookPUBLIC"-//OASIS//DTDDocBookXMLV4.2//EN">
<book><title>書籍名稱</title>
<chapter><title>章標題</title>
<para>章引言...</para>
......
</chapter>
......
</book>

如果你想要把根標籤換掉，比方是 article ，那你的 DocBook 表示方法應該是：

<?xmlversion="1.0"?>
<!DOCTYPEarticlePUBLIC"-//OASIS//DTDDocBookXMLV4.2//EN">

<article><title>研究主題</title>
<sect1><title>標題</title>
<para>引言...</para>
......
</sect1>
......
</article>

文件的根標籤要與 SGML 定義宣告區 DOCTYPE 裡的根標籤宣告相同。

掌握這些範例的文件基本模型，就可以掌握基本的 DocBook 寫作技巧，也就可以開始製作你自己的 DocBook 文件了。就算你用這些陽春結構，一樣可以通過 SGML 編譯轉換器的轉換，產生方便閱讀的其他格式文件，或者建立了 Text Base 的樹狀資料庫，它沒有任何結構的缺陷或不完整。所以剩下的其他，都只是使你文件形式更豐富，功能更多樣而已，供你行有餘力而為。所以，下面我們要介紹一些能增加你文件的表現形式或特殊功能的標籤用法，首先，我們介紹一些類似於 HTML 格式的資料，然後再談一些 DocBook 自己所有的特殊用法。

1.7. 條列資料表示法

縱使文字敘述區塊 para 的使用率，佔了 DocBook 顯示資料的七八成，但有些資料顯示，用別的格式卻遠比 para 更恰當及有表現力。譬如同質的數筆資料，使用條列式就比區塊式敘述要好。

1.7.1. 單行條列式

以 HTML 標記語言為例，如果我們將電腦的所有設備分類加以陳述，大概呈現方法是：

Example 1-10. HTML 的編號列示資料表示法

Example 1-11. DocBook 的編號列示資料表示法

<orderedlist>
<title>電腦設備分類列表</title>
<listitem><para>處理設備</para></listitem>
<listitem><para>儲存設備</para></listitem>
<listitem><para>輸入設備</para></listitem>
<listitem><para>輸出設備</para></listitem>
</orderedlist>

DocBook 的列示資料表示法比 HTML 多的是 title ，不過這是選項的，也就是如果你希望為你的列示區塊下個標題，你就可以用 title 標籤，不只列示資料區塊是如此，幾乎所有的區塊皆是如此。此外除了有編號列示區塊表示法之外，還有種無編號列示資料表示法：HTML 是用 ul 取代 ol ， SGML 則是用 itemizedlist 取代 orderedlist ，其他子結構則完全相同。

所以一個完整的文件範例應該是：

<!DOCTYPEchapterPUBLIC"-//OASIS//DTDDocBookV4.2//EN">
<chapter><title>電腦設備簡介</title>
<sect1><title>電腦設備分類</title>
<para>我們可將電腦所有使用設備粗分為下列類別：</para>
<orderedlist><title>電腦設備分類列表</title>
<listitem><para>處理設備</para></listitem>
<listitem><para>儲存設備</para></listitem>
<listitem><para>輸入設備</para></listitem>
<listitem><para>輸出設備</para></listitem>
</orderedlist>
</sect1>
</chapter>

1.7.2. 兩段條列式

兩段條列式的結構和一般詞彙解釋的結構安排相同，就是前面一個簡短名詞當作一個段落，後面的解釋敘述當作另一個段落。形成一個既有所分別，又互相隸屬的關係。如果你熟悉 HTML ，那麼 dl 標籤是一個很好的詮釋：

Example 1-12. HTML 的兩段條列式資料表示法

<dl>
<dt>SGML</dt>
<dd>StandardGeneralizedMarkupLanguage(一般標準標記語言)</dd>
<dt>XML</dt>
<dd>ExtensibleMarkupLanguage(可延伸標記語言)</dd>
<dt>HTML</dt>
<dd>HyperTextMarkupLanguage(超文字標記語言)</dd>
</dl>

Example 1-13. DocBook 的兩段條列式資料表示法

<variablelist>
<varlistentry>
<term>SGML</term>
<listitem><para>StandardGeneralizedMarkupLanguage
(一般標準標記語言)</para></listitem>
</varlistentry>
<varlistentry>
<term>XML</term>
<listitem><para>ExtensibleMarkupLanguage
(可延伸標記語言)</para></listitem>
</varlistentry>
<varlistentry>
<term>HTML</term>
<term>XHTML</term>
<listitem><para>HyperTextMarkupLanguage
(超文字標記語言)</para></listitem>
</varlistentry>
</variablelist>

如果你夠細心，你會看出我在 DocBook 兩段條列式範例中，在第三條用了兩個 term 標籤，這不是錯誤。而是 DocBook 的兩段條列式允許用數個簡短名詞排列在一個區段，但只允許用一個解釋敘述區段。這和 HTML 的一個簡短名詞配一個解釋敘述的方法，有小小的差異。

現在讓我們做個完整的 article 文件吧：

<!DOCTYPEarticlePUBLIC"-//OASIS//DTDDocBookV4.2//EN">
<article><title>格式文件概論</title>
<sect1><title>常見的格式文件形式</title>
<para>我們常接觸到的標記語言文件有下列幾種：</para>
<varia

分享到：

DocBook学习(v1.6.7) | 安装配置Docbook工具

2006-05-14 13:33
浏览 908
评论(0)
查看更多

发表评论

您还没有登录,请您登录后再发表评论

最近访客 更多访客>>

博主相关

文章分类

社区版块

存档分类

最新评论

DocBook 文件寫作入門

DocBook 文件寫作入門

作者. 老貢生

Edited by

總編. 老貢生

我的感謝

導論

1. DocBook 是什麼

1.1. 寫一份學術著作

1.2. 一次輸入多種輸出

1.3. 建立可搜尋的文字庫

1.4. 共同文件寫作

2. DocBook 的源流

2.1. HTML

2.2. LinuxDoc

2.3. DocBook

3. 開始寫作前的準備工作

4. DocBook 編寫的注意事項

4.1. 標記語法的規則

4.2. 特殊字符的表示法

4.3. 放棄版面編排的習慣

4.4. 其他注意事項

Chapter 1. 基礎標籤的運用

1.1. 無用之用

1.2. 文件型態宣告

1.3. 根標籤

1.4. 常用的根標籤介紹

1.5. DocBook 最基本的文件結構 -- Sect

1.6. 基本的根標籤結構

1.7. 條列資料表示法

1.7.1. 單行條列式

1.7.2. 兩段條列式

评论

发表评论

相关推荐

最近访客更多访客>>