はじめに

この記事では、DocBook XML と Eclipse IDE (integrated development environment: 統合開発環境) とを組み合わせて使うことで、多くのフォーマットで容易に配布できる再利用可能な技術文書を作成する方法について説明します。DocBook XML は標準 XML タグのライブラリーであり、これを使うことで、ほとんどすべての出力の生成が可能なスタイルシートを作成することができます。しかし DocBook が登場してから 10 年近く経過しているため、HTML やテキスト、PDF、man ページなど、多くのタイプの文書を生成する数多くのスタイルシートが既に作成されています。

この記事を読み終わると、皆さんは DocBook XML を使って文書を作成し、それを HTML に生成して Eclipse のヘルプ・プラグインに使用したり、あるいは 1 つの XML ソース・ファイルから PDF を作成したりできるようになっているはずです。この記事を読むためには、XML に関する実際的な知識が少し必要です。また、Eclipse IDE から Ant ビルド・ファイルを実行することを含めて、Eclipse と Apache Ant の使い方にも慣れている必要があります。ここでは、Eclipse V3.2 以上と DocBook XML V4.x DTD (Document Type Definition)、DocBook XSL スタイルシート、Apache Xalan-Java™、そして (オプションとして) Apache FOP が必要です (ダウンロードに関しては「参考文献」を参照してください)。

DocBook XML の概要

DocBook XML は、文書を作成するために調整された、XML タグのライブラリーです。DocBook では数多くのタグが利用できることから、DocBook は技術的な文書を作成するための当然の選択肢と言うことができます。また DocBook は XML なので、スタイルシートを使って数多くのさまざまな出力フォーマットに変換することができます。そのため DocBook XML は、技術文書を一度作成し、それをさまざまなフォーマットで生成するための当然の選択肢なのです。

注意: この記事で取り上げるコードは DocBook XML V4.5 を使って開発されました。V5.0 は、この記事の執筆時点ではリリースの候補というステータスでした。

上に戻る

上位レベルの要素

表 1 は、DocBook XML ファイルの上位レベル要素として一般的に使われる要素を示しています。

上に戻る

コンテンツのための要素

上位レベル要素の中に、実際のコンテンツ (段落や表、リスト、コード・サンプルなど) を追加しなければならないことがあります。表 2 は、book や chapter、あるいは article に内容を追加するために使われる一般的な要素のいくつかを示しています。

下記は、表 2 にリストされた各要素を少なくとも 1 つ持つ book を含んだ簡単なサンプル文書です。

                
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
<title>My Example Book</title>
<titleabbrev>Example</titleabbrev>
<bookinfo>
<author>
<personname>
<firstname>Nathan</firstname>
<surname>Good</surname>
</personname>
</author>
</bookinfo>
<preface id="preface1">
<title>Required Preface</title>
<para>You will like my book (I think).</para>
</preface>
<chapter id="chapter1">
<title>Your First Chapter</title>
<para>You must include at least one chapter in your book.</para>
<para>Here is another paragraph.</para>
<important>
<para>This is some really important text.</para>
</important>
<tip>
<para>Look both ways before crossing the street!</para>
</tip>
<caution>
<para>
Liberal use of <code>new</code> in loops can cause performance issues!
</para>
</caution>
<example>
<title>Example 1</title>
<programlisting>
String something = "Something";
</programlisting>        
</example>
</chapter>
</book>

このファイルが HTML として生成され、ブラウザーで描画されると、図 1 のようなものになります。

どのような DocBook XML タグがあるかを 1 つ 1 つ説明していると際限がないため、そうした説明はリファレンス・マニュアルに任せるのが一番です。リファレンス・マニュアルの HTML 版へのリンクを「参考文献」にあげてあります。DocBook XML に関する本もあります。表 2 にリストされたタグは出発点としては十分ですが、他にもスクリーンショットやコマンド・プロンプト、ユーザー入力、商標、引用符に関するものなど、数えられないほど多数のタグがあります。

上に戻る

環境を設定する

XSLT (Extensible Stylesheet Transformation Language) 変換を行うためにはツールを使う必要があり、またツールと合わせて、HTML や PDF などの便利なフォーマットに DocBook XML を変換するための XSL スタイルシートも使う必要があります。自分専用で独自の XML を作成する場合であったとしても、やはり独自のスタイルシートを作成する必要があります。しかし DocBook XML のような確立されたフォーマットを使うことで、既に他の人が作成したスタイルシートを使えるのです。既製のスタイルシートを使うためには、それらをダウンロードします (「参考文献」を参照)。この記事の執筆時点で、DocBook XML V4.5 用のスタイルシートのセットは DocBook XSL V1.72.0 です。

スタイルシートを取得する

DocBook XSL を含む、ダウンロードしたアーカイブ・ファイル (例えば docbook-xsl-1.72.0.zip など) には、スタイルシートが生成する出力のタイプ別に分けられたディレクトリーに、スタイルシートが含まれています。つまり html ディレクトリーは HTML を出力するためのスタイルシートを含んでおり、fo ディレクトリーは FO (Formatting Objects) フォーマットでファイルを生成するためのスタイルシートを含んでいる、等々です。

アーカイブ・ファイルをダウンロードし、それを後で思い出しやすい場所に保存します。アーカイブ・ファイルからファイルを解凍する必要はありません。後で Eclipse の中に直接インポートします。

Xalan を使う

この記事では、XSLT プロセッサーとして Xalan を使います。ただし、Eclipse に付属しているバージョンの Ant と一緒に Xalan を使うと、1 つ問題があります。このバージョンは最新バージョンよりも古く、XSL を処理しようとすると問題が発生します。

Xalan は Apache のプロジェクトですが、Xalan C++ と Xalan-Java という 2 つのサブプロジェクトがあります。皆さんのマシンに Xalan-Java がなかったら、これをダウンロードします。ファイルのダウンロードを終了したら、覚えやすい場所に保存します。スタイルシートを含むアーカイブ・ファイルと同様、まだファイルの内容を解凍してはいけません。

上に戻る

Eclipse プロジェクトを作成する

ここまでに、いくつかのサンプル・ファイルを見てきました。そして最新バージョンの DocBook XSL スタイルシートと、(まだ持っていなかった場合には) 最新バージョンの Xalan をダウンロードしたはずです。また DocBook XML スキーマ・ファイルもダウンロードしたはずです。そしてアーカイブ・ファイル (例えば docbook-xsl-1.72.0.zip と xalan-j_2_7_0_bin-2jars.zip、そして docbook-xml-4.5.zip) は、見つけやすい場所に保存されているはずです。

すべてのアーカイブ・ファイルをダウンロードして保存できると、Eclipse を起動して新しいプロジェクトを作成する準備は完了です。そして DocBook XML と Ant スクリプトを編集し、DocBook XML をさまざまなフォーマットに変換します。

Eclipse が起動したら、File > New > Project を選択して新しいプロジェクトを作成します。General の下にある汎用の Project をクリックし、次に Next をクリックします。プロジェクトの名前を入力して Finish をクリックすると、ワークスペースに新しいプロジェクトが作成されます。

上に戻る

アーカイブからファイルをインポートする

Eclipse で新しいプロジェクトを作成したので、DocBook XML の作成に使用するファイルをインポートします。

DTD ファイルをインポートする

まず、DocBook XML DTD ファイルをインポートします。下記のように File > Import を選択し、次に General カテゴリーから Archive File を選択します。Import Wizard が表示されたら Browse をクリックし、DocBook XML DTD アーカイブ・ファイル (docbook-xml-4.5.zip) を見つけるために使用するファイル・ブラウザーを開きます。

Into folder ボックスで、プロジェクト名の後に /docbook-xml と入力します。下記のように、/ フォルダーが選択されていることを確認します。選択されていない場合や、グレー・アウトされている場合は Select All をクリックし、そして Finish をクリックします。アーカイブの中のファイルがプロジェクトに挿入されます。

XSL スタイルシートをインポートする

DocBook XML DTD ファイルのインポートが終わったら、同じ手順で docbook-xsl-1.72.0.zip ファイルの中身をインポートします。しかしこの場合は、Into folder ボックスでプロジェクト名の後にフォルダー名を指定する必要はありません。これは、プロジェクト内に docbook-xsl-1.72.0 という名前のフォルダーが作成され、その中にアーカイブの中身がインポートされるからです。

これで XSL スタイルシートをインポートできたので、Xalan の Web サイトからダウンロードしたアーカイブから、必要な JAR (Java Archive) ファイルをインポートします。この手順は他のアーカイブ・ファイルをインポートする場合と同じですが、この場合は docs、licenses、samples というディレクトリーを必ずクリアーし、これらがプロジェクトにインポートされないようにします。これらのディレクトリーをクリアーしたら、Into folder ボックス内のプロジェクト名に /lib を追加します。

必要なファイルをすべてインポートしたら、プロジェクトの中に追加のフォルダーを 1 つ作成し、src という名前を付けます。このフォルダーが、すべての DocBook XML ファイルのベース・フォルダーとなります。

この段階で、Eclipse 内のプロジェクトには下記のフォルダーが作成されているはずです。

• DocBook XML DTD を含む docbook-xml
• DocBook XSL スタイルシートを含む docbook-xsl-1.72.0
• Xalan JAR ファイルを含む lib
• 現在は空の、src

プロジェクト内にこれらのフォルダーがすべて用意できたら、変換プロセスを実行するための Ant ファイル build.xml を追加する準備が整ったことになります。

Ant スクリプトを作成する

Ant は Java ベースのビルド・ツールであり、XML スクリプトを読み取り、そのスクリプトに定義された数多くのタスクを実行することができます。Ant になじみがない人は、「参考文献」を参照してください。この記事では Eclipse を使って Ant を開始するので、コマンド・ラインから Ant を実行する方法を理解する必要はありません。また、Eclipse IDE V3.2.x には Ant が付属しているため、Ant のダウンロードやインストールを気にする必要はありません。この Ant (V1.65) は最新のバージョン (V1.7) よりも古いのですが、この記事の場合には問題ありません。

しかし、 V1.6.5 の Ant に付属しているバージョンの Xalan は、最新の DocBook XSL と一緒に使おうとすると、うまく動作しないようでした。しかし最新バージョンの Xalan (そしてそこに含まれているバージョンの Xerces) をダウンロードして使えば、問題なく動作するはずです。

上に戻る

Ant で Xalan を使う

Ant に付属しているデフォルト・バージョンの Xalan ではなく、ある特定のバージョンの Xalan (あるいは他の任意の XSLT プロセッサー) を使うことを Ant に対して指定する方法が、いくつかあります。その 1 つが Ant のクラスパスを変更する方法です。Eclipse IDE の中で Ant を使う場合には、これは非常に簡単です。Window > Preferences を選択し、Ant/CLASSPATH の下の設定を変更します。CLASSPATH タブ上にある、Xalan あるいは Xerces への参照をすべて削除し、ダウンロードしたバージョンで置き換えます。

変換を行う人が 1 人のみであれば、変換動作を正しく行わせるために Ant の設定を変更するのはその人のみなので、この方法でも問題はありません。しかしチームで作業する場合には、プロジェクトの Xalan と Xerces の JAR ファイルをディレクトリー (例えば lib) の中に含め、そして build.xml ファイルを変更して xslt タスク用のライブラリーを使うようにした方が賢明です。この方法を使うと、Eclipse IDE の設定を変更しなくても、ソース・コントロールから簡単にファイルをチェック・アウトしたり、あるいはプロジェクトを配布して実行したりすることができます。

xslt タスクに JAR ファイルを提供する例として、下記のような Ant ビルド・スクリプトをあげることができます。

                
<?xml version="1.0"?>
<!--
- Author:  Nathan A. Good <mail@nathanagood.com>
-->
<project name="docbook-src" default="usage">

<description>
This Ant build.xml file is used to transform DocBook XML to various
</description>

<!--
- Configure basic properties that will be used in the file.
-->
<property name="docbook.xsl.dir" value="docbook-xsl-1.72.0" />
<property name="doc.dir" value="doc" />
<property name="html.stylesheet" value="${docbook.xsl.dir}/html/docbook.xsl" />
<property name="xalan.lib.dir" value="lib/xalan-j_2_7_0" />

<!--
- Sets up the classpath for the Xalan and Xerces implementations
- that are to be used in this script, since the versions that ship
- with Ant may be out of date.
-->
<path id="xalan.classpath">
<fileset dir="${xalan.lib.dir}" id="xalan.fileset">
<include name="xalan.jar" />
<include name="xercesImpl.jar" />
</fileset>
</path>

<!--
- target:  usage
-->
<target name="usage" description="Prints the Ant build.xml usage">
<echo message="Use -projecthelp to get a list of the available targets." />
</target>

<!--
- target:  clean
-->
<target name="clean" description="Cleans up generated files.">
<delete dir="${doc.dir}" />
</target>

<!--
- target:  depends
-->
<target name="depends">
<mkdir dir="${doc.dir}" />
</target>

<!--
- target:  build-html
- description:  Iterates through a directory and transforms
-     .xml files into .html files using the DocBook XSL.
-->
<target name="build-html" depends="depends" 
description="Generates HTML files from DocBook XML">
<xslt style="${html.stylesheet}" extension=".html" 
basedir="src" destdir="${doc.dir}">
<classpath refid="xalan.classpath" />
</xslt>
</target>

</project>

太字で示した <property> タグを使うと、Xalan JAR ファイルの場所を指定することができます。<path> 要素は、Ant スクリプト全体で再利用できるパスを定義します。また Xalan XSLT プロセッサーへのパスを xslt ターゲットに指定する方法として、refid 属性を使ってパスを参照する代わりに、classpath 属性を使う方法や、あるいは classpath 要素内のパスを指定する方法があります。

xslt ターゲットは、basedir 属性と extension 属性、そして destdir 属性を使ってフォルダーを再帰的に調べ、そしてディレクトリーの中にある各 XML ファイルに対して HTML ファイルを生成するように設計されています。この出力はフォルダーに保存され、後ほど説明する Eclipse プラグインと組み合わされるヘルプ・ファイルのための HTML ソースとして後で使うことになります。

上に戻る

build.xml ファイルを作成する

File > New >File を選択し、build.xml ファイルを作成します。ファイル名として build.xml と入力し、そしてこのファイルの場所として、プロジェクトを選択します。Finish をクリックすると Ant ファイルが作成されます。

リスト 2 に示す内容は、新しいビルド・ファイルの内容にすることができます。もし選択したディレクトリー名のいずれかが、ここで使用したものと異なる場合には、すべてを適切に動作させるためには property 要素の中のいくつかの値を調整する必要があるかもしれません。

Eclipse には Ant ビルド・スクリプトを実行するためのフックが組み込まれているため、Eclipse から直接 build.xml ファイルを実行することができます。Ant を使うと、他にもいくつか利点があります。まず、クロス・プラットフォームである点です。これはつまり、この同じビルド・スクリプトを、Java コードを実行する任意のオペレーティング・システムで実行できるということです。もう 1 つの利点は、このビルド・スクリプトを IDE とは独立に実行できることです。従って、このスクリプトを自動ビルド・プロセスの中に容易に組み込むことができ、あるいはコマンド・ラインから実行することもできます。私は最初、Eclipse プロパティーを設定し、XSLT プロセッサーを外部ツールとして実行する (Run > External Tools を見てください) ことを考えましたが、この考えをあきらめ、上記の利点を利用することにしました。

上に戻る

build-html ターゲットを実行する

build.xml ファイルを作成できたら、build-html ターゲットを実行します。まだ DocBook XML ファイルがないので、ターゲットは何も有効なことはしません。ただし、このスクリプトを実行しても何かエラーが起きることはないはずです。

Ant ターゲットを実行するために最も容易な方法は、エディターの中でビルド・ファイルが開いているときに Outline ビューから実行する方法です。Outline ビューの中で build-html ターゲットの名前を右クリックし、そして Run As > Ant Build を選択します。Ant ビルド・スクリプトからのメッセージがあれば、Console ビューに表示されます。

上に戻る

DocBook XML ファイルを作成する

Eclipse プロジェクトの中には、DocBook XML DTD ファイルと DocBook XSL ファイル、Xalan ライブラリー、そして今や build.xml があるはずです。これで、DocBook XML ファイルの作成を始めるために必要なものがすべて揃いました。

最初の DocBook XML ファイルを作成する

最初の DocBook XML ファイルを Eclipse で作成するためには、

1. File > New > Other を選択します。
2. XML カテゴリーから XML を選択し、そして Next をクリックします。
3. Create XML File ウィンドウで Create XML file from a DTD file を選択し、Next をクリックします。
4. File name ボックスに chapter1.xml と入力し、次にプロジェクトの中で src フォルダーが選択されていることを確認し、そして Next をクリックします。
5. Select DTD File で、プロジェクトの docbook-xml フォルダーの docbookx.dtd ファイルまでナビゲートし、そして Next をクリックします。
6. Select Root Element ウィンドウが表示されたら、Root element から chapter を選択し、次にCreate first choice of required choice チェックボックスをクリアーします。
7. -//OASIS//DTD DocBook XML V4.5//EN と入力し、そして Finish をクリックします。

XML エディターで chapter1.xml を処理する

Eclipse は XML エディターの中で chapter1.xml を開きます。Eclipse の XML エディターは、ファイルに対して Design と Source という 2 つのビューを持っています。XML ファイルの Design ビューは、そのファイルの要素を、要素名を左の列、要素の内容を右の列とするグリッドで表示します。新しい要素をファイルに追加するには、ファイルを右クリックし、Add Child、あるいはAdd After、Add Before のいずれかを選択します。

DTD を使っている場合には、コンテキスト・メニューの選択肢によって、有効な要素しか追加できないように制限されます。この機能によって、後で変換を行う際に XML ファイルで大量の妥当性検証エラーが発生するのを確実に防ぐことができます。

上に戻る

モジュール構造の文書を作成する

数多くの文書を作成する場合、特に大企業やあるグループのメンバーなど同じ読者層を対象にする場合には、作成される文書同士が似てしまうことがよくあるものです。例えば皆さんが何冊かの技術書を読んだことがあれば、ほとんどすべての本に、その本の中でヒントや助言、インライン・コード、コード・リストなどの形式を説明した、「この本で使われている規則」という節 (section) や章 (chapter) があることに気付いたはずです。

DocBook XML ファイルを分割する

DocBook XML を使うと、文書を多くのファイルに分割することができます。それらのファイルは 1 つの単位にコンパイルすることができ、再利用される可能性があります。例えば、自分が書いた本 (book) の各 chapter を個別の XML 文書にすることができます。そしてその XML 文書を別の book の中で使ったり、あるいは単純にそれらを別ファイルに分割し、維持管理しやすくしたりすることもできます。そうすると、そうした chapter を book の中に含め、スタイルシートを使って処理できるようになります。

リスト 3 は、他の DocBook XML ファイルを動的に含める DocBook XML 文書を作成する例を示しています。このファイルが変換処理される時には、このファイル (ここでは chapter1.xml) は、まるで &chap1; が記述されている場所にあるかのように処理されます。

                
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"../docbook-xml/docbookx.dtd" [
<!ENTITY chap1 SYSTEM "chapter1.xml">
]>
<book>
&chap1;
</book>

この方法を使う際には、注意すべき点がいくつかあります。まず、chapter1.xml ファイルを変更し、XML のプリプロセスを行うディレクティブと DOCTYPE 要素を削除する必要があります。chapter1.xml の内容は &chap1 の実体がある場所に置かれるため、book.xml はファイルの真ん中に XML のプリプロセスを行うディレクティブと DOCTYPE 要素を含むことになり、book.xml が無効になってしまいます。

第 2 に、もはや個々の chapter ファイルを個別の HTML ファイルにする処理が必要なくなったら、chapter ファイルの処理をスキップするように Ant ビルド・スクリプトを変更する必要があります。幸い Ant の xslt タスクのおかげで、この変更はごくわずかなもので済みます。xslt タスクは、Ant の fileset 要素と同じ要素を含むことができ、含めるファイルや除外するファイルのリストをかなり簡単に作成できるということです。リスト 4 は、処理の中で一部のファイルをスキップするために必要な追加を、<exclude> 要素を使って含める方法を示しています。

                
<target name="build-html" depends="depends" 
description="Generates HTML files from DocBook XML">
<xslt style="${html.stylesheet}" extension=".html" 
basedir="${source.dir}" destdir="${doc.dir}">
<classpath refid="xalan.classpath" />
<include name="**/*.xml" />
<exclude name="chapter1.xml" />

</xslt>
</target>

こうした方法があったとしても、やはりすべての文書をビルドしたい場合には、上記の exclude 要素を削除します。

分割できるのは chapter や book だけではありません。意味が通じるのであれば、任意の場所で物理的に DocBook XML ファイルを分割することができます (例えば section をファイルとして独立させる、など)。さらに、DocBook 要素の最上位レベルである set 要素の中に book を含めることもできます。

ヘルプ・プラグインを作成する

Eclipse フレームワークの強力な機能の 1 つは、拡張性です。私はさまざまな企業を観察してきましたが、データベースへの接続やトランザクションの処理、あるいはエラーの処理などに関して「その会社が承認した」特定の方法を使用する企業を見ると、なぜ開発者が実際に作業を行う環境以外の場所で文書を探させるのだろう、と不思議に思います。なぜ、同じ HTML 文書をヘルプの形で企業のイントラネットから利用できるようにし、開発者に配布しないのでしょう。そうすれば IDE から容易にアクセスでき、索引付けでき、そして検索できるのです。

Eclipse IDE に付属しているテンプレートを使うことで、HTML ファイル形式のヘルプを含むプラグイン・プロジェクトを素早く作成することができます。以下の数セクションでは、こうしたプラグイン・プロジェクトを作成する方法について説明します。こうしたプラグイン・プロジェクトを作成できると、作成した HTML ファイルを DocBook XML プロジェクトに含めることができます。

上に戻る

実際にヘルプ・プラグインを作成する

ヘルプ・プラグインを作成するためには、

1. File > New > Project を選択して New Project Wizard を起動します。
2. 利用可能なウィザードのリストの中で、Plug-in Development カテゴリーから Plug-in Project を選択し、Next をクリックします。
3. Project name ボックスに MyHelpPlugin と入力し、Next をクリックします。
4. 図 4 に示すウィンドウで Next をクリックします。
   
   図 4. 新しいプラグイン・プロジェクト
   
   
   
5. Available Templates リストから Plug-in with sample help content を選択し、そして Next をクリックします。
6. 次のウィンドウで、Finish をクリックします。ここで Plug-in Development パースペクティブに切り替えるように指示されるかもしれません。もしそのように指示されたら、Yes をクリックするようにお勧めします。このパースペクティブはヘルプの作成に便利なビューを自動的に含むからです。

新しいプロジェクトは html というフォルダーを含み、そしてこのフォルダーの中に、HTML ファイルのサンプルがいくつか含まれています。これらのファイルを、DocBook プロジェクトで生成される HTML ファイルで置き換えます。

進行状況をチェックする

まだ何も変更しない状態で Run > Run As > Eclipse Application を選択して Eclipse のインスタンスを持つプラグインを実行し、この状態でヘルプがどう見えるかを調べます。そのプラグインを使って Eclipse の新しいインスタンスが起動します。Eclipse が起動したら、Help > Help Contents を選択し、プラグインの動作を調べます。もし何も変更していなければ、コンテンツのリストの中に Test TOC が表示されるはずです (図 5)。

DocBook XML プロジェクトの HTML を組み込む

新しいヘルプ・プラグインのデフォルトのコンテンツを見たので、今度は先ほど作成した、DocBook XML プロジェクトの HTML を組み込みます。そのためには新しいヘルプ・プラグイン・プロジェクトから HTML 出力をコピーする必要がありますが、これを毎回手動で行うのは避けたいものです。手動プロセスのままにすると、プラグインのビルドを行う際に間違えたり、実行し忘れたりしやすくなります。

Ant ファイルを追加する

HTML ファイルを自動的にコピーするための最初のステップとして、単純な Ant ファイルを作成します。この Ant ファイルは、DocBook XML プロジェクトからプラグイン・プロジェクトの html フォルダーに HTML ファイルをコピーすることだけを行います。そしてこの Ant ファイルは、Eclipse がプロジェクトをビルドするたびに実行されます。

この Ant ファイルの内容を下記に示します。このファイルは prepare という 1 つのターゲットのみを持っています。これはビルド・ファイルのデフォルト・ターゲットでもあります。このビルド・ファイルは Eclipse にしか呼び出されないので、私はデフォルト・ターゲットを prepare のままとしています。

                
<?xml version="1.0"?>
<project name="MyHelpPlugin" default="prepare">
<description>
Prepares the Help plug-in project by copying the HTML help files
from the DocBook XML project into this one.
</description>

<property name="docbook.project.dir" value="../myProject" />
<property name="html.dir" value="html" />
<property name="html.src.dir" value="${docbook.project.dir}/doc" />

<fileset id="html-files" dir="${html.src.dir}">
<include name="**/*.html" />
<include name="**/*.css" />
</fileset>

<target name="prepare">
<copy todir="${html.dir}">
<fileset refid="html-files" />
</copy>
</target>
</project>

ビルダーを定義する

Eclipse では、Eclipse がプロジェクトをビルドする際に実行するプログラムを定義することができます。こうしたプログラムはビルダーと呼ばれます。ビルダーを変更するためには、プロジェクトの名前をクリックし、そして Project > Properties を選択します。Builders の下に、そのプロジェクトのために既に設定されたビルダー (Java Builder と Plug-in Manifest Builder、そして Extension Point Schema Builder) が表示されています。Eclipse に Ant スクリプトを実行させ、HTML ファイルをプラグイン・プロジェクトにコピーするためには、

1. Builders プロパティー・ページから New をクリックします。
2. リストから Ant Build を選択し、OK をクリックします。
3. 新しいビルダーの名前として、例えば Ant Builder と入力します。
4. Buildfile の下で Browser Workspace をクリックし、ワークスペースの中にある Ant ファイルを見つけます。
5. Targets タブをクリックし、After a "Clean" ターゲットと Manual Build ターゲットが<default target selected> を表示していることを確認します。
6. OK をクリックしてビルダーを保存します。
7. Builders ページで、たった今作成したばかりの新しい Ant ビルダーを選択し、そしてそのビルダーがリストの先頭に来るまで Up をクリックします。これは、他の作業をする前にファイルをプラグイン・プロジェクトにコピーするために必要です。

新しいビルダーを設定したら、Project > Clean あるいは Project > Build を選択し、それぞれプロジェクトを削除、あるいはビルドします。Ant ビルダーが実行され、DocBook XML プロジェクトから自動的に HTML ファイルが引き出されます。

ビルダーの追加は、DocBook XML プロジェクトの場合も同じです。Ant ビルダーを DocBook XML プロジェクトに追加し、任意のターゲットを、プロジェクトを削除する際、あるいはビルドする際に実行するターゲットとして設定します。(こうしたターゲットとして、usageターゲットがデフォルトだったことを思い出してください。)

上に戻る

ヘルプの TOC ファイル

HTML ヘルプ・ファイルの TOC (table of contents) は、プラグイン・プロジェクトに含まれる 2 つの XML ファイルの中にあります。これらのファイルを下記に示します。

                
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Test TOC">
<link toc="toc.xml" />
</toc>

リスト 6 に示す TestTOC.xml ファイルは、ヘルプ・ウィンドウの Contents ペインに表示されるヘッダーの名前を含んでいます。このファイルは toc.xml ファイルにリンクする以外のことは何もしません。

                
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Sample Table of Contents">
<topic label="Main Topic" href="html/book.html"> 
</topic>
</toc>

toc.xml ファイルは、基本トピックの下に表示されるメイン・トピックを含んでいます。これらのメイン・トピックは href 属性によって HTML ページにリンクされています (リスト 7 では太字で示してあります)。

ヘルプは、book のように 1 つのファイルとしてビルドすることができ、そのファイルを 1 つのメイン・トピックのみが指すようにすることができます。しかし、別々の chapter に文書を分割することも考えてみてください。toc.xml ファイルで各 chapter に索引付けし、必要であれば 1 つの book にビルドすることもできるのです。自由に構成できる、物理的に別々なファイルに文書を分割する方法のヒントについては、「モジュール構造の文書を作成する」を参照してください。

上に戻る

DocBook 出力をカスタマイズする

ここまでの段階で、Eclipse プラグインの中でヘルプとして使用可能な通常の HTML に変換される DocBook XML ができました。しかし、変換によって出力される HTML の見た目を整えたい場合には、どうすればよいのでしょう。

幸い、HTML を少しパーソナライズしたり、カスタムのフォーマットにしたりするために独自の XSL スタイルシートを作成する必要はありません。そうしたスタイルシートを作成する代わりに XSLT 変換ステップに変数を渡し、HTML のフォーマットを整えるための CSS (Cascading Style Sheet) を割り当てることができます。

上に戻る

CSS スタイルシートを割り当てる

DocBook XML を HTML に変換するための XSL スタイルシートは、html.stylesheet という名前の変数を調べます。もしこの変数が値を含んでいたら、その値をHTML の link 要素の中で使って、指定するスタイルシートにリンクします。

リスト 8 は、important と caution というクラスを持つ単純な CSS を示しています。この CSS は、これらのクラスのテキストの色を変更します。ページが表示されると、これらのクラスが、それぞれ <important> タグで囲まれたコンテンツと <caution> タグで囲まれたコンテンツに対応することがわかります。

                
body { font-family : arial,sans-serif; font-size : small; }
.important { color : blue; }
.caution { color : red; }

上に戻る

Ant ビルド・ファイルを変更する

リスト 8 に示す CSS を、DocBook XML プロジェクトの lib ディレクトリー内の style.css という名前のファイルに保存します。このファイルを保存したら、Ant ビルド・ファイルを変更する必要があります (CSS ファイルの名前を xslt ターゲットに渡し、そしてCSS ファイルを、lib フォルダーから他の HTML 出力と同じフォルダーにコピーするように変更します)。リスト 9 は、これらの変更を太字で示してあります。

                
<target name="build-html" depends="depends" 
description="Generates HTML files from DocBook XML">
<xslt style="${html.stylesheet}" extension=".html" 
basedir="${source.dir}" destdir="${doc.dir}">
<classpath refid="xalan.classpath" />
<include name="**/*.xml" />
<exclude name="chapter1.xml" />
<param name="html.stylesheet" expression="style.css" />
</xslt>
<!-- Copy the stylesheet to the same directory as the HTML files -->
<copy todir="${doc.dir}">
<fileset dir="lib">
<include name="style.css" />
</fileset>
</copy>
</target>

上記の変更を行ったら、DocBook XML プロジェクトの Ant ビルド・スクリプトを再度実行します。そして出力 HTML ファイルを見ると、フォントが変更されており、「Important」部分と「Caution」部分のフォントの色が新しくなっていることがわかります。

上に戻る

PDF を作成する

ここまでは、イントラネットのサイトで配布可能で、Eclipse のヘルプ・プラグインに含められる HTML を、さまざまなツールを使って DocBook XML から生成する方法を見てきました。しかし私は先ほど、同じ DocBook XML ソース・ファイルを使って PDF も生成できることに触れました。DocBook XML から PDF を生成するためには、もう 1 つのツール、Apache XML Graphics Project の FOP ライブラリー (「参考文献」を参照) を追加する必要があります。

FOP ライブラリーには、DocBook XML プロジェクトの既存の Ant ビルド・ファイルの中に直接置ける Ant タスクが含まれています。この Ant タスク、つまり fop は、DocBook XSL に付属の FO スタイルシートを使ってビルドされる FO ファイルを変換します。

上に戻る

FOP ライブラリーを使って PDF を生成する

FOP ライブラリーを使うためには、このバイナリー・ディストリビューションを含む ZIP ファイル (例えば fop-0.93-bin-jdk1.4.zip など) を Web サイトからダウンロードします。この ZIP ファイルの名前から、このファイルは J2SE (Java 2 Platform, Standard Edition) のJDK (Java Development Kit) V1.4 専用にビルドされたように思えるかもしれませんが、Java V5 でも問題なく動作します。これまでダウンロードした他のアーカイブ・ファイルと同様、このファイルも、まだ解凍する必要はありません。

Eclipse では、File > Import を選択し、そして「アーカイブからファイルをインポートする」で説明した手順と同じ手順を繰り返します。しかし今回、build フォルダーと lib フォルダーのみをインポート用に選択します。

ファイルのインポートが終わったら、Ant ビルド・スクリプトを変更して fop ターゲットを設定し、それを新しい build-pdf ターゲットの中で呼びだします。これを下記に示します。

                
<!--
- target:  build-pdf
- description:  Iterates through a directory and transforms
-     .xml files into .fo files which can then be turned into DocBook XML
-     files.
-->>
<target name="build-pdf" depends="depends" 
description="Generates PDF files from DocBook XML">>
<xslt style="${fo.stylesheet}" extension=".fo" 
basedir="${source.dir}" destdir="${fo.dir}">>
<classpath refid="xalan.classpath" />>
<include name="book.xml" />>
</xslt>>

<property name="fop.home" value="lib/fop-0.93" />>

<taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop">>
<classpath>>
<fileset dir="${fop.home}/lib">>
<include name="*.jar" />>
</fileset>>
<fileset dir="${fop.home}/build">>
<include name="fop.jar" />>
<include name="fop-hyph.jar" />>
</fileset>>
</classpath>>
</taskdef>>

<fop format="application/pdf" fofile="${fo.dir}/book.fo" 
outfile="${dist.dir}/book.pdf" />>
</target>>

このターゲットを設定したら、Eclipse IDE から build-pdf ターゲットを実行します。すると、dist ディレクトリーの中に book.pdf という名前のファイルが表示されます。

まとめ

DocBook XML は、HTML や PDF など、さまざまな出力を生成できる技術文書を作成するための、強力なフォーマットです。このフォーマットを利用することで、スタイリングを別にした上で文書のコンテンツに集中することができます。DocBook XML は成熟しているため、DocBook XML で文書を編集し、作成するためのツールが数多くあります。

Eclipse IDE には、XML 文書を作成し、妥当性検証をするためのエディターが含まれています。また Eclipse には Ant が統合されており、これを利用すると、Eclipse で通常のビルダーとして実行できる強力なビルド・ファイルを作成することができます。また、Eclipse に含まれているテンプレートを使うことで、Eclipse のヘルプに使用できる HTML ファイルを含んだプラグイン・プロジェクトを含め、さまざまなプラグイン・プロジェクトを素早く作成することができます。

これらのツールを組み合わせて使うことによって、1 ヵ所で技術文書を作成し、それをさまざまなフォーマットで広範な種類の読者に配布することができます。

参考文献

学ぶために

• DocBook: The Definitive Guide で DocBook XML について学んでください。
  
  
• Apache Ant manual で Ant タスクについて学んでください。
  
  
• 「Eclipse オススメ情報リスト」を調べてみてください。
  
  
• developerWorks には他にも Eclipse に関する資料が豊富に用意されています。
  
  
• Eclipse が初めての人は、Eclipse project resources の Start Here を見るとよいでしょう。
  
  
• IBM developerWorks の Eclipse project resources を利用して Eclipse のスキルを磨いてください。
  
  
• developerWorks podcasts では、ソフトウェア開発者のための興味深いインタビューや議論を聞くことができます。
  
  
• Eclipse プラットフォームへの入門として、「Eclipse Platform 入門」を読んでください。
  
  
• developerWorks の Technical events and webcasts で最新情報を入手してください。
  
  
• IBM のオープンソース技術や製品機能を調べ、学ぶために、無料の developerWorks On demand demos をご覧ください。
  
  
• IBM オープンソース開発者にとって関心のある、世界中で今後開催される会議や業界展示会、ウェブキャスト、その他のイベントについて調べてみてください。
  
  
• developerWorks の Open source zone">Open source ゾーンをご覧ください。オープンソース技術を使った開発や、IBM 製品でオープンソース技術を使用するためのハウ・ツー情報やツール、プロジェクトの更新情報など、豊富な情報が用意されています。
  
  

製品や技術を入手するために

• Eclipse.org から Eclipse をダウンロードしてください。
  
  
• PDF など、さまざまなフォーマットに FO ファイルを変換する Apache FOP を Apache FOP のサイトからダウンロードしてください。
  
  
• DocBook XML の DTD ファイルをダウンロードしてください。
  
  
• 独自のスタイルシートを作成しなくても変換を行える、DocBook XSL スタイルシートを入手してください。
  
  
• 最新バージョンの Xalan-Java をダウンロードし、これについて読んでください。
  
  
• IBM alphaWorks に用意された最新の Eclipse technology downloads を調べてください。
  
  
• IBM 製品の試用版をダウンロードし、DB2® や Lotus®、Rational®、Tivoli®、WebSphere® などのアプリケーション開発ツールやミドルウェア製品を実際に試してみてください。
  
  
• 皆さんの次期オープンソース開発プロジェクトを IBM trial software を使って革新してください。ダウンロード、あるいは DVD で入手することができます。
  
  

議論するために

• Eclipse に関する質問を議論するための最初の場所として、Eclipse Platform newsgroups があります (このリンクをクリックすると、デフォルトの Usenet ニュース・リーダー・アプリケーションが起動し、eclipse.platform が開きます)。
  
  
• Eclipse newsgroups には、Eclipse を利用し、拡張することに関心を持つ人達のために、さまざまなリソースが用意されています。
  
  
• developerWorks blogs からdeveloperWorks コミュニティーに加わってください。
  
  

著者について

この記事を評価する

コメント

上に戻る

目次

• はじめに
• DocBook XML の概要
• 上位レベルの要素
• コンテンツのための要素
• 環境を設定する
• Eclipse プロジェクトを作成する
• アーカイブからファイルをインポートする
• Ant スクリプトを作成する
• Ant で Xalan を使う
• build.xml ファイルを作成する
• build-html ターゲットを実行する
• DocBook XML ファイルを作成する
• 最初の DocBook XML ファイルを作成する
• XML エディターで chapter1.xml を処理する
• モジュール構造の文書を作成する
• DocBook XML ファイルを分割する
• ヘルプ・プラグインを作成する
• 実際にヘルプ・プラグインを作成する
• DocBook XML プロジェクトの HTML を組み込む
• ヘルプの TOC ファイル
• DocBook 出力をカスタマイズする
• CSS スタイルシートを割り当てる
• Ant ビルド・ファイルを変更する
• PDF を作成する
• FOP ライブラリーを使って PDF を生成する
• まとめ
• 参考文献
• 著者について
• コメント