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

オープンソースプロジェクトでも使われるドキュメントツール

ブックの分割

　サイズが大きなドキュメントは、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リソースを利用すれば、ドキュメントとコードを同時に改訂でき、たとえアジャイル環境であっても、ドキュメントとコードを同期させることができます。そして最終的には、目的に応じた適切な配布形式で、整然としたドキュメントを生成できます。