↑↓ 选择↵ 打开⌫ 切换范围完整搜索

PG.CENTER 连接 PostgreSQL 文档、百科与生态知识。由 Pigsty 维护。

支持中的版本: 当前版本 (18) / 17 / 16 / 15 / 14
开发中的版本: 19 / 20devel
已结束支持的版本: 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4
历史版本。 PostgreSQL 8.2 已结束支持。 请参阅 当前版本手册.

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. Print Output via RTF

你也可以把PostgreSQL文档转换为 RTF并用办公套件做一些小的格式修正,从而生成可打印版本。视具体办公套件的能力而定,随后可以把文档转换为 PostScript 或 PDF。下面的过程以Applixware 为例说明。

注意

当前版本的PostgreSQL文档似乎会触发 OpenJade 的某个错误,或者超出其大小限制。如果RTF版本的构建过程长时间挂起且输出文件大小仍为 0,你可能是遇到了这个问题。(不过请记住,正常构建也需要 5 到 10 分钟,所以不要太早中止。)

Applixware RTF Cleanup

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;}作为文档的第 0 号样式。按照Applixware的说法,RTF 标准不允许添加隐式的第 0 号样式,不过 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 10.40.4
      TOC-Heading 20.80.8
      TOC-Heading 31.21.2

  5. 在整个文档中完成以下工作:

    • 调整分页。

    • 调整表格列宽。

  6. 用正确的值替换 ToC 中 Examples 和 Figures 部分右对齐的页码。这只需要几分钟。

  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把它保存为文本,并放到现有文件的位置。在 HTML 到文本的转换方面,Netscape 似乎能提供最好的质量(优于 lynx 和 w3m)。

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

G.3.6. 语法检查

构建文档可能非常耗时。但有一种方法可以只检查文档文件的语法是否正确,这只需要几秒钟:

doc/src/sgml$ gmake check

报告文档问题

阅读 上游文档. 反馈更正前请先核对 当前版本手册.