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> ```