G.2. ツールセット

ドキュメントを処理する過程でつぎのようなツールが使われます。 そのうちのいくつかは付記されているようにオプションです。

DocBook DTD

DocBook そのものの定義です。現在は 3.1 バージョンを使用していて、 これより古いまたは新しいバージョンは使用できません。また XML バージョンの DocBook もありますが 使わないでください。

ISO 8879 character entities

DocBook に必要なものですが、ISO でメンテナンスされているため 別に配布されています。

OpenJade

SGML を処理する基本パッケージです。パッケージには SGML パーサ、(DSSSL を使って SGML を他のフォーマットに変換するプログラムである) DSSSL プロセッサ、および数多くの関連するツールが 含まれています。Jade は現在 James Clark ではなく OpenJade グループがメンテナンスしています。

DocBook DSSSL Stylesheets

DocBook のソースを HTML のような他のフォーマットに 変換する処理を指定します。

DocBook2X tools

マニュアルページを作成するオプションのパッケージです。 このパッケージ自身が必要とするパッケージがいくつかあります。 Web サイトで確認してください。

JadeTeX

お望みならば JadeTeX をインストールして Jade をフォーマットするバックエンドとして TeX を使うこともできます。 JadeTeX によると Postscript または (ブックマーク付の)PDF ファイルが作成できます。

とはいっても、JadeTeX での出力は RTF バックエンドで得られる結果よりも品質が劣ります。 特に問題があるのは表と水平垂直方向のスペーシングに関係する多彩な細工に かかわる部分です。さらに、でき上がった結果を手作業で修正することもできません。

ドキュメントを作成するために必要なさまざまなツールのインストール方法 についての経験をまとめました。以下に記載します。これらのツールは別に パッケージ化されて配布されていることも考えられます。もしそのような 配布物を見付けた場合は doc のメーリングリストに報告して下さい。 そのような情報をここに付け加えたいと思います。

G.2.1. Linux RPM のインストール

数多くのベンダーがディストリビューションの中に DocBook 処理用の RPM パッケージ一式を提供していています。インストールに際しては "SGML" オプションまたは sgml-commondocbookstylesheetsopenjade(あるいは jade) パッケージがあるか確認して下さい。sgml-tools も必要かもしれません。お手持ちのディストリビューションで提供されて いないときは、そのほかの互換性のある配布元のパッケージを利用できるはずです。

G.2.2. FreeBSD のインストール

FreeBSD のドキュメントプロジェクトそのものが DocBook のヘビーユーザ ですから、FreeBSD 上で使用できるドキュメント作成用ツールの "port" 一式が揃っていることは驚くにあたりません。 FreeBSD 上でドキュメントをビルドするには以下の ports が必要です。

/usr/ports/printtexjadetex)の中にも興味を引くものが数多くあります。

port は /usr/local/share/sgml/catalog にある メインカタログファイルを更新しない可能性があります。

CATALOG "/usr/local/share/sgml/docbook/3.1/catalog"

という行があることを確認してください。 もしもファイルを編集したくない場合は環境変数 SGML_CATALOG_FILES をカタログファイルにコロンで分割して (上記のように)設定することもできます。

FreeBSD でのドキュメント作成ツールについての更に詳しい情報は FreeBSD Documentation Project's instructions にあります。

G.2.3. Debian パッケージ

Debian GNU/Linux 用のドキュメント作成 パッケージの一式が揃っています。インストールには以下を使います。

apt-get install jade
apt-get install docbook
apt-get install docbook-stylesheets

G.2.4. ソースから手作業でインストール

DocBook ツールを手作業でインストールするのは何かと複雑ですから もし既にできているパッケージがあるならばそちらを使ったほうが よいでしょう。 ここでは標準的なインストール手順として一般的な 機能以外を持たせない標準的なセットアップのみを説明します。 詳しいことはそれぞれにパッケージのドキュメントと SGML の入門資料を読んでください。

G.2.4.1. OpenJade のインストール

  1. OpenJade のインストールは GNU 形式の ./configure; make; make install ビルド手順で 行います。詳しいことは OpenJade ソース配布物の中にあります。 要約すると次のようになります。

    ./configure --enable-default-catalog=/usr/local/share/sgml/catalog
    make
    make install

    "デフォルトカタログ"をどこに置いたか覚えておいてください。 あとで必要になります。そのままにしておいても構いませんが、あとで jade を使用する時には環境変数 SGML_CATALOG_FILES を設定してファイルの場所を指定する 必要があります。(既に OpenJade がインストールされていて残りのツール 一式を別の場所にインストールしたい場合にはこの方法を使用する手があります。)

  2. さらに dsssl ディレクトリからどこか、 例えば /usr/local/share/sgml/dsssl といった ディレクトリに dsssl.dtdfot.dtdstyle-sheet.dtd および catalog をインストールします。 ディレクトリ全てを一括コピーすることが一番簡単です。

    cp -R dsssl /usr/local/share/sgml

  3. 最後に、ファイル /usr/local/share/sgml/catalog を作成して 以下の行を付けくわえます。

    CATALOG "dsssl/catalog"

    (これは ステップ2 にインストール されたファイルへの相対的参照パスです。インストール先のレイアウトを 変更している場合にはそれに合わせる必要があります。)

G.2.4.2. DocBook DTD キットのインストール

  1. DocBook V3.1 を入手します。

  2. /usr/local/share/sgml/docbook31 ディレクトリ を作成してそこに移動します。(正確にこの場所でなくても構いませんが、 ここで説明して行く流れの中では筋が通っているものです。)

    $ mkdir /usr/local/share/sgml/docbook31
    $ cd /usr/local/share/sgml/docbook31

  3. アーカイブを解凍します。

    $ unzip -a ...../docbk31.zip

    (アーカイブは置かれた場所に解凍されます。)

  4. /usr/local/share/sgml/catalog ファイル(もしくは インストール時に jade に指定したファイルに)に以下の一行を付けくわえる 編集を行います。

    CATALOG "docbook31/docbook.cat"

  5. docbook.cat ファイルの DTDDECL が書かれている行をコメントアウトしたり削除したりすることは自由です。 この作業を行わない場合は jade が警告を 出しますが、特に問題はありません。

  6. ISO 8879 character entities アーカイブをダウンロードし、解凍して できたファイルを DocBook のファイルと同じディレクトリに置きます。

    $ cd /usr/local/share/sgml/docbook31
    $ unzip ...../ISOEnts.zip

  7. DocBook と ISO ファイルを置いたディレクトリで以下のコマンドを実行します。

    perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat

    (この操作によって DocBook カタログファイルで使われる名称と実際の ISO 文字登録ファイル間での重複が整理されます。)

G.2.4.3. DocBook DSSSL スタイルシートのインストール

スタイルシートのインストールは配布物を解凍してたとえば /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 は このカタログエントリを使用しません。どのようにスタイルシートを 選択するかについての情報は 項G.2.5 を参照してください。

G.2.4.4. JadeTeX のインストール

JadeTeX をインストールし使用するには toolsgraphics パッケージ BabelAMS フォントおよび AMS-LaTeXPSNFSS 拡張と "the 35 fonts" の付属キット、 PostScript を生成する dvips プログラム、 マクロのパッケージとして fancyhdrhyperrefminitocurl および ot2enc がサポートされている TeXLaTeX2e が既にインストールされていなくてはなりません。 これらすべては、好意的な仲間でもある CTAN サイトにあります。 TeX の基本システムのインストールはこの紹介文の範囲を はるかに越えています。どのようなシステム上でも稼働する TeX のバイナリパッケージはいずれかに存在します。

JadeTeXPostgreSQL のドキュメントソースに適用する前に TeX 内部データ構造の容量を増やさないといけない場合があります。この件に関しての詳細は JadeTeX のインストールの説明のところに記載されています。

この操作を終えたところで JadeTeX をインストールできるようになります。

$ gunzip jadetex-xxx.tar.gz
$ tar xf jadetex-xxx.tar
$ cd jadetex
$ make install
$ mktexlsr

最後の二つの入力は root になって行います。

G.2.5. configure の書き方

PostgreSQL 本体のプログラムをビルドした 時のように、ドキュメントをビルドする時に 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 をあとで再実行します。