J.3. 制作文档 · PostgreSQL 中文文档 9.3

# J.3\. 制作文档一旦把所有的东西都设置好了，进入目录`doc/src/sgml` 然后运行下面其中一条命令(记得要用 GNU make)： ## J.3.1\. HTML 制作HTML版本的文档： ``` <samp class="literal">doc/src/sgml$</samp> <kbd class="literal">gmake html</kbd> ``` 这也是缺省目标。在子目录`html`里输出。要创建一个适当的索引，可能处理几个相同的阶段。如果你不关心该索引，只是想校对输出，使用`draft`: ``` <samp class="literal">doc/src/sgml$</samp> <kbd class="literal">gmake draft</kbd> ``` 要建立文档为一个HTML页，使用： ``` <samp class="literal">doc/src/sgml$</samp> <kbd class="literal">gmake postgres.html</kbd> ``` ## J.3.2\. 手册页用DocBook XSL样式表把DocBook的`refentry` 页面转换成适于做手册页的 *roff 输出。这些手册页也是以 tar 归档的形式发布的，与HTML版本类似。要创建手册页包，用命令： ``` cd doc/src/sgml gmake man ``` ## J.3.3\. 用JadeTeX生成的打印输出如果你想用JadeTex生成一个可打印的文档，可以用下面的命令： * 使用DVI生成一个A4格式的PostScript： ``` <samp class="literal">doc/src/sgml$</samp> <kbd class="literal">gmake postgres-A4.ps</kbd> ``` U.S.信件的格式： ``` <samp class="literal">doc/src/sgml$</samp> <kbd class="literal">gmake postgres-US.ps</kbd> ``` * 制作一个PDF： ``` <samp class="literal">doc/src/sgml$</samp> <kbd class="literal">gmake postgres-A4.pdf</kbd> ``` 或： ``` <samp class="literal">doc/src/sgml$</samp> <kbd class="literal">gmake postgres-US.pdf</kbd> ``` 当然，你也可以从 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实现的过程。 > **Note:** 目前看来PostgreSQL的当前版本的文档碰到了 OpenJade 的大小限制的一些毛病。如果制作RTF版本的时候停住了好长时间，而输出文件还是 0 ，那么你很有可能碰到了这个毛病。不过，正常的制作要花 5 到 10 分钟，因此不要太快退出。 **Applixware RTF 清理** OpenJade忽略了声明文本主体的缺省风格。以前，这个未经查明的问题导致目录生成的长时间处理。不过，在Applixware 的工作人员的全力帮助下，这个病症被诊断出来并且找到了绕开的办法。 1. 键入下面命令生成RTF版本： ``` <samp class="literal">doc/src/sgml$</samp> <kbd class="literal">gmake postgres.rtf</kbd> ``` 2. 修复 RTF 文件，以正确声明所有风格，尤其是缺省风格。如果文档包含`refentry`段，那么还必须把和前面的段落与当前段落绑定的格式化暗示替换为当前的段落和后面的段落绑定。在`doc/src/sgml`里有一个`fixrtf`用于完成这样的修补： ``` <samp class="literal">doc/src/sgml$</samp> <kbd class="literal">./fixrtf --refentry postgres.rtf</kbd> ``` 该脚本把`{\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` 调整边距。使用下面的值： <table> <thead> <tr> <th>风格</th> <th>第一边距(英寸)</th> <th>左边距(英寸)</th> </tr> </thead> <tbody><tr> <td><code>TOC-Heading 1</code></td> <td><code>0.4</code></td> <td><code>0.4</code></td> </tr> <tr> <td><code>TOC-Heading 2</code></td> <td><code>0.8</code></td> <td><code>0.8</code></td> </tr> <tr> <td><code>TOC-Heading 3</code></td> <td><code>1.2</code></td> <td><code>1.2</code></td> </tr> </tbody></table> 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` 文件对应[Chapter 15](#calibre_link-1156)，只有一点用于不同环境的修改。要重建这个文件，进入目录`doc/src/sgml`然后敲入<kbd class="literal">gmake INSTALL</kbd>。这样就会创建一个叫`INSTALL.html`的文件，你可以用 Netscape Navigator把它另存为一个文本文件，然后把它拷到现存文件的位置。好像Netscape提供了最高的HTML 到文本的转换质量(比lynx和w3m好)。文件`HISTORY`可以用类似方法创建，用的命令是<kbd class="literal">gmake HISTORY</kbd>。对于`src/test/regress/README`文件，命令是<kbd class="literal">gmake regress_README</kbd>。 ## J.3.7\. 语法检查制作文档可能需要很长时间。但是有一个方法用于只检查文档文件的语法正确性，只要花几秒钟： ``` <samp class="literal">doc/src/sgml$</samp> <kbd class="literal">gmake check</kbd> ```