J.2.工具集

以下工具用于处理文档。如前所述,有些可能是可选的。

  • DocBook DTD

    • 这是 DocBook 本身的定义。我们目前使用的是 4.2 版;您不能使用更高或更低的版本。您需要相同版本的 DocBook DTD 的 SGML 和 XML 变体。这些通常将放在单独的程序包中。
  • ISO 8879 字符实体

    • 这些是 DocBook SGML 所必需的,但由于它们是由 ISO 维护的,因此需要单独分发。
  • DocBook XSL 样式表

    • 这些包含将 DocBook 源转换为其他格式(例如 HTML)的处理说明。

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

  • OpenSP

    • 这是 SGML 处理的基本包。请注意,我们不再需要 OpenSSL,DSSSL 处理器,仅需要将 SGML 转换为 XML 的 OpenSP 软件包。
  • Libxml2 xmllint

    • 该库及其包含的xmllint工具用于处理 XML。许多开发人员已经安装了 Libxml2,因为在构建 PostgreSQL 代码时也会使用它。但是请注意,xmllint可能需要从单独的子软件包中安装。
  • Libxslt xsltproc

    • xsltproc是 XSLT 处理器,即使用 XSLT 样式表将 XML 转换为其他格式的程序。
  • FOP

    • 这是一个用于将 XML 转换为 PDF 的程序。

我们已经记录了处理各种文档所需的各种工具的几种安装方法的经验。这些将在下面描述。这些工具可能还有其他打包的发行版。请将包裹状态报告给文档邮件列表,我们将在此处提供该信息。

您可以不必在本地安装 DocBook XML 和 DocBook XSLT 样式表,因为所需的文件将从 Internet 下载并本地缓存。如果您的 os 软件包仅提供了旧版本(尤其是样式表),或者根本没有软件包,则实际上这可能是首选解决方案。有关更多信息,请参见xmllintxsltproc--nonet选项。

J.2.1. 在 Fedora,RHEL 和衍生产品上安装

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

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

J.2.2. 在 FreeBSD 上安装

FreeBSD 文档项目本身就是 DocBook 的繁重用户,因此,在 FreeBSD 上有完整的“端口”文档工具集就不足为奇了。需要安装以下端口以在 FreeBSD 上构建文档。

  • 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 文档工具的更多信息。

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 套件

  • 获取DocBook V4.2 发行版

  • 创建目录/usr/local/share/sgml/docbook-4.2并切换到该目录。 (确切的位置无关紧要,但是在我们按照此布局布局中,这一位置是合理的.)

$ mkdir /usr/local/share/sgml/docbook-4.2
$ cd /usr/local/share/sgml/docbook-4.2
  • 解压缩 Files:
$ unzip -a ...../docbook-4.2.zip

(Files 会将其文件解压缩到当前目录中.)

  • 编辑文件/usr/local/share/sgml/catalog(或在安装过程中告诉过的玉石),并在其中添加如下代码:
CATALOG "docbook-4.2/docbook.cat"
$ 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.6. 通过配置检测

在生成文档之前,需要像在构建 PostgreSQL 程序本身一样运行configure脚本。在运行即将结束时检查输出,它应该看起来像这样:

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 软件包的一部分。您可以传递环境变量NSGMLS进行配置,以指向未自动找到的程序。如果未找到“ DocBook V4.2”,则说明您没有将 DocBook DTD 套件安装在 OpenSP 可以找到它的地方,或者您没有正确设置目录文件。请参阅上面的安装提示。