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`脚本。