工具集
From PostgreSQL
| PostgreSQL 9.6.0 手册 | |||
|---|---|---|---|
| 上一页 | 上一级 | 附录 J. 文档 | 下一页 |
J.2. 工具集
下面的工具用于处理此文档。如标注所示，有些工具可能是可选的。
- DocBook DTD
-
这是 DocBook 本身的定义。我们目前使用版本 4.2；你不能使用更新或者更早的版本。你需要 DocBook DTD 的SGML变体，但是要构建手册页还需要相同版本的XML变体。
- ISO 8879 字符实体
-
这是 DocBook 需要的，但是被独立发布，因为它们由 ISO 维护。
- DocBook DSSSL 样式表
-
这些包含了将 DocBook 源码转换到其他格式（如HTML）所要用的处理指令。
- DocBook XSL 样式表
-
这是另一个将 DocBook 转化为其它格式的样式表。我们当前用它来产生手册页和可选的 HTMLHelp。 你也可以使用这个工具链生产 HTML 或 PDF 输出，但是官方 PostgreSQL 发布会使用 DSSSL 样式表来做这些工作。
最低要求的版本当前是 1.74.0。
- OpenJade
-
这是SGML处理的基本包。它包含一个SGML解析器，一个DSSSL处理器（即使用DSSSL样式表把SGML转换成其它格式的程序）以及一系列相关工具。目前Jade由 OpenJade 组维护， 而不再由 James Clark 维护。
- xmllint的Libxml2
-
这个库和它所包含的xmllint工具被用来处理 XML。 很多开发者将已经安装了Libxml2，因为在编译 PostgreSQL 代码时就已经用到它了。不过要注意，可能需要从一个独立的包中 安装xmllint。
- xsltproc的Libxslt
-
这是与 XSLT 样式表一起使用的处理工具（像jade是 DSSSL 样式表的处理工具）。
- JadeTeX
-
如果你需要，你还可以安装JadeTeX把TeX作为Jade的一种格式化后端。JadeTeX可以创建 Postscript 或者PDF文件（后者带书签）。
不过，来自JadeTeX的输出比你从RTF后端得到的输出要稍差一点。主要的问题区域是表格和各种竖直和水平空白的效果。而且，你还没有机会手工润色输出结果。
我们已经在文档中记录了几种安装处理此文档所需的各种工具的方法。它们将在下文中描述。也可能有这些工具的其他打包发布。请向文档邮件列表报告那些包的状态，我们就会在这里包括它们的信息。
J.2.1. 在 Fedora、RHEL 和衍生品上安装
要安装所需的包，可使用：
yum install docbook-dtds docbook-style-dsssl docbook-style-xsl libxslt openjade
J.2.2. 在 FreeBSD 上安装
FreeBSD 文档计划本身就是 DocBook 的重度使用者，所以在 FreeBSD 中有一整套文档工具的"移植"可用也就不足为奇。要在 FreeBSD 中编译文档，你必须安装下面的移植。
-
textproc/docbook-sgml
-
textproc/docbook-xml
-
textproc/docbook-xsl
-
textproc/dsssl-docbook-modular
-
textproc/libxslt
-
textproc/openjade
你可能也会对来自/usr/ports/print（tex、jadetex）的很多东西有兴趣。
你可以在FreeBSD 文档项目指导中找到更多有关 FreeBSD 文档工具的信息。
J.2.3. Debian 包
Debian GNU/Linux也有一整套可以用的文档工具包。要安装，只需简单地使用：
apt-get install docbook docbook-dsssl docbook-xsl libxml2-utils 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
-
OpenJade 的安装提供了一个 GNU 风格的./configure; make; make install编译过程。 你可以在 OpenJade 源代码包里找到详细内容。在一个 nutshell 中：
./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 应该会消除这个错误。
-
此外，你应该从在某个地方的dsssl目录中安装dsssl.dtd、fot.dtd、style-sheet.dtd和catalog文件，也许是安装到/usr/local/share/sgml/dsssl中。最简单的可能就是拷贝整个目录：
cp -R dsssl /usr/local/share/sgml
-
最后，创建文件/usr/local/share/sgml/catalog并且加入下面这行：
CATALOG "dsssl/catalog"
这是一个相对路径引用安装文件在step 2。 如果你选择不同的安装布局，请你务必调整它。 （这是一个引用在步骤 2中安装的文件的相对路径。如果你选择你自己的不同的安装布局，记住要调整它）。
J.2.5.2. 安装 DocBook DTD 工具箱
-
创建目录/usr/local/share/sgml/docbook-4.2并切换到其中（准确的路径可能不相干，但是在我们这里遵循的布局中它是合理的）。
$ mkdir /usr/local/share/sgml/docbook-4.2 $ cd /usr/local/share/sgml/docbook-4.2
-
解压：
$ unzip -a ...../docbook-4.2.zip（压缩包会把它的文件解包到当前目录中）。
-
编辑文件/usr/local/share/sgml/catalog（或者你在安装中告诉 jade 的任何东西）并且把类似下面一行的内容加入进去：
CATALOG "docbook-4.2/docbook.cat"
-
下载ISO 8879 字符实体压缩包，解压它并且将文件放在与 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 字符实体文件的真实名称之间的混合）。
J.2.5.3. 安装 DocBook DSSSL 样式表
要安装样式表，unzip 并 untar 发行包并把它移动到一个合适的位置，例如/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，你将需要一个TeX和LaTeX2e的可工作的安装，包括提供支持的tools和graphics包、Babel、AMS 字体和AMS-LaTeX、PSNFSS扩展和"the 35 fonts"的伴侣工具集、生成PostScript的dvips程序、宏包fancyhdr、hyperref、minitoc、url和ot2enc。所有这些可以在你临近的CTAN 站点上找到。TeX基础系统的安装已经超出了本介绍的范围。任何可以运行TeX的系统上应该都有可用的二进制包。
在你可以对PostgreSQL文档源代码使用JadeTeX之前，你将需要增加TeX的内部数据结构的尺寸。有关于此的细节可以在JadeTeX的安装指南中找到。
一旦完成这些，你就可以安装JadeTeX了：
$ gunzip jadetex-xxx.tar.gz $ tar xf jadetex-xxx.tar $ cd jadetex $ make install $ mktexlsr
最后两个操作需要以root身份完成。
J.2.6. 用configure检测
在你能编译文档之前，你需要运行configure脚本，就像你在编译PostgreSQL程序本身时所作的那样。检查运行末尾附近的输出，应该看起来像这样：
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 包的一部分。如果它们没有被自动找到，你可以向 configure 传递环境变量JADE和NSGMLS来指出这些程序。如果没有找到"DocBook V4.2"，那么你就没有把 DocBook DTD 工具集安装在 Jade 能找到它的地方，或者你还没有正确地设置目录文件。见上文的安装提示。会在多个相关的标准位置查找 DocBook 样式表，但是如果如果你把它们放在某个其他地方，那么你需要设置环境变量DOCBOOKSTYLE指向该位置并且之后再运行configure。