?
本文檔使用
php中文網(wǎng)手冊 發(fā)布
下面的工具用于處理此文檔。有些可能是可選的,在文中標(biāo)注了。
這是 DocBook 本身的定義。目前使用版本 4.2 ;你不能使用 更新或者早些的版本。 你需要SGML,其為DocBook DTD的變體,但是構(gòu)建手冊頁還需要同版本的XML變體。
這是 DocBook 需要的,但是獨立發(fā)布,因為它們是由 ISO 維護的。
These contain the processing instructions for converting the DocBook sources to other formats, such as HTML.
這是另一個將DocBook轉(zhuǎn)化為其它格式的樣式表。我們當(dāng)前使用這來制作手冊頁和可選的HTM幫助。 你也可以使用這個工具生成HTML或PDF輸出,但是官方PostgreSQL發(fā)布使用DSSSL樣式表做這些事。
這是處理 SGML 的基本包。它包含一個 SGML 分析器,一個 DSSSL (使用 DSSSL 風(fēng)格表把 SGML 轉(zhuǎn)換成其它格式的程序),還有一系列相關(guān)工具?,F(xiàn)在 Jade 由 OpenJade 組維護, 而不再是 James Clark 了。
這是個使用XSLT樣式表的處理工具。(像jade是對DSSSL樣式表的處理工具)
如果你需要,你還可以安裝 JadeTeX 把 TeX 用做 Jade 的一種格式化后端。JadeTeX 可以生成 Postscript 或者 PDF 文件(后者帶書簽)。
不過,JadeTeX 的輸出比 RTF 后端稍差一點的打印輸出。主要是表的 格式和各種豎直和水平的空白效果。而且,你還沒有機會手工潤色 輸出結(jié)果。不過,它運行得很好,尤其是那些不用表格的簡單些的文檔。
我們已經(jīng)在文檔中記錄了幾種安裝處理此文檔所需的各種工具的方法。 它們在下面描述。也可能有其它包發(fā)布這些工具。請向 doc 郵件列表報告那些包的狀態(tài),就會在這里包括那些信息。
許多供應(yīng)商在它們的版本里提供了一整套處理 DocBook 的 RPM 包, 請檢查一下"SGML"選項,或者下列包之一: sgml-common, docbook, stylesheets, openjade (或 jade)??赡苓€需要 sgml-tools 。如果你的版本沒有提供這些東西, 那么你應(yīng)該可以使用來自一些其它合理兼容的發(fā)行商的包。
FreeBSD 文檔計劃本身就非常頻繁地使用 DocBook ,所以在 FreeBSD 里有一整套可以用的文檔工具的"ports" 就一點也不奇怪了。要在 FreeBSD 里制作文檔,你必須安裝下面的 port。
textproc/sp
textproc/openjade
textproc/iso8879
textproc/dsssl-docbook-modular
textproc/docbook-420
很多東西來自 /usr/ports/print (tex, jadetex) 你也可能會感興趣。
這些 port 很可能不會更新位于 /usr/local/share/sgml/catalog.ports 的 主目錄文件或命令是不正確的。務(wù)必在文件的開頭有以下幾行: 確保你有下面這行:
CATALOG "openjade/catalog" CATALOG "iso8879/catalog" CATALOG "docbook/dsssl/modular/catalog" CATALOG "docbook/4.2/catalog"
如果你不想編輯文件,還可以把環(huán)境變量 SGML_CATALOG_FILES 設(shè)置為一個冒號分隔的目錄 文件列表(比如上面那樣的)。
你可以在 FreeBSD Documentation Project's instructions 里找到更多有關(guān) FreeBSD 文檔工具的信息。
Debian GNU/Linux 里面也有一整 套可以用的文檔工具的包。安裝時, 只需要用下面的命令:
apt-get install docbook docbook-dsssl docbook-xsl openjade xsltproc
DocBook 工具的手工安裝過程有些復(fù)雜,因此如果你有預(yù)先制作好的包, 最好還是用它們。在這里只描述一個標(biāo)準(zhǔn)的安裝,而且安裝到標(biāo)準(zhǔn)的 路徑里,并且沒有"fancy"的特性。相關(guān)的更多的細(xì)節(jié), 你應(yīng)該學(xué)習(xí)相關(guān)包的文檔,并且閱讀 SGML介紹性材料。
OpenJade 提供了一個 GNU 風(fēng)格的 ./configure; make; make install 制作過程。 你可以在 OpenJade 源程序包里找到詳細(xì)內(nèi)容。在 shell 里:
./configure --enable-default-catalog=/usr/local/share/sgml/catalog make make install
確保你記住這里設(shè)置"default catalog"的位置, 后面將需要它。也可以不用注明這句話,但是稍后使用 jade 的時候, 你就不得不把環(huán)境變量 SGML_CATALOG_FILES 設(shè)置為指向該文件的位置。如果 OpenJade 已經(jīng)安裝, 并且你想在本地安裝其它工具的時候,這也是個可選的方法。
另外,你應(yīng)該從 dsssl 目錄里把 dsssl.dtd, fot.dtd, style-sheet.dtd, 和 catalog 文件安裝上, 可能是安裝到 /usr/local/share/sgml/dsssl 吧。最簡單的可能就是復(fù)制整個目錄:
cp -R dsssl /usr/local/share/sgml
最后,創(chuàng)建文件 /usr/local/share/sgml/catalog 并且把下面行加入其中:
CATALOG "dsssl/catalog"
這是一個相對路徑引用安裝文件在step 2。 如果你選擇不同的安裝布局,請你務(wù)必調(diào)整它。
下載 DocBook V4.2 distribution。
創(chuàng)建目錄/usr/local/share/sgml/docbook-4.2 并且進入該目錄。實際的位置并非關(guān)鍵,上面這個只是在這里的布局 的比較合理的位置。
$ mkdir /usr/local/share/sgml/docbook-4.2 $ cd /usr/local/share/sgml/docbook-4.2
解壓這個歸檔。
$ unzip -a ...../docbook-4.2.zip
解壓這個歸檔文件到當(dāng)前目錄。
編輯 /usr/local/share/sgml/catalog 文件(或者任何安裝的時候你告訴 jade 的東西)并且把類似下面的 行放到該文件里面:
CATALOG "docbook-4.2/docbook.cat"
下載 ISO 8879 character entities archive, 解壓,然后把文件放到 DocBook 文件的同一個目錄里:
$ cd /usr/local/share/sgml/docbook-4.2 $ unzip ...../ISOEnts.zip
在有 DocBook 和 ISO 文件的目錄里運行下面的命令:
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
這個動作修補了一個小毛病,這個毛病把 DocBook 目錄文件里使用的 名字和 ISO 字符實體文件的名字混淆了。
要安裝樣式表,解開發(fā)布的工具包,然后把它挪到一個合適的地方。 (比如 /usr/local/share/sgml)。歸檔會自動創(chuàng)建子目錄)
$ gunzip docbook-dsssl-1.xx.tar.gz $ tar -C /usr/local/share/sgml -xf docbook-dsssl-1.xx.tar
你也可以在 /usr/local/share/sgml/catalog 里制作常用的目錄條目:
CATALOG "docbook-dsssl-1.xx/catalog"
因為樣式表變化頻繁,因此有時候多實驗幾個版本也挺好, PostgreSQL 并不使用這個表項。 參閱章Section I.2.5獲取有 關(guān)如何選擇樣式表的信息。
要安裝和使用 JadeTeX ,就需要一套能用的 TeX 和 LaTeX2e , 包括支持的 tools 和 graphics 包 Babel, AMS 字體 和 AMS-LaTeX, PSNFSS 擴展 和 工具箱 "35個字體", dvips 用于生成 PostScript, 宏包 fancyhdr, hyperref, minitoc, url 和 ot2enc。 所有這些你都可以在你最近的 CTAN 網(wǎng)站 鏡像站點找到。 基本 TeX 系統(tǒng)的安裝遠遠超出了這份介紹的范圍。 你應(yīng)該可以在任何可以運行 TeX 的系統(tǒng)上找到二進制包。
在你開始使用 JadeTeX 處理 PostgreSQL 文檔之前,你需要增大 TeX 的內(nèi)部數(shù)據(jù)結(jié)構(gòu)的大小。 關(guān)于這些事情的細(xì)節(jié)可以在 JadeTeX 的安裝指導(dǎo)里找到。
一旦完成了這些你就可以安裝 JadeTeX 了:
$ gunzip jadetex-xxx.tar.gz $ tar xf jadetex-xxx.tar $ cd jadetex $ make install $ mktexlsr
最后兩步需要以 root 身份處理。
在你制作文檔之前,你需要像制作程序本身那樣運行 configure 腳本。檢查運行結(jié)尾處的輸出,應(yīng)該看起來像這樣:
checking for onsgmls... onsgmls checking for openjade... openjade checking for DocBook V4.2... yes checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular checking for collateindex.pl... /usr/bin/collateindex.pl checking for xsltproc... xsltproc checking for osx... osx
如果 onsgmls 和 nsgmls 都沒有找到,那么你就看不到最后四行。nsgmls 是 JADE 包的一部分??梢酝ㄟ^傳遞環(huán)境變量 JADE 和 NSGMLS 給 configure 來指定這些程序的位置。如果沒有找到"DocBook V4.2", 那么就是你沒有把 DocBook DTD 工具箱裝到 jade 可以找到的地方, 或者你沒有正確設(shè)置目錄文件。參閱上面的安裝提示。 配置腳本會在一些比較標(biāo)準(zhǔn)的位置尋找 DocBook 樣式表, 但如果你把它們放在其它位置,那么就應(yīng)該設(shè)置環(huán)境變量 DOCBOOKSTYLE 為該位置并且重新運行 configure 腳本。