↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。

不受支持的版本: 7.3 / 7.2 / 7.1
历史版本PostgreSQL 7.2 已于 2007 年 2 月结束社区维护,本页译文保留供仍在使用旧版本的读者参考。新系统请看当前版本手册首页。

B.3. 构建文档 #

在构建文档之前,你需要像构建程序本身一样运行 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 本书的集成版本,由于浏览器 界面让你可以通过点击轻松地在全部文档之间跳转,这种方式很实用。

B.3.1. HTML

在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 默认安装。

B.3.2. 手册页 #

我们使用 docbook2man 工具将 DocBook REFENTRY 页面转换为适合手册页的 *roff 输出。 手册页也以 tar 归档的形式分发,与 HTML 版本类似。要创建手册页包,使用命令

cd doc/src
gmake man

这会在 doc/src 目录中生成一个 tar 文件。

man 构建会产生大量令人困惑的输出,而且要产生高质量的结果需要特别 小心。这方面仍有改进的余地。

B.3.3. 硬拷贝生成 #

硬拷贝 Postscript 文档的生成方法是:先把 SGML 源码转换为 RTF,然后导入 ApplixWare。经过少量清理(见下一节)后, 把输出“打印”到一个 postscript 文件。

在生成 Postscript 硬拷贝时需要处理若干方面的问题,包括 RTF 修复、 目录(ToC)生成和分页调整。

Applixware RTF 清理

硬拷贝过程不可或缺的组成部分 jade 没有为正文文本指定默认样式。过去,这个未确诊的问题导致目录 (ToC)生成过程极其漫长。不过,在 ApplixWare 方面的大力帮助下,症状已得到诊断, 并且有了可用的变通方法。

  1. 输入以下命令生成 RTF 输入(例如):

    % cd doc/src/sgml
    % make tutorial.rtf
          
    
  2. 修复 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。

  3. 在Applix Words中打开一个新文档, 然后导入RTF文件。

  4. 使用 ApplixWare 生成新目录(ToC)。

    1. 从第一行第一个字符开始到最后一行最后一个字符为止,选中现有的 ToC 行。

    2. 使用 Tools.BookBuilding.CreateToC构建新的 ToC。选择 前三级标题。这会 用 ApplixWare 原生的 ToC 替换从 RTF 导入的现有行。

    3. 使用 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


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

    • 调整分页。

    • 调整表格列宽。

    • 把插图插入文档。使用 ApplixWare 工具栏上的 居中边距按钮把每幅图在页面上居中。

      注意

      并非所有文档都有插图。你可以在 SGML 源文件中 grep 字符串 graphic,来找出文档中可能带有插图 的部分。有少数插图在文档的不同部分重复出现。

  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. 将文档保存为 Applix Words 原生格式,以便日后更容易地进行最后时刻的编辑。

  10. 把文档“打印”到 PostScript 格式的文件。

  11. 使用 gzip 压缩 Postscript 文件。 把压缩后的文件放入 doc 目录。

B.3.4. 纯文本文件

若干文件以纯文本形式分发,供安装过程中阅读。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 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。