DocBookで作るHtmlHelpサンプル

DocBook形式で日本語の文書を作る実験をしました。 DocBook XMLの語彙に従い原稿を書き、DocBook XSLスタイルシートとApacheの変換ツールを使って、同じ原稿から、HTML、PDFはもちろん、HtmlHelpのヘルプも作成できました。

HtmlHelpについては、そのままでは日本語の表示や検索ができなかったのですが、プロジェクトソースに修正を加えることで対処できました。この問題は韓国語や中国語などCJK圏で共通に見られるものと思います。従って解決法も同じと思います。

はじめに

主に技術文書を書くために設計されたXML形式のひとつ、DocBookを用いて、HTML、PDF、Windows Help（HtmlHelp）の日本語の文書を作成してみました。

使用したツールは次のとおりです。

テストはWindows XPで行いました。

以下では、それぞれの出力形式ごとに、おおまかな作成手順、原稿および生成されたファイル群、使用ツールを示し、最後に、HtmlHelpソースに加えた加工について触れます。

DocBookの原稿

サンプルのZIPファイルを解凍すると、次のフォルダがあります。

	src/
		sample.xml ← クリックしてブラウザでそのまま表示
		toolchain.gif

DocBookの原稿はsample.xmlです。GIFの図をひとつ使います。

DocBookの設計理念は単一のソースから様々な出力を作り出すことです。このサンプルでも一個の原稿から別々の形式の文書を得ます。

なお、DocBookのXML原稿は、XSLTやXSL-FOプロセッサで変換しなくとも、ざっとの確認であれば、DocBook用CSSを使ってWebブラウザでプレビューできます。

DocBook用CSS（WYSIWYGdocbook）でプレビュー → sample.xml

DocBook → HTML

DocBookからHTMLのファイルを生成するにはDocBook XSLとXSLTプロセッサを使用します。 DocBook XSLは二種類の構成のHTMLファイルを作成できます。単一ファイルと複数ファイル（chunk）です。

	html/
		single.html ← クリックして表示
		run.bat
	chunk/
		index.html ← クリックして表示
		ch*.html
		ix01.html
		run.bat

htmlフォルダには、すべてを一個のHTMLファイルに収めたsingle.htmlがあります。

chunkフォルダには、章や節ごとに個別のHTMLファイルに収めた、複数のHTMLファイルがあります。 index.htmlが目次、chではじまるHTMLファイルが各章や節の本文、ix01.htmlが索引です。

両方のフォルダにあるrun.batは、srcフォルダから原稿ファイルをカレントフォルダにコピーして、変換ツールを実行して、最終出力を生成するためのDOSバッチファイルです。

DocBook XSL

html/docbook.xsl - 単一ファイル出力用
html/chunk.xsl - 複数ファイル出力用（chunked）

Xalan XSLTプロセッサ

DocBook → PDF

HTML出力はいっきに、DocBookの原稿とDocBook XSLをXSLTプロセッサに渡して生成できました。原理的にはPDFの作成には二段階の変換処理が必要です。

DocBook XSLとXSLTプロセッサでDocBook原稿をFOに変換
FOをXSL-FOプロセッサでPDFに変換

とはいえ、Apache FOP XSL-FOプロセッサはApache Xalan XSLTプロセッサを含んでおり、この二段階の処理を一度にやってくれます。

サンプルフォルダの内容です。

	pdf/
		mydocbook.xsl
		sample.pdf ← クリックして表示
		sample.fo
		run.bat

sample.pdfが最終出力のPDFファイルです。 sample.foは中間出力のFOファイルです。Apache FOPをふつうに実行すればできないファイルですが、-fooutオプションを付けて生成しました。 mydocbook.xslは、DocBook XSLにパラメタを渡すためのXSLファイルです。

run.batはsrcフォルダから原稿ファイルコピーして、変換ツールを実行するバッチファイルです。 run.batで実行されるツールは以下のとおりです。

DocBook XSL (fo/docbook.xsl)
Xalan XSLTプロセッサ（Apache FOPに同梱のものを使用）
FOP XSL-FOプロセッサ

DocBook → HtmlHelp

Windows Help（HtmlHelp）もPDFと同様、二段階の処理手順を経ます。まずDocBook XSLで複数ファイルのHTMLファイルを作成します（HTMLのチャンク方式と同じ）。このとき、HtmlHelp Workshop（ヘルプコンパイラ）への入力となるプロジェクトファイルも生成されます。第二段階で、生成されたプロジェクトソースとHTMLファイルをコンパイルして、一個のバイナリのヘルプファイルができあがります。

	htmlhelp/
		sample.chm
		index.html
		ch*.html
		htmlhelp.hhp
		toc.hhc
		index.hhk
		mydbk2hh.xsl
		run.bat
		textcook-docbook-htmlhelp-fixer.jar ← 後述

sample.chmが最終出力のHtmlHelpファイルです。 index.htmlが最初に表示されるページ、chではじまるHTMLファイルが各章や節の本文です。 htmlhelp.hhp、toc.hhc、index.hhkが、HtmlHelp Workshopへ渡すプロジェクトソースで、それぞれプロジェクトファイル、目次ファイル、索引（キーワード）ファイルです。 mydbk2hh.xslは、DocBook XSLにパラメタを渡すためのXSLファイルです。

run.batで実行されるツールは以下のとおりです。

DocBook XSL (htmlhelp/htmlhelp.xsl)
Xalan XSLTプロセッサ
HtmlHelp Workshop

しかし、このようにして作成したHtmlHelpはこのままでは日本語のオンラインヘルプとしては使えません。

Bad HtmlHelp

DocBook XSLが出力したHtmlHelpソースの修正

上記の方法で作成したHtmlHelpファイルの問題は次のとおりです。

<book lang="ja">でHtmlHelpプロジェクトの言語を指定したにもかかわらず、プロジェクトファイル内の日本語の文字コードがWindows-932（Shift_JIS）で出力されない。つまり、左ペインに表示される目次や索引、ウィンドウのタイトルが文字化けする。
DocBook XSLのパラメタのhtml.encodingでHTMLファイルの文字セットをShift_JISに指定したにもかかわらず、文字セットはISO-8859-1になり、日本語の文字コードが文字エンティティ形式のUnicodeで出力される（&#nnnnn;）。HtmlHelpの右ペインはIEエンジンが表示を担当する。文字は正しく表示されるが、左ペインで検索したときにヒットしない。

この問題は、DocBook XMLやXSLTプロセッサの改版が進めばいずれ解決されると予想しますが、一時的な対処法として、DocBook XSLが出力したソースファイルの文字セット指定や文字コードを、HtmlHelp Workshopが前提とするプラットフォーム文字セット（日本語の場合はShift_JIS）に変換することで解決しました。

Bad HtmlHelp

このために、TextCookerという、横浜工文社で文字セット変換や一括検索置換で使用している社内ツールを使用しました。

サンプルのフォルダには、DocBook XSLが出力したHtmlHelpソースの修正が行えるTextCookerの限定版（textcook-docbook-htmlhelp-fixer.jar）を収めてあります。このプログラムを動かすにはJava 1.4以上をインストールしてください。

同様の問題は韓国語や中国語でも起こるのではないかと予想します。また、上記と同じ方法で解決できると予想します。中国語や韓国語でお試しになった方は結果をお知らせいただければさいわいです。

補足

今回の実験ではXalan 2.7.1を使用しました。FOPに同梱のXalanを使うこともできますが、両者はバージョンが異なります。FOP 0.95に含まれるXalan 2.7.0では、プロジェクトソースに文字エンティティ（&#nnnnn;）すら出力されず、上記の方法で解決することができませんでした。
TextCookerは自動的に変換するファイルのバックアップを取ります。ファイル名の最後に「~」がついたファイルが変換前のファイルです。

環境設定

もしこのサンプルをソースから生成しなおしたいとご希望なら、XSLTプロセッサ、XSL-FOプロセッサ、DocBook XSLを設定して、各フォルダのバッチファイル（run.bat）をそれぞれ、ご自分の環境に合わせて変更してから実行する必要があります。

ご参考まで筆者が使用した環境を示します。

set XSL=c:\docbook-xsl-1.75.2
set XLN=c:\xalan-2.7.1
set FOP=c:\fop-0.95

set XLNEXT=%XSL%\xalan-extension-1.00 <- DocBook XSL extension for Xalan
set FOPFNT=%fonts%\fonts <- contains font metrics files for Windows fonts

参考

このサイトのほかの文書サンプルです。

横浜工文社の関連ビジネスです。

このDocbookサンプルに関すること、広くテキスト・XMLベースの文書作成、電子出版など、お問い合わせ、コメント、お困りの点のご相談など、歓迎いたします。

Contact

DocBookで作るWindows Helpサンプル

まとめ