JBoss ManualにならってJBoss FANの文書をDocBook形式のXMLで書くことにしました。XMLで書いておけば、機械的にHTMLやXHTMLに変換したり、目次や索引を自動作成することができます。フリーのDocBookツールはいくつかありますが、Norman Walsh氏のDocBook XSLTスタイルシートを使うことにします。これとXalanのようなJava上で動作するXSLTプロセッサを組み合わせればJava版のDocBookツールができあがります。XSLTを使う理由はそのカスタマイズの容易さです。たとえば、各文書のフッタにコピーライトを入れるようなことをXSLTのテンプレートを書くことで実現できます。この文書では、DocBookの導入方法とDocbookで日本語文書を書くポイントをまとめてみます。
DocBook XSLスタイルシートは、古いバージョンではlinkやxrefが動作しないので、最新版の1.48を使います。XSLTプロセッサとしてはapacheプロジェクトのXalanを使います。XalanのリリースパッケージにはXercesが含まれているので、UTF以外にもXMLのencodingとしてShift_JISやEUC-JPなどを使うことができます。
表 1. 必要なツール一式
| ツール名 | URL | 説明 |
|---|---|---|
| docbook-xsl 1.48 | http://sourceforge.net/project/showfiles.php?group_id=21935 | DocBook用のXSLスタイルシート |
| xalan-j_2_2_D14 | http://xml.apache.org/xalan-j/index.html | XSLTプロセッサ |
DocBook DTDを満たすXML文書を書きます。次の例は2つのchapterから構成されるbookを表します。
<?xml version="1.0" encoding="UTF-8"?>
<book>
<bookinfo>
<title>EJBのコツ</title>
<pubdate>最終更新日: 2001年 12月 13日</pubdate>
<copyright>
<year>2001</year>
<holder>MINAMOTO Fusayuki</holder>
</copyright>
</bookinfo>
<chapter id="cmp">
<title>CMPとは何か</title>
<section>
<title>CMPだと簡単</title>
<para>
本当ですか?
</para>
</section>
<section>
<title>CMPを使えばSQLいらず</title>
<para>
そんなことはない。
</para>
</section>
</chapter>
<chapter id="bmp">
<title>BMPならどうだ</title>
<section>
<title>BMPだとチューニングができる</title>
<para>
でも面倒では？
</para>
</section>
</chapter>
</book>
DocBookがサポートするタグの種類は多いですが、通常よく使うものは限られています。DocBook DTDについてはDocBook XSL Stylesheet Documentationをご覧ください。
DocBook文書に対してXSLTで書いたスタイルシートを適用してHTML文書を生成することにします。DocBook XSLでは、HTML生成用にhtml/docbook.xslという汎用のスタイルシートが用意されています。私たちユーザは自前のXSLTスタイルシートにこれをimportして、カスタマイズするためのパラメタを上書きすればよいのです。次の例では、html/docbook.xslをimportしたのちに、CSSファイル名を指定しています。
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'> <xsl:import href="../../html/docbook.xsl"/> <xsl:param name="html.stylesheet">article.css</xsl:param> </xsl:stylesheet>
DocBook XMLファイルのエンコーディングを指定します。 encoding属性をEUC-JPにします。
<?xml version="1.0" encoding="UTF-8"?>
DocBook XSLは地域化(localization)の対応がなされています。たとえば、日本語の対応をするには、XML文章のルートの要素で次のようにlang="ja"を指定すると、Chapter 1は「第1章」のように出力されます。
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> <book lang="ja"> ... </book>
DocBook XSLTスタイルシートを修正します。 初期状態では、HTMLのスタイルシートhtml/docbook.xslでは出力エンコーディングにISO-8859-1を指定していますので、これをEUC-JPに修正します。
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version='1.0'>
<xsl:import href="../../html/docbook.xsl"/>
<xsl:output method="html"
encoding="EUC-JP"
indent="no"/>
</xsl:stylesheet>
HTML文書の生成はXSLTプロセッサであるXalanがおこないます。次の設定ではorg.apache.xalan.xslt.Processの引数として、XMLファイル名、XSLTスタイルシート名、結果のHTMLファイル名を渡しています。
XALAN_HOME=/home/minamoto/xalan-j_2_2_D14 CLASSPATH=$XALAN_HOME/bin/xerces.jar:$XALAN_HOME/bin/xalan.jar:$XALAN_HOME/bin/xalansamples.jar:$CLASSPATH java -cp $CLASSPATH org.apache.xalan.xslt.Process -in docbook-intro.xml -xsl article.xsl -out docbook-intro.html