J.3. 使用 Make 构建文档 #
一切设置妥当后,切换到 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)的系统,构建要么会因交换而非常缓慢,要么根本无法工作。
在默认配置下,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。