レベル: 初級 Robert Anderson (robander@us.ibm.com), Developer, Information Development Workbench, IBM
Don Day (dond@us.ibm.com), Lead DITA Architect, IBM
Erik Hennum (ehennum@us.ibm.com), Information Architect, IBM
2005年 1月 31日 Darwin Information Typing Architecture (DITA) は、最近になって注目を集めている標準のトピック指向ドキュメント・アーキテクチャーです。DITA には、HTML で直接作成された情報に比べて、再利用がしやすい、表示形式を変更しやすい、シングル・ソーシングが簡単であるなど数多くの利点があります。この2回シリーズの第1回である今回は、既存の HTML トピックを使用した DITA のスタート・ガイドです。ここでは、提供されたXSLT 変換を使用して移行を行う方法と、高品質な結果を得るために必要な条件について説明します。インターネットの出現とともに、IBM では膨大な量のドキュメントを HTML ページで作成してきました。これらのドキュメントを再利用しやすいトピック指向のアーキテクチャーに移行するためには、IBM 内の多くのグループが大量の情報を DITA に移行しなければなりませんでした。
しかし、この移行プロセスには問題がありました。これまでのコンテンツは、それぞれ HTML 形式の異なるさまざまなツールを使って作成されていたため、共通の移行プロセスを用いることが難しかったのです。非常に厳密な HTML オーサリング・テンプレートを使用しない限り、単純な移行ユーティリティーを混乱させる事態が頻繁に発生してしまいます。
この記事は、これらの問題への対処方法について説明する2部構成シリーズの第1部です。第1部では、移行の概要、移行に適した条件、および移行のために実行すべきことを中心に説明します。また、IBMでの実際の移行作業から得られたテクニックもいくつか紹介します。
IBM では、ここに記載するコードを使用して、HTMLドキュメントをDITAに変換しています。多くの作成者がこの移行ツールを変更せずに使用していますが、常にそのまま使用できるとは限りません。ここで提供するコードは、一般的な変換であり、すべてのHTML ドキュメントに対応できるわけではないことをご理解ください。一般に、ドキュメントには、DITA 構造と容易に対応付けできる特定のマークアップがすでに含まれています。この場合は、より効率的に移行を行い、既存の情報アーキテクチャーを保持するために、この移行コードを部分的にオーバーライドすることをお勧めします。第2部では、この移行ツールをオーバーライドして、お使いの情報固有の結果を得る方法について詳しく説明します。
単純な HTML トピックの場合、XSLT を使用しない場合、または DITA 出力に対してクリーンアップを実行する予定である場合は、必要なことはここにすべて網羅されています。提供のツールを利用するだけで、DITA のメリットを十分に活かすことができます。
手作業によるクリーンアップを極力減らすために XSLT を使用したい場合は、この記事を概要としてお読みください。XSLT を使用する場合でも、移行の前に必要なことや、拡張機能を追加する前に考慮すべきことについて知っておく必要があります。その上で、XSLT の編成や、デフォルトの移行を簡単にオーバーライドする方法の例について説明する第 2 部に進んでください。
DITA の基本的な情報を参照する場合は、まず次の 2 つの記事から読むことをお勧めします。
移行に適した条件
すべての HTML トピックを DITA に移行できるとは限りませんし、また移行すべきであるとも限りません。「Why use DITA to produce HTML deliverables?」には、変換すべきでないトピックの例がいくつか記載されています。この種のトピックには、特殊目的の HTML ベース UI、コンテンツではなく外観を重視して作成されたドキュメント、変更または再利用する必要のない特殊なドキュメントなどがあります。それ以外にも、変換すべきものですが、自動ツールではうまく移行できないトピックもあります。一般に、この種のトピックとしては、旧式の HTML オーサリング・ツールを使用して記述されているものや、見やすさを重視するためだけにテーブルやリスト、インデント付きの引用部などを多用しているものが挙げられます。
DITA アーキテクチャーは、スクロールをあまり使用しなくてもブラウザ・ウィンドウに収まる程度の比較的小さな情報単位のトピックに主眼を置いています。すでにこの方法で保存されている情報のほうが、DITA への移行は容易になります。
変換に最も適しているのは、十分に構造化された HTML を使用しているトピック、つまり標準のオーサリング・テンプレートを使用しているトピックです。
コンテンツの分析
コンテンツがコンセプト、タスク、および参照項目に分けられていない場合は、状況に応じて、移行前にドキュメントを再加工する必要があります。DITA ドキュメントは通常、これら 3 つの情報タイプを使用して作成されますが、これらのメイン・カテゴリーのいずれにも適さない情報の場合は、より汎用的なトピック・タイプを使用して作成されます。できるだけ、3 つの特定タイプのいずれかに直接移行することをお勧めします。そうしないと、後でもう一度移行が必要になる可能性があります。
ここで説明する移行テクニックでは、HTML Tidy や任意バージョンの XSLT などの一般に普及しているツールをいくつか使用します。ここでは、移行前のクリーンアップ (グローバル編集や HTML Tidy など)、XSLT 移行スクリプト/変換を使用した上位変換、移行後の検証および修正について説明します。
ここで説明する基本的な移行スクリプトは、一度に1つの情報タイプを対象にしています。前述の3つのタイプを表すように情報をディレクトリーにと分割できる場合は、それぞれを1つのグループとして変換するほうが簡単です。ここでは、バッチ・ユーティリティーを使用して、同じ情報タイプを使用する所定ディレクトリー内のすべての HTML ファイルを変換します。情報タイプ毎に別々のディレクトリーを設けると、コマンドを数回実行するだけですべてのトピックをごく簡単に変換できます。もちろん、HTML トピックが混在するディレクトリー内にある各ファイルを移行する際に、最適な移行方法を選択するスクリプトを記述することも可能です。
クリーンアップするアイテム
この移行ユーティリティーは有効な XHTML ファイルにしか使用できないため、ほとんどの HTML ファイルは処理前にクリーンアップを行う必要があります。クリーンアップには Tidy コマンドを使用することをお勧めします (「参考文献」を参照)。Tidy を使用するときには、移行ユーティリティーが各ファイルの検証を行わないように、ドキュメント・タイプを削除してください。
この変換では、表示要素の<br/> と<hr/> が削除されます。これは、DITA には対応するタグがないためです。読者に何らかの情報を伝えるためにこれらの要素を意図的に使用する場合は、別の表示方法を考える必要があります。たとえば、<br/> の代わりに事前にフォーマットされたテキストを使用したり、<hr/> を使用してセクションを区切る代わりにテーブルを使用したりすることができます。これはまた、DITA に移行する場合は一般にトピックの修正が必要になることも意味しています。
Tidy を使用して HTML から XHTML へ変換する必要があるほか、その他のクリーンアップを移行前と移行後のどちらに行うほうが簡単かを判断する必要もあります。これを行うには、まずいくつかのサンプル・ファイルを変換してみることをお勧めします。実質的な目的のない<div> 要素など、修正しやすい定型構造が HTML に含まれている場合は、変換前にそれらを更新したほうが簡単でしょう。ただし、移行ユーティリティーは問題を検出するとメッセージを出すため、一般には移行後に問題を見つけるほうが簡単です。移行後に更新を行う場合は、検証エディターを使用して、クリーンアップが有効であることを確認することも可能です。
移行に関するその他の一般的な注意事項
移行を行う際には、次の点にも注意してください。
- 提供の移行ユーティリティーは、1 つのファイルに対して動作するように記述されています。このユーティリティーは、必要な情報タイプをパラメーター (infotype) として取り込み、それに従ってトピックを作成します。infotype パラメーターの値は、topic (デフォルト)、task、concept、reference のいずれかになります。1 つのファイルで出力される値は常に 1 つです。
- HTML コンテンツにすでにトピック・アーキテクチャーが含まれている場合は、HTML ページを特定のトピック・タイプに移行することで、既存のアーキテクチャーを保持することができます。特定のタイプを使用すると、出力時にタイプ別にリンクをソートできるなど、多数の利点があります。また、これにより、表示内容を整理しやすくなるほか、探している情報がわかっている場合は、その情報を見つけやすくなります。IBM では、ユーザーがトピックに直接変換したものの、後で特定のトピックが必要になり、結局もう一度移行ステップを実行することがよくあります。
- XSLT 1.0 を使用して移行を行う場合は、doctype を出力に含めることができません。トピックが DITA 形式になった後で、トピックを使用して doctype を継続する必要があります。この場合、次のようなオプションがあります。
- バッチ・プロセッサー、または複数ファイル間での検索/置換が可能なエディターを使用して、doctype を手作業で追加できます。
- 正しい doctype を設定し、移行内容をインポートするラッパー XSLT シェルを作成できます。この場合は、情報タイプごとに異なるシェルを呼び出す必要があります。
- プロセッサーによっては、変数を使用して doctype を設定することで、この問題を回避できます。たとえば、Saxon では XSLT 1.1 を指定してから、doctype を動的に設定することができます。
このユーティリティーでは、doctype をユーザー自身が設定することを前提としています。ただし、このユーティリティーには、Saxon の XSLT 1.1 処理を利用するコードが含まれています (これは他のプロセッサーとも連携させることができると思われます)。Saxon の 1.1 レベルの処理を使用して doctype を動的に設定したい場合は、XSLT についての知識がなくても、ごく簡単に設定できます。提供のプログラムは、リスト 1 に示すコードで開きます。
リスト 1. 開始コード
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" indent="no" encoding="utf-8" />
<xsl:param name="infotype">topic</xsl:param>
|
動的バージョンに切り替えるには、このコードをコメント・マーカーで囲む必要があります (コードの前に<!--、後に--> を挿入します)。次に、リスト 2 に示すコードから、同じコメント・マーカーを削除する必要があります。
リスト 2. doctypes を動的に作成するための XSLT コード
<!--<xsl:stylesheet version="1.1"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:saxon="http://icl.com/saxon"
extension-element-prefixes="saxon">
<xsl:param name="infotype">topic</xsl:param>
<xsl:param name="systemid">
<xsl:choose>
<xsl:when test="$infotype='concept'">../dtd/concept.dtd</xsl:when>
<xsl:when test="$infotype='task'">../dtd/task.dtd</xsl:when>
<xsl:when test="$infotype='reference'">../dtd/reference.dtd</xsl:when>
<xsl:otherwise>../dtd/topic.dtd</xsl:otherwise>
</xsl:choose>
</xsl:param>
<xsl:param name="publicid">
<xsl:choose>
<xsl:when test="$infotype='concept'">-//IBM//DTD DITA Concept//EN</xsl:when>
<xsl:when test="$infotype='task'">-//IBM//DTD DITA Task//EN</xsl:when>
<xsl:when test="$infotype='reference'">-//IBM//DTD DITA Reference//EN</xsl:when>
<xsl:otherwise>-//IBM//DTD DITA Topic//EN</xsl:otherwise>
</xsl:choose>
</xsl:param>
<xsl:output method="xml" indent="no" encoding="utf-8"
doctype-system="{$systemid}" doctype-public="{$publicid}"/>-->
|
- リンクを変換すると、すべてのローカル HTML トピックの拡張子が「.dita」に変更されます。外部リソースや HTML 以外のリソースへのリンクは変更されません。「.dita」拡張子を使用したくない場合は、
dita-extension パラメーターを使用して単に必要な値を渡すか (例:dita-extension=xml)、またはソース・コードの値を変更することで、この拡張子を変更できます。
- DITA トピックでは、ID 属性が必要となります。この移行ユーティリティーでは、HTML ファイルの名前 (パラメーターとして渡す必要があります) を検証することで ID を判別します。HTML ファイル名が渡されない場合は、生成された ID が使用されます。別の方法 (トピック・タイトルや各トピックの先頭付近のフレーズなど) でトピック IDを作成したい場合は、
genidattribute テンプレートを更新するか、filename-id 変数のデフォルトを変更する必要があります。
- 一般に、この移行ツールでは、すべての要素の移行方法について最適な推測が行われますが、状況によっては、既存のデータ構造が適切な DITA 要素と確実に対応付けられない場合があります。ユーティリティーが正しい移行方法を判断できない場合には、該当するコンテンツが
<required-cleanup> 要素内に置かれ、出力の修正が必要であることを示すメッセージが出されます。
 |
この移行で実行されないこと
この移行を利用する際には、トピックを対象に移行が行われることに注意してください。HTML ページの内容は、複数のブック・セクションのようなものではなく、ネストされたセクションを持たない単一のセクションでなければなりません。前述のように、DITA アーキテクチャーはトピックに重点を置いているため、ブック用に記述された情報は、トピック・ベースのアーキテクチャーに合うように再設計する必要があります。また、移行後に DITA マップを使用して、変換されたトピックに対してネストを定義することで、階層を再構成することも可能です。
また、この方法は移行のみを主目的としていることも覚えておいてください。したがって、処理のパイプラインの一部としては、それほど便利ではありません。トピック指向の情報から始めないと、DITA を実行するだけでは実際のトピックは作成できません。また、HTML トピックを DITA に移行した後で、多少のクリーンアップが必要となります。クリーンアップを省くために XSLT を徹底的に修正することも可能ですが、後で別の作成者が予想外の場所に<br/> タグを挿入した場合などに問題が発生してしまいます。長期的に見れば、ファイルを移行し、DITA コンテンツをクリーンアップした後、CSS を使用して必要に応じて出力を調整したほうがはるかに簡単です。
特殊な HTML 慣行の考慮
ご存じのとおり、HTML ではさまざまなことを実行して表示内容を調整できますが、それにより、コンテンツが間違って表現されてしまう場合もあります。たとえば、ブロック引用が実際にブロック引用である場合と、インデントが設定された単なる 1 段落である場合とがあります。十分に構造化された HTML の場合、CSS ベースの表示に対応するため<blockquote> 要素は使用されません。DITA でも同じアプローチをとるので、DITA への移行時には、同時にマークアップの修正も必要になることがよくあります。
IBM では以前に、RoboHelp で作成された多数のトピックを扱うプロジェクトがいくつかありましたが、これらのファイルの多くはオーダードリストの保存方法のせいで、正常に変換できませんでした。リスト内の各アイテムは専用のオーダードリストに入っており、番号付けは各リストの start 属性を使用して保存されていました。たとえば、5 番目のアイテムは 5 番目のリストに<ol start="5"> として指定されていました。追加スペースを必要とするリストの場合、各リスト・アイテムの間に空の段落が挿入されていました。
DITA では、これを 1 つのリストとして保存し、CSS で出力のスペースを調整するほうがはるかに効率的です。これは特に、<steps> 要素を 1 つしか使用できない (各アイテムを専用の<steps> 要素に区切ることができない) タスク処理の際に重要となります。
IBM では、トピックをチェックし、start 属性が使われているリストが含まれているかどうかを確認することでこれに対処しました。このようなリストが含まれている場合は、まとめる必要があるリストをマージしながら、トピックに対して最初のパスを実行してツリー全体をコピーします。提供されたXSLT でのこの実行方法を確認するには、「shift-lists」モードを参照してください。この結果のツリーは変数に入れられ、その変数の内容がオリジナル・ファイルと同じように処理されます。
このような変数の処理方法により、一部の XSLT プロセッサーでは問題が発生する場合があります (前述の Saxon プロセッサーの場合は問題なく処理されます)。お使いのプロセッサーで問題が発生する場合は、マージされた XHTML を一時ファイルに送信し、代わりにそのファイルを処理してください。また、実際の 2 パス・モデルを設定して変換を順次実行するか、あるいはこの問題を単に無視して移行し、後からリストを手作業でマージすることも可能です。なお、この問題は、start 属性を使用するリストが実際にある場合にのみ発生します。この属性が使われていない場合は、マージ・プロセスがスキップされます。
ここで説明しているプロセスは本来 RoboHelp ユーザー用のオーバーライドとして作成されたものですが、このマークアップを使用しているすべてのユーザーがオーバーライドを実行できるように、オリジナルの移行にも組み込まれています。
移行の実行
XSLT を変更したくない場合は、XSLT をダウンロードし、システム上の適当な場所に保存しておくだけでかまいません。トピックの変換には任意の XSLT プロセッサーを使用できます。
XSLT 自体を実行する前に、ファイルが有効な XHTML であることを確認する必要があります。これを簡単に行うには、TIDY コマンドを使用します (「参考文献」を参照)。IBM では、XHTML ができるだけクリーンな状態になるように、Tidy でいくつかのオプションを使用しています。
表 1. Tidy コマンドのオプション
|
Tidy のオプション
|
説明
|
-c
|
FONT、NOBR
Center の各タグを、CSS を指す参照と置き換えます。 |
-n
| 各エンティティーが、名前付きの値ではなく数値を使用するようにします (可能な場合)。 |
-m
| 各エンティティーが、名前付きの値ではなく数値を使用するようにします (可能な場合)。-m オリジナル・ファイルが、更新されたファイルで置き換えられるようにします。このオプションを使用する場合は、オリジナルの HTML ファイルのバックアップを作成しておいてください。 |
--output-xml yes
| 出力が有効な XML であることを確認します。 |
--doctype omit
| が出力に表示されないようにします。出力が XHTML の場合は、これにより、変換前に XSL パーサーが各XHTML トピックを検証しないように設定できます。 |
Tidy の呼び出し例は次のようになります。
tidy -c -n -m --output-xml yes --doctype omit input.htm > output.htm
|
繰り返しますが、この呼び出しを使用する前に、HTML ファイルのバックアップを必ず作成してください。これには、バッチ・ユーティリティーを使用すると便利です。IBM では、そのディレクトリーにある全てのHTMLファイルのバックアップを作成してから、それらのファイルを更新する単純なバッチ・スクリプトを使用しています。
これで有効な XHTML トピックができたので、トピックを移行する XSLT 呼び出しに進むことができます。
- リスト 3 の呼び出しは、タスク ID 用に生成された ID を使用し、デフォルトの拡張子として「.dita」を使用して、タスクを作成します。
リスト 3. Saxon と Xalan を使用した移行呼び出し例
java com.icl.saxon.StyleSheet mytask.htm h2d.xsl infotype=task > mytask.dita
java org.apache.xalan.xslt.Process -in mytask.htm -xsl h2d.xsl
-out mytask.dita -param infotype task
|
- リスト 4 の呼び出しは、ID としてファイル名を使用し、デフォルトの拡張子として「.xml」を使用して、コンセプトを作成します。
リスト 4. 追加パラメーターを使用した、より複雑な移行呼び出し
java com.icl.saxon.StyleSheet myconcept.html h2d.xsl infotype=concept
FILENAME=myconcept.html dita-extension=xml > myconcept.xml
java org.apache.xalan.xslt.Process -in myconcept.html -xsl h2d.xsl -out myconcept.xml
-param infotype task -param filename myconcept.html
-param dita-extension xml |
変換するトピックが多数ある場合は、これを実行するためのバッチ・ファイルを作成することをお勧めします。IBM で作成したバッチ・ファイルは、同じ情報タイプを使用する 1 つのディレクトリー内のすべてのトピックを変換します。つまりこの場合、移行の前にタイプごとに分類する必要があります。これが最も簡単な方法である場合もありますが、この代わりに、各トピックを移行する前に情報タイプを問い合わせるバッチ・ファイルを作成することもできます。
まとめ
トピックを HTML から DITA に移行することで得られるメリットは多数あります。たとえば、トピック全体またはトピックの一部を再利用しやすいこと、複数の出力形式を生成できること、CSS ファイルを切り替えるだけでドキュメント全体の表示をすばやく変更できることなどが挙げられます。信じられないという方は、「Why use DITA to produce HTML deliverables?」を参照してください。
十分に構造化されたトピックがすでにある場合は、そのいくつかを使用し、ここで提供した変換ツールを使用してみてください。手作業による調整をほとんど必要とせずに、DITA をソースとする環境に完全に移行できるでしょう。複雑な HTML を使用している場合でも、簡単な作業だけで出力をクリーンアップできるはずです。もちろん、XSLT を使用することも可能です。XSLT の使用方法に関するヒントについては、この記事の第 2 部を参照してください。
ダウンロード | 内容 | ファイル名 | サイズ | ダウンロード形式 |
|---|
| XSLT 移行スクリプトとサンプル | x-dita8asource.zip | 21KB | HTTP |
|---|
参考文献
-
Migrating HTML to DITA, Part 2を読んでください。ここでは移行に関して（また移行をオーバーライドする方法に関して）、より詳細に解説しています（developerWorks, 2005年2月）。
- DITAについてさらに学ぶために、developerWorksにある、下記の記事を読んでください。
-
OASIS Cover Pagesにも、DITAに関する情報があります。
- 移行を行う際に便利なツールとして、下記のようなものがあります。
- HTML Tidy がSourceForge.netから入手できます。Java版も、同じくSourceForgeのJTidy pageから入手できます。
-
Saxon XSLTエンジンもSourceForge.netから入手できます。
-
Xalan XSLTエンジンがApacheから入手できます。
- その他にも、こうしたXSLTリンクが利用できます。
著者について | 
| |
Robert D. Andersonは、1999年からIBMのInternal Information Development Workbenchに取り組んできました。SGML (IBMIDDoc) 用とXML (DITA) 用の両方の移行ツールを書いてきており、また維持管理も行ってきました。2001年からは主に、DITA用の変換ツールと、（OASISに移る前は）汎用のDITA設計に取り組んできています。連絡先はrobander@us.ibm.comです。 |
| | |
Don Dayは、IBMのInformation Developmentコミュニティー向けの公開ツールの設計・サポートを行っており、またW3CのXSLワーキング・グループとCSSワーキング・グループでは、IBMの代表でした。この3年間は、DITAのDTDと仕様の開発と維持管理を行うワークグループのリーダーを努めています。英語とジャーナリズムで学士号を、また技術的/専門的コミュニケーションで修士号を、ニューメキシコ州立大学で取得しています。連絡先はdond@us.ibm.comです。
|
| | | Erik Hennum氏は、IBM Storage Systems GroupのUser Assistanceを設計および実装する業務に携わっています。以前の職責でこれまでに貢献した業務には、生の実例を注釈付きのソース・コードと同期させるWebベース・システムの設計と開発があります。彼は、ハーバード大学で英国文学の学士号を取得したことを思い出したようです。連絡先はehennum@us.ibm.com です。 |
記事の評価
| 
