J.3. 构建文档 #
一切设置妥当后,切换到 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 二进制发行版 FOP_OPTS='-Xmx1500m' # Debian JAVA_ARGS='-Xmx1500m' # Red Hat ADDITIONAL_FLAGS='-Xmx1500m'
所需内存存在一个最低门槛,而且在一定程度上,内存越多似乎会让构建稍快一些。对于内存很少(小于 1 GB)的系统,构建要么会因交换而非常缓慢,要么根本无法工作。
也可以手工使用其他 XSL-FO 处理器,但自动化构建过程只支持 FOP。
J.3.4. 纯文本文件
安装说明也以纯文本形式分发,以便在没有更好的阅读工具时使用。INSTALL 文件对应第 16 章,并针对不同语境作了少量调整。要重新生成该文件,请切换到 doc/src/sgml 目录,然后输入 make INSTALL。构建文本输出还需要 Pandoc 1.13 或更新版本作为额外的构建工具。
过去,发行说明和回归测试说明也曾以纯文本形式分发,但现已停止这种做法。
J.3.5. 语法检查
构建文档可能非常耗时。但有一种方法可以只检查文档文件的语法是否正确,这只需要几秒钟:
doc/src/sgml$make check