G.3. 构建文档 #
一切设置妥当后,切换到doc/src/sgml目录,并运行后续各小节中介绍的某个命令来构建文档。(记得使用 GNU make。)
G.3.1. HTML
要构建文档的 HTML 版本:
doc/src/sgml$gmake html
这也是默认目标。
构建 HTML 文档时,该过程还会为索引项生成链接信息。因此,如果你希望文档最后带有一个概念索引,就需要先构建一次 HTML 文档,然后再按你喜欢的任意格式重新构建一次文档。
为了便于在最终发行包中处理,构成 HTML 文档的各文件存储在一个 tar 归档中,并在安装时解包。要创建 HTML 文档包,使用命令
cd doc/src gmake postgres.tar.gz
在发行包中,这些归档位于
doc 目录中,并会随
gmake install 默认安装。
G.3.2. 手册页
我们使用 docbook2man 工具将
DocBook
refentry 页面转换为适合手册页的 *roff 输出。手册页也以 tar 归档的形式分发,与 HTML 版本类似。要创建手册页包,使用命令
cd doc/src gmake man.tar.gz
这会在 doc/src 目录中生成一个 tar 文件。
要生成高质量的手册页,可能需要使用转换工具的修改版本,或者做一些手工后处理。所有手册页在分发之前都应人工检查。
G.3.3. 通过 JadeTex 生成打印输出
如果你想使用 JadeTex 生成文档的可打印版本,可以使用下列命令之一:
要制作 DVI 版本:
doc/src/sgml$gmake postgres.dvi要从 DVI 生成 Postscript:
doc/src/sgml$gmake postgres.ps要制作 PDF:
doc/src/sgml$gmake postgres.pdf(当然,你也可以用 Postscript 生成 PDF 版本,但如果直接生成 PDF,它将带有超链接和其他增强特性。)
G.3.4. 通过 RTF 生成打印输出
你也可以把PostgreSQL文档转换为 RTF并用办公套件做一些小的格式修正,从而生成可打印版本。视具体办公套件的能力而定,随后可以把文档转换为 PostScript 或 PDF。下面的过程以Applixware 为例说明。
注意
当前版本的PostgreSQL文档似乎会触发 OpenJade 的某个错误,或者超出其大小限制。如果RTF版本的构建过程长时间挂起且输出文件大小仍为 0,你可能是遇到了这个问题。(不过请记住,正常构建也需要 5 到 10 分钟,所以不要太早中止。)
Applixware RTF 清理
OpenJade没有为正文文本指定默认样式。过去,这个未确诊的问题导致目录生成过程极其漫长。不过,在 Applixware方面的大力帮助下,症状已得到诊断,并且有了可用的变通方法。
输入下面的命令生成 RTF 版本:
doc/src/sgml$gmake postgres.rtf修复 RTF 文件,使其正确指定所有样式,特别是默认样式。如果文档包含
refentry小节,还必须替换把前一段落与当前段落绑定的格式提示,改为把当前段落与后一段落绑定。doc/src/sgml中提供了一个实用程序fixrtf来完成这些修复:doc/src/sgml$./fixrtf --refentry postgres.rtf该脚本会添加
{\s0 Normal;}作为文档的第 0 号样式。按照Applixware的说法,RTF 标准不允许添加隐式的第 0 号样式,不过 Microsoft Word 恰好能处理这种情况。对于修复refentry小节,脚本会把\keepn标记替换为\keep。在Applixware Words中打开一个新文档,然后导入RTF文件。
使用Applixware生成新目录(ToC)。
从第一行第一个字符开始到最后一行最后一个字符为止,选中现有的 ToC 行。
使用 → → 构建新的 ToC。选择让 ToC 包含前三级标题。这会用Applixware原生的 ToC 替换从 RTF 导入的现有行。
使用 → 调整 ToC 格式,依次选择三种 ToC 样式,并调整
First和Left的缩进。使用以下数值:样式 首行缩进(英寸) 左缩进(英寸) TOC-Heading 10.40.4TOC-Heading 20.80.8TOC-Heading 31.21.2
在整个文档中完成以下工作:
调整分页。
调整表格列宽。
用正确的值替换 ToC 中 Examples 和 Figures 部分右对齐的页码。这只需要几分钟。
如果索引节为空,从文档中删除它。
重新生成并调整目录。
选中 ToC 域。
选择 → → 。
通过选择 → → 解除 ToC 的保护。
删除 ToC 中的第一行,那是 ToC 自身的条目。
将文档保存为Applixware Words原生格式,以便日后更容易地进行最后时刻的编辑。
把文档“打印”到 PostScript 格式的文件。
G.3.5. 纯文本文件
若干文件以纯文本形式分发,供安装过程中阅读。INSTALL 文件对应于第 14 章,并有一些次要的改动以适应文本介质。如果因为某个原因需要重新生成该文件,切换到目录doc/src/sgml并输入
gmake INSTALL。这会创建一个
INSTALL.html 文件,可以用
Netscape Navigator把它保存为文本,并放到现有文件的位置上。Netscape似乎为 HTML
到文本的转换提供了最好的质量(优于
lynx和
w3m)。
文件HISTORY可以类似地用命令
gmake HISTORY创建。对于文件
src/test/regress/README,命令是
gmake regress_README。
G.3.6. 语法检查
构建文档可能非常耗时。但有一种方法可以只检查文档文件的语法是否正确,这只需要几秒钟:
doc/src/sgml$gmake check