Question

一旦把所有的东西都设置好了，进入目录 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 生成打印输出

你也可以通过把它转换成 RTF 并且用一个办公套件进行格式微调的办法把 PostgreSQL 文档转换成 RTF 格式的办法来创建一个可打印的版本。根据你使用的不同的办公套件，然后你就可以分别把文档转换成 Postscript 或者 PDF 。下面的步骤演示了使用 Applixware 实现的过程。

【注意】目前看来 PostgreSQL 的当前版本的文档碰到了 OpenJade 的大小限制的一些毛病。如果制作 RTF 版本的时候停住了好长时间，而输出文件还是 0 ，那么你很有可能碰到了这个毛病。不过，正常的制作要花 5 到 10 分钟，因此不要太快退出。

Applixware RTF 清理

OpenJade 忽略了声明文本主体的缺省风格。以前，这个未经查明的问题导致目录生成的长时间处理。不过，在 Applixware 的工作人员的全力帮助下，这个病症被诊断出来并且找到了绕开的办法。

1. 键入下面命令生成 RTF 版本：

   doc/src/sgml$ gmake postgres.rtf

2. 修复 RTF 文件，以正确声明所有风格，尤其是缺省风格。如果文档包含 refentry 段，那么还必须把和前面的段落与当前段落绑定的格式化暗示替换为当前的段落和后面的段落绑定。在 doc/src/sgml 里有一个 fixrtf 用于完成这样的修补：

   doc/src/sgml$ ./fixrtf --refentry postgres.rtf

   该脚本把 {\s0 Normal;} 增加为文档的零级风格。根据 Applixware ，RTF 标准会禁止增加一种隐含的零级风格，尽管 Microsoft Word 碰巧可以处理这种情况。为了修复 refentry 段落，该脚本把 \keepn 标记替换为 \keep

3. 在 Applixware Words 里打开新的文档，然后输入该 RTF 文件。

4. 用 Applixware 生成一个新的目录(ToC)。

   1. 选择现有的 ToC 行，从第一行第一个字符到最后一行最后一个字符。

   2. 用 Tools->Book Building->Create Table of Contents 制作一个新的 ToC 。选择头三层头用于包含在 ToC 里。这将用本地的 Applixware ToC 代替从 RTF 里输入进来的行。

   3. 使用 Format->Style 调整 ToC 格式，选择每三种 ToC 风格，然后为 First 和 Left 调整边距。使用下面的值：

      风格	第一边距(英寸)	左边距(英寸)
      TOC-Heading 1	0.4	0.4
      TOC-Heading 2	0.8	0.8
      TOC-Heading 3	1.2	1.2

5. 对文档进行加工：

   • 调整分页符

   • 调整表列宽

6. 用正确的值替换 ToC 里例子和图片部分右对齐的页数。这些对每个文档只需要花几分钟。

7. 如果索引是空的，那么从文档中删除它。

8. 重新生成并调整目录。

   1. 选择 ToC 字段

   2. 选择 Tools->Book Building->Create Table of Contents

   3. 通过选择 Tools->Field Editing->Unprotect 解除 ToC

   4. 删除 ToC 中的第一行，它是指向 ToC 本身的一条记录。

9. 把该文档保存为 Applixware Words 本地文档格式以便于最后的编辑。

10. 把该文档以 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