ドキュメントをビルドする前にプログラムそのものをビルドしたと同様、configure スクリプトを実行する必要があります。実行の終りのほうで以下のような出力がなされるかどうか確認します。
checking for onsgmls... onsgmls checking for openjade... openjade checking for DocBook V3.1... yes checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular checking for sgmlspl... sgmlspl
もしも onsgmls あるいは nsgmls が見つからなかった場合には残り 4 行は表示されません。 nsgmls は Jade パッケージの一部です。"DocBook V3.1" が見つからない場合は DocBook DTD キットを jade が見つけられない場所に置いたか、もしくはカタログファイルが正しく設定されていません。前述のインストレーションのヒントを見てください。DocBook スタイルシートはいくつかの比較的標準となっている場所から探されますので、別の場所に置いた時には環境変数 DOCBOOKSTYLE でその場所を設定してから configure をあとで再実行します。
すべての設定が終了したら doc/src/sgml ディレクトリに移動して以下のコマンドの 1 つを実行して下さい (GNU make を使うのを忘れずに)。
HTML 形式の管理者用ガイド を作るにはつぎのようにします。
doc/src/sgml$ gmake admin.html
RTF 形式はつぎのようにして作ります。
doc/src/sgml$ gmake admin.rtf
JadeTeX で DVI 形式を作るにはつぎのようにします。
doc/src/sgml$ gmake admin.dvi
そして DVI から Postscript を生成します。
doc/src/sgml$ gmake admin.ps
Note: 公式の Postscript 形式のドキュメントは異なった方法で生成されています。下記 Section B.3.3 を見てください。
このほかの冊子も類似のコマンドで admin の部分をそれぞれ developer、programmer、tutorial または user とすることで作成できます。postgres とすると 5 冊すべての冊子をまとめたものが作成されて、ブラウザインターフェイスによってクリックするだけでドキュメント全体にわたってあちこち閲覧できますので実用的です。
doc/src/sgml に HTML 形式を作成する場合、その結果作成されたファイルの名前が冊子間で競合する可能性が (ほぼ確実に) あります。ですから、通常の配布で HTML 形式のファイルはこのディレクトリに入れていません。その代わりとして各冊子に付帯するファイルは tar でアーカイブされていて、インストールの際に解凍されます。HTML 形式のドキュメント一式を作成するには以下のコマンドを使用します。
cd doc/src gmake tutorial.tar.gz gmake user.tar.gz gmake admin.tar.gz gmake programmer.tar.gz gmake postgres.tar.gz gmake install
これらのアーカイブは配布物の doc ディレクトリにあって何もしなくても gmake install でインストールされます。
DocBook REFENTRY ページをマニュアルページに対応した *roff 形式に出力する際は docbook2man ユーティリティを使用します。man のページも HTML 形式と同じように tar アーカイブで配布されています。マニュアルページの一式を作成するにはつぎのようにします。
cd doc/src gmake man
結果として doc/src に tar ファイルが生成されます。
作成されたマニュアルページには数多くの紛らわしい出力が混ざっていますので、質の高い結果を得るには特別の処置を必要とします。この分野はまだ改善の余地があります。
Postscript によるハードコピードキュメントは SGML のソースコードを RTF に変換したあと、Applixware にインポートして生成されます。ちょっとした手入れをしたのち(つぎ節を見てください) postscript ファイルに"出力"されます。
RTF の修正、ToC (目次)の生成、ページ区切りの調整を含むくつかの部分が Postscript ハードコピーを生成する過程で適正処理されます。
Applixware RTF の手入れ
ハードコピープロシージャの統合的部分である jade はテキスト本文に対するデフォルトのスタイルシート指定を省略します。過去においてはこの原因が究明されていない問題で目次 (ToC) の生成に多くの処理を要しました。 しかし、Applixware の皆さんの多大な助力のおかげでこの症状が診断され、代替方法をとれるようになりました。
下記のコマンド(ひとつの例です)により RTF 入力を生成します。
% cd doc/src/sgml
% make tutorial.rtf
すべてのスタイル (特にデフォルトスタイル) を正しく指定するように RTF ファイルを修正します。ドキュメントに REFENTRY 節がある場合、その段落をつぎに続く段落に連結させないで その前の段落をその段落に連結させるようにその節はなおかつフォーマットのヒンティングを置き換えなければなりません。 これらの修正を完了するためのユーティリティである fixrtf は、doc/src/sgml にあります。
% cd doc/src/sgml
% fixrtf tutorial.rtf
または
% cd doc/src/sgml
% fixrtf --refentry reference.rtf
このスクリプトはそのドキュメントのなかでのゼロ番目のスタイルとして {\s0 Normal;} を付けくわえます。 Applixware によるとそれ自体に含まれているゼロ番目のスタイルを追加することを禁じていますが、M$Word は扱えるようになっています。REFENTRY 節を修正するためにスクリプトが \keepn タグを \keep に置き換えます。
Applixware Words で新規ドキュメントを開き RTF ファイルをインポートします。
Applixware で新規 ToC を生成します。
そこにある ToC の行の 1 行目の始めの文字から最終行の最後の文字までを選択します。
Tools.BookBuilding.CreateToC で新規 ToC をビルドします。ToC に含めるためヘッダーの上から 3 レベルまでを選択します。 こうすると RTF からインポートされた既存の行が Applixware 本来の Toc と入れ換わります。
Format.Style を使って ToC のフォーマットを調整します。3 つの ToC スタイルのそれぞれを選択し First と Left インデントを調整します。下記の値を使用します。
ドキュメントにたいし下記に従って作業します。
改ページの調整をします。
表の列幅の調整をします。
ドキュメントに図表を挿入します。 Applixware のツールバーの中央配置ボタンでそれぞれの図表を中央に配置します。
Note: すべてのドキュメントに図表があるわけではありません。 SGML ソースファイルを文字列 graphic で grep し、図表があるドキュメントの部分を特定します。 いくつかの図表はドキュメントの異なった部分で共用されています。
ToC の Examples と Figures 部分の右寄せのページ番号を正しい値に修正します。1 つのドキュメントにつき数分しかかかりません。
索引になにもない場合は削除します。
目つぎの再生成と調整をおこないます。
ToC フィールドを選択します。
Tools->Book Building->Create Table of Contents の選択をします。
Tools->Field Editing->Unprotect を選択して ToC を開放します。
ToC そのもののエントリーである ToC の第 1 行目を削除します。
あとでの最終編集を容易にするため Applixware Words 固有のフォーマットでドキュメントを保存します。
Postscript フォーマットでドキュメントをファイルに "出力"します。
gzip で Postscript ファイルを圧縮します。圧縮したファイルを doc ディレクトリに格納します。
インストールする過程で読むためにいくつかのプレーンテキスト形式によるファイルが配布されています。INSTALL ファイルは異なった内容を説明するためにちょっとした変更がくわえられていますが、管理者用ガイドの章と対応しています。このファイルを作るには doc/src/sgml に移動して gmake INSTALL と入力します。その結果 Netscape Navigator 用のテキストファイル INSTALL.html が作成され、既存ファイルと同じ場所に置かれます。Netscape は (lynx や w3m と比べて) HTML をテキストに変換するのにもっとも品質の良い結果をもたらすようです。
HISTORY ファイルも同じようにして gmake HISTORY コマンドで作成できます。src/test/regress/README ファイルの場合は gmake regress_README です。