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

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

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

DG2.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 格式文档是用另一种方法生成的。参见下面的 第 DG2.3.3 节。

其他书可以用类似的命令构建,只需把 admin 换成 developer、programmer、 tutorial 或 user 之一。使用 postgres 会构建全部 5 本书的集成版本,由于浏览器 界面让你可以通过点击轻松地在全部文档之间跳转,这种方式很实用。

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

DG2.3.2. 手册页 #

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

cd doc/src
gmake man

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

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

DG2.3.3. 硬拷贝生成 #

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

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

Applixware RTF 清理

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

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

    % cd doc/src/sgml
    % make tutorial.rtf
          
    
  2. 修复 RTF 文件,使其正确指定所有 样式,特别是默认样式。该字段可以用 vi 或者下面这个小小的 sed 过程添加:

    #!/bin/sh
    # fixrtf.sh
    # Utility to repair slight damage in RTF files generated by jade
    # Thomas Lockhart <lockhart@alumni.caltech.edu>
    #
    for i in $* ; do
      mv $i $i.orig
      cat $i.orig | sed 's#\\stylesheet#\\stylesheet{\\s0 Normal;}#' > $i
    done
    
    exit
          
    

    该脚本会在 {\s0 Normal;} 的位置添加它作为文档的第 0 号样式。 按照 ApplixWare 的说法,RTF 标准不允许添加 隐式的第 0 号样式,不过 M$Word 恰好能处理这种情况。

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

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

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

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

    3. 使用 Format.Style 调整 ToC 格式,依次选择三种 ToC 样式,并调整First 和Left的缩进。使用以下数值:

      表 DG2.1. 目录的缩进格式

      样式 首行缩进(英寸) 左缩进(英寸)
      TOC-Heading 1 0.6 0.6
      TOC-Heading 2 1.0 1.0
      TOC-Heading 3 1.4 1.4


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

    • 调整分页。

    • 调整表格列宽。

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

      注意

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

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

  7. 如果存在书目,从每个条目中删除短形式 引用标题。Norm Walsh 的 DocBook 样式表似乎会把这些打印出来,尽管这只是紧随其后的信息的 一个子集。

  8. 将文档保存为 Applix Words 原生格式,以便日后更容易地进行最后时刻的编辑。

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

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

DG2.3.4. 纯文本文件

若干文件以纯文本形式分发,供安装过程中阅读。INSTALL 文件对应于 管理员指南中的对应章节,并有一些次要的改动以适应文本介质。如果因为某个原因需要重新生成该 文件,切换到目录doc/src/sgml并输入 gmake INSTALL。这会创建一个 INSTALL.html 文件,可以用 Netscape Navigator把它保存为文本, 并放到现有文件的位置上。 Netscape似乎为 HTML 到文本的转换提供了最好的质量(优于 lynx和 w3m)。

文件HISTORY可以类似地用命令 gmake HISTORY创建。应当从得到的文本文件中 手工删除目录。

由于它不常变化,文件 src/test/regress/README 的生成没有完全 自动化。在构建管理员指南的 HTML 版本后,用 Netscape 把生成的文件 regress.html 和 regress-platform.html 转换为文本。然后把 文本文件粘贴到一起,并按喜好编辑(例如删除导航栏、删除对其他 章节的引用)。

提交更正

译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。