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 工具把 DocBookREFENTRY 页面转换成适于做 man page 的 *roff 输出。 这些手册页也是以 tar 归档的形式发布的,与 HTML 版本类似。要创建手册页包,用命令

cd doc/src
gmake man.tar.gz

这些命令最后会在 doc/src 目录生成一个 tar 文件。

要生成高质量的手册页,我们可能必须使用一个黑过的版本的转换工具,或者做 一些手工调整。所有手册页都应该在发布之前手工检查。

G.3.3. 用 JadeTex 生成的打印输出

如果你想用 JadeTex 生成一个可打印 的文档,你可以用下面的命令:

G.3.4. 通过 RTF 生成打印输出

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

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

ApplixwareRTF 清理

OpenJade,忽略了声明文本主体的缺省风格。以前,这个未经查明的问题 导致目录(ToC)生成的长时间处理。不过,在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 标准会禁止增加一种隐含的零级风格, 尽管 M$Word 碰巧可以处理这种情况。为了修复 REFENTRY 段落,该脚本把 \keepn 标记替换为 \keep

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

  4. Applixware生成一个新的 ToC。

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

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

    3. 使用 Format->Style, 调整 ToC 格式,选择每三种 ToC 风格, 然后为 FirstLeft调整边距。使用下面的值:

      风格第一边距(英寸)左边距(英寸)
      TOC-Heading 10.40.4
      TOC-Heading 20.80.8
      TOC-Heading 31.21.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 文件对应 Chapter 14, 只有一点用于不同环境的修改。要创建这个文件,进入 目录 doc/src/sgml 然后敲入 gmake INSTALL。 这样就会创建一个叫 INSTALL.html 的文件, 你可以用 Netscape Navigator 把它 另存为一个文本文件,然后把它拷到现存文件的位置。 好象 Netscape 提供了最高的 HTML 到文本的转换质量。(比 lynxw3m好)。

文件 HISTORY 可以用类似方法创建,用的命令是 gmake HISTORY。对于 src/test/regress/README 文件,命令是 gmake regress_README

G.3.6. 语法检查

制作文档可能需要很长时间。但是有一个方法用于只检查文档文件的语法正确性, 只要花几秒钟:

doc/src/sgml$ gmake check