DITAは、現在はOASIS DITA技術委員会によって管理されているトピック指向のアーキテクチャーです。DITAでは、小さな独立した単位でコンテンツを作成し、それらを集めて、オンライン・ヘルプ、ブック、またはコースなどの成果物を作ることができます。（詳細については、「参考文献」を参照してください。）

DITA以前の世界

最近まで、IBM社内の主要な大規模オーサリング形式はIBMIDDoc SGMLでした。IBMIDDoc DTDは10年以上前から使用されていました。10年というのは、大きなライブラリーや複雑な処理ツールを開発するには十分な期間です。IBMがDITAへの移行を開始したときも、これらの古いツールを使い続けるべき多くの理由がありました。

• 既存のツールは、変換およびアクセシビリティのサポートについて徹底的にテストされていました。
• DITAは大規模な情報の集合がないときでも、既存のツールであれば、非常に大きなブックでもうまく行くことが実証済みでした。
• 著者は既存のプロセスに慣れていたので、古いブックについては、これからも既存のツールを使い続けるでしょう。
• DITAでは、README形式のテキストや完全な書式形式のPDFへの変換など、多くのパブリッシング・オプションがまだありませんでした。

もちろん、著者の工数低減曲線を最小化するために、古いシステムの機能に該当するDITA用の新しいツールを作成することもできました。しかし、新しいツール一式の作成には、数々のデメリットがありました。

• 多額の先行投資が必要です。
• 現在使用しているツールへの投資が無駄になります。
• 古いSGMLの情報と新しいDITAの情報を組み合わせることができません。
• 最も重要なこととして、新しいツールの準備ができるまで、DITAを使い始めることができません。

この記事では、さまざまなソリューションの評価中に気づいたメリットとデメリットを中心に述べます。また、IBMが選んだDITAソリューションとその理由を示し、そのソリューションの技術的詳細を述べます。

上に戻る

変換による再利用

IBMでは、IBMIDDoc SGMLをさまざまなフォーマットに変換する大型のツールセットを使用しています。このツールセット（ID Workbench）を使用すると、IBMのすべてのドキュメントのスタイルを統一することができ、サポートされているすべての言語について適切な出力が得られ、すべてのアクセシビリティ規則に準拠できます。また、その他多くの要件を満たすことができます。このシステムを完全に引退させるには何年もかかるでしょう。

IBMIDDocで使用可能な堅牢なツールセットがあるとして、DITAの利用法として最初に思いついたのは、IBMIDDoc SGMLを一部またはすべての出力変換の中間形式として使用することでした。これによって、多数の出力形式へのアクセスが直ちに得られ、すべてのIBM要件への準拠が保証されます。しかし、すぐに、制限が明らかになりました。

オプション1： すべてをSGMLに変換する

DITAをIBMIDDocに変換するのは、比較的簡単です。なぜなら、DITAトピックの特定の構造とセマンティクスは、IBMIDDocの、より一般的なブック構造に容易に適合するからです。また、SGML出力を利用して、既存のIBMIDDoc変換の1つを開始するのも容易です。ただし、この方法では、単純な変換が2ステップのプロセスになるので、著者にとって煩わしい作業となります。また、SGMLファイルの多くはソース・ファイルと驚くほど似た状態のままなので、間違ったファイルにアップデートしてしまう恐れがあります。第3に、マークアップに多くの共通点があるとはいえ、特に非常に具体的な情報で特殊化されたDITAマークアップを考えると、IBMIDDocでの意味上のニュアンスのすべてを残すことは不可能です。

あらゆることを考慮すると、これらは比較簡単に回避できる問題です。2ステップの作業は面倒ですが、ショートカットを作成すれば簡単になります。中間のSGMLを一時フォルダーに格納すれば、実際のソースと混同することはありません。セマンティクスの消失は問題ですが、出力の見た目は正しいです。

残る1つの問題は、はるかに重要です。すなわち、「SGMLに変換してから」というソリューションでは、既存のIBMIDDocブックにDITAコンテンツを追加する手段がありません。IBMには、大量のSGMLライブラリーがあります。これらのブックを更新する必要が生じたら、どうなるでしょう。新しいコンテンツをIBMIDDocまたはDITAで書かなければならないのでしょうか。最終的にはブックをDITAに変換するとしても、今のところ、その時間がないとしたらどうでしょう。最後に、同じコンテンツを2つの製品で再利用する場合、一方はDITAだけを使用し、もう一方はIBMIDDocブックもサポートするとしたら、どうなるでしょう。

オプション2： SGMLの断片に変換する

明らかに、既存のIBMIDDocに新しいDITAコンテンツを併合できるソリューションが必要でした。この時点での提案の1つは、DITAをIBMIDDocのブックではなく断片に変換するという方法でした。IBMのSGML DTDでは、DITAトピックはディビジョン要素にほぼ該当します。各トピックをディビジョンに変換して、そのディビジョンを既存のブックに挿入して処理することは可能でした。しかし、このソリューションには明らかな制約もありました。

DITAをSGMLの断片として含めるときには、後で解決できるように、それらの断片をSGML実体として宣言しなければなりません。トピックが変換される前に、これらの実体を宣言するのは膨大な作業であり、間違いがおきやすい作業です。DITAトピックがSGMLに変換されない限り、完全なIBMIDDocブックを処理することはできません。断片が作成されたら、再び、余分な「ソース」ファイルの登場です。これらのSGML断片を編集してブックの流れを改善したくなるかもしれませんが、そうすると、ソースが2部できてしまいます。

このプランの真の障害は、変換プロセスのコストです。たとえば、ある製品で使用するために、DITAソース・ファイルを変換するとします。このトピックを再利用するIBMIDDocブックを変換するには、いくつかの方法があります。

• 英語のDITAファイルをSGMLに変換して、英語のブック全体を翻訳に送ります。トピックは2度変換されることになります。マークアップは正確には一致しないので、プロセスは完全自動ではありません。この結果、余分なコストが発生します。
• 変換後のDITAをSGMLに変換して、それらの変換済み断片を英語のブックとともに送ります。この場合、言語ごとに異なるパッケージが必要です。前回の使用後にDITAコンテンツに加えられた更新は、翻訳後のファイルには反映されません。また、このソリューションは、DITAトピックとSGMLファイルが同時に変換される場合は不可能です。
• 変換後にマージする方法を指示して、SGMLファイルとDITAファイルをいっしょに送る。これは処理に時間がかかるので、それだけで変換コストが増します。1ステップのプロセスの方が安上がりです。

この点で、SGMLツールを再利用できるソリューションが必要になりました。IBMIDDocとDITAを同時に処理できるようなソリューション、また、著者や翻訳への影響ができるだけ少ないソリューションが必要でした。IBMIDDocがDITAコンテンツを参照して、自動的に使用できなければ、このようなソリューションは可能になりません。

上に戻る

参照によってDITAを含める

あらかじめ変換したり、翻訳のことを心配したり、余分なソースのコピーを作ることなくDITAを含める最良の方法は、単純にポインターで含めることです。DITAトピックまたはマップを指す要素をIBMIDDocで作成して、処理ストリームですべてを裏で解決させることができます。

参照によってDITAを含めると、今までに挙げた問題のすべてが解消します。

• 既存のブックからDITAトピックまたはマップを指すのは簡単です。著者は、余分な処理ステップを覚える必要がありません。
• ユーザーはDITAソースのSGMLバージョンを追跡する必要がありません。
• DITAトピックがすでに翻訳されていた場合、新しい翻訳では、現在のDITAソースと既存のDITAベースの翻訳メモリを比較すれば、メモリ内の古いコンテンツのすべてがヒットします。

さらに、DITAポインター以外には実際のコンテンツを何も含まない単純なIBMIDDocドキュメント・シェルを使用して、IBMIDDocツールセットによってすでにサポートされている任意の出力形式を取得することができます。

SGMLにDITAを含める：XMLObj要素

ポインターとして、XMLObjという名前の要素を作成して、それをIBMIDDoc DTDに含めました。これは実体参照を使用してDITAトピックまたはマップを指し、ディビジョンが許される任意の場所で使用できます。

たとえば、ラマに関することを定義しているブックがあるとします。このブックは、ラマがブームになり始めた数年前にIBMIDDocで作成されました。今では、より小さなアルパカに目を向けている人が増えてきているので、このブックを更新する必要があります。オリジナルのブックをDITAに変換する時間はないので、XMLObj要素を使うのに理想的なシチュエーションです。マークアップは非常に単純です。実体を宣言して、それを参照するだけです。

                
<!DOCTYPE IBMIDDOC PUBLIC "+//ISBN 0-933186::IBM//DTD IBMIDDoc//EN" [
<!ENTITY alpacas SYSTEM "allAboutAlpacas.ditamap" NDATA ditamap>
<!ENTITY buyalpaca SYSTEM "buyingYourAlpaca.dita" NDATA dita>
]>
<ibmiddoc>
  ....<!-- Document title and prolog -->
  <body>
    ... <!-- Existing description of llamas -->
    <xmlobj obj="alpacas">  <!-- Point to the DITA map -->
  </body>
  <backm>  <!-- Appendix information -->
    ...  <!-- Info on how to purchase llamas -->
    <xmlobj obj="buyalpaca"> <!-- Point to the DITA topic -->
  </backm>
</ibmiddoc>

DITA参照の処理

IBMIDDoc出力変換はすべて、同じ検証および正規化プロセスから始まります。このプロセスでDITA参照が検出されると、変換は一時停止して、指定されたファイルを検索します。本来のプロセスを保留している間に、DITAコンテンツが、まずIBMIDDocに変換され、次に正規化IBMIDDocに変換されます。DITAコンテンツ（今は正規化SGML形式になっている）にわずかな修正が加えられて、本来の出力ストリームに挿入されます。これは、任意の数のトピックまたはマップで行うことができます。（上記のサンプル・ブックには、1つのマップと1つのトピックが含まれています。）

1. たとえば、上記のIBMIDDocブックの場合、プロセスは次のようになります。
2. 変換プロセスを呼び出して、ブック（llama.idd）をPDFに変換します。
   1. 変換は正規化ステップから始まります。
   2. ドキュメント・タイトルとプロローグが処理されます。
   3. ラマの各章が処理されます。
   4. <xmlobj obj="alpacas">実体が検出されて、ファイルallAboutAlpacas.ditamapが検索されます。
   5. allAboutAlpacas.ditamapがIBMIDDoc（allAboutAlpacas.idd）に変換されます。変換は、元の形式のすべてのファイルに対して行われます。したがって、NLSバージョンの場合、このプロセスによって変換後のDITAと変換後のIBMIDDocがマージされます。
   6. allAboutAlpacas.iddが正規化されます（allAboutAlpacas.idn）。
   7. 正規化されたIBMIDDocファイルallAboutAlpacas.idnが出力ストリームにコピーされます（下記の「ごく些細な詳細」で述べるマジックで）。
   8. 処理は、次の<xmlobj>要素が検出されるまで続きます。buyingYourAlpaca.ditaがbuyingYourAlpaca.iddに変換され、次にbuyingYourAlpaca.idnに変換されて、出力ストリームに含められます。
3. 処理が完了すると、1つの正規化されたSGMLファイル（llama.idn）が生成されます。
4. 正規化されたSGMLは、既存のプロセスに何も変更を加えずに、PDFに変換されます。
5. アルパカに関するIBMIDDoc断片はすべて、一時的な処理ディレクトリーにしか存在せず、処理の終了時に廃棄されます。

DITA参照のその他の用途

例で示したように、このプロセスでは、DITAとIBMIDDocを容易に統合できます。では、このプロセスには他にも何かメリットがあるでしょうか。

大きなメリットの1つは、IBMのDITAツールキットがまだサポートしていない出力形式へのショートカットになる点です。上記のサンプルの場合、アルパカ・マップだけを使用して出力を生成したいときはどうでしょう。この記事の執筆時点では、正式なDITAブック・モデル（ブックマップと呼ばれています）は、まだOASIS DITA技術委員会による審議中です。多くのベンダーがブックマップをうまく利用していますが、今までは、OASISの審議を待つつもりでした。それまでは、このIBMIDDocシェルを使用して完全なブックを生成できます。

                
<!DOCTYPE IBMIDDOC PUBLIC "+//ISBN 0-933186::IBM//DTD IBMIDDoc//EN" [
<!ENTITY alpacas SYSTEM "allAboutAlpacas.ditamap" NDATA ditamap>
]>
<ibmiddoc>
  <prolog>
    <title>Everything Alpaca</title>
    ... required metadata, such as document numbers or ISBN...
  </prolog>
  <body>
    <xmlobj obj="alpacas">  <!-- Point to the DITA map -->
  </body>
</ibmiddoc>

このシンプルなファイルは、DITAコンテンツを使用して、すべてのスタイル、翻訳、およびアクセシビリティ・ルールを自動的に満たすPDFを生成します。最も重要なこととして、IBMIDDocには、IBMがブックに必要とするすべての情報を入れる余地がすでにあります。我々は2年前から、この方法でブックを作成してきました。ブックマップの正式な承認を待っていたとしたら、まだ、DITAからブックを生成していなかったでしょう。

ID Workbenchですでにサポートされているどの形式でも同じファイルを使用できることも指摘しておかなければなりません。PDFだけでなく、README形式のテキスト出力、PostScript、またはBookManagerのようなレガシー形式も生成できます。

ごく些細な詳細

前述のとおり、DITAを正規化処理ストリームに引き入れるには、いくつかの技術的詳細を工夫する必要がありました。完全なソリューションにするためには、以下のような詳細のすべてに対処する必要がありました。このリストは長く見えるかもしれませんが、そのほとんどはきわめて簡単なものであり、その他は、複雑なDITAマークアップをサポートするために必要なものでした。DITA用の完全なツールセットを書き直すことに比べると、すべて単純なことばかりです。

• もちろん、DITAからSGMLへの変換プロセスが必要でした。特にレガシー形式については既存のIBMIDDoc変換を利用したい我々にとって、これは当然のことでした。
• 前述のプロセスでは、正規化された一時ファイルallAboutAlpacas.idnは、正規化されたブックllama.idnの中央に置かれています。現実には、allAboutAlpacas.idnには、含める前に削除する必要がある項目がいくつか含まれていました（ルート<ibmiddoc>要素や<body>要素など）。簡単な修正方法は、ファイルをスキャンして、<body>要素の内容だけを含めることでした。
• IBMIDDocでは、IDの重複は許されません。2つのDITAトピックが同じIDを使用したり、あるDITAトピックがSGMLブックにもあるIDを使用していた場合、単純にマージしただけではエラーになります。この問題は、各IDの前にdit2idNNという生成値を使用することで解決しました。NNはXMLObj参照のたびに増分される番号です。
• 我々の正規化ファイルでは、リビジョン定義などの項目はメイン・プロローグに置かれています。allAboutAlpacas.idnの本文（body）をllama.idnに入れるときには、各IDNファイルのリビジョンをマージしなければなりませんでした。これは、上記のスキャンの際に解決しました。<body>の前の情報を廃棄する代わりに、プロローグ定義を保存して、それらを"llama"ブックのメイン・プロローグにコピーしました。
• llamaサンプルでは、allAboutAlpacas.ditamapとbuyAlpaca.ditaの両方が1つのブックに含まれています。最終的にはどのトピックがブックに含まれることになるのかわからないままに、これらのそれぞれが別々にIBMIDDocに変換されました。これが一方から他方へのリンクを複雑にしました。我々には、ターゲット・トピックが含まれるのかどうかも、含まれるときにどのIDが使用されるのかもわからなかったからです。これは、これまでの問題よりも手ごわい問題でした。これらの詳細のうち、我々の初期のDITAサポートに含まれていなかったのは、これだけでした。我々はこれを、各DITAターゲットに使用されるIDと、（一時的に）無効な各リンクに使用されるIDのリストを作成することによって解決しました。正規化ファイルが完成すると、このリストを使って、各リンクを修正しました。たとえば、次のとおりです。
  1. allAboutAlpacasには、buyAlpaca.ditaへのリンクが含まれていました。変換後は、"dit2id1_invalid_1"というようなIDを参照します。ターゲットとIDは、無効IDのリストに保存されます。
  2. buyAlpaca.ditaを含めるときには、"dit2id2_buyAlpaca"というようなIDを使用します。ターゲットとIDは、有効IDのリストに保存されます。
  3. すべてのDITAコンテンツが処理された後、そのコンテンツの中の無効IDをスキャンします。
  4. スキャンによって"dit2id1_invalid_1"が見つかると、これはbuyAlpaca.ditaへのリンクとして認識されます。有効リンクから、buyAlpaca.ditaが存在し、IDは"dit2id2_buyAlpaca"であることがわかります。
  5. 無効なリンクが正しい値に置き換えられます。正しい値がわからない場合は、この時点でユーザーに警告を表示します。

上に戻る

他のシステムへの拡張

参照によってDITAを使用することのメリットは明らかですが、IBMIDDocを（あるいはSGMLさえ）使用していない企業にとって、この情報は役に立つでしょうか。答えはイエスです。複雑さの程度は違いますが、あらゆるSGMLシステムにもXMLシステムにも、同じアプローチを適用できます。

どのようなSGMLまたはXMLシステムでも、DITAコンテンツを参照する新しいDITAオブジェクト要素を追加できるはずです。コンテンツをマージしたり、既存のツールを再利用するためには、DITAから現在の形式への変換も必要です。そこから先のソリューションは、現在の形式がどのようなものかによって異なります。中心的定義のプロローグがない場合は、ネストされたコンテンツに直接変換することができます（ルートまたは<body>要素は不要です）。別々に含まれたコンテンツ間のリンクをサポートしなければ、IDと参照を認識するための複雑なメカニズムも不要です。

たとえば、添付のZIPファイル（「ダウンロード」を参照）には、DocBookブックと記事を参照によってDITAコンテンツにインポートするためのDocBookのカスタマイズが含まれています。このカスタマイズでは、DITAトピックまたはマップ（ブックマップを含む）を参照できる新しい<ditaref>要素をDocBookに追加して、DocBookで定義された書誌単位内の内容の一部または全部をサポートします。

また、このプロトタイプでは、DITA Open Toolkitの既存のDITAからDocBookへの変換の前後にラッパーを追加して、DocBookブックまたは記事を処理します。このプロセスは、<ditaref>要素を、参照されたDITAコンテンツから生成されたDocBookコンテンツに置き換えます。その結果をDocBookツールで処理することができます。DocBookツールセットを持っている人は、このANTファイルによって、この作業を1ステップで実行することができ、一時的なマージファイルは削除されます。そうでない場合、これらのスクリプトでは、マージ後のDocBookファイルが残ります。

このメカニズムを使用して、DITAをDocBook環境に統合することができます。また、DocBookのブック・モデルとツールを利用して、トピックからブックを生成することもできます。これは単純なDITAコンテンツでの概念実証にすぎませんが、完全な生産システムでの、より堅牢なサポートに拡張することができます。

上に戻る

まとめ

IBMIDDocのXMLObj要素は、既存のパブリッシング・システムを放棄しなくてもDITAへの移行が可能であることを示しています。我々は、大規模な移行が可能な時代が来るはるか前から、既存のブックでDITAコンテンツを使い始めることができました。我々は、DITAから、まだサポートされていない古い出力形式へのパスを作り上げました。これらのことから、DITAベースのシステムが実用化される何年も前に、まったく新しいシステムに投資することなく、DITAコンテンツを利用できるようになりました。

上に戻る

ダウンロード

ダウンロード形式について

参考文献

学ぶために

• IBMは2004年3月に、OASIS標準化組織にDITAを寄贈しました。これは現在、OASIS DITA Technical Committee（http://www.oasis-open.org/committees/dita/）によって管理されています。2005年4月、OASISはDITA仕様のVersion 1.0を承認しました。この仕様は、下記の文書から構成されています。
  • OASIS Darwin Information Typing Architecture (DITA) Language Specification: http://xml.coverpages.org/DITAv10-OS-LangSpec20050509.pdf
  • OASIS Darwin Information Typing Architecture (DITA) Architectural Specification: http://xml.coverpages.org/DITAv10-OS-ArchSpec20050509.pdf
  • すべての仕様とDTD、Schemaを含んだ統合zipファイルが、OASIS DITA Technical Committeeサイトの文書セクションに公開されています。http://www.oasis-open.org/committees/download.php/15316/dita10.zip
  • DTDとSchemaは、最近幾つかのバグを修正して更新されました。このバージョン（DITA 1.0.1）も、OASIS DITA Technical Committeeサイトの文書セクションに公開されています。http://www.oasis-open.org/committees/download.php/15396/dita-document-definitions-1.0.1.zip
  
  
• developerWorks版とOASIS 1.0版両方のDITA DTD/Schemaの基準実装ツールキットが、SourceForgeのDITA Open Toolkitプロジェクトのサイト（http://dita-ot.sourceforge.net）から入手できます。DITA Open Toolkitは、これまでdeveloperWorksで公開された、すべてのバージョンを置き換えるものです。その中で最後のバージョンは、一般に「dita132」と呼ばれていました。
  
  
• 更新されたdeveloperWorksの記事、「Darwin Information Typing Architectureの紹介」（developerWorks, 2005年9月に更新）を読んでください。
  
  
• 「Darwin Information Typing Architectureでの特殊化」（developerWorks, 2005年9月に更新）を読んで、新しいトピック構造を定義してください。
  
  
• OASIS Cover PagesであるDarwin Information Typing Architecture (DITA XML) では、DITAに関して、あらゆるものを一ヶ所で入手することができます。
  
  
• DocBookについて学ぶために、OASIS DocBook Technical Committeeを見てください。
  
  
• DocBookで作業を行うための情報を得るために、sourceforgeのthe DocBook projectを見てください。
  
  

製品や技術を入手するために

• 皆さんの次期開発プロジェクトを、IBM trial softwareを使って構築してください。developerWorksから直接ダウンロードすることができます。
  
  
• 添付のZIPファイルを使うために必要なオープンソースの処理システム、DITA Open Toolkitをダウンロードしてください。
  
  

著者について

Robert D. Andersonは、1999年からIBMのInternal Information Development Workbenchに取り組んできました。SGML (IBMIDDoc) 用とXML (DITA) 用の両方の移行ツールを書いてきており、また維持管理も行ってきました。2001年からは主に、DITA用の変換ツールと、（OASISに移る前は）汎用のDITA設計に取り組んできています。連絡先はrobander@us.ibm.comです。

Erik Hennum氏は、IBM Storage Systems GroupのUser Assistanceを設計および実装する業務に携わっています。以前の職責でこれまでに貢献した業務には、生の実例を注釈付きのソース・コードと同期させるWebベース・システムの設計と開発があります。彼は、ハーバード大学で英国文学の学士号を取得したことを思い出したようです。連絡先はehennum@us.ibm.com です。

この記事を評価する

コメント

上に戻る

目次

• DITA以前の世界
• 変換による再利用
• 参照によってDITAを含める
• 他のシステムへの拡張
• まとめ
• ダウンロード
• 参考文献
• 著者について
• コメント