Postgresql 中文操作指南

J.3. Building the Documentation with Make #

设置好一切后，切换到 doc/src/sgml 目录并运行以下子部分中描述的命令之一以构建文档。（请记住使用 GNU make。）

Once you have everything set up, change to the directory doc/src/sgml and run one of the commands described in the following subsections to build the documentation. (Remember to use GNU make.)

J.3.1. HTML #

要构建文档的 HTML 版本：

To build the HTML version of the documentation:

doc/src/sgml$ make html

这也是默认目标。输出显示在 html 目录中。

This is also the default target. The output appears in the subdirectory html.

要使用 postgresql.org上使用样式表生成 HTML 文档，而不是使用默认简单的样式，请使用：

To produce HTML documentation with the stylesheet used on postgresql.org instead of the default simple style use:

doc/src/sgml$ make STYLE=website html

如果使用了 _STYLE=website_选项，生成的 HTML 文件将包含对托管在 postgresql.org上的样式表的引用，并且需要网络访问权限才能查看这些文件。

If the STYLE=website option is used, the generated HTML files include references to stylesheets hosted on postgresql.org and require network access to view.

J.3.2. Manpages #

我们使用 DocBook XSL 样式表将 DocBook refentry 页面转换为适合手册页的 *roff 输出。要创建手册页，请使用命令：

We use the DocBook XSL stylesheets to convert DocBook refentry pages to *roff output suitable for man pages. To create the man pages, use the command:

doc/src/sgml$ make man

J.3.3. PDF #

要使用 FOP 制作文档的 PDF 版本，您可以根据首选纸张格式使用以下命令之一：

To produce a PDF rendition of the documentation using FOP, you can use one of the following commands, depending on the preferred paper format:

由于 PostgreSQL 文档相当庞大，因此 FOP 将需要大量的内存。正因为如此，在某些系统上，构建将会失败并显示与内存相关的错误消息。这通常可以通过在配置 ~/.foprc 中配置 Java 堆设置来修复，例如：

Because the PostgreSQL documentation is fairly big, FOP will require a significant amount of memory. Because of that, on some systems, the build will fail with a memory-related error message. This can usually be fixed by configuring Java heap settings in the configuration file ~/.foprc, for example:

# FOP binary distribution
FOP_OPTS='-Xmx1500m'
# Debian
JAVA_ARGS='-Xmx1500m'
# Red Hat
ADDITIONAL_FLAGS='-Xmx1500m'

需要最少的内存量，而且在某种程度上，更多的内存似乎能让事情更快一些。在内存非常低（少于 1 GB）的系统上，构建速度会因交换而非常慢，甚至根本无法工作。

There is a minimum amount of memory that is required, and to some extent more memory appears to make things a bit faster. On systems with very little memory (less than 1 GB), the build will either be very slow due to swapping or will not work at all.

FOP 在其默认配置中将为每一页发出 INFO 消息。日志级别可通过 ~/.foprc 更改：

In its default configuration FOP will emit an INFO message for each page. The log level can be changed via ~/.foprc:

LOGCHOICE=-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN

也可以手动使用其他 XSL-FO 处理器，但自动化构建过程仅支持 FOP。

Other XSL-FO processors can also be used manually, but the automated build process only supports FOP.

J.3.4. Plain Text Files #

安装说明也以纯文本形式分发，以备在无法使用更好的阅读工具的情况下使用。 INSTALL 文件对应于 Chapter 17 ，对其进行了某些小改动以解决不同的上下文。若要重新创建此文件，请切换到目录 doc/src/sgml 并输入 make INSTALL 。生成文本输出需要使用 Pandoc 版本 1.13 或更高版本作为附加的构建工具。

The installation instructions are also distributed as plain text, in case they are needed in a situation where better reading tools are not available. The INSTALL file corresponds to Chapter 17, with some minor changes to account for the different context. To recreate the file, change to the directory doc/src/sgml and enter make INSTALL. Building text output requires Pandoc version 1.13 or newer as an additional build tool.

过去，发布说明和回归测试说明也以纯文本形式分发，但这种做法已经停止。

In the past, the release notes and regression testing instructions were also distributed as plain text, but this practice has been discontinued.

J.3.5. Syntax Check #

构建文档可能需要很长时间。但有一种方法可以仅检查文档文件的正确语法，这只需几秒钟：

Building the documentation can take very long. But there is a method to just check the correct syntax of the documentation files, which only takes a few seconds:

doc/src/sgml$ make check