J.3. 编译文档

一旦你把所有的东西都设置好以后,切换到doc/src/sgml目录,并且运行下面小节中介绍的命令之一就可以编译文档(记住使用 GNU make)。

J.3.1. HTML

要编译文档的HTML版本:

doc/src/sgml$ make html

这也是默认的目标。这个命令的输出将出现在子目录html中。

要用postgresql.org所使用的样式表 而不是默认的简单样式生成 HTML 文档:

doc/src/sgml$ make STYLE=website html

要创建正确的索引,编译可能要处理几个不同的阶段。如果你不关心索引,并且只希望校对输出,可以使用draft目标:

doc/src/sgml$ make draft

要把文档编译成单个 HTML 页面,可以使用:

doc/src/sgml$ make postgres.html

J.3.2. 手册页

我们使用 DocBook XSL 样式表来把DocBook refentry页转换成适合于手册页的 *roff 输出。和HTML版本相似,手册页也是以一个 tar 档案被发布的。要创建手册页,使用命令:

cd doc/src/sgml
make man

J.3.3. 通过JadeTeX打印输出

如果你希望使用JadeTex产生一个本文档的可打印形式,你可以使用下列命令之一:

在使用 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.logpostgres-A4.log。在一英寸中有 72 个点,因此任何被报告为超过 72 个点而过宽的东西都将可能无法放在一个打印页中(假设边距为一英寸)。要寻找导致溢出的SGML文本,找到提到上述溢出消息的第一页的页号,如[50 ###](第 50 页),并且在PDF文件中查看该页号后的页面(如第 51 页),从中找到溢出文本并且相应地调整SGML

J.3.5. 通过RTF打印输出

你也可以通过把文档转换到RTF并且使用一个办公套件应用小幅的格式更正来创建一个PostgreSQL文档的可打印版本。基于特定办公套件的能力,你可以把文档转换为PDF的 PostScript。下面的过程展示了使用Applixware进行这种处理:

注意: It appears that current versions of the 似乎当前版本的PostgreSQL文档会触发 OpenJade 的某些缺陷或者超过它的一些尺寸限制。如果RTF版本的编译处理挂起很长时间并且输出文件大小仍然为 0,那么你可能遇到了那个问题(但是记住一次正常的编译需要 5 到 10 分钟,因此不要太快中止它)。

Applixware RTF Cleanup

OpenJade忽略为正文文本指定一个默认风格。在过去,这个未被诊断的问题会导致表格内容生成的长时间处理。不过,在Applixware兄弟们的大力帮助下,这个症状已经被诊断出来并且已经有可用的解决方法。

  1. 通过输入以下命令生成RTF版本:

    doc/src/sgml$ make postgres.rtf

  2. 修复 RTF 文件来正确地指定所有风格,特别是默认风格。如果文档包含refentry节,我们也必须替换将前一段联系到当前段落的格式化提示,并且将当前段落联系到下一个段落。一个小工具fixrtfdoc/src/sgml中可用)可以用来完成这些修复:

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

    该脚本增加{\s0 Normal;}作为文档中的零号风格。根据Applixware,RTF 标准将禁止增加一个隐式的零号风格,尽管微软的 Word 可以处理这种情况。为了修复refentry节,该脚本用\keep标记替换\keepn标记。

  3. Applixware Words中打开一个新文档并导入RTF文件。

  4. 使用Applixware生成一个内容的新表(TOC)。

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

    2. 使用Tools->Book Building->Create Table of Contents建立一个新的 ToC。选择前三级 header 用于包含在 ToC中。这将把 RTF 中现有的导入行替换为一个本地的Applixware ToC。

    3. 通过使用Format->Style调整 ToC 格式,选择三个 ToC 风格中的每一个并且为FirstLeft调整缩进。使用下列值:

      风格First 缩进(英寸)Left 缩进(英寸)
      TOC-Heading 10.40.4
      TOC-Heading 20.80.8
      TOC-Heading 31.21.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 本身的项。 ToC itself.

  9. 把文档保存为本地Applixware Words格式来使最后一分钟的编辑更容易。

  10. 把文档"打印"到一个 PostScript 格式的文件。

J.3.6. Plain Text Files

安装指导也被发布为纯文本,它们被用于那些没有好的阅读工具的情况。INSTALL文件对应于第 16 章,但针对不同的环境做了小幅修改。要重建该文件,切换到目录doc/src/sgml并输入make INSTALL

在过去,发行注记和回归测试指导也被作为纯文本发布,但是事实上已经没有这样做了。

J.3.7. 语法检查

便以文档可能会花很长时间。但是有办法只检查文档中的语法,这个过程只需要数秒:

doc/src/sgml$ make check