ドキュメントを作成する過程でつぎのようなツールが使われます。そのうちのいくつかは付記されているようにオプションです。
DocBook そのものの定義です。現在は 3.1 バージョンを使用していて、これより古いまたは新しいバージョンは使用できません。また XML バージョンの DocBook もありますが使わないでください。
DocBook に必要なものですが、ISO でメンテナンスされているため別に配布されています。
SGML を処理する基本パッケージです。パッケージには SGML パーサ、(DSSSL を使って SGML を他のフォーマットに変換するプログラムである) DSSSL プロセッサ、および数多くの関連するツールが含まれています。Jade は現在 James Clark ではなく OpenJade グループがメンテナンスしています。
DocBook のソースを HTML のような他のフォーマットに変換する処理を指示します。
マニュアルページを作成するオプションのパッケージです。このパッケージ自身が必要とするパッケージがいくつかあります。Web サイトで確認してください。
お望みならば JadeTeX をインストールして Jade をフォーマットするバックエンドとして TeX を使うこともできます。JadeTeX によると Postscript または (ブックマーク付の) PDF ファイルが作成できます。
とはいっても、JadeTeX での出力は RTF バックエンドで得られる結果よりも品質が劣ります。特に問題があるのは表と水平垂直方向のスペーシングに関係する多彩な細工にかかわる部分です。さらに、でき上がった結果を手作業で修正することもできません。
ここではドキュメントを作成するために必要なさまざまなツールのインストール方法についての経験をまとめました。以下に記載します。これらのツールは別にパッケージ化されて配布されていることも考えられます。もしそのような配布物を見付けた場合は doc のメーリングリストに報告して頂けませんか。 ここに付け加えますので。
数多くのベンダーがディストリビューションの中に DocBook 処理用の RPM パッケージ一式を提供していています。 パッケージは通常 Red Hat Software 社の努力による docbook-tools に基づいています。 インストールに際しては "SGML" オプションまたは sgml-common、 docbook、stylesheets、 openjade (あるいは jade) パッケージがあるかチェックして下さい。sgml-tools も必要かもしれません。お手持ちのディストリビューションで提供されていないときは、そのほかの互換性のある配布元のパッケージを利用できるはずです。
FreeBSD のドキュメントプロジェクトそのものが DocBook のヘビーユーザーですから、FreeBSD 上で使用できるドキュメント作成用ツールの "port" 一式が揃っていることは驚くにあたりません。FreeBSD 上でドキュメントをビルドするには以下の ports が必要です。
textproc/sp
textproc/openjade
textproc/docbook-310
textproc/iso8879
textproc/dsssl-docbook-modular
同時に /usr/ports/print (tex、 jadetex) の中にも数多くの関連するものがあります。
port は /usr/local/share/sgml/catalog にあるメインカタログファイルを更新しない可能性があります。という行があることを確認してください。
CATALOG "/usr/local/share/sgml/docbook/3.1/catalog"
もしもファイルを編集したくない場合は環境変数 SGML_CATALOG_FILES をカタログファイルにコロンで分割して(上記のように)設定することもできます。
FreeBSD でのドキュメント作成ツールについての更に詳しい情報は FreeBSD Documentation Project's instructions にあります。
Debian GNU/Linux 用のドキュメント作成用パッケージの一式が揃っています。インストールには以下を使います。
apt-get install jade apt-get install docbook apt-get install docbook-stylesheets
DocBook ツールを手作業でインストールするのは何かと複雑ですからもし既にできているパッケージがあるならばそちらを使ったほうがよいでしょう。 ここでは標準的なインストールパスに一般的な機能以外を持たせない標準的なセットアップのみを説明します。詳しいことはそれぞれにパッケージのドキュメントと SGML の入門資料を読んでください。
OpenJade のインストールは GNU 形式の ./configure; make; make install 構築手順で行います。詳しいことは OpenJade ソース配布物の中にあります。要約すると、次のようになります。
./configure --enable-default-catalog=/usr/local/share/sgml/catalog make make install
"デフォルトカタログ"をどこに置いたか覚えておいてください。 あとで必要になります。そのままにしておいても構いませんが、あとで jade を使用する時には環境変数 SGML_CATALOG_FILES を設定してファイルの場所を指定する必要があります。(既に OpenJade がインストールされていて残りのツール一式をローカルにインストールしたい場合にはこの方法を使用する手があります。)
さらに dsssl ディレクトリからどこか、例えば /usr/local/share/sgml/dsssl といったディレクトリに dsssl.dtd、 fot.dtd、style-sheet.dtd および catalog をインストールします。いちばん簡単なのはディレクトリ毎コピーすることです。
cp -R dsssl /usr/local/share/sgml
最後に、ファイル /usr/local/share/sgml/catalog を作成して以下の行を付けくわえます。
CATALOG "dsssl/catalog"
(これは step 2 にインストール されたファイルへの相対的参照パスです。インストール先のレイアウトを変更している場合にはそれに合わせる必要があります。)
DocBook V3.1 を入手します。
/usr/local/share/sgml/docbook31 ディレクトリを作成してそこに移動します。(正確にこの場所でなくても構いませんが、ここで説明して行く流れの中では合理的です。)
$ mkdir /usr/local/share/sgml/docbook31 $ cd /usr/local/share/sgml/docbook31
アーカイブを解凍します。
$ unzip -a ...../docbk31.zip
(アーカイブは置かれた場所に解凍されます。)
ファイルを編集します。 /usr/local/share/sgml/catalog (またはインストール時に jade に指定したファイル)に以下の一行を付けくわえます。
CATALOG "docbook31/docbook.cat"
docbook.cat ファイルの DTDDECL が書かれている行をコメントアウトしたり削除したりすることは随意です。この作業を行わなかった場合は jade が警告を出しますが、特に問題はありません。
ISO 8879 character entities アーカイブをダウンロードし、解凍してできたファイルを DocBook のファイルと同じディレクトリに置きます。
$ cd /usr/local/share/sgml/docbook31 $ unzip ...../ISOEnts.zip
DocBook と ISO ファイルを置いたディレクトリで以下のコマンドを実行します。
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
(この操作によって DocBook カタログファイルで使われる名称と実際の ISO 文字構成要素の名称間での重複が整理されます。)
スタイルシートのインストールは配布物を解凍してたとえば /usr/local/share/sgml のような適当な場所に置きます。(アーカイブは自動的にサブディレクトリを作成します。)
$ gunzip docbook-dsssl-1.xx.tar.gz $ tar -C /usr/local/share/sgml -xf docbook-dsssl-1.xx.tar
/usr/local/share/sgml/catalog にある一般的なカタログエントリも作成されます。
CATALOG "docbook-dsssl-1.xx/catalog
スタイルシートはしばしば変更がかかることにくわえ、時として代わりとなるバージョンを試してみることは有益ですから、PostgreSQL はこのカタログエントリを使用しません。どのようにスタイルシートを選択するかについての情報は Section B.3 を参照してください。
JadeTeX をインストールし使用するには tools と graphics パッケージ Babel、AMS フォントおよび AMS-LaTeX、PSNFSS 拡張と "the 35 fonts" の付属キット、PostScript を生成する dvips プログラム、マクロのパッケージとして fancyhdr、hyperref、minitoc、url および ot2enc がサポートされている TeX と LaTeX2e が既にインストールされていなくてはなりません。これらすべては、便利な CTAN サイトにあります。TeX の基本システムのインストールはこの紹介文の範囲をはるかに越えています。どのようなシステム上でも稼働する TeX のバイナリパッケージがどこかにあるはずです。
JadeTeX をPostgreSQL のドキュメントソースに適用する前に TeX 内部データ構造の容量を増やさないといけない場合があります。この件に関しての詳細は JadeTeX のインストールの説明のところに記載されています。
この操作を終えたところで JadeTeX をインストールできるようになります。
$ gunzip jadetex-xxx.tar.gz $ tar xf jadetex-xxx.tar $ cd jadetex $ make install $ mktexlsr
終りの二つの入力は root になって行います。