PostgreSQL 8.2.3 中文文档
后退快退附录G. Documentation快进前进

G.2. 工具集

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

DocBook DTD

这是 DocBook 本身的定义。目前使用版本 4.2 ;你不能使用更新或者早些的版本。请注意,别用 XML 版本的 DocBook 。

ISO 8879 character entities

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

OpenJade

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

DocBook DSSSL Stylesheets

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

DocBook2X tools

这个可选的包是用于创建手册页的。它自己有一系列包要求先安装。请查看网站。

JadeTeX

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

不过,JadeTeX 的输出比 RTF 后端稍差一点的打印输出。主要是表的格式和各种竖直和水平的空白效果。而且,你还没有机会手工润色输出结果。不过,它运行得很好,尤其是那些不用表格的简单些的文档。

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

G.2.1. Linux RPM 安装

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

G.2.2. FreeBSD 安装

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

很明显,现在还没有 DocBook V4.2 SGML DTD 的 port 。你需要手工安装它。

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

这些 port 很可能不会更新位于 /usr/local/share/sgml/catalog 的主目录文件。确保你有下面这行:

CATALOG "/usr/local/share/sgml/docbook/4.2/docbook.cat"

如果你不想编辑文件,还可以把环境变量 SGML_CATALOG_FILES 设置为一个冒号分隔的目录文件列表(比如上面那样的)。

你可以在 FreeBSD Documentation Project's instructions 里找到更多有关 FreeBSD 文档工具的信息。

G.2.3. Debian 包

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

apt-get install jade
apt-get install docbook
apt-get install docbook-stylesheets

G.2.4. 从源程序手工安装

DocBook 工具的手工安装过程有些复杂,因此如果你有预先制作好的包,最好还是用它们。在这里只描述一个标准的安装,而且安装到标准的路径里,并且没有"神奇"的特性。相关的更多的细节,你应该学习相关包的文档,并且阅读 SGML 介绍性材料。

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

  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 里安装的文件。请根据你自己的安装布局进行调整。

G.2.4.2. 安装 DocBook DTD 工具箱

  1. Obtain the DocBook V4.2 distribution

  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 文件的同一个目录里。

    $ cd /usr/local/share/sgml/docbook-4.2
    $ unzip ...../ISOEnts.zip
  6. 在装有 DocBook 和 ISO 文件的目录里运行下面的命令:

    perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat

    这个动作修补了一个小毛病,这个毛病把 DocBook 目录文件里使用的名字和 ISO 字符实体文件的名字混淆了。

G.2.4.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 并不使用这个表项。参阅章G.2.5获取有关如何选择样式表的信息。

G.2.4.4. 安装 JadeTeX

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

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

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

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

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

G.2.5. configure 检测

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

checking for onsgmls... onsgmls
checking for openjade... openjade
checking for DocBook V4.2... yes
checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
checking for sgmlspl... sgmlspl

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


后退首页前进
DocBook上一级制作文档