J.2. 工具集 · PostgreSQL 中文文檔 9.3

# J.2\. 工具集下面的工具用于處理此文檔。有些可能是可選的，在文中標注了。 [DocBook DTD](http://www.oasis-open.org/docbook/) 這是 DocBook 本身的定義。目前使用版本 4.2 ；你不能使用更新或者早些的版本。你需要SGML版本的DocBook DTD，但是建立手冊頁也需要 XML版本的相同版本。 [ISO 8879 character entities](http://www.oasis-open.org/cover/ISOEnts.zip) 這是 DocBook 需要的，但是獨立發布，因為它們是由 ISO 維護的。 [DocBook DSSSL Stylesheets](http://wiki.docbook.org/DocBookDssslStylesheetDocs) 這些東西包含把 DocBook 源代碼轉換成其它格式(比如HTML)的處理指令。 [DocBook XSL Stylesheets](http://wiki.docbook.org/DocBookXslStylesheets) 這是另外一個轉化DocBook到其他格式的樣式表。我們當前使用它來生成手冊頁和可選的HTML幫助。你也可以使用這個工具生成HTML或PDF輸出，但是官方的PostgresSQL發布使用DSSSL stylesheets。當前所需的最小版本是1.74.0。 [OpenJade](http://openjade.sourceforge.net) 這是處理SGML的基本包。它包含一個SGML分析器，一個DSSSL處理器(也就是一個用DSSSL風格表把 SGML轉換成其它格式的程序)，還有一系列相關工具。現在Jade 由 OpenJade 組維護，而不再是 James Clark 了。 [Libxslt](http://xmlsoft.org/XSLT/) for `xsltproc` 這是和XSLT stylesheets一起使用的處理工具（類似`jade`，是處理DSSSL stylesheets的工具）。 [JadeTeX](http://jadetex.sourceforge.net) 如果你需要，你還可以安裝JadeTeX把TeX 用做Jade的一種格式化后端。JadeTeX 可以生成 Postscript 或者PDF文件(后者帶書簽)。不過，JadeTeX的輸出比RTF后端稍差一點的打印輸出。主要是表的格式和各種豎直和水平的空白效果。而且，你還沒有機會手工潤色輸出結果。我們已經在文檔中記錄了幾種安裝處理此文檔所需的各種工具的方法。它們在下面描述。也可能有其它包發布這些工具。請向 doc 郵件列表報告那些包的狀態，就會在這里包括那些信息。 ## J.2.1\. Linux RPM 安裝許多供應商在它們的版本里提供了一整套處理 DocBook 的 RPM 包，請檢查一下"SGML"選項，或者下列包之一：`sgml-common`, `docbook`, `stylesheets`, `openjade`(或`jade`)。可能還需要`sgml-tools`和`xsltproc`或`libxslt`。如果你的版本沒有提供這些東西，那么你應該可以使用來自一些其它合理兼容的發行商的包。 ## J.2.2\. FreeBSD 安裝 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` 的主目錄文件或順序不合適。確保文件的開頭有下面這幾行： ``` CATALOG "openjade/catalog" CATALOG "iso8879/catalog" CATALOG "docbook/dsssl/modular/catalog" CATALOG "docbook/4.2/catalog" ``` 如果你不想編輯文件，還可以把環境變量`SGML_CATALOG_FILES` 設置為一個冒號分隔的目錄文件列表(比如上面那樣的)。你可以在[FreeBSD Documentation Project's instructions](http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html)里找到更多有關 FreeBSD 文檔工具的信息。 ## J.2.3\. Debian 包 Debian GNU/Linux里面也有一整套可以用的文檔工具的包。安裝時，只需要用下面的命令： ``` apt-get install docbook docbook-dsssl docbook-xsl openjade1.3 opensp xsltproc ``` ## J.2.4\. Mac OS X 如果你使用MacPorts，你將使用以下命令來設置： ``` sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl libxslt openjade opensp ``` ## J.2.5\. 從源程序手工安裝 DocBook 工具的手工安裝過程有些復雜，因此如果你有預先制作好的包，最好還是用它們。在這里只描述一個標準的安裝，而且安裝到標準的路徑里，并且沒有"神奇"的特性。相關的更多的細節，你應該學習相關包的文檔，并且閱讀SGML介紹性材料。 ### J.2.5.1\. 安裝 OpenJade 1. OpenJade 提供了一個 GNU 風格的`./configure; make; make install`制作過程。你可以在 OpenJade 源程序包里找到詳細內容。在 shell 里： ``` ./configure --enable-default-catalog=/usr/local/share/sgml/catalog make make install ``` 確保你記住了"default catalog"的位置，后面還會需要它。也可以不用注明這句話，但是稍后使用jade的時候，你就不得不把環境變量`SGML_CATALOG_FILES` 設置為指向該文件的位置。如果 OpenJade 已經安裝，并且你想在本地安裝其它工具的時候，這也是個可選的方法。 > **Note:** 一些用戶已經報告了使用OpenJade 1.4devel建立PDF時的分段錯誤，信息如下： > > ``` > openjade:./stylesheet.dsl:664:2:E: flow object not accepted by port; only display flow objects accepted > make: *** [postgres-A4.tex-pdf] Segmentation fault > ``` > > 使用低級的OpenJade 1.3應該鞥解決這個錯誤。 2. 另外，你應該從`dsssl`目錄里把`dsssl.dtd`, `fot.dtd`, `style-sheet.dtd`, `catalog` 文件安裝上，可能是安裝到`/usr/local/share/sgml/dsssl`吧。最簡單的可能就是復制整個目錄： ``` cp -R dsssl /usr/local/share/sgml ``` 3. 最后，創建文件`/usr/local/share/sgml/catalog`并且把下面行加入其中： ``` CATALOG "dsssl/catalog" ``` 這是一個相對路徑，指向在[step 2](#calibre_link-2170)里安裝的文件。請根據你自己的安裝布局進行調整。 ### J.2.5.2\. 安裝 DocBook DTD 工具箱 1. 獲取[DocBook V4.2 發布](http://www.docbook.org/sgml/4.2/docbook-4.2.zip) 2. 創建目錄`/usr/local/share/sgml/docbook-4.2`并且進入該目錄。實際的位置并非關鍵，上面這個只是在這里的布局的比較合理的位置。 ``` <samp class="literal">$</samp> <kbd class="literal">mkdir /usr/local/share/sgml/docbook-4.2</kbd> <samp class="literal">$</samp> <kbd class="literal">cd /usr/local/share/sgml/docbook-4.2</kbd> ``` 3. 解包歸檔： ``` <samp class="literal">$</samp> <kbd class="literal">unzip -a ...../docbook-4.2.zip</kbd> ``` 這個歸檔將把它的文件解開到當前目錄。 4. 編輯`/usr/local/share/sgml/catalog`文件(或者任何安裝的時候你告訴 jade 的東西) 并且把類似下面的行放到該文件里面： ``` CATALOG "docbook-4.2/docbook.cat" ``` 5. 下載[ISO 8879 字符記錄歸檔](http://www.oasis-open.org/cover/ISOEnts.zip)，解開它，然后把文件放到 DocBook 文件的同一個目錄里。 6. 在裝有 DocBook 和 ISO 文件的目錄里運行下面的命令： ``` perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat ``` 這個動作修補了一個小毛病，這個毛病把 DocBook 目錄文件里使用的名字和 ISO 字符實體文件的名字混淆了。 ### J.2.5.3\. 安裝 DocBook 的DSSSL樣式表要安裝樣式表，解開發布的工具包，然后把它挪到一個合適的地方(比如`/usr/local/share/sgml`)。歸檔會自動生成一個子目錄。 ``` <samp class="literal">$</samp> <kbd class="literal">gunzip docbook-dsssl-1.`_xx_`.tar.gz</kbd> <samp class="literal">$</samp> <kbd class="literal">tar -C /usr/local/share/sgml -xf docbook-dsssl-1.`_xx_`.tar</kbd> ``` 你也可以在`/usr/local/share/sgml/catalog`里制作常用的目錄條目： ``` CATALOG "docbook-dsssl-1._xx_/catalog" ``` 因為樣式表變化頻繁，因此有時候多實驗幾個版本也挺好，PostgreSQL 并不使用這個表項。參閱[Section J.2.6](#calibre_link-2171)獲取有關如何選擇樣式表的信息。 ### J.2.5.4\. 安裝 JadeTeX 要安裝和使用JadeTeX，就需要一套能用的TeX 和LaTeX2e，包括支持的工具和圖形包。Babel、 AMS 字體、AMS-LaTeX 、 PSNFSS擴展、"the 35 fonts"工具箱、用于生成 PostScript 的dvips程序，宏包fancyhdr。 hyperref， minitoc， url ，ot2enc，所有這些你都可以在你最近的 [CTAN 鏡像站點](http://www.ctan.org)找到。基本TeX系統的安裝遠遠超出了這份介紹的范圍。你應該可以在任何可以運行TeX的系統上找到二進制包。在你開始使用JadeTeX處理PostgreSQL文檔之前，你需要增大TeX的內部數據結構的尺寸。關于這些事情的細節可以在JadeTeX的安裝指導里找到。一旦完成了這些你就可以安裝JadeTeX了： ``` <samp class="literal">$</samp> <kbd class="literal">gunzip jadetex-`_xxx_`.tar.gz</kbd> <samp class="literal">$</samp> <kbd class="literal">tar xf jadetex-`_xxx_`.tar</kbd> <samp class="literal">$</samp> <kbd class="literal">cd jadetex</kbd> <samp class="literal">$</samp> <kbd class="literal">make install</kbd> <samp class="literal">$</samp> <kbd class="literal">mktexlsr</kbd> ``` 最后兩步需要以root身份處理。 ## J.2.6\. `configure`檢測在你制作文檔之前，你需要像制作程序本身那樣運行`configure`腳本。檢查運行結尾處的輸出，應該看起來像這樣： ``` <samp class="literal">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</samp> ``` 如果`onsgmls`和`nsgmls`都沒有找到，那么下面的測試將被跳過。`nsgmls`是 Jade 包的一部分。可以通過傳遞環境變量`JADE`和`NSGMLS` 給 configure 來指定這些程序的位置。如果沒有找到"DocBook V4.2"，那么就是你沒有把 DocBook DTD 工具箱裝到 jade 可以找到的地方，或者你沒有正確設置目錄文件。參閱上面的安裝提示。配置腳本會在一些比較標準的位置尋找 DocBook 樣式表，但如果你把它們放在其它位置，那么就應該設置環境變量 `DOCBOOKSTYLE` 為該位置并且重新運行`configure`腳本。