pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。
在构建文档之前,你需要像构建程序本身一样运行 configure 脚本。检查运行即将结束时的输出, 它应该类似于这样:
checking for onsgmls... onsgmls
checking for openjade... openjade
checking for DocBook V3.1... yes
checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
checking for sgmlspl... sgmlspl
如果onsgmls和nsgmls都没有找到, 你就看不到余下的 4 行。nsgmls是 Jade 软件包的 一部分。如果没有找到“DocBook V3.1”,则说明 DocBook DTD 工具包没有安装到 jade 能找到的位置,或者目录文件没有正确设置。请参阅 上面的安装提示。DocBook 样式表会在若干个较为标准的位置中查找, 但如果你把它们放在其他地方,则应该设置环境变量 DOCBOOKSTYLE指向该位置,然后重新运行 configure。
一切设置妥当后,切换到doc/src/sgml目录,并运行下列命令之一:(记得使用 GNU make。)
要构建管理员指南的 HTML 版本:
doc/src/sgml$gmake admin.html
同一书的 RTF 版本:
doc/src/sgml$gmake admin.rtf
通过 JadeTeX 获得 DVI 版本:
doc/src/sgml$gmake admin.dvi
以及从 DVI 生成 Postscript:
doc/src/sgml$gmake admin.ps
官方的 Postscript 格式文档是用另一种方法生成的。参见下面的 第 B.3.3 节。
其他书可以用类似的命令构建,只需把 admin 换成 developer、programmer、 tutorial 或 user 之一。使用 postgres 会构建全部 5 本书的集成版本,由于浏览器 界面让你可以通过点击轻松地在全部文档之间跳转,这种方式很实用。
在doc/src/sgml中构建 HTML 文档时,某些生成的文件在书与书之间可能(或几乎肯定)会重名。 因此在常规发行包中,文件并不放在那个目录里。相反,每本书的 文件存储在一个 tar 归档中,并在安装时解包。要创建一组 HTML 文档包,使用命令
cd doc/src gmake postgres.tar.gz gmake tutorial.tar.gz gmake user.tar.gz gmake admin.tar.gz gmake programmer.tar.gz gmake install
在发行包中,这些归档位于 doc 目录中,并会随 gmake install 默认安装。
我们使用 docbook2man 工具将 DocBook REFENTRY 页面转换为适合手册页的 *roff 输出。 手册页也以 tar 归档的形式分发,与 HTML 版本类似。要创建手册页包,使用命令
cd doc/src gmake man
这会在 doc/src 目录中生成一个 tar 文件。
man 构建会产生大量令人困惑的输出,而且要产生高质量的结果需要特别 小心。这方面仍有改进的余地。
硬拷贝 Postscript 文档的生成方法是:先把 SGML 源码转换为 RTF,然后导入 ApplixWare。经过少量清理(见下一节)后, 把输出“打印”到一个 postscript 文件。
在生成 Postscript 硬拷贝时需要处理若干方面的问题,包括 RTF 修复、 目录(ToC)生成和分页调整。
Applixware RTF 清理
硬拷贝过程不可或缺的组成部分 jade 没有为正文文本指定默认样式。过去,这个未确诊的问题导致目录 (ToC)生成过程极其漫长。不过,在 ApplixWare 方面的大力帮助下,症状已得到诊断, 并且有了可用的变通方法。
输入以下命令生成 RTF 输入(例如):
% cd doc/src/sgml
% make tutorial.rtf
修复 RTF 文件,使其正确指定所有 样式,特别是默认样式。如果文档包含 REFENTRY小节,还必须替换把前面段落与当前段落绑定 的格式提示,改为把当前段落与后一段落绑定。 doc/src/sgml 中提供了一个实用程序fixrtf来完成这些修复:
% cd doc/src/sgml
% fixrtf tutorial.rtf
或者
% cd doc/src/sgml
% fixrtf --refentry reference.rtf
该脚本会添加{\s0 Normal;}作为文档的第 0 号样式。 按照Applixware的说法,RTF 标准不允许添加 隐式的第 0 号样式,不过 M$Word 恰好能处理这种情况。对于修复 REFENTRY小节,脚本会把\keepn 标记替换为\keep。
在Applix Words中打开一个新文档, 然后导入RTF文件。
使用 ApplixWare 生成新目录(ToC)。
从第一行第一个字符开始到最后一行最后一个字符为止,选中现有的 ToC 行。
使用 Tools.BookBuilding.CreateToC构建新的 ToC。选择 前三级标题。这会 用 ApplixWare 原生的 ToC 替换从 RTF 导入的现有行。
使用 Format.Style 调整 ToC 格式,依次选择三种 ToC 样式,并调整First 和Left的缩进。使用以下数值:
表 B.1. 目录的缩进格式
| 样式 | 首行缩进(英寸) | 左缩进(英寸) |
|---|---|---|
TOC-Heading 1 |
0.4 |
0.4 |
TOC-Heading 2 |
0.8 |
0.8 |
TOC-Heading 3 |
1.2 |
1.2 |
在整个文档中完成以下工作:
调整分页。
调整表格列宽。
把插图插入文档。使用 ApplixWare 工具栏上的 居中边距按钮把每幅图在页面上居中。
并非所有文档都有插图。你可以在 SGML 源文件中 grep 字符串 graphic,来找出文档中可能带有插图 的部分。有少数插图在文档的不同部分重复出现。
用正确的值替换 ToC 中 Examples 和 Figures 部分右对齐的页码。这只需要 几分钟(每份文档)。
如果索引节为空,从文档中删除它。
重新生成并调整目录。
选中 ToC 域。
选择 Tools->Book Building->Create Table of Contents。
通过选择 Tools->Field Editing->Unprotect 解除 ToC 的保护。
删除 ToC 中的第一行,那是 ToC 自身的条目。
将文档保存为 Applix Words 原生格式,以便日后更容易地进行最后时刻的编辑。
把文档“打印”到 PostScript 格式的文件。
使用 gzip 压缩 Postscript 文件。 把压缩后的文件放入 doc 目录。
若干文件以纯文本形式分发,供安装过程中阅读。INSTALL 文件对应于 管理员指南中的对应章节,并有一些次要的改动以适应文本介质。如果因为某个原因需要重新生成该 文件,切换到目录doc/src/sgml并输入 gmake INSTALL。这会创建一个 INSTALL.html 文件,可以用 Netscape Navigator把它保存为文本, 并放到现有文件的位置上。 Netscape似乎为 HTML 到文本的转换提供了最好的质量(优于 lynx和 w3m)。
文件HISTORY可以类似地用命令 gmake HISTORY创建。对于文件 src/test/regress/README,命令是 gmake regress_README。
译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。