编译文档
From PostgreSQL
| PostgreSQL 9.6.0 手册 | |||
|---|---|---|---|
| 上一页 | 上一级 | 附录 J. 文档 | 下一页 |
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产生一个本文档的可打印形式，你可以使用下列命令之一：
-
要通过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 ###]（第 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兄弟们的大力帮助下，这个症状已经被诊断出来并且已经有可用的解决方法。
-
通过输入以下命令生成RTF版本：
doc/src/sgml$ make postgres.rtf -
修复 RTF 文件来正确地指定所有风格，特别是默认风格。如果文档包含
refentry节，我们也必须替换将前一段联系到当前段落的格式化提示，并且将当前段落联系到下一个段落。一个小工具fixrtf（doc/src/sgml中可用）可以用来完成这些修复：doc/src/sgml$ ./fixrtf --refentry postgres.rtf该脚本增加{\s0 Normal;}作为文档中的零号风格。根据Applixware，RTF 标准将禁止增加一个隐式的零号风格，尽管微软的 Word 可以处理这种情况。为了修复
refentry节，该脚本用\keep标记替换\keepn标记。 -
在Applixware Words中打开一个新文档并导入RTF文件。
-
使用Applixware生成一个内容的新表（TOC）。
-
从第一行的第一个字符到最后一行的最后一个字符，选择现有的 ToC 行。
-
使用Tools->Book Building->Create Table of Contents建立一个新的 ToC。选择前三级 header 用于包含在 ToC中。这将把 RTF 中现有的导入行替换为一个本地的Applixware ToC。
-
通过使用Format->Style调整 ToC 格式，选择三个 ToC 风格中的每一个并且为First和Left调整缩进。使用下列值：
-
-
遍历文档：
-
调整分页。
-
调整表格列宽。
-
-
将该 ToC 中的例子和图表部分中的右对齐页号替换为正确的值。这只需要几分钟。
-
如果索引节为空，则从文档中删除索引节。
-
重新生成并调整内容的表格。
-
选择 ToC 域。
-
选择Tools->Book Building->Create Table of Contents。
-
通过选择Tools->Field Editing->Unprotect解除 ToC 绑定。
-
删除 ToC 中的第一行，它是用于 ToC 本身的项。 ToC itself.
-
-
把文档保存为本地Applixware Words格式来使最后一分钟的编辑更容易。
-
把文档"打印"到一个 PostScript 格式的文件。
J.3.6. Plain Text Files
安装指导也被发布为纯文本，它们被用于那些没有好的阅读工具的情况。INSTALL文件对应于第 16 章，但针对不同的环境做了小幅修改。要重建该文件，切换到目录doc/src/sgml并输入make INSTALL。
在过去，发行注记和回归测试指导也被作为纯文本发布，但是事实上已经没有这样做了。