はじめに
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の概要と、このツールを使用して次の作業を行う方法を説明します。
- シンプルなドキュメントを記述する。
- Velocity DocBook Frameworkを使用して、そのドキュメントをPDFおよびHTMLに変換する。
- ソースコードの抜粋を自動的にドキュメントに差し込む。
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を認識および検証するために必要です。
