Postgresql 中文操作指南

J.2. Tool Sets #

以下工具用于处理文档。一些工具可能是可选的，如注释所示。

The following tools are used to process the documentation. Some might be optional, as noted.

  • DocBook DTD #

    • This is the definition of DocBook itself. We currently use version 4.5; you cannot use later or earlier versions. You need the XML variant of the DocBook DTD, not the SGML variant.

  • DocBook XSL Stylesheets #

    • These contain the processing instructions for converting the DocBook sources to other formats, such as HTML.

    • The minimum required version is currently 1.77.0, but it is recommended to use the latest available version for best results.

  • Libxml2 for xmllint #

    • This library and the xmllint tool it contains are used for processing XML. Many developers will already have Libxml2 installed, because it is also used when building the PostgreSQL code. Note, however, that xmllint might need to be installed from a separate subpackage.

  • Libxslt for xsltproc #

    • xsltproc is an XSLT processor, that is, a program to convert XML to other formats using XSLT stylesheets.

  • FOP #

    • This is a program for converting, among other things, XML to PDF. It is needed only if you want to build the documentation in PDF format.

我们已记录了使用各种工具处理文档所需的几种安装方法的体验。这些将在下面予以说明。可能还有这些工具的一些其他打包发行版。请将软件包状态报告给文档邮件列表，我们将在此处包括该信息。

We have documented experience with several installation methods for the various tools that are needed to process the documentation. These will be described below. There might be some other packaged distributions for these tools. Please report package status to the documentation mailing list, and we will include that information here.

J.2.1. Installation on Fedora, RHEL, and Derivatives #

要安装所需的软件包，请使用：

To install the required packages, use:

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

J.2.2. Installation on FreeBSD #

要使用 pkg 安装所需的软件包，请使用：

To install the required packages with pkg, use:

pkg install docbook-xml docbook-xsl libxslt fop

当根据 doc 目录构建文档时，你将需要使用 gmake，因为提供的 Makefile 不适用于 FreeBSD 的 make。

When building the documentation from the doc directory you’ll need to use gmake, because the makefile provided is not suitable for FreeBSD’s make.

J.2.3. Debian Packages #

对于 Debian GNU/Linux，有适用于文档工具的全套软件包。要安装，只需使用：

There is a full set of packages of the documentation tools available for Debian GNU/Linux. To install, simply use:

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

J.2.4. macOS #

如果您使用 MacPorts，则以下步骤将帮助您进行设置：

If you use MacPorts, the following will get you set up:

sudo port install docbook-xml docbook-xsl-nons libxslt fop

如果您使用 Homebrew，则使用以下命令：

If you use Homebrew, use this:

brew install docbook docbook-xsl libxslt fop

Homebrew 提供的程序需要设置以下环境变量。对于基于 Intel 的计算机，请使用以下命令：

The Homebrew-supplied programs require the following environment variable to be set. For Intel based machines, use this:

export XML_CATALOG_FILES=/usr/local/etc/xml/catalog

对于基于 Apple Silicon 的计算机，请使用以下命令：

On Apple Silicon based machines, use this:

export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog

如果没有，xsltproc 将会引发如下错误：

Without it, xsltproc will throw errors like this:

I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
...

虽然可以使用 Apple 提供的 xmllint 和 xsltproc 版本，而不是 MacPorts 或 Homebrew 中的版本，但仍然需要安装 DocBook DTD 和样式表，并设置一个指向它们的目录文件。

While it is possible to use the Apple-provided versions of xmllint and xsltproc instead of those from MacPorts or Homebrew, you’ll still need to install the DocBook DTD and stylesheets, and set up a catalog file that points to them.

J.2.5. Detection by configure #

在构建文档之前，您需要运行 configure 脚本，就像在构建 PostgreSQL 程序本身时一样。检查运行结束时的输出；它应该类似于以下内容：

Before you can build the documentation you need to run the configure script, as you would when building the PostgreSQL programs themselves. Check the output near the end of the run; it should look something like this:

checking for xmllint... xmllint
checking for xsltproc... xsltproc
checking for fop... fop
checking for dbtoepub... dbtoepub

如果找不到 xmllint 或 xsltproc，您将无法构建任何文档。fop 仅用于构建 PDF 格式的文档。dbtoepub 仅用于构建 EPUB 格式的文档。

If xmllint or xsltproc is not found, you will not be able to build any of the documentation. fop is only needed to build the documentation in PDF format. dbtoepub is only needed to build the documentation in EPUB format.

如果需要，您可以告诉 configure 在哪里找到这些程序，例如：

If necessary, you can tell configure where to find these programs, for example

./configure ... XMLLINT=/opt/local/bin/xmllint ...

如果您更愿意使用 Meson 构建 PostgreSQL，请如 Section 17.4 中所述运行 meson setup，然后参阅 Section J.4。

If you prefer to build PostgreSQL using Meson, instead run meson setup as described in Section 17.4, and then see Section J.4.