G.3. ドキュメントのビルド

すべての設定が終了したら doc/src/sgml ディレクトリに移動して以下のコマンドの 1 つを実行して下さい。 (GNU make を使うのを忘れずに。)

G.3.1. HTML

HTML 形式のドキュメントを作成するには次のようにします。

doc/src/sgml$ gmake html

これはデフォルトでの対象物です。

HTML ドキュメントが作成されると、処理の過程で索引項目にリンクする 情報が生成されます。ですから最後のところに大まかな索引をつけたいと 思った場合はもう一度 HTML ドキュメントをビルドする必要があり、 希望するところのどんな形式のドキュメントでも再ビルドしてください。

最終の配布物の取り扱いを簡単にするため HTML ドキュメントを構成する ファイルは tar でアーカイブされインストールの時に解凍されます。 HTML 形式のドキュメント一式を作成するには 以下のコマンドを使用します。

cd doc/src
gmake postgres.tar.gz

これらのアーカイブは配布物の doc ディレクトリ にあって何もしなくても gmake install で インストールされます。

G.3.2. マニュアルページ

DocBook refentry ページを マニュアルページに対応した *roff 形式に変換するのに docbook2man ユーティリティを使用します。 man ページも HTML 形式と同じように tar アーカイブで 配布されています。マニュアルページの一式を作成するには次のようにします。

cd doc/src
gmake man.tar.gz

結果として doc/src に tar ファイルが生成されます。

マニュアルページを生成するには質の高い変換ユーティリティもしくは 手作業の処理が必要になることがあります。マニュアルページの全ては 配布する前に目で見てチェックする必要があります。

G.3.3. JadeTex からの印刷

JadeTex を使って印刷可能なドキュメントを 作成したい時は以下のコマンドの中から一つを選んでください。

G.3.4. RTF からの印刷

PostgreSQL ドキュメントの印刷できるバージョンを RTF に変換した後、ちょっとした修正を Office Suite で施すことで作成できます。特定の Office Suite による機能でドキュメントを 引続いて PDF の Postscript に変換できます。 以下に Applixware を使ってこの手順を示します。

注意: 現バージョンの PostgreSQL ドキュメントは OpenJade の大きさの限界 とそれを越えた部分でのバクを引き起こすようです。もし RTF バージョンが ビルド過程で長時間にわたってハングアップし、かつ出力ファイルのサイズが 0 のままであるよう な場合はこの問題に遭遇したことになります。(とはいっても、通常のビルドには 5 分から 10 分 を要しますのであせってアボートしないように注意してください。)

Applixware RTF の手入れ

OpenJade は本文に対してデフォルトのスタイルシートの特定を省略 します。過去においてはこの原因が究明されない問題によって表内容を生成するまで長い過程を 必要としました。しかし、Applixware に係わっている仲間 の助力でこの症状の診断することができるようになりしっくり行くようになりました。

  1. RTF バージョンを生成するためには次のように入力します。

    doc/src/sgml$ gmake postgres.rtf

  2. すべてのスタイル(特にデフォルトスタイル)を正しく指定するように RTF ファイルを 修正します。ドキュメントに refentry 節がある場合、前の段落を 現在の段落に連結されるフォーマット指示を、現在の段落が次の段落に連結するように 置き換えなければなりません。これらの修正を行ってくれるユーティリティ fixrtfdoc/src/sgml にあります。

    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 の行の 1 行目の始めの文字から最終行の最後の文字までを 選択します。

    2. Tools->Book Building->Create Table of Contents で新規 ToC をビルドします。 ToC に含めるためヘッダーの上から 3 レベルまでを選択します。 こうすると RTF からインポートされた既存の行が Applixware 本来の Toc と入れ換わります。

    3. Format->Style を使って ToC のフォーマットを調整します。3 つの ToC スタイルのそれぞれを選択し FirstLeft インデントを調整します。 下記の値を使用します。

      StyleFirst インデント(インチ)Left インデント(インチ)
      TOC-Heading 10.40.4
      TOC-Heading 20.80.8
      TOC-Heading 31.21.2

  5. ドキュメントにたいし下記に従って作業します。

    • 改ページの調整をします

    • 表の列幅の調整をします。

  6. ToC の Examples と Figures 部分の右寄せのページ番号を正しい値に修正します。 ほんの数分しかかかりません。

  7. 索引になにもない場合は削除します。

  8. 目次の再生成と調整をおこないます。

    1. ToC フィールドを選択します。

    2. Tools->Book Building->Create Table of Contents を選択します。

    3. Tools->Field Editing->Unprotect を選択して ToC を開放します。

    4. ToC そのもののエントリである ToC の第 1 行目を削除します。

  9. あとでの最終編集を容易にするため Applixware Words 固有のフォーマットでドキュメントを保存します。

  10. Postscript フォーマットでドキュメントをファイルに "出力"します。

G.3.5. 平文ファイル

インストールする過程の参照用としていくつかの平文によるファイルが配布 されています。INSTALL ファイルは 第14章 と連係していて、異なった内容を説明するためにちょっとした変更がくわえられています。 このファイルを生成するには doc/src/sgml ディレクトリに移動し gmake INSTALL と入力します。この操作で Netscape Navigator 用の平文 INSTALL.html が作成され、既存ファイルと同じ場所に置かれます。 Netscape は(lynxw3m と比べて)HTML を平文に 変換するのにもっとも品質の良い結果をもたらすようです。

HISTORY ファイルも同じようにして gmake HISTORY コマンドで作成できます。 src/test/regress/README ファイルの場合は gmake regress_README です。

G.3.6. 構文検証

ドキュメントのビルドにはとても時間がかかります。でもドキュメント ファイルの正しい構文だけを検証する方法があります。以下のように 入力します。ほんの数秒しかかかりません。

doc/src/sgml$ gmake check