选择 打开 改范围 完整检索页
受支持版本: 当前版本 (18) / 17 / 16 / 15 / 14
开发版本: 19 / devel
不受支持的版本: 13 / 12 / 11 / 10
当前 PostgreSQL 版本不在支持生命周期内。
您可以参阅当前版本的对应页面,或其他在上面列出的活跃大版本。

J.2. 工具集 #

以下工具用于处理文档。其中一些可能是可选的,具体见说明。

DocBook DTD

这是 DocBook 自身的定义。我们当前使用 4.2 版;不能使用更高或更低的版本。你需要同一版本 DocBook DTD 的SGMLXML变体。它们通常位于不同的软件包中。

ISO 8879 字符实体

DocBook SGML 需要这些实体,但由于它们由 ISO 维护,因此单独分发。

DocBook XSL Stylesheets

它们包含将 DocBook 源文件转换成其他格式(例如 HTML)的处理指令。

当前要求的最低版本是 1.77.0,但建议使用最新可用版本以获得最佳效果。

OpenSP

这是处理SGML的基础软件包。注意,我们不再需要DSSSL处理器 OpenJade,只需要 OpenSP 软件包将 SGML 转换为 XML。

Libxml2,用于xmllint

这个库及其所含的xmllint工具用于处理 XML。许多开发者可能已经安装了 Libxml2,因为构建 PostgreSQL 代码时也会用到它。不过请注意, xmllint可能需要通过单独的子包安装。

Libxslt,用于xsltproc

xsltproc是一个 XSLT 处理器,也就是使用 XSLT 样式表把 XML 转换成其他格式的程序。

FOP

这是一个可将 XML 转换成 PDF 等格式的程序。

我们已经记录了多种安装处理文档所需工具的方法,下面将加以介绍。 这些工具也可能还有其他打包发行形式。请将软件包状态报告到文档邮件列表, 我们会把这些信息补充到这里。

可以不在本地安装 DocBook XML 和 DocBook XSLT 样式表,因为所需文件会从互联网下载并在本地缓存。如果操作系统软件包只提供旧版本(尤其是旧版样式表),或者根本没有这些软件包,这实际上可能是更好的办法。更多信息见xmllintxsltproc--nonet选项。

J.2.1. 在 Fedora、RHEL 及其衍生版上安装

要安装所需软件包,请使用:

yum install docbook-dtds docbook-style-xsl fop libxslt opensp

J.2.2. 在 FreeBSD 上安装

FreeBSD Documentation Project 本身就大量使用 DocBook,因此 FreeBSD 提供了完整的文档工具ports也就不足为奇了。要在 FreeBSD 上构建文档,需要安装以下 ports。

  • textproc/docbook-sgml

  • textproc/docbook-xml

  • textproc/docbook-xsl

  • textproc/dsssl-docbook-modular

  • textproc/libxslt

  • textproc/fop

  • textproc/opensp

要安装所需软件包,可以使用pkg,命令如下:

pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp

doc目录构建文档时,你需要使用gmake, 因为所提供的 makefile 不适用于 FreeBSD 的make

更多关于 FreeBSD 文档工具的信息,请参阅FreeBSD Documentation Project 的说明

J.2.3. Debian 软件包

完整的文档工具软件包也适用于Debian GNU/Linux。只需使用以下命令即可安装:

apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc

J.2.4. macOS

如果使用 MacPorts,以下命令即可完成配置:

sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp

J.2.5. 从源码手动安装

手动安装 DocBook 工具的过程有些复杂,因此如果有预构建的软件包,就使用它们。这里只描述一种标准配置,使用合理且标准的安装路径,不使用任何花哨功能。有关细节,应查阅各软件包的文档,并阅读SGML入门资料。

J.2.5.1. 安装 OpenSP

OpenSP 的安装采用 GNU 风格的./configure; make; make install构建过程。详细信息可在 OpenSP 源码发行包中找到。简要来说:

./configure --enable-default-catalog=/usr/local/etc/sgml/catalog
make
make install

务必记住默认目录文件的存放位置,后面会用到它。也可以不指定,但这样以后每次使用 OpenSP 中的程序时,都必须设置环境变量SGML_CATALOG_FILES,使其指向该文件。(如果 OpenSP 已经安装,而你希望在本地安装工具链的其余部分,也可以采用这种方法。)

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 文件的同一目录:

    $ 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 字符实体文件的实际名称之间的混淆。)

J.2.6. 通过configure检测 #

在构建文档之前,需要运行configure脚本,就像构建PostgreSQL程序本身时一样。检查运行即将结束时的输出,它应该类似于:

checking for onsgmls... onsgmls
checking for DocBook V4.2... yes
checking for dbtoepub... dbtoepub
checking for xmllint... xmllint
checking for xsltproc... xsltproc
checking for osx... osx
checking for fop... fop

如果onsgmlsnsgmls都没有找到,后续一些测试会被跳过。nsgmls是 OpenSP 软件包的一部分。如果没有自动找到这些程序,可以向 configure 传递环境变量NSGMLS以指明它们的位置。如果没有找到DocBook V4.2,则说明 DocBook DTD 工具包没有安装到 OpenSP 能找到的位置,或者目录文件没有正确设置。请参阅上面的安装提示。