PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗

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

J.3.1. HTML
J.3.2. Man 手册页
J.3.3. PDF
J.3.4. 语法检查

一切就绪后,切换到 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. Man 手册页 #

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

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. 语法检查 #

构建文档可能耗时很长。但有一种只检查文档文件语法是否正确的方法, 只需几秒钟:

doc/src/sgml$ make check