PostgreSQL 16 文档: J.3. 使用 Make 构建文档

J.3. 使用 Make 构建文档
上一个	向上	附录 J. 文档	主页	下一个

J.3. 使用 Make 构建文档 #

J.3.1. HTML
J.3.2. 手册页
J.3.3. PDF
J.3.4. 纯文本文件
J.3.5. 语法检查

设置好一切后，转到目录 doc/src/sgml，然后运行以下小节中描述的命令之一来构建文档。（请记住使用 GNU make。）

J.3.1. HTML #

构建文档的 HTML 版本

doc/src/sgml$ make html

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

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

doc/src/sgml$ make STYLE=website html

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

J.3.2. 手册页 #

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

doc/src/sgml$ make man

J.3.3. PDF #

若要使用 FOP 生成文档的 PDF 呈现，您可以使用以下命令之一，具体取决于首选的纸张格式

对于 A4 格式
```
doc/src/sgml$ make postgres-A4.pdf
```
对于美国信纸格式
```
doc/src/sgml$ make postgres-US.pdf
```

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

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

需要最少量的内存，并且在某种程度上，更多的内存似乎会让事情变得更快。在内存非常少（少于 1 GB）的系统上，构建要么由于交换而非常慢，要么根本不起作用。

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

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

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

J.3.4. 纯文本文件 #

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

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

J.3.5. 语法检查 #

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

doc/src/sgml$ make check