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

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

已结束支持的版本: 7.3 / 7.2 / 7.1
历史版本。 PostgreSQL 7.1 已结束支持。 请参阅 当前版本手册.

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 10.60.6
      TOC-Heading 21.01.0
      TOC-Heading 31.41.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 转换为文本。然后把文本文件粘贴到一起,并按喜好编辑(例如删除导航栏、删除对其他章节的引用)。

报告文档问题

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