ドキュメントを処理する過程で次のようなツールが使われます。 そのうちのいくつかは付記されているように省略しても構いません。
DocBookそのものの定義です。 現在は4.2バージョンを使用していて、これより古いまたは新しいバージョンは使用できません。 また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パッケージ一式を提供しています。 インストールに際しては"SGML"オプションまたはsgml-common、docbook、stylesheets、openjade(あるいはjade)パッケージがあるか確認してください。 sgml-toolsも必要かもしれません。 お手持ちのディストリビューションで提供されていない時は、その他の互換性のある配布元のパッケージを利用できるはずです。
FreeBSDのドキュメントプロジェクトそのものがDocBookのヘビーユーザですから、FreeBSD上で使用できるドキュメント作成用ツールの"port"一式が揃っていることは驚くに当たりません。 FreeBSD上でドキュメントをビルドするには以下のportsが必要です。
textproc/sp
textproc/openjade
textproc/iso8879
textproc/dsssl-docbook-modular
textproc/docbook-420
/usr/ports/print(tex、jadetex)の中にも興味を引くものが数多くあります。
portは/usr/local/share/sgml/catalogにあるメインカタログファイルを更新しない可能性があります。
CATALOG "openjade/catalog" CATALOG "iso8879/catalog" CATALOG "docbook/dsssl/modular/catalog" CATALOG "docbook/4.2/catalog"
という行があることを確認してください。 もしもファイルを編集したくない場合はSGML_CATALOG_FILES環境変数をカタログファイルにコロンで分割して(上記のように)設定することもできます。
FreeBSDでのドキュメント作成ツールについてのさらに詳しい情報はFreeBSD Documentation Project's instructionsにあります。
Debian GNU/Linux用のドキュメント作成パッケージの一式が揃っています。 インストールには以下を使います。
apt-get install openjade1.3 apt-get install docbook apt-get install docbook-dsssl
(ただのopenjadeパッケージではOpenJade 1.4をインストールしますが、これでは動作しないようです。)
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"
(これはステップ2でインストールされたファイルへの相対的参照パスです。 インストール先のレイアウトを変更している場合にはそれに合わせる必要があります。)
DocBook V4.2を入手します。
/usr/local/share/sgml/docbook-4.2ディレクトリを作成してそこに移動します。 (正確にこの場所でなくても構いませんが、ここで説明して行く流れの中では筋が通っているものです。)
$ mkdir /usr/local/share/sgml/docbook-4.2 $ cd /usr/local/share/sgml/docbook-4.2
アーカイブを解凍します。
$ unzip -a ...../docbook-4.2.zip
(アーカイブは置かれた場所に解凍されます。)
/usr/local/share/sgml/catalogファイル(もしくはインストール時にjadeに指定したファイルに)に以下の1行を付け加える編集を行います。
CATALOG "docbook-4.2/docbook.cat"
ISO 8879 character entitiesアーカイブをダウンロードし、解凍してできたファイルをDocBookのファイルと同じディレクトリに置きます。
$ cd /usr/local/share/sgml/docbook-4.2 $ 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はこのカタログエントリを使用しません。 どのようにスタイルシートを選択するかについての情報は項I.2.5を参照してください。
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
最後の2つの入力はrootになって行います。
PostgreSQL本体のプログラムを構築した時のように、ドキュメントを構築する際にconfigureスクリプトを実行する必要があります。 実行が終わる近辺の次のような出力を確認してください。
checking for onsgmls... onsgmls checking for openjade... openjade checking for DocBook V4.2... yes checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular checking for sgmlspl... sgmlspl
もしもonsgmlsあるいはnsgmlsが見つからなかった場合には残り4行は表示されません。 nsgmlsはJadeパッケージの一部です。 自動検出できなかった場合、環境変数JADE、NSGMLSを渡すことで、これらのプログラムの場所を指定することができます。 "DocBook V4.2"が見つからない場合はDocBook DTDキットをjadeが見つけられない場所に置いたか、もしくはカタログファイルが正しく設定されていません。 前述のインストレーションのヒントを見てください。 DocBookスタイルシートはいくつか比較的標準となっている場所から探されますので、別の場所に置いた時には、DOCBOOKSTYLE環境変数でその場所を設定してからconfigureを後で再実行します。