DocBookによるドキュメント作成

はじめに

　DocBookはテクニカルドキュメントをXMLで作成するためのOASIS標準で、SpringやHibernateのドキュメントはDocBookで生成されています。DocBookは特にコンピュータ関連のコンテンツに適しており、テクニカルコンテンツ用のDTD（Document Type Definition）とXMLスキーマによって定義された一連のXMLタグで構成されています。DocBookおよびその他のオープンソースプロジェクトには、DTDの他にも、DocBook対応のXMLをPDF、HTML、Eclipse Help、およびMANページに変換できるようにするツールとフレームワークのコレクションが用意されています。これにより、同じマテリアルを何度も記述したり、手動で形式を変換したりする手間を多少緩和することができます。

　「そんな大騒ぎするほどのことでもないね。必要ならHTMLでもEclipse HelpでもPDFでも作成できるし、DocBookのどこが特別なのかわからないよ」と言う人もいるでしょう。DocBookモデルでは、素材となる生コンテンツをXMLで一度記述しておけば、それをDocBookツールでさまざまな形式に変換、つまり「コンパイル」できます。これは、コーディングとコンパイル、という作業を日頃から行っている開発者にとってはお馴染みのパラダイムです。つまり、ドキュメントを記述しなければならない開発者にとって、DocBookは理想的なツールです。テクニカルコンテンツを対象としているだけでなく、DocBookファイルは他のXMLファイルと同様にIDE内で管理および編集できるからです。「ドキュメンテーションはまた別の仕事」という時代は終わりました。DocBookモデルならば、ソースコードのすぐ隣でドキュメントを書くことも可能です。これにより、開発とソフトウェアドキュメントの作成を並行して進めることも容易になります。

　DocBook XML構造では、表現ではなく構造やコンテンツに焦点を当てているため、書式設定や表示方法を気にかける必要はありません。書式や表示の詳細については、XML変換ツールやスタイルシートが処理します。生成されるドキュメントの外観はXML変換ツールによって統一され、生コンテンツから切り離してカスタマイズできます。

　この記事ではDocBookの概要と、このツールを使用して次の作業を行う方法を説明します。

1. シンプルなドキュメントを記述する。
2. Velocity DocBook Frameworkを使用して、そのドキュメントをPDFおよびHTMLに変換する。
3. ソースコードの抜粋を自動的にドキュメントに差し込む。

DocBookの概要

　DocBook対応のXMLファイルを記述するには、特別なドキュメンテーションツールは必要ありません。DocBook DTDにアクセスしてDocBookタグを認識しXMLを検証できるものであれば、どんなXMLエディタまたはIDEプラグインでも使用できます。無料のWYSIWYG Eclipseプラグインやスタンドアロンエディタもありますが、WTPまたはMyEclipseに付属している標準XMLエディタまたはIDEプラグインで十分に事足ります。

　DocBook XMLファイルを作成して開発環境に配置すれば、そのドキュメントを開発プロセスにシームレスに統合できます。DocBook XMLファイルでは次のことができます。

• バージョン管理（チェックイン、チェックアウト、タグ付け、リリースごとの分岐）
• 開発環境内での編集（標準IDEやXMLエディタプラグインで編集可能）
• コードとの同期、およびコードリファクタリングへの対応（クラス名が変更された場合は、ドキュメント内の参照も同じように変更される）
• ビルドプロセスへの統合（PDFやHTMLなどの配布ドキュメントの自動ビルド）

　DocBookには、多数のタグ（<book>、<chapter>、<title>など）とプログラミング用の要素（<classname>、<programlisting>、<database>など）が用意されています。しかし、最初からすべてを覚える必要はなく、基本的な要素さえ押さえていれば十分です。シンプルなDocBook XMLファイルは1つの<Book>要素から成り、その中に1つ以上の<chapter>要素が含まれています。ブックは配布可能な単一ドキュメントで、最終的なドキュメント内の論理セクションに対応するいくつかのチャプタが含まれます。チャプタは階層構造になっており、1つのチャプタに他のチャプタを挿入できます。また、階層の深さに制限はありません。

　この記事でサンプルとして使用する単純なDocBook XMLドキュメントを次に示します。このドキュメントには、<title>タグ、<bookinfo>タグ、<toc>タグ、および2つの<chapter>タグがあり、それぞれのタグにテキストが含まれています。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book >
  <title>DocBook Framework Overview</title>

  <bookinfo>
    <releaseinfo>V 1.0</releaseinfo>
    <author>devx
    </author>

  </bookinfo>

  <toc/>
  
  <chapter id="intro">
    <title>Introduction</title>
    <para>DocBook is simple to use and provides a rich set of 
          tags for common elements.</para>  
  </chapter>
  
  <chapter id="basics">
    <title>Basic Elements</title>
    <para>This section describes the basic tags.</para>
  </chapter>
  
</book>

　冒頭のDTD参照に注目してください。この参照は、XMLエディタがDocBook構造でXMLを認識および検証するために必要です。

HTMLおよびPDFへの変換

　Apache Velocityは、DocBook XMLファイルをHTMLおよびPDFに変換するためのフレームワークです。この変換処理でVelocityが使用するのは、一連のANTビルドファイルです。この記事の手順を実際に試してみたい場合は、まずVelocity DocBookフレームワークをダウンロードし、インストールしてください。そして、EclipseなどのIDEで新しいプロジェクトを作成し、Velocityフレームワークをインポートします。Xercesライブラリも必要です。このライブラリはxerces.apache.orgからダウンロードして、サードパーティのjarと一緒に新しいプロジェクトのlibフォルダにコピーします。ここまでの作業が完了すると、プロジェクトの「docs/src/docbook/dbf」フォルダには、Velocityツールと、DocBookで記述されたVelocityドキュメントが格納されているはずです。それでは、実際に独自のサンプルドキュメントを作成してみましょう。まずは、このフォルダに前掲の単純なDocBook XMLドキュメントを「simple.xml」として作成します。

　「simple.xml」をPDFまたはHTMLに変換するには、Velocityビルドスクリプトを編集して新しいファイルを選択する必要があります。プロジェクト構造とANTスクリプトに手を加えればプロジェクトへの適合性やビルドプロセスとの統合性を高めることができますが、今回はデモンストレーションなので、単純にANTファイル「build.xml」を開き、<property name="docbook.file" value="DBFUserGuide"/>というエントリを<property name="docbook.file" value="simple"/>に書き換えます。これにより、新しいサンプルファイルが確実に参照されます。

　EclipseでPDFおよびHTMLを生成するには、「build.xml」ファイルを右クリックして、［Run As］、［ANT Build］を順に選択するだけです。ビルドが完了したら、「doc/target/dbf/singlehtml」フォルダにHTMLが出力され、「doc/target/dbf/pdf」にPDFが出力されていることを確認します。

　生成されたドキュメントを図1（HTML）と図2（PDF）に示します。

図1　Simple.xmlから生成されたHTML

図2　Simple.xmlから生成されたPDF

DocBookの語彙

　DocBookでは、基本リスト、表、リンク、画像などのコンテンツを表すタグが多数用意されているだけでなく、より具体的なプログラミング用のタグも用意されています。たとえば項目リストを作成するには、<orderedlist>タグまたは<itemizedlist>タグと、子要素を示す<listitem>タグを使用します。コード例を以下に示します。

...
<chapter id="list">
  <title>Lists</title>
  <para>You can use:</para>
    <itemizedlist mark="opencircle">
      <listitem>
        <para> itemizedlist; or </para>
      </listitem>

      <listitem>
        <para> orderedlist </para>
      </listitem>

    </itemizedlist>
</chapter>

　<mediaobject>タグおよび<ulink>タグを使用すれば、画像とリンクを組み込むことができます。たとえば次のコードを使用すると、画像「logo.png」を挿入できます。

<mediaobject>
  <imageobject>
    <imagedata fileref="images/logo.png"/>
  </imageobject>
</mediaobject>

　また、次のコードではDocBook Webサイトへのリンクを追加できます。

<ulink url="http://www.docbook.org">docBook</ulink>

　ソースコードを挿入するには、<programlisting>要素を使用します。

<programlisting><![CDATA[
  protected void test() {
    System.out.println("This is a sample extract");
  }
...]]>
</programlisting>

　試しにタグをいくつか「simple.xml」ファイルに追加し、ANTビルドを実行して、そのタグがどのようにレンダリングされるかを見てみましょう。

ブックの分割

　サイズが大きなドキュメントは、1つのXMLファイルにまとめると管理が難しくなります。特に、複数の人が編集する場合はすぐに管理不能な状態に陥ってしまいます。この問題を克服する手段として、ドキュメントをチャプタ、または論理的に関連するチャプタグループごとに分割し、複数の小さなファイルを作成するという方法があります。この方法を採用すると、ドキュメントの各部を複数の人がお互いに影響を及ぼすことなく編集できます。また、もし間違いがあっても、DocBookでエラーが発生するのですぐに分かります。

　また、共通のチャプタを抜き出して独立したファイルにまとめ、別のブックで再利用することもできます。これはたとえば、トレーニングマニュアルとインストールガイドの冒頭に、標準的な製品著作権情報のセクションを含めたい場合に役立ちます。それぞれのドキュメントは別個のブックですが、共通のコンテンツを含めることができます。<xi:include>を使用すれば、DocBookファイルを他のDocBookファイルに挿入できます。たとえば、サンプルドキュメントの構造を1つのブックファイルと2つのチャプタファイルという構成にする場合は、メインファイルである「simple.xml」を次のように変更します。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book >
  <title>DocBook Framework Overview</title>

  <bookinfo>
    <releaseinfo>V 1.0</releaseinfo>
    <author>devx
    </author>

  </bookinfo>

  <toc/>
  
  <xi:include href="intro.xml" 
      xmlns:xi="http://www.w3.org/2003/XInclude" />
  <xi:include href="basics.xml" 
      xmlns:xi="http://www.w3.org/2003/XInclude" />
</book>

　さらに、各チャプタ要素を別々のファイルに分解します。「intro.xml」は次のようになり、

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="intro">
    <title>Introduction</title>
    <para>DocBook is simple to use and provides a rich set of tags 
          for common elements.</para>  
</chapter>

　「basics.xml」は次のようになります。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="basics">
    <title>Basic Elements</title>
    <para>This section describes the basic tags.</para>
</chapter>

　各チャプタをそれぞれ独立したファイル内に配置していることに注意してください。ファイルをXMLエディタまたはプラグインで編集したい場合は、正しいDTD参照を指定する必要もあります。Velocityフレームワークで1つのブックが複数のファイルを処理できるようにするには、<xi:include>要素が正しく解決されるようにSaxon（Velocityが使用する基幹XSLTエンジン）を設定します。具体的には、「build-docbook.xml」ファイルを編集し、SaxonエントリにXercesを登録します。

<java classname="com.icl.saxon.StyleSheet" fork="true"
  dir="${basedir}" classpathref="dbf.classpath">
    <jvmarg value="-Djavax.xml.parsers.DocumentBuilderFactory=
            org.apache.xerces.jaxp.DocumentBuilderFactoryImpl" />
    <jvmarg value="-Djavax.xml.parsers.SAXParserFactory=
            org.apache.xerces.jaxp.SAXParserFactoryImpl" />
    <jvmarg 
        value="-Dorg.apache.xerces.xni.parser.XMLParserConfiguration=
            org.apache.xerces.parsers.XIncludeParserConfiguration" />
  <arg line="-x org.apache.xml.resolver.tools.ResolvingXMLReader"/>
  <arg line="-y org.apache.xml.resolver.tools.ResolvingXMLReader"/>
  <arg line="-r org.apache.xml.resolver.tools.CatalogResolver"/>
  <arg value="-o"/>
  <arg value="@{output}"/>
  <arg value="@{input}"/>
  <arg value="@{style}"/>
</java>

<xi:include>によるソースコードの組み込み

　<xi:include>は、ブックの構造化だけでなく、ソースコードの挿入にも利用できます。テクニカルドキュメントを作成する上でよく問題になるのは、コードとの同期をいかに維持するかという点です（特にアジャイル環境では難しい問題です）。ドキュメント内のサンプルのソースコードはすぐに古くなります。手動のコピー＆ペースト操作で挿入されたソースコードはエラーが発生しやすく、テストも困難です。また、誰かが常にコードサンプルのメンテナンスをしていなければあっという間に使えなくなってしまいます。しかし、DocBookを使えば状況は変わってきます。

　DocBookでは、ドキュメントに掲載するコードをユニットテストに配置できます。このコードはユニットテスト内で自動的にテストできるほか、通常のリファクタリングも行うことができ、DocBookに含める部分をマークアップできます。単純な抽出プログラムさえあれば、このコードベース内からマークアップされたコードを検索し、その部分のコードをDocBook XMLファイルに抽出することができます。そして、これらのファイルは他のDocBookファイルと同様、<xi:include>を使用して挿入できます。

　<xi:include>の動作を確認するために、「SampleClass.java」というサンプルのJavaクラスを作成します。//@extract-start <extractname>および//@extract-end <extractname>というJavaコメントを使用して、test()メソッドをマークします。//@extract-start <extractname>は抽出箇所の始まりを、//@extract-end <extractname>は終わりをマークします。

public class SampleClass {

    //@extract-start test
    protected void test() {
        System.out.println("This is a sample extract");
    }
    //@extract-end test
}

　このマークアップは、この記事のダウンロードサンプルに含まれているような抽出プログラムで処理できます。この例では、test()内のコードがDocBook XMLファイル「test.xml」に抽出されます。抽出先ファイルの名前は、マークアップタグによって指定されます。

　「test.xml」を開いてみると、マークアップされたJavaコードを含む<programlisting>要素が追加されていることがわかります。

<?xml version="1.0" encoding="UTF-8"?>
<para>
<programlisting><![CDATA[
    protected void test() {
        System.out.println("This is a sample extract");
    }
...]]>
</programlisting>
</para>

　<programlisting>要素をチャプタに追加するには、次のようにします。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="programlisting">
    <title>including source code</title>
    <xi:include href="test.xml" 
     xmlns:xi="http://www.w3.org/2003/XInclude" />
</chapter>

　このアプローチのメリットは、コードをソースファイル内で一括管理でき、なおかつビルドの一部としてユニットテストを実施できるという点です。ユニットテストにパスすれば、ドキュメント内のコードが正しいことが保証されます。DocBook ANTビルドスクリプトと組み合わせれば、ANTタスクを利用して抽出処理を統合でき、ドキュメントが確実に生成され、最新のコードを含んでいることが保証されます。

まとめ

　DocBookは、開発者向けのテクニカルドキュメント作成にうってつけのツールです。DocBookを使用すれば、コードを扱うのと同じようにドキュメント作成にも力を入れることができます。また、このDocBookは、SpringやHibernateなどの有名なオープンソースプロジェクトでドキュメント生成に使用されています。ただし、他のテクノロジと同様にマイナス面もあります。たとえば、XMLタグおよびDocBookタグの使用方法や、レンダリングツールおよびスタイルシートをビルドプロセスに統合する方法を学習するために先行投資が必要です。同じくXMLベースであるDITAなど、他の仕様の方が使いやすいと思うならば、それを代わりに使用してもかまいません。

　もちろん、DocBookは、出来の悪いドキュメントの質を良くするものではありません。しかし、このDocBookを開発環境に組み込み、Webで公開されている多数のDocBookリソースを利用すれば、ドキュメントとコードを同時に改訂でき、たとえアジャイル環境であっても、ドキュメントとコードを同期させることができます。そして最終的には、目的に応じた適切な配布形式で、整然としたドキュメントを生成できます。