ヒント

DITA Open Toolkit による容易なコマンドライン処理

DITA 文書を多様な出力フォーマットに変換する際に Ant を知っている必要はありません

Comments

コンテンツシリーズ

このコンテンツは全#シリーズのパート#です: ヒント

このシリーズの続きに乞うご期待。

このコンテンツはシリーズの一部分です:ヒント

このシリーズの続きに乞うご期待。

はじめに

DITA (Document Information Typing Architecture) は、トピック指向のオーサリングのための一連の XML 文書型です。DITA には、これらの文書型の特別なバージョンを作成するための一連の機構も含まれているため、DITA の DTD やスキーマをカスタマイズし、特定コンテンツの構造により適したものにすることができます。多くの標準の場合と同じく、DITA の魅力の 1 つは、DITA に準拠することによって、DITA 標準に合わせて作成された商用のソフトウェアやフリーのソフトウェアを利用できるようになることです。

フリーの DITA ソフトウェアとして最も一般的なものは、DITA ファイルを処理するための Java ベースの環境である DITA Open Toolkit (または「DITA OT」) です。このツールキットをインストールすると、DITA XML 文書から (あるいは、もっと便利なことに、ユーザー自身がカスタマイズした特別な DITA スキーマに準拠する文書から)、HTML や PDF、RTF、troff、Eclipse Help、その他いくつかのフォーマットのバージョンを、このツールキットを使って作成することができます。

私は、初めて DITA Open Toolkit をインストールした際、「Verifying the installation (インストールを検証する)」(「参考文献」を参照) の中にあったインストール手順に従ってビルド・デモを実行しました。このツールキットがサンプルのソース DITA ファイルから作成可能な出力フォーマットの一覧を見て、私は感激しました。しかし次に、私は正直言って少し戸惑いました。このビルド・デモは Ant スクリプトによって実行されたのですが、このスクリプトは 800 行を超える長さがあり、しかもそのスクリプトは別の Ant ビルド・ファイルを含み、そのファイルがさらに十数個のファイルを含んでいたのです。私の Ant のスキルは非常に初歩的なレベルなので、どの部分を取り出して別ファイルにすれば簡単な変換が行えるのか、ほとんど見当がつきませんでした (私は独自の DITA 文書の 1 つを XHTML または PDF に変換したかったのです)。

そして私は最終的に、特定の DITA 文書を (DITA OT がサポートする) 任意の出力フォーマットに変換するよう DITA OT に指示するための方法を見つけました。この方法はコマンド・プロンプトのたった 1 行ですみ、Ant スクリプトを見る必要すらありません。

DITA Open Toolkit は何を自動化するのか

Xalan や Saxon などの XSLT プロセッサーに対して「DITA 文書 mydoc.xml に対して DITA OT のスタイルシート whatever.xsl を実行しなさい」と命令しても、必ずしもその命令が動作するとは限りません。DITA OT のさまざまな部分すべてを協調させ、適切に動作させるためには、いくつかの環境変数を設定し、その他の関係を特定する必要があります。これは、特殊化を使用する場合には特に重要です。例えば、レシピという文書タイプの中の ingredients (材料) 要素が DITA の prereq 要素を特殊化したものであるとします。そのレシピの HTML バージョンを作るように DITA OT に命令する場合、ingredients 要素に対して行った特殊化の処理を DITA OT が見つけられなければ、DITA OT は必要な参照を行い、ingredients 要素に対して prereq 処理を使うかどうかを判断しなければなりません。

こうしたことのためのセットアップが、ビルド・デモ用の Ant スクリプトが自動的に行っていることの大部分です。つまり、必要な出力フォーマットにファイルを変換するためには DITA OT の動作を自動化するための Ant スクリプトが必要なのです。Ant のスキルを向上させるための時間をしばらく取れない Ant 初心者にとって幸いなことに、Ant ビルド・ファイルの作成も自動化することができます。DITA OT の dost.jar ファイルに対して、どのソース DITA ファイルを変換するのか、そしてどの出力フォーマットが必要なのかを指定すると、あとは dost.jar ファイルが行ってくれるのです。

dost.jar ファイルを使う

適切な動作をする大部分の jar ファイルの場合と同様、-jar というスイッチと、jar ファイルの名前を指定し、他のパラメーターは指定せずに Java 環境を起動すると、dost.jar に付けられるパラメーターのリストが表示されます。パラメーターは約 30 あり、そのうちの 2 つのみが必要とのことですが、私は 1 つだけ、つまり入力ファイルの名前のみでよいことに気付きました。以下のコマンド行を DITA OT のホーム・ディレクトリーから実行すると、DITA OT は XHTML バージョンの currywurst.xml をデフォルトの out サブディレクトリーに置きます。

java -jar lib/dost.jar /i:C:/temp/currywurst.xml

ドキュメンテーションによると /i 入力ファイル・パラメーターと /transtype 変換型パラメーターの両方が必要ということなので、後者のデフォルト値が必ず XHTML とは思えません。

このパラメーターに以下のような別の引数を与えると、本当に楽しいことが始まります。

java -jar lib/dost.jar /i:C:/temp/currywurst.xml /transtype:pdf

これによって、DITA 入力ファイルから XSL-FO ファイルが作成されます。もし DITA Open Toolkit のインストール資料の説明どおりに Apache FOP がインストールされており、適切な変数が適切に設定されていれば、上記から、つまりこの 1 行の比較的短いコマンド行から、PDF ファイルが作成されるのです。

コマンドのオプションの一つひとつについて、ドキュメンテーションに説明されていることを繰り返すつもりはありませんが、さまざまなオプションを完全に理解するために非常に重要なことを説明しておきます。DITA Open Toolkit のドキュメンテーションのどこを見ても、DITA OT のコマンドライン・オプションのすべてを完全に説明したページはありませんが、2 つのページを組み合わせると、それが説明されているのです。「Processing from the Java command line (Java コマンドラインからの処理)」(「参考文献」を参照) は、/i/transtypeなどのコマンドライン・パラメーターやそれらに相当する Ant スクリプト・パラメーターを掲載しており、また「Ant processing parameters (Ant 処理パラメーター)」(「参考文献」を参照) は、スクリプト・パラメーターが何を行うか、そしてそれらのパラメーターのデフォルト値を詳細に説明しています。

そうした説明を見ても、使用可能な /transtype の値の完全なリストは得られません。しかし /transtype の引数として不適切な値を与えると、dost.jar は以下のように使用可能な値のリストを返すのです。

パラメーター作成されるもの
xhtmlW3C の XHTML 標準に準拠した HTML。
eclipsehelpEclipse IDE で使われるプラグイン用のヘルプを提供するために必要な XHTML と付属ファイル。
eclipsecontentEclipse プラグインとしてインストールでき、その情報を Eclipse が動的にレンダリングできるファイル。
javahelpJava のヘルプ・プロセッサーへの入力。
htmlhelpWindows の HTML ヘルプ・コンパイラーへの入力。
pdfXSL-FO 出力と、そこから Apache FOP を使って作成される PDF 出力。このオプションは現在、pdf2 オプションを優先するために非推奨となっています。
pdf2XSL-FO と、そこから RenderX の XEP FO エンジンと Idiom プラグインを使って作成される PDF。このオプションは FO プラグインをインストールしないと利用できません。このオプションを再構成し、XEP 以外の他のプロセッサーを使うようにすることもできます。
trofftroff フォーマット。これは、元々は AT&T による初期の UNIX® システム用に開発された、歴史のある一連のフォーマット・コードです。
docbook技術文書用の一般的な標準である DocBook DTD に準拠した XML。
wordrtfかつて Microsoft のワード・プロセッサー Word の入出力用として一般的だったテキスト・ベースのフォーマットである、(Microsoft® の) リッチ・テキスト・フォーマット。

DITA Open Toolkit を使用する、大規模で複雑な実動環境をセットアップする場合には、Ant が提供するものすべてを利用し、そうした複雑さを処理することが現実的です。DITA OT を使うためには、いずれにせよ Ant をインストールしておく必要があります。そのため大規模なプロジェクトでは、Ant について学んでから、DITA OT に含まれている Ant スクリプトを核にいくつかの Ant スクリプトを作成する、という手順が賢明です。ただし、まだ DITA OT を使い始めたばかりであれば、dost.jar は DITA OT の持つすべての機能を試すための手段として最適です。コマンドラインで 1 行入力するだけで、DITA OT に渡す各パラメーターの効果に関して、即座にフィードバックを得られるのです。楽しんでみてください。


ダウンロード可能なリソース


関連トピック

  • Installing the DITA Tookit full package distribution には DITA Open Toolkit のインストール方法とテスト方法が説明されています。
  • Ant processing parameters には Ant 処理パラメーターの詳細が、有効な値やデフォルト、使い方などを含めて、アルファベット順にリストされています。
  • Processing from the Java command line には、Ant を呼び出すのではなく、コマンドラインから Java JVM を呼び出してこのツールキットのビルド・コードを実行する方法と、サポートされているパラメーターが説明されています。
  • Darwin Information Typing Architectureの紹介」(developerWorks、Don Day、Michael Priestley、David Schell の共著、2005年9月) は、DITA とは何か、また Web 上のオンライン・ヘルプや製品サポート・ポータルといった技術文書に DITA を適用する方法について解説しています。
  • Frequently Asked Questions about the Darwin Information Typing Architecture」(developerWorks、Don Day、Michael Priestley、Gretchen Hargis の共著、2005年9月) は、ドキュメンテーション用の XML ベースの DITA (Darwin Information Typing Architecture) に関する FAQ とヒント、手法などを解説しています。
  • XML および関連技術において IBM 認証開発者になる方法については、IBM XML certification を参照してください。
  • DITA Open Toolkit sourceforge home page には、DITA の DTD とスキーマに関する OASIS DITA Technical Committee による仕様の Java ベースの実装を使って、DITA コンテンツ (マップやトピックなど) を配布可能なフォーマットに変換する方法が解説されています (Windows、Linux/UNIX、Mac OS オペレーティング・システムで使用することができます)。
  • 皆さんの次期開発プロジェクトを IBM trial software を使って構築してください。developerWorks から直接ダウンロードすることができます。

コメント

コメントを登録するにはサインインあるいは登録してください。

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=XML, Open source
ArticleID=286715
ArticleTitle=ヒント: DITA Open Toolkit による容易なコマンドライン処理
publish-date=01082008