制作文档

PostgreSQL 9.4.4 中文手册
上一页 | 上一级 | 附录 J. 文档 | 下一页

# J.3. 制作文档

一旦把所有的东西都设置好了，进入目录`doc/src/sgml` 然后运行下面其中一条命令(记得要用 GNU make)：

## J.3.1. HTML

制作HTML版本的文档：

    doc/src/sgml$ make html

这也是缺省目标。在子目录`html`里输出。

要创建一个适当的索引，可能处理几个相同的阶段。如果你不关心该索引， 只是想校对输出，使用`draft`:

    doc/src/sgml$ make draft

要建立文档为一个HTML页，使用：

    doc/src/sgml$ make postgres.html

## J.3.2. 手册页

用DocBook XSL样式表把DocBook的`refentry` 页面转换成适于做手册页的 *roff 输出。这些手册页也是以 tar 归档的形式发布的， 与HTML版本类似。要创建手册页包，用命令：

    cd doc/src/sgml
    gmake man

## J.3.3. 用JadeTeX生成的打印输出

如果你想用JadeTex生成一个可打印的文档，可以用下面的命令：

- 使用DVI生成一个A4格式的PostScript：

      doc/src/sgml$ make postgres-A4.ps

  U.S.信件的格式：

      doc/src/sgml$ make postgres-US.ps

- 制作一个PDF：

      doc/src/sgml$ make postgres-A4.pdf

  或：

      doc/src/sgml$ make postgres-US.pdf

  当然，你也可以从 Postscript 里制作PDF版本，但是如果你直接生成 PDF，那么它会有超链接和其它增强的特性。

当使用 JadeTeX 生成PostgreSQL文档时，你可能需要增大一些TeX的内部参数。 通过设置文件`texmf.cnf`来实现。下面的设置立即生效：

    hash_extra.jadetex  = 200000
    hash_extra.pdfjadetex  = 200000
    pool_size.jadetex = 2000000
    pool_size.pdfjadetex = 2000000
    string_vacancies.jadetex = 150000
    string_vacancies.pdfjadetex = 150000
    max_strings.jadetex = 300000
    max_strings.pdfjadetex = 300000
    save_size.jadetex = 15000
    save_size.pdfjadetex = 15000

## J.3.4. 溢出文本

偶尔文本超出了打印的边缘，并且在极限情况下，超出了打印的纸张的宽度，例如，非包裹的文本， 宽表格。过宽的文本在TeX日志输出文件中产生"Overfull hbox"信息，例如， `postgres-US.log` 或 `postgres-A4.log`。一英寸有72个点， 所以任何超过72个点的报告都太宽，可能不适合打印页（假设一英寸）。 要找到导致溢出的SGML文本，首先找到上面提到的溢出消息的首页码，例如， `[50 ###]` (page 50)，然后在PDF文件中查找其后的页码(例如页 51)， 查看溢出文本并相应的调整SGML。

## J.3.5. 通过RTF生成打印输出

你也可以通过把它转换成RTF并且用一个办公套件进行格式微调的办法来创建一个 PostgreSQL文档的可打印的版本。根据你使用的不同的办公套件， 然后你就可以分别把文档转换成 PDF格式的Postscript。 下面的步骤演示了使用Applixware实现的过程。

> 注意: 目前看来PostgreSQL的当前版本的文档碰到了 OpenJade 的大小限制的一些毛病。 如果制作RTF版本的时候停住了好长时间，而输出文件还是 0 ， 那么你很有可能碰到了这个毛病。不过，正常的制作要花 5 到 10 分钟，因此不要太快退出。

Applixware RTF 清理

OpenJade忽略了声明文本主体的缺省风格。以前， 这个未经查明的问题导致目录生成的长时间处理。不过，在Applixware 的工作人员的全力帮助下，这个病症被诊断出来并且找到了绕开的办法。

1. 键入下面命令生成RTF版本：

       doc/src/sgml$ make postgres.rtf

2. 修复 RTF 文件，以正确声明所有风格，尤其是缺省风格。如果文档包含`refentry`段， 那么还必须把和前面的段落与当前段落绑定的格式化暗示替换为当前的段落和后面的段落绑定。 在`doc/src/sgml`里有一个`fixrtf`用于完成这样的修补：

       doc/src/sgml$ ./fixrtf --refentry postgres.rtf

   该脚本把`{\s0 Normal;}`增加为文档的零级风格。根据 Applixware，RTF 标准会禁止增加一种隐含的零级风格， 尽管 Microsoft Word 碰巧可以处理这种情况。为了修复`refentry`段落， 该脚本把`\keepn`标记替换为`\keep`。

3. 在Applixware Words里打开新的文档，然后输入该RTF文件。

4. 用Applixware生成一个新的目录(ToC)。

   1. 选择现有的 ToC 行，从第一行第一个字符到最后一行最后一个字符。

   2. 用Tools->Book Building->制作一个新的 ToC。选择头三层头用于包含在 ToC 里。这将用本地的 Applixware ToC 代替从 RTF 里输入进来的行。

   3. 使用Format->Style 调整 ToC 格式，选择每三种 ToC 风格，然后为`First`和`Left` 调整边距。使用下面的值：

      风格 | 第一边距(英寸) | 左边距(英寸)
      --- | --- | ---
      `TOC-Heading 1` | `0.4` | `0.4`
      `TOC-Heading 2` | `0.8` | `0.8`
      `TOC-Heading 3` | `1.2` | `1.2`

5. 对文档进行加工：

   - 调整分页符

   - 调整表列宽

6. 用正确的值替换 ToC 里例子和图片部分右对齐的页数。这些对每个文档只需要花几分钟。

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 格式"打印"到一个文件。

## J.3.6. 纯文本文件

该安装说明书也以纯文本的模式发布了，以防它们在没有更好的阅读工具的时候使用。`INSTALL` 文件对应第 15 章，只有一点用于不同环境的修改。要重建这个文件， 进入目录`doc/src/sgml`然后敲入`make INSTALL`。

在过去，版本说明和回归测试说明也以纯文本的格式发布了， 但是已经停止这个做法了。

## J.3.7. 语法检查

制作文档可能需要很长时间。但是有一个方法用于只检查文档文件的语法正确性，只要花几秒钟：

    doc/src/sgml$ make check

上一页 | 起始页 | 下一页
工具集 | 上一级 | 文档写作