J.2. 工具集

下面的工具用于处理此文档。有些可能是可选的,在文中标注了。

DocBook DTD

这是 DocBook 本身的定义。目前使用版本 4.2 ;你不能使用更新或者早些的版本。 你需要SGML版本的DocBook DTD,但是建立手册页也需要 XML版本的相同版本。

ISO 8879 character entities

这是 DocBook 需要的,但是独立发布,因为它们是由 ISO 维护的。

DocBook DSSSL Stylesheets

这些东西包含把 DocBook 源代码转换成其它格式(比如HTML)的处理指令。

DocBook XSL Stylesheets

这是另外一个转化DocBook到其他格式的样式表。我们当前使用它来生成手册页和可选的HTML帮助。 你也可以使用这个工具生成HTML或PDF输出,但是官方的PostgresSQL发布使用DSSSL stylesheets。

当前所需的最小版本是1.74.0。

OpenJade

这是处理SGML的基本包。它包含一个SGML分析器, 一个DSSSL处理器(也就是一个用DSSSL风格表把 SGML转换成其它格式的程序),还有一系列相关工具。现在Jade 由 OpenJade 组维护,而不再是 James Clark 了。

Libxslt for xsltproc

这是和XSLT stylesheets一起使用的处理工具(类似jade,是处理DSSSL stylesheets的工具)。

JadeTeX

如果你需要,你还可以安装JadeTeXTeX 用做Jade的一种格式化后端。JadeTeX 可以生成 Postscript 或者PDF文件(后者带书签)。

不过,JadeTeX的输出比RTF后端稍差一点的打印输出。 主要是表的格式和各种竖直和水平的空白效果。而且,你还没有机会手工润色输出结果。

我们已经在文档中记录了几种安装处理此文档所需的各种工具的方法。它们在下面描述。 也可能有其它包发布这些工具。请向 doc 邮件列表报告那些包的状态,就会在这里包括那些信息。

J.2.1. Linux RPM 安装

许多供应商在它们的版本里提供了一整套处理 DocBook 的 RPM 包,请检查一下"SGML"选项, 或者下列包之一:sgml-common, docbook, stylesheets, openjade(或jade)。 可能还需要sgml-toolsxsltproclibxslt。 如果你的版本没有提供这些东西,那么你应该可以使用来自一些其它合理兼容的发行商的包。

J.2.2. FreeBSD 安装

FreeBSD 文档计划本身就非常频繁地使用 DocBook , 所以在 FreeBSD 里有一整套可以用的文档工具的"ports"就一点也不奇怪了。 要在 FreeBSD 里制作文档,你必须安装下面的 port :

很多东西来自/usr/ports/print(texjadetex) 你也可能会安装。

这些 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里找到更多有关 FreeBSD 文档工具的信息。

J.2.3. Debian 包

Debian GNU/Linux里面也有一整套可以用的文档工具的包。 安装时,只需要用下面的命令:

apt-get install docbook docbook-dsssl docbook-xsl openjade1.3 opensp xsltproc

J.2.4. 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 已经安装,并且你想在本地安装其它工具的时候,这也是个可选的方法。

    注意: 一些用户已经报告了使用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"

    这是一个相对路径,指向在步骤 2里安装的文件。 请根据你自己的安装布局进行调整。

J.2.5.2. 安装 DocBook DTD 工具箱

  1. 获取DocBook V4.2 发布

  2. 创建目录/usr/local/share/sgml/docbook-4.2并且进入该目录。 实际的位置并非关键,上面这个只是在这里的布局的比较合理的位置。

    $ mkdir /usr/local/share/sgml/docbook-4.2
    $ cd /usr/local/share/sgml/docbook-4.2

  3. 解包归档:

    $ unzip -a ...../docbook-4.2.zip

    这个归档将把它的文件解开到当前目录。

  4. 编辑/usr/local/share/sgml/catalog文件(或者任何安装的时候你告诉 jade 的东西) 并且把类似下面的行放到该文件里面:

    CATALOG "docbook-4.2/docbook.cat"

  5. 下载ISO 8879 字符记录归档, 解开它,然后把文件放到 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)。 归档会自动生成一个子目录。

$ 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 并不使用这个表项。参阅第 J.2.6 节获取有关如何选择样式表的信息。

J.2.5.4. 安装 JadeTeX

要安装和使用JadeTeX,就需要一套能用的TeXLaTeX2e,包括支持的工具图形包。BabelAMS 字体AMS-LaTeXPSNFSS扩展、"the 35 fonts"工具箱、 用于生成 PostScriptdvips程序, 宏包fancyhdrhyperrefminitocurlot2enc,所有这些你都可以在你最近的 CTAN 镜像站点找到。 基本TeX系统的安装远远超出了这份介绍的范围。 你应该可以在任何可以运行TeX的系统上找到二进制包。

在你开始使用JadeTeX处理PostgreSQL文档之前, 你需要增大TeX的内部数据结构的尺寸。 关于这些事情的细节可以在JadeTeX的安装指导里找到。

一旦完成了这些你就可以安装JadeTeX了:

$ gunzip jadetex-xxx.tar.gz
$ tar xf jadetex-xxx.tar
$ cd jadetex
$ make install
$ mktexlsr

最后两步需要以root身份处理。

J.2.6. configure检测

在你制作文档之前,你需要像制作程序本身那样运行configure脚本。 检查运行结尾处的输出,应该看起来像这样:

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

如果onsgmlsnsgmls都没有找到, 那么下面的测试将被跳过。nsgmls是 Jade 包的一部分。 可以通过传递环境变量JADENSGMLS 给 configure 来指定这些程序的位置。如果没有找到"DocBook V4.2", 那么就是你没有把 DocBook DTD 工具箱装到 jade 可以找到的地方,或者你没有正确设置目录文件。 参阅上面的安装提示。配置脚本会在一些比较标准的位置寻找 DocBook 样式表, 但如果你把它们放在其它位置,那么就应该设置环境变量 DOCBOOKSTYLE 为该位置并且重新运行configure脚本。