Saqib Ali

saqib@seagate.com

老貢生

&author.joe.mail;

v1.0.0 2003-11-19 將 TLPD HOWTO 站原文 v2.2.8 版翻譯成繁體中文版，並首次在網路公開散佈。 Mr. Ali 的這篇介紹如何建立設定 docbook 格式文件執行環境的文章，寫得非常簡潔明白，對我個人在接觸 docbook 初期的環境安排幫助很大，所以翻譯成中文，希望對有志學習者有所幫助。但由於某些本 HOWTO 所談到的執行套件已有新的改版，照著 Mr. Ali 的原方法反而無法執行順利，因此我擅自做了一些修正，並加入了一些繁體中文特有的問題說明，所以如果你希望看到完全忠實的原文，請到 TLDP：HOWTO 原文的大本營，去找 DocBook XML/SGML Processing Using OpenJade 這篇文章。如果是對譯文本身有修正補充意見，請 E-Mail &author.joe.mail; 譯文作者。 術語縮寫: SGML - Standard Generalized Markup Language(一般標準標記語言) XML - Extensible Markup Language(可延伸標記語言) RTF - Rich Text Format(MS Windows 系統的格式化文件) HTML - HyperText Markup Language(超文字標記語言) PDF - Portable Document Format(可攜式格式文件) 本文主題在討探，如何安裝設定 OpenJade 這個解譯器，來把 DocBook 3.1 和 4.2 這些由 SGML 和 XML 格式語言定義出來的文件，轉換成 HTML,RTF,PDF 這些其他輸出格式的文件。 這段因為是適用美國法律上的意涵，所以不敢隨便亂翻，大意是說 Mr. Sagib Ali 准許你複製包裝改寫此文件，但你必須受 GPL 公共授權條款的約束，也就是基於此文衍生的文件，應使用同樣的授權方式給他的使用者。但一切法律上的解釋應依原文字句的意義，而非翻譯者中譯的解釋。(譯者註：也因為如此，此份中譯文件，也與 Mr. Sagib Ali 的原文一樣授權方式，准許你複製包裝改寫此文件。) This document is Copyright 2001 by Saqib Ali. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is available at http://www.gnu.org/copyleft/fdl.html. 當然最先要感謝原文作者 Mr.Sagib Ali 和協助他完成本文的朋友(包括真主阿拉在內)，因為沒有他的原文，當然也就沒有這篇譯文。 其次是要感謝透過網路建立交流管道的朋友，不管你曾經給予寶貴建議，給我很多啟發，或者只是單純的閱覽此篇文章而已，當缺少注目和掌聲，一切就會缺乏意義而不必持續了，所以你們才是一切翻譯的原動力。 結尾總是要感謝我娘，那個享受不到任何奉養，還整天要貼老本維持兒子三餐起居的可憐老婦人。她永遠搞不懂為何每天我都很忙卻賺不進一毛錢，但她沒有抱怨，只要我活的快樂就好。我，總是揮霍她的慷慨，很任性的追求我自己的意義。 DocBook 是一種文件型態的定義(document type definition:簡稱 DTD)，而 DTD 的主要作用就是定義一個文件的語法。DocBook 敘述了一種適用於技術文件上的結構和形式，他有利於普及化的原因是使用簡單而又功能完整。 一個 DTD 就如同一本文法書一般定義了一個文件應有的語法，藉由一組標籤和屬性的設定，來描述一個文件各類別不同的資料。所以 Docbook 也就是一本文件寫作的文法書，每個在文件中使用的標籤，都必須在 DTD 中明確而正式的被定義。 我們稱一個文件樣式語法規格的語言為 DSSSL (Document Style Semantics and Specification Language)， DSSSL 定義了如何將一個 SGML 文件(譯者註:這裡是指 Docbook 文件)，轉換成方便人們閱讀的格式，例如 HTML, RTF 和 PDF 等等。 設定 OpenJade 轉換 SGML 和 XML 格式文件的工具有: 必要工具 執行格式轉換工作絕對不能缺少的基本工具: OpenJade(SGML 的解析器和轉譯器) DocBook DTDs(Docbook 的格式定義文件) ISO Entities(外部插入實體的設定文件) Norman Walsh's DSSSL(敘述如何轉換成其他格式的樣式文件) 選項工具 能和 openjade一起合作，轉換成更多種格式的執行程式和樣式表: HTMLDOC(能把 HTML 文件轉換成 PDF 文件的程式) LDP DSL(LDP 組織特別為 Docbook SGML 格式的 HOWTO 文件設計的樣式表，你如果要寫 Linux 的 HOWTO 文件，應該用 LDP DSL 取代 Norman Walsh's DSSSL的預設選項。) 所有的工具組件都可以在網路上自由下載使用，下一章就是為大家介紹如何下載這些工具組件。 很多 Linux 的發行版都已經設定好了 Docbook 文件的轉換格式工作執行環境，利用你發行版為你設定好的 Docbook 轉換工具，會比使用本文安裝方式更為便利。所以譯者在附錄加了 各 Linux 釋出版的 DocBook 安裝套件 一節。你應該先前往該節，檢查你使用的系統是否已有 docbook 工具。除非你確定系統中沒有這些工具，或者不滿意原來的設定，否則不必多此一舉，增加自己無謂的負擔。 本文是假設你的機器中已有下列基本的程式已安裝完備: gzip(解壓縮工具） - available from http://www.gnu.org/directory/ gcc and GNU make(C 語言編譯工具組) - available from http://www.gnu.org/directory/ unzip(解壓縮工具） - available from http://www.info-zip.org/pub/infozip/ Standard Unix utilities - tar, mkdir, mv ...(標準的基本系統工具) 你真正需要編譯的只有 OpenJade 這個套件，本文將解釋編譯的過程，讓你很輕易的就能從原始碼把工具給安裝起來。而我們需要的工具包，大部分可以在The Linux Documentation Project (TLDP)網站找到。 建立一個目錄 /tmp/downloads ，我們需要使用這目錄來放置下載回來的各個工具組。 Mr.Ali 的原文只有下載 OpenJade 一個工具套件而已，那是因為舊的版本 OpenSP 是包括在 OpenJade 裡的，但到了 OpenJade 1.3.2 把 OpenSP 和 OpenJade 分成了兩個工具組，OpenSp 負責底層的函式庫，提供文件解析的呼叫公用函式，而由 OpenJade 依照 DSSSL 樣式表的敘述來轉換 Docbook 到其他格式文件。所以你到 http://openjade.sourceforge.net/ 下載 OpenJade 時，別忘了把 OpenSP 一起下載。 譯者翻譯時，釋出版是 OpenJade-1.3.2.tar.gz，OpenSP 釋出版是 OpenSP-1.5.tar.gz 。 Mr. Ali 在原文中說所有的 DocBook DTDs 檔案都可以在 Linux 的 LDP 網站 http://www.tldp.org/authors/index.html#resources 找到，其實不盡然，那只是幾個 Linux 下最常被用到的 Docbook 版本格式而已。真正所有使用 XML or SGML 定義出來的 Docbook 各版本 DTD 還是要到 OASIS-open.org 去找。 SGML DTD 請到 http://www.oasis-open.org/docbook/sgml 。 XML DTD 請到 http://www.oasis-open.org/docbook/xml 。 由於 Linux LDP 網站上列舉的 DTD 壓縮包都是目前很通行的 Docbook DTD ，所以你該通通下載下來，但如果你拿到了一份 Docbook ，他在第一行的 DTD 宣告不是 LDP 所列舉的版本，你還是必須到 OASIS-Open.org 去下載與 Docbook 文件相符的 DTD 來轉換你的 Docbook 文件。 建議先只安裝 LDP 建議的 DTD ，等到整個安裝完成測試無誤後，再視需要加入其他的 DTD 。 The Linux Documentation Project 將所有要用到的插入實體檔 (Entities) 包裹成一個壓縮包放在 http://www.tldp.org/authors/tools/entities.tar.gz ，讓使用者很方便的使用，真要感謝 TLDP 為大家做的這些。 SGML 格式定義常會使用到一些特殊符號，這些符號在不同的系統，不同的文件格式下有不同的表示方法，為了避免溝通的混亂，所以在 SGML 中使用實體這樣的概念來表示。也就是為每個特殊符號取一個統一名稱，當系統從文件中的實體名稱得知顯示特殊符號的需求時，再以合適的表現法表示之。本來是可以把他也算做 DTD 的一部分，但因為這些實體是由 ISO 組織負責在制定的，OASIS 的 DTD 只是遵照沿用 ISO ENTITY 的規定而已。所以 OASIS 的 DTD 只定義了 Docbook 相關部份，ISO ENTITY 要另外安裝。 你可以從 http://sourceforge.net/project/showfiles.php?group_id=21935 處得到這個 Docbook 的樣式定義檔案組，譯者在撰文時 DSSSL 的是出版是 docbook-dsssl-1.78 。 DSSSL 不是只有一個樣式表，而是一組樣式表，OpenJade 就是由 DSSSL 樣式表得知該如何將 Docbook 轉換成其他格式文件的，所以想要把 Docbook 轉換成那種格式文件，就需要透過參數來告訴 OpneJade 參考那張樣式表來進行轉換工作。 LDP DSL 是 The Linux Documentation Project (TLDP) 網站設計出來，統一輸出各式說明文件的樣式表。它是 Norman Walsh's DSSSL 的延伸利用，增加了一些像背景和表格的強化風格輸出。你可以在 http://www.tldp.org/authors/tools/ldp.dsl 下載他。 ldp.dsl 需要搭配 Normal Walsh's DSSSL 樣式組的使用，如果你想為 TLDP 寫 HOWTO 文件，應該下載 ldp.dsl。 如果你想產生 PDF 檔，可以先把 Docbook 轉成 HTML ，再使用 HTMLDOC 轉成 PDF ，你可以在 http://www.easysw.com/htmldoc/software.php 處下載 HTMLDOC。 這一節我們要介紹如何把 OpenJade 相關工具放到適當的路徑下。Mr. Ali 原文是建議放 /usr/local/dbtools/ 路徑下，但譯者不認為這是一個好辦法。因為按照 Linux FHS 2.0 檔案協定的精神，與機器碼無關的檔案應放 /usr/share/ 或者 /usr/local/share/ 路徑下。而機器碼與函式庫則放 /usr/lib/ 或者 /usr/local/lib/ 較妥當，而且 FHS 2.0 也非常不鼓勵在 /usr/ 或 /usr/local/ 下任意加入其他路徑名稱。因此本文將把 OpenSP 和 OpenJade 工具組放 &system.docbookexec.path; 下，而把 DTD,ISO ENTITY,DSSSL 這些東西放 &system.docbookshare.path; 。這表示 docbook 的資料不僅供 OpenJade 使用，也可以供其他 SGML or XML 解析轉譯器使用。所以請你執行下面建立路徑的指令: # mkdir -p &system.docbookexec.path; # mkdir -p &system.docbookshare.path; 新版的 OpenJade 必須先裝 OpenSP ，否則 OpenJade 會因為缺少必要的函括檔而無法編譯，所以我們現在就把 OpenSP 裝起來吧。 首先把路徑切換到 /tmp/downloads. # cd /tmp/downloads 解開 OpenSP 的壓縮包: # tar -zxvf OpenSp-1.x.tar.gz 切換到 OpenSP 路徑下: # cd OpenSp-1.x 設定 OpenSP 的編譯選項: # ./configure --prefix=&system.docbookexec.path; 編譯程式模組: # make 把執行程式，放到指定的 &system.docbookexec.path; 路徑下。 # make install 安裝 OpenJade 的手續大抵上和安裝 OpenSP 沒有什麼差別，所以我們下面就只列出指令方法，不再多作重複說明: # cd /tmp/downloads # tar -zxvf openjade-1.3.x.tar.gz # cd openjade-1.3.x # ./configure --prefix=&system.docbookexec.path; #make #make install 安裝 OpenJade 比 OpenSP 要多一個手續是要把 OpenJade 附屬的轉換樣式表 dsssl 目錄從 /tmp/downloads/openjade-1.3.x 複製到 &system.docbookexec.path; 路徑下。 # cp -dpR dsssl &system.docbookexec.path;/ Norman Walsh's DSSSL 是一組利用 SGML 樣式表語法設計，把 Docbook 轉換成其他格式依據的設定文件，所以要把它們擺到適當位置，讓 OpneJade 可以找到他們。由於 DSSSL 檔案都是純文字格式，因此不需要去編譯，只要把他們解壓縮到適當路徑即可。 切換路徑到 /tmp/downloads # cd /tmp/downloads 解壓縮檔案 # tar -zxvf docbook-dsssl-1.7x.tar.gz 把相關檔案移到 &system.docbookshare.path;. # mv docbook-dsssl-1.7x &system.docbookshare.path;/ 為了了簡化搜尋路徑並使用統一好記的名稱，我們做一個符號連結檔 dsssl. # ln -s &system.docbookshare.path;/docbook-dsssl-1.7x &system.docbookshare.path;/dsssl 希望你還記得 DTD 是幹嘛用的，總之每個 Docbook 都需要提供一個相對應的 DTD 給 OpenJade ，OpenJade 才知道怎樣正確的理解文件的內容。所以只要 Docbook 的文件格式宣告他是遵照那個 DTD 製作的，在你的系統裡就必須有那份 DTD，必且被 OpenJade 找到。現在，就請依照這原則把所有需要的 DTD 解壓縮到適當的路徑位置。 切換路徑到你設定的 docbook 資料共享目錄 &system.docbookshare.path;. # cd &system.docbookshare.path; 依照你下載的 DTD 類別和版本分別建立相對應的目錄，譬如：由 XML 標記語言定義出來的 DTD 就取名叫 xml-dtd ，SGML 定義的就叫 sgml-dtd，然後最後加上版本名稱，如：xml-dtd-4.1.2 or sgml-dtd-4.2，這樣做的目的是可以一目了然，免得日子一久你就搞混了。 # mkdir xml-dtd-4.1.2 # mkdir sgml-dtd-4.2 切換路徑到 xml-dtd-4.1.2. # cd xml-dtd-4.1.2 解壓縮 DocBook XML v4.1.2 到設定路徑下。 # unzip /tmp/downloads/docbkx412.zip 切換路徑到 sgml-dtd-4.2. # cd ../sgml-dtd-4.2 解壓縮 DocBook SGML v4.2 到設定路徑下。 # unzip /tmp/downloads/docbk42.zip 上面只是舉兩個例子，你從網路上抓下多少的 Docbook DTD 壓縮包，就必須一一為他們設定位置後解壓縮。當所有解壓縮完成後，你必須到每一個 DTD 目錄裡去整理一下檔案。因為所有的 DTD 都是一組檔案，然後用一個 CATALOG FILE 去把他們連在一起的，有點討厭的是這些 CATALOG FILE 在不同的 DTD 版本下會用不同的名稱，有的直接叫 catalog ，有的卻叫 docbook.cat ，這常常導致你在要引用某個 DTD 時，還要去回想這個版 DTD 的 CATALOG FILE 叫什麼名字。因此我們要到每個 dtd 目錄下去查，把所有叫 docbook.cat ，通通加個 catalog 的 link，這樣以後引用，就一律使用 catalog 來呼叫，而不用管他原來叫什麼了。(原來就叫 catalog 的就什麼都不做) # cd ../xml-dtd-4.1.2 # ln -s docbook.cat catalog # cd ../sgml-dtd-4.2 # ln -s docbook.cat catalog 就如前面提到的，其實你可以把 ISO Entities 當作整個 DTD 的一部分，只因為是兩個組織訂定的標準，所以才分作兩個壓縮包，要分別安裝。所以安裝 ISO Entities 的方法就是把這些 Entities 檔案放到和 DTD 同一個目錄就好了。譬如我們現在把 ISO Entities 放到 SGML DTD 4.2 裡: 切換路徑到 &system.docbookshare.path;/sgml-dtd-4.2. # cd &system.docbookshare.path;/sgml-dtd-4.2 解壓縮 /tmp/download/entities.tar.gz 到設定路徑。 # tar -zxvf /tmp/download/entities.tar.gz . 原則上是有多少個 DTD 就該重複多少次這動作，但有下列例外: XML 類型的 DTD 不需要，因為他們已經將 ISO Entities 統整在 DTD 結構下了。 Docbook SGML DTD 4.2 版因為他的 catalog 宣告裡又加了個 XML DTD 4.2 的宣告，所以除了前面的方式加入 ISO Entities 外，還要把 XML DTD 裡的 ent/ 子目錄檔案複製過來。 # cd &system.docbookshare.path;/sgml-dtd-4.2 # cp -dpR &system.docbookshare.path;/xml-dtd-4.2/ent ./ Docbook SGML DTD 4.1 和 3.1 版，LDP 計畫工作者都幫你把 ISO Entities 裝在一個 DTD 裡了，不需再行安裝。 所以我們要有個概念，Docbook DTD 要包括 ISO Entities 才算完整，已經有的就不必加，沒的才加。其實，有了再加一遍也沒啥妨礙，只是有可能變毫無作用的垃圾而已，至於 ISO Entities 包括那些檔案，你把/tmp/downloads/entities.tar.gz 解壓縮到一個暫存路徑即可觀察。 做完前面的步驟，其實整個 OpenJade 必要的檔案就算完整了，下面的安裝，則是功能選項，有需要就可以加裝。首先是 LDP DSL ，它是 Linux LDP Project 的工作者為了統一輸出格式，用 DSSSL 語法設計的樣式輸出表，如果你想要為 LDP 寫作和翻譯 HOWTO 文件，你應該安裝這個樣式表。 切換到 /tmp/downloads 目錄。 # cd /tmp/downloads 複製 ldp.dsl 檔案到 &system.docbookshare.path;/dsssl/print/ 目錄。 # cp ldp.dsl &system.docbookshare.path;/dsssl/print/ 複製 ldp.dsl 檔案到 &system.docbookshare.path;/dsssl/html/ 目錄。 # cp ldp.dsl &system.docbookshare.path;/dsssl/html/ HTMLDOC 可以幫你把 HTML 格式文件轉換成 PDF 格式文件，如果你需要，可以安裝他。 切換到下載檔案目錄。 # cd /tmp/downloads 將 HTMLDOC 原碼檔解壓縮。 # tar -zxvf htmldoc-1.8.xx-source.tar.gz # cd htmldoc-1.8.xx 設定,編譯,安裝: # ./configure --prefix=/usr/local/lib/htmldoc # make # make install Mr. Ali 在原文說 HTMLDOC ver 1.8.20-1 ，編譯時可能會產生字型的錯誤而導致編譯終止，但譯者使用的是 1.8.23 版，非常順利，一路到底。所以，如果你在編譯時產生錯誤，請查閱原文的 Installing HTMLDOC 這一小節。 在這一節裡我們將介紹如何使用 OpenJade ，把遵照 SGML/XML docbook DTD 規則寫做的文件，轉換成 HTML, RTF, 和 PDF 的其他格式文件。 雖然網路上有各式各樣的 Docbook 文件，但因充滿個人化的色彩，常需要增加許多其他的相關支援模組才能執行。為了避免一開始就掉入複雜的設定中，我們只要使用一個最簡單形式的 Docbook 文件，來測試前階段安裝的 OpenJade 是否能運作正常即可。所以下面就是我們用 shell 指令做的最簡單的 Docbook 文件。 由於現今有 XML/SGML 兩種標記語言都製作出 Docbook DTD ，也都在網路上流傳使用。他們標籤用法大抵相同，但文件開頭的格式宣告卻有些小小的差異，所以我們要分別做出 XML 和 SGML 兩種不同的 Docbook 文件，來測試 OpenJade 是否在兩方面都運作正常。首先我們先把下面這整段敘述複製，在終端機下貼上執行，就會得到一個名為 /tmp/downloads/test.sgml 的 SGML Docbook 文件。 /tmp/downloads/test.sgml docbook 初學者 本文件作為測試 Docbook 轉換運作環境是否順暢之用途 ，歡迎複製,改寫,散佈使用。 Docbook 主要文件內容所在。 補充及參考資料。 EOF ]]> 我們利用前面製作出 SGML Docbook 文件，將首行的文件型態宣告稍微改一下，就可以變成 XML Docbook 文件。 # cp /tmp/downloads/test.sgml /tmp/downloads/test.xml # vi /tmp/downloads/test.xml ]]> 加到文件開頭 ]]> 前面一個段落我們安裝了許多 SGML 的檔案轉換工具和相關的 DTD,ISO Entity,DSSSL 檔案，接著我們就必須做一些系統設定，把所有相關檔案做一個結合，打造一個 DocBook 轉換的執行平台。 在 &system.docbookexec.path;/lib 路徑下，有 OpenSP 和 OpenJade 提供的外部連結函式庫，我們應該把它們加到系統的外部連結函式登錄資料庫中。 # cp /etc/ld.so.conf /etc/ld.so.conf.bak # echo "&system.docbookexec.path;/lib" >> /etc/ld.so.conf # ldconfig OpenJade 在執行 DocBook 文件的格式轉換時需要許多外部的含括檔案，不管這些檔案是在你自己的主機上，還是在網路伺服器上，你都必須把它們的路徑位置詳細的寫在 DocBook 的 catalog 檔案中，這樣 OpenJade 才能順利的開啟它們並順利執行，所以我們必須在主機上設定一個路徑來放置我們的 catalog 檔。 # mkdir -p &system.docbookcat.path; 在前面的 DTD 檔案安裝時，我們就提到 DocBook 每個版本的 DTD 群組檔案裡，都有一個 catalog 檔案，規定了該版本的 DocBook 所有執行時所需要含括進來的檔案，他們在系統中的檔案路徑為何。但光有與 DocBook 文件相符的 DTD catalog 還不夠，一個 DocBook 完整的 catalog 資料應該包括下列幾個部份： 與 DocBook 文件型態宣告版本相符的 DTD catalog，以 DocBook 4.2 為例，路徑位置是 &system.docbookshare.path;/sgml-dtd-4.2/catalog 。 OpenJade 本身提供的 DSSSL catalog ，路徑位置是 &system.docbookexec.path;/dsssl 。 Norman Walsh's DSSSL 所提供的 DSSSL catalog ，路徑位置是 &system.docbookshare.path;/dsssl 。 所以一個適合於 DocBook SGML 4.2 版的 catalog 似乎應該是這樣設定： CATALOG "&system.docbookshare.path;/sgml-dtd-4.2/catalog" CATALOG "&system.docbookexec.path;/dsssl/catalog" CATALOG "&system.docbookshare.path;/dsssl/catalog" 你的編輯檔案命令應該是： #vi &system.docbookcat.path;/sgml-4.2.cat 每個系統中不同 DocBook 版本的 catalog 檔都需要分別設定，基本原理都相同，但要做檔名的區別，以及 catalog 內容的第一項，要符合下載的 DTD 群組路徑。例如現在改作 DocBook xml-4.1.2 版的 catalog ，那檔名可改作 &system.docbookcat.path;/xml-4.1.2.cat ，而其內容的第一項，應由CATALOG "&system.docbookshare.path;/sgml-dtd-4.2/catalog"改為CATALOG "&system.docbookshare.path;/xml-dtd-4.1.2/catalog" 由上面段落的為每個不同 DocBook 版本撰寫 catalog 檔可知，catalog 檔本身可以包含其他的 catalog 檔，最後形成一個樹狀階層結構，只要含括檔路徑寫在某個階層的 catalog 檔中，經由上層 catalog 的讀取，OpenJade 一樣最後能找到此含括檔的位置。所以在我們為不同版本的 DocBook 寫好個別的 catalog 後，可以用一個總 catalog 把不同版本的 catalog 都含括進來。那麼你為 OpenJade 指定 catalog 路徑時，就不需因 DocBook 文件宣告不同的版本而做不同的指定，你可以用一個總 catalog 來含括所有不同版本的 catalog 。 你可以用這樣的編輯命令： #vi &system.sgmlcat.path;/catalog 內容是各不同版本 DocBook 的 catalog 檔路徑： CATALOG "&system.docbookcat.path;/sgml-4.2.cat" CATALOG "&system.docbookcat.path;/sgml-4.1.cat" CATALOG "&system.docbookcat.path;/sgml-3.1.cat" CATALOG "&system.docbookcat.path;/xml-4.2.cat" CATALOG "&system.docbookcat.path;/xml-4.1.2.cat" 你必須把 &system.docbookexec.path;/bin 路徑加到 PATH 環境變數中，以方便啟動 OpneJade 。此外 OpneJade 需要參考 SGML_CATALOG_FILES 環境變數，來找到前面我們為 Docbook 編寫的那個總 catalog 檔。為了避免每次執行前都要打一長串環境變數設定指令，我們可以考慮把他們寫在 /etc/profile 或 $HOME/.bash_profile 指令檔的最尾端，以便一登入就可以自動執行。下面這一段就是使用 bash shell 適用的 script 範例。 # 加入 OpenJade 執行檔路徑 PATH=$PATH:&system.docbookexec.path;/bin # 加入 HTMLDOC 執行檔路徑 PATH=$PATH:/usr/local/lib/htmldoc/bin # 加入系統最上層 catalog 檔路徑 SGML_CATALOG_FILES=&system.sgmlcat.path;/catalog export PATH SGML_CATALOG_FILES 一路執行指令到此，可以說基本的 Docbook 轉換工具和相關設定都已經做好了，你可以先登出，再以一個一般 user 帳號登入，來讓先前的 script 設定生效，或者直接在目前的程序中執行: # source /etc/profile OpenJade 是一個幫 SGML/XML 格式文件轉換輸出的工具，理論上只要提供正確的 DTD 和 StyleSheet ，OpenJade 就可以運作，而並非只限於 Docbook 而已。所以使用 OpenJade 工具時，如何指定合適的命令參數，就是成功轉換格式文件的關鍵。還記得我們剛剛製作的 test.sgml 和 test.xml 嗎，下面就讓我們用這兩個檔案來做，各種格式文件轉換的試驗。 # cd /tmp/downloads # openjade -t sgml -d &system.docbookshare.path;/dsssl/html/docbook.dsl test.sgml # mozilla book1.htm || netscape book1.htm || lynx book1.htm 指令及參數解說: openjade : 轉換工具名稱 -t sgml : 文件型態是 sgml -d pathstring : 指定使用哪一個樣式轉換表(同樣的一份文件可以因選擇不同的樣式表而有不同的輸出樣貌) test.sgml : 需要被轉換的 docbook 來源檔 你或許會很奇怪，DTD 宣告怎麼沒加在命令參數裡？其實 OpenJade 在做 Docbook 文件解析時，會依照文首的 DTD 版本宣告，到環境變數 SGML_CATALOG_FILES 中去找適合他版本的 catalog ，然後找到他所有需要的相關 DTD 檔案。這也就是在前一小節設定環境變數時，要設定 SGML_CATALOG_FILES 的緣故。 一般預設 Docbook 轉換到 HTML 格式，會依章節區分作多頁輸出，如果你希望只輸出成一頁以方便傳送，指令是: # openjade -V nochunks -t sgml -d &system.docbookshare.path;/dsssl/html/docbook.dsl test.sgml > book1.htm 這指令較上一個多出的是: -V nochunks : 指定不分頁輸出 > book1.htm : 不分頁輸出會直接輸出到標準輸出(電腦螢幕)上，因此利用重導符號把輸出轉向到檔案。 # openjade -t rtf -d &system.docbookshare.path;/docbook/dsssl/print/docbook.dsl test.sgml 這個指令串和前面不同的是: -t rtf : 指定檔案型態 -d pathstring : 和剛剛輸出成 HTML 使用 html/docbook.dsl 不同的是這裡使用 print/docbook.dsl 樣式表，選擇樣式表不同，輸出結果也不同。 上面的指令會得到一個能在 MS Windows 系統顯示的 RTF 格式文件檔，只是很多 unix 文件轉換成所謂可列印格式文件時(rtf,ps,pdf) ，都會產生中文字型無法順利移植到新文件的困擾，這份 test.rtf 亦復如此。或許你願意參考附錄的 列印格式文件轉換的中文字型顯示問題 一節，了解一下別種比較理想的處理方式。 希望你還記得我們曾從 TLDP 網站下載了一個他們設計的樣式表 ldp.dsl ，放在 &system.docbookshare.path;/dsssl 路徑下，現在要利用它來使我們寫的 Docbook 輸出成有 HOWTO 風格的網頁。 # openjade -t sgml -i html -d &system.docbookshare.path;/dsssl/html/ldp.dsl#html test.sgml # mozilla index.html || netscape index.html || lynx index.html 這個命令串比前一個 HTML 輸出的差別是: -i html : 因為 ldp.dsl 是利用原 Norman Walsh's DSSSL 的樣式表加以加工而成的，所以必須以 -i html 指定要含括 /docbook/dsssl/html 路徑裡的其他 dsl。 -d $SGML_SHARE/dsssl/ldp.dsl#html : 指示 ldp.dsl 做 HTML 輸出。 剛剛 SGML 文件用 test.sgml 轉換，這會當然就要用 test.xml 當測試工具囉。 # openjade -t xml -d &system.docbookshare.path;/dsssl/html/docbook.dsl &system.docbookshare.path;/dsssl/dtds/decls/xml.dcl test.xml # mozilla book1.htm || netscape book1.htm || lynx book1.htm 這個指令串和 SGML 轉換不同的是: -t xml : 檔案型態是 XML xml.dcl : XML 型態文件轉換前要先經過 xml.dcl 宣告 # openjade -t rtf -d &system.docbookshare.path;/dsssl/print/docbook.dsl &system.docbookshare.path;/dtds/decls/xml.dcl test.xml 除了多加個 xml.dcl 的參考外，其他參數和 SGML 轉換到 RTF 並無不同，結果也差不多，中文字型無法移轉，在 RTF 中呈亂碼狀態。 HTMLDOC 這個格式文件轉換工具可以幫助產生 PDF 格式文件，但他只能轉換 HTML 為來源格式的文件，所以我們先用 OpenJade 產生個不分頁的 HTML 文件。 # openjade -V nochunks -t sgml -d &system.docbookshare.path;/dsssl/html/docbook.dsl test.sgml > input.html 執行 HTMLDOC 產生 PDF 文件 # htmldoc -f outfile.pdf input.html 如同 RTF 格式轉換一樣，中文顯示仍然是個問題。 因為這節牽涉到如何設定網頁伺服器，伺服端指令稿伺服器，以及 DocBook 間相互配合的問題，已經不是單純的文件格式轉換了。像這種 DocBook 格式文件延伸利用，我覺得已足夠單獨用一個專題來探討，附加在這篇文章下，不僅不完整，而且也與主題有所偏離。所以譯者將這一節略過不譯，有興趣的讀者請自行閱覽 TLDP 網站中 DocBook XML/SGML Processing Using OpenJade 一文的 Serving DocBook 4.1.2 XML 章節的原文。 這節將提供一些網路上相關的 DocBook 討論研究資料。 原文作者 Mr. Ali 希望如果你有更多 DocBook網路資源訊息，可以寫信到 saqib@seagate.com 告訴他。 comp.text.sgml (easily accessible from Google! Groups) comp.text.xml (easily accessible from Google! Groups) htmldoc.general (server - news.easysw.com) 制定 DocBook 格式的 OASIS 組織自己維護的郵寄通訊論談 http://www.oasis-open.org/committees/docbook/mailinglist/index.shtml TLDP 網站維護的郵寄通訊論壇 http://www.tldp.org/mailinfo.html xml-doc @ Yahoo Groups. Visit http://groups.yahoo.com/group/xml-doc/ for more info. DocBook IRC Channel. #docbook on irc://irc.openprojects.net http://www.oasis-open.org/ 的官方網站 http://www.xml-dev.com/blog/ XML / XHTML WebLog http://docbook.org/wiki/moin.cgi/ The DocBook Wiki http://www.docbook.org/tdg/en/ 官方版的 DocBook 格式定義線上文件 http://www.bureau-cornavin.com/opensource/crash-course/index.html Writing Documentation Using DocBook: A Crash Course，一個非常適合初學者入門的 DocBook 文件撰寫指導。 http://www-106.ibm.com/developerworks/library/l-docbk.html 一個通盤介紹 DocBook 格式文件的短文。 http://www.tldp.org/LDP/LDP-Author-Guide/index.html ，介紹如何用 DocBook 文件來寫 LDP 的 HOWTO 。 http://www.tldp.org/authors/index.html#resources 由 TLDP 網站整理的 DocBook 相關資源下載處。 http://www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/ 一篇介紹 DocBook 格式發展演變過程的文章。 http://www.xml-dev.com:8080/cocoon/mount/docbook/ 教你如何用 Tomcat + Cocoon + DocBook 做出一個 DocBook 伺服站的範例。 你可以在 http://www.xml-dev.com/blog/#19 找到許多好用的 XML 編輯器。 eXchaNGeR - XML 瀏覽及編輯器 http://xngr.org/ XERLIN - XML 模型程式 http://www.xerlin.org/ DocPro by Command Prompt, INC. http://www.commandprompt.com/entry.lxp?lxpe=2 YAWC Pro by XML Workshop LTD. http://www.yawcpro.com/ 能夠把 MS Word 文件轉換成簡單的 DocBook XML 格式的工具。 Logictran RTF Converter. http://www.logictran.com/. Word/RTF to HTML/XML. MajiX - Word 到 XML 的轉換器 http://tetrasys.dhs.org/ XMETAL by SoftQuad http://www.softquad.com/ Tagless Editor by i4i (DocBook DTD not supported) http://www.i4i.com/ XML 編輯器 by XMLmind http://www.xmlmind.com/xmleditor/ upCast and downCast by Inifinity Loop http://www.infinity-loop.de/en/products.html W2XML by DocSoft http://www.docsoft.com/w2xmlv2.htm XMLWrite by Wattle Software http://xmlwriter.net/ oXygen XML 編輯器 - 在 Java 虛擬機器上執行的 http://www.oxygenxml.com/ Xeena by IBM http://www.alphaworks.ibm.com/tech/xeena Excosoft XML 使用者介面 http://www.excosoft.se/eweb/site/exc_pd.html Timelux Xpress http://www.timelux.lu/html/Xpress2001.html Morphon http://www.morphon.com/ Conglomerate http://conglomerate.org/ 就如同本文一開始就建議的，你應該先試著查詢你所使用的 Linux 發行版，是否已有規劃好的 DocBook 工具套件。如果有，你該優先使用你發行版規劃的方式，因為那將更容易，功能也更完整。 docbook-utils : 將 SGML DocBook 轉換成其他格式文件的工具。 xmlto : 將 XML DocBook 轉換成其他格式文件的工具。 Red Hat 都是用 RPM 套件來構成他的系統的，所以你當然該使用 rpm 指令來查詢你套件的安裝狀況: $ rpm -qa | grep -i docbook-utils $ rpm -qa | grep -i xmlto 不管是 docbook-utils 和 xmlto 都有相依的問題，請依照 Red Hat 的 RPM 指示安裝相依套件，使用方法請參考套件自己的說明檔。 與 Red Hat 9.0 使用的基本工具大抵相同，也是使用 docbook-utils 相關組件，查詢方式亦如 Red Hat ，但 Mandrake 似乎不提供 xmlto 這個工具包。 他的下載 ISO 檔好像並未包括 DocBook 的相關工具，只是在 extra 路徑下，有另外的 sgml-tools-1.0.9 的套件包和 source 包。有需要的使用者大概需要另外到 Slackware 相關安裝網站，下載回來安裝在主機上，應該即可建立 DocBook 解譯轉換環境。 Linux 各發行板眾多，每個系統規劃和工具選用各有不同，大抵上使用 docbook-utils 或 sgml-tools 工具組件，都能建立 DocBook 的執行環境，所以不妨從這兩個方向查詢你目前使用發行版的系統狀況。如果還是毫無頭緒，就參照本文的敘述方法，從下載 source 來建立 DocBook 執行環境。或者也可以參考另一篇 HOWTO 提供的，DocBook 執行環境建立的方法 DocBook Install mini-HOWTO 。 一般在處理 DocBook 文件格式轉換時，會將輸出格式分為線上和列印兩大類。線上是指像 HTML,TXT 這種，主要是直接在螢幕上觀看瀏覽的文件格式。而列印是指像 PS,RTF,PDF 這種，用作排版列印的文件格式。 OpenJade 在做線上文件格式轉換時，能正確的轉譯處理中文相關字集。但在列印格式文件轉換上，卻每每遭遇中文字型無法移轉，造成轉換後的文件中，中文字變成亂碼顯示的問題。下面會列出一些其他 linux 先進在處理列印格式文件中文字集顯示的經驗，供大家做個參考。 雖然由 DocBook 直接轉換至 RTF,PDF,PS 等格式列印文件，因為中文字型的獨特問題，顯得問題重重。但 DocBook 的同宗親戚，HTML 網頁文件，現在早已是大家共同支援的標準，不管是中文支援或再轉換成其他格式列印文件，都不會有問題。因此，如果 DocBook 轉成 HTML 是沒問題，那麼就讓我們利用 HTML 這個敲門磚，去打開通往其他列印格式文件轉換之路。 首先，讓我們參考SGML 到 HTML(單頁式)的作法產生一個不分頁的單獨 HTML 文件，為了確保這份 HTML 文件在被各式各樣編輯器載入時，中文編碼會被正確處理，最好在 HTML 的 META 區有正確 charset 的敘述。譬如我們使用台灣地區最通行的 big-5 編碼，那麼你該檢查一下是否有下列敘述，沒有的話，手動加上他。 ...... ...... ]]> 好了，現在你已經有了一個包含了你所有 DocBook 訊息的單一 HTML 檔案，譬如我們把他取名叫 output.html ，現在就可以利用他做其他格式的轉換。 mozilla 的解決方案 譯者測試使用的版本是 mozilla-1.2.1-26 在 mozilla 中載入 output.html 在 mozilla 上方功能表中執行 檔案(F)/列印(P...)/列印到檔案 將 HTML 網頁轉換成 PostScript 列印格式檔案(副檔名 *.ps)。 OpenOffice 的解決方案 譯者測試使用的版本是 OpenOffice-1.0.2-4 啟動 OpenOffice 功能表 檔案(F)/開啟舊檔(O) 在對話窗中，檔案類型選網頁，檔案名稱選 output.html，然後按開啟舊檔按鈕。 載入後如果是亂碼，表示你 output.html 的 META charset 沒有設定正確。正確的是顯是中文或中文呈現空白，如果中文空白，請執行 編輯(E)/全部選取(A) 然後在字型選擇列示盒裡選擇一個中文字型。 在 OpenOffice 中調整一下版面設定，作成你喜歡的樣子。 執行： 檔案(F)/列印(P) 在列印對話盒選取列印成檔案功能， OpenOffice 就會讓你選擇 PostScript or PDF 的輸出，按列印就可以得到我們的列印格式檔案。 執行： 檔案(F)/另存新檔(A) 可以存成其他格式文件，譬如說 MS Word or RTF 。 如果你的系統中沒有像 mozilla 或 OpenOffice 這種龐然大物，也不希望去動用他們，那麼有許多文字編輯器如 KDE 環境的 kwrite,kate，都可以將中文的純文字檔轉換成 PostScript 或 PDF 格式。 可不要以為純文字檔格式單純最好做格式轉換，事實上由 DocBook 轉到 HTML 反而最單純，因為彼此格式大同小異，轉到文字檔要牽涉行寬字數，縮排字元計算，空白行保留等。所以我們下載的一組 DSSSL 樣式表裡，竟沒有一個樣式表方便做 DocBook 對 text 轉換的。所以我們將借用文字型態的網頁瀏覽器 lynx 的 dump 功能，將 output.html dump 成純字檔，再載入到 kwrite 處理。 lynx output.html 在 lynx 中按 P 鍵執行 P)rint 功能 選擇 Save to a local file 在 Enter a filename: 提示字串旁輸入 output.txt 按 Q 鍵執行 Q)uit 功能 kwrite output.txt 在 kwrite 中執行 檔案(F)/列印(P...) 在列印對話盒選擇列印到文件(PDF)或列印到檔案(PostScript) 除上所列，還有一些比較專門的解決辦法。但由於並非一般使用者常用的工具，其執行環境建立及操作技巧比較複雜，所以不在此一一詳述，只列出相關參考文件位址，有興趣的讀者可以自行前往瀏覽。 自由軟體元件細圖中的中文輸出相關章節，中華民國軟體自由協會著。 FreeBSD Chinese HOWTO Chapter 9. 中文的列印 ，作者 Shen Chuan-Hsing 。 酷學園技巧心得一章 由 TeX/LaTeX 製作中文 PDF 檔 ，作者 李果正 Edward G.J. Lee。 酷學園技巧心得一章 使用 pdfTeX/pdfLaTeX 讓 pdf 檔內嵌中文 TTF/TTC ，作者 李果正 Edward G.J. Lee。 本小節列出譯者曾在網路上看到的中文 DocBook 資料，如果你知道有其他完整的，清楚的 DocBook 中文資源，沒在這裡列出來的，請請寄信到 &author.joe.mail; ，來信主旨欄請註明 Docbook question ，我將十分感謝您的協助。 用Open Source工具開發軟體Chapter 2. 製作文件工具 ，作者 黃郁熙。本篇雖然是把 DocBook 當作結構文件的一種加以綜合介紹，但仍舉出了一些 DocBook 的簡單寫作範例以供參考。 本 HOWTO 譯文的原始格式文件 &source.sgml.filename; ，沒錯，還有什麼比用 DocBook 來詮釋 DocBook 更貼切呢？ 我不想使用 docbook-utils 規劃的執行模式，卻想直接操作 OpenJade ，該怎麼做？ 一般 Red Hat or Mandrake 發行版的使用者，系統中都會安裝 docbook-utils 套件可以執行 DocBook 文件的格式轉換工作。如果你不喜歡 docbook-utils 為你設定的執行方式，而想像本 HOWTO 一樣直接操作 OpenJade ，那麼你必須做幾件事： 確定 openjade 路徑有在 $PATH 變數中 你可以用 # which openjade來測試，如果顯示出錯誤訊息，那你就必須執行 # rpm -ql openjade來找出 openjade 被安裝到那個路徑下，然後把這路徑加到 $PATH 環境變數中。 找到系統中的最上層 catalog 檔 通常他們的路徑和本 HOWTO 一樣，是 &system.sgmlcat.path;/catalog 。 設定 $SGML_CATALOG_FILES 環境變數 你可以使用下列的指令讓 $SGML_CATALOG_FILES 立即生效。 # export SGML_CATALOG_FILES=&system.sgmlcat.path;/catalog 如果你無法找到供 openjade 使用的 catalog 階層設定檔及相關結構，就只有請參考設定 OpenJade 的函式庫及環境變數一節，自己手動編寫 catalog 檔了。當你完成了這些程序，你就可以按轉換 SGML Docbook 文件的方式使用 OpenJade 。 openjade:file.xml:22:0:E: could not get "/xml/4.1.2/docbookx.dtd"... 如果你常從網路上抓 XML 語法格式定義的 DocBook 文件，回來本機執行格式轉換時，卻發覺在 OpenJade 環境下，會出現這種找不到含括檔的錯誤，問題是明明你系統中 XML DTD 設定是完整的，版本也對啊，為何會這樣呢？ 其實這多半是 XML 文件宣告時，SYSTEM ID 惹的禍。因為 SGML 格式的文件宣告多半只是： ]]> 就解決了，真正的 DocBook DTD 路徑要到 catalog 裡找。但合法的 XML 文件宣告卻常是： ]]> 依據文件設定優先於系統設定的原則，OpenJade 會去網路上找 http://docbook.org/xml/4.1.2/docbookx.dtd，而不是你系統中的設定。萬一網路上的該 URL 有任何更動或你的使用權限問題，導致你無法取得 docbookx.dtd ，當然就是產生錯誤，連帶的也讓後續的檔案含括通通失敗，終至轉換格式終止。 所以你在 XML 型態的 DocBook 文件格式轉換產生上列的錯誤訊息時，最簡單的方法是就是把那個 DOCTYPE 標簽中的 URL SYSTEM ID 字串拿掉，讓這份文件使用你系統中 catalog 中設定的 docbookx.dtd 。當然這不是全無壞處，因為 DocBook 是個可客製化的標記語言，萬一製作此 DocBook 文件的組織採用了特別客製的 DocBook DTD ，那一定和你系統中的 DTD 不同，你用你系統中的 DTD 取代，還是無法得到正確的轉換。不過一般這樣的例子不多，大部分都是 URL 取得錯誤的烏龍事件而已。