レベル: 初級 Robert Anderson (robander@us.ibm.com), Developer, Information Development Workbench, IBM
2005年 2月 10日 Darwin Information Typing Architecture（DITA）には、HTMLで直接作成された情報に比べて、再利用しやすい、表示形式を変更しやすい、シングル・ソーシングが簡単であるなど数多くの利点があります。HTMLトピックをDITAにすばやく移行する方法についてのこの2部シリーズの第2部では、移行の詳細を説明し、このプロセスの一部をオーバーライドして理想的な結果を得る方法を説明します。
このシリーズの第1部では、IBMで実際に使われているHTMLからDITAへの移行ツールの使い方を中心に説明しました。移行の前に必要なクリーンアップについて簡単に説明し、このツールでの処理に適したマークアップの種類についてヒントを述べました。
DITAの記事は、一般に情報のタイプによって分けられます。このツールは、デフォルトの状態で、トピック、コンセプト、参照項目、およびタスク情報タイプへの移行をサポートしています。この記事では、これらの各タイプの移行パスについて詳しく説明し、変換の一部をオーバーライドしたい人のための出発点を示します。最後に、特定の要素を迂回したい人のためのオーバーライドのサンプルを示し、より広範囲なオーバーライドのために使用すべき項目を示します。
はじめに
まだDITAをよく知らないという方は、次の2つの記事を読むことをお勧めします。
手っ取り早く始めたいが、このシリーズの第1部をまだ読んでいないという方は、まず第1部を読むことをお勧めします。
基本トピックへの変換
HTMLとDITAには共通の要素が多いので、HTMLから単純なDITAトピックへの移行は比較的簡単です。トピック情報タイプへの移行は、理想的でなくても、適切な解決策である場合があります。また、トピックへの基本的な移行は、より特殊な移行の基礎となります。
この移行では、デフォルトで基本トピックが作成されるので、infotypeパラメーターを"topic"に設定してもよいですし、何も指定しなくてもかまいません。見出しが1つだけの単純なトピックの場合、トピックへの移行は非常に簡単です。見出しはトピックのタイトルに置かれ、メタ情報はプロローグに置かれます。ファイルの内容はボディに置かれます。トピックの終わりには、リンクの集合が生成されます。これには、ファイル内で見つかった外部リンクのすべてが含まれます。これらを手動で更新したい場合があります。ファイル内に生成された相互参照を削除したい場合が多いのですが、ときには、関連リンクではなくインライン参照項目にしておく方がよい場合もあります。
HTML内の<title>要素は、表示されるタイトルの短縮版であることが多く、検索でトピックを探すときに多くのユーザーの目に触れるものでもあります。このため、このユーティリティーは<title>要素の内容をDITAトピックの<searchtitle>に入れて、最初の見出しの内容をDITAの<title>要素に入れます。2つの値が同じ場合、<searchtitle>要素は作成されないことに注意してください。移行のために、これを更新する必要がある場合は、提供のXSLTのgentitlealtsテンプレートを検索してください。
<p>、<ol>、<pre>など、DITAに直接渡すことができるHTML要素もあります。<table>、<dl>など、その他の要素は簡単な変換によって修正する必要があります。これらのルールのどちらにも属さない例外は、<div>要素です。この要素は無限にネストでき、表示のためにCSSとともに使用されることが多いので、そのままでは一般的な移行ルールに適用できません。そのため、このユーティリティーは、コンテンツを単純に処理します。<div>要素を使用している通常の構造の場合、移行のこの部分をオーバーライドしたほうがよいでしょう。
<span>要素は一般にマッピングが容易ですが、<div>要素と同じ問題がありがちです。<span>でclass属性をよく使用素を使用したいとみなされ、ボールドやイタリックなどのスタイル情報が保持されます。この要素セットを、DITAでは強調ドメイン(highlighting domain)と言います。
複雑なトピック
複数の見出しがあるトピックや、小見出しがあるトピックは、処理が少し難しくなります。単純なトピックと同様、最初のタイトルがトピックのタイトルになります。2番目の見出しまでは、すべて同じように処理されます。すなわち、直接、トピックのボディになります。
2番目の見出しは、<section>要素を生成するために使用されます。この見出しがセクションのタイトルになり、3番目の見出しまでのすべてがそのセクションに含まれます。その後の見出しも、同じようにセクションになります。これはXSLTのモードを使用して行われ、別の見出しが検出されるまで、要素が順に処理されます。「このユーティリティーによって使用されるモード」については、この記事の後の方で詳しく述べます。
見出し処理の例外として、各見出しが最初の見出しと同じレベルか1レベル下のレベルでなければなりません。すなわち、<h1>で始まるトピックでは、他の<h1>または<h2>見出しからセクションが作成されますが、<h3>は許されません。<h2>で始まるトピックでは、他の<h2>または<h3>見出しからセクションが作成されますが、<h4>は許されません。このような無効な見出しがあった場合、セクションは作成されますが、内容のすべてが<required-cleanup>要素に置かれて、移行後に修正が必要になります。
リスト1は移行のサンプルであり、入力されたXHTMLとそれに対するDITA出力を示しています。この例から分かるように、小見出しによってセクションが作成されますが、下のレベルの見出しを修正する必要があります。
リスト1. 基本トピック情報タイプへの移行パスの例
<html> <topic id="filename">
<head>
<title>Topic title</title> <title>Topic title</title>
</head>
<body> <h1>Topic title</h1> <body>
<p>Intro paragraph</p> <p>Intro paragraph</p>
<table>...</table> <table>...</table>
<ol><li>list item</li></ol> <ol><li>list item</li></ol>
<h2>Sub-heading</h2> <section><title>Sub-heading</title>
<p>Text in the sub-heading</p> <p>Text in the sub-heading</p>
<p>More text</p> <p>More text</p>
</section>
<h3>Tertiary heading</h3> <section><required-cleanup>
<p>Text in the <title>Tertiary heading</title>
invalid heading</p> <p>Text in the invalid heading</p>
</required-cleanup></section>
</body> </body>
</html> </topic>
|
コンセプト・トピックへの変換
コンセプト・トピックの作成は、実際には基本トピックの作成と同じですが、<topic>および<body>タグに新しい名前が加わります。このコンテンツ・モデルでの唯一の違いは、ボディ内にセクションを置いたら、セクションまたは例しか使用できないことです。この制限は、すでに一般的なトピック移行に従っているので、コンセプト・トピックのための新たな処理は必要ありません。提供の移行でコンセプト出力を生成するには、infotypeパラメーターを"concept"に設定するだけです。
リスト2は、複数の小見出しを含んだ単純なコンセプトの移行パスの例です。
リスト2. コンセプト情報タイプへの移行パスの例
<html> <concept id="filename">
<head>
<title>Concept title</title> <title>Concept title</title>
</head>
<body> <h1>Concept title</h1> <conbody>
<p>Intro paragraph</p> <p>Intro paragraph</p>
<table>...</table> <table>...</table>
<ol><li>list item</li></ol> <ol><li>list item</li></ol>
<h2>Sub-heading</h2> <section><title>Sub-heading</title>
<p>Text in the sub-heading</p> <p>Text in the sub-heading</p>
<p>More text</p> <p>More text</p>
</section>
<h2>Another sub-heading</h2> <section>
<p>Text in the <title>Another sub-heading</title>
last heading</p> <p>Text in the last heading</p>
</section>
</body> </conbody>
</html> </concept>
|
参照項目トピックへの変換
参照項目トピックの作成は、基本トピックの作成よりやや複雑です。参照項目トピックのコンテンツ・モデルは、より限定的なためです。
サンプルのXSLTから参照項目出力を生成するには、infotypeパラメーターを"reference"に設定します。参照項目モデルと基本トピックまたはコンセプト・モデルとの主な違いは、参照項目内のすべてがセクションまたはテーブルの中に入らなければならないことです。次のような可能性を考えてみましょう。
- 見出しが1つしかなく、1つの段落やリスト・コンテンツしかないHTMLトピックは単純です。見出しがトピックのタイトルになり、テキスト・コンテンツのすべてがボディ内のセクションに置かれます。
- 見出しは1つしかないが、段落とテーブル・コンテンツが混在するトピックは、やや難しくなります。テーブル自体は、直接ボディに入りますが、テーブルの外側のコンテンツのすべてを処理するために、セクションを作成する必要があります。
- 複数の見出しがあり、テーブルが含まれないトピックは、通常のトピックやコンセプトと同じように処理されます。唯一の違いは、最初または2番目の見出しまでのすべてがセクションに入らなければならないことです。
- 複数の見出し、通常のコンテンツ、およびテーブルが混在するトピックが、最も複雑です。この場合、各テーブルがボディの子になります。同様に、各見出しからボディ内のセクションが作成されます。テーブルと見出しの間の要素は、タイトルのない別のセクションの中に入れる必要があります。
これは、出力がどのように作成されるかを示しています。gen-referenceテンプレートを見ると、はるかに複雑になっているのが分かります。それは、最初の見出しと最初のテーブルまたは小見出しの間に内容が存在するかどうかを判断するための長い条件を含んでいるためです。存在する場合、その内容が処理されてから、ボディの残りが処理されます。冗長なXSLT構文を無視して、これを単純なテストと考えると、コーディングはコンセプトやタスクの場合とほぼ同じです。
リスト3は、参照項目の移行例です。これを見ると、要素を有効なセクションにまとめる方法が分かります。テーブルだけがセクションの外側に残ります。小見出しから新しいセクションが始まります。
リスト3. 参照項目情報タイプへの移行パスの例
<html> <reference id="filename">
<head>
<title>Reference title</title> <title>Reference title</title>
</head>
<body> <h1>Reference title</h1> <refbody>
<p>Intro paragraph</p> <section><p>Intro paragraph</p></section>
<table>...</table> <table>...</table>
<p>Text after table</p> <section><p>Text after table</p>
<p>More text</p> <p>More text</p></section>
<h2>Sub-heading</h2> <section><title>Sub-heading</title>
<p>Text in the sub-heading</p> <p>Text in the sub-heading</p>
<p>More text</p> <p>More text</p>
</section>
</body> </refbody>
</html> </reference>
|
タスク・トピックへの変換
タスクは、移行が最も複雑な記事です。タスクのコンテンツ・モデルは最も制限が厳しく、タスクが実際にステップを含んでいるかどうかによって処理方法が違います。
タスク・モデルは複数のオプション・セクションからなり、それらのセクションが順に並んでいなければなりません。これらのセクションは、prereq、context、steps、result、example、およびpostreqです。タスクを移行する際の最大の問題は、内容をこれらのセクションに分割する方法を決めることです。基本的な移行は、あまりインテリジェントではありません。ステップのセットの前（すなわち、最初の番号付きリストの前）にある内容はすべて、contextセクションに入ります。ステップの後にあるものはすべて、resultセクションに入ります。ご推察のとおり、ステップそのものは、その間のstepsに入ります。
タスク出力を作成するには、infotypeパラメーターを"task"に設定するだけです。
ステップのないタスク
ステップのないタスクは、通常、他のタスク・グループの概要です。タスクがステップを含まない場合は、すべてがcontextセクションに置かれます。追加の見出しが在った場合は、context内でセクションをネストすることはできないので、<required-cleanup>要素に入れられます。
概要タスクが一般的なコンテキスト情報ではなく、前提条件に関する情報を述べるものである場合は、このすべてをcontextではなくprereqセクションに入れるほうがはるかに簡単です。情報を分割したい場合は、内容を分析して、分割方法を考えてください。
ステップのあるタスク
ステップを含むタスクのほうが一般的です。この移行では、ステップはトピック内の最初の番号付きリストとして識別されます。DITAタスクでは、番号なしステップも可能ですが、このサポートはまだ移行ユーティリティーに含まれていません。
概要タスクと同様、一連の見出しを付けることはできません。最初の番号付きリストまでのものはcontextセクションに置かれます。これには、段落とテキストだけでなく、テーブル、見出し、またはその他のタイプのリストが含まれます。タスクが通常の構造の場合、prereq情報とcontext情報を区別する手段がほしいかもしれません。
ファイル内の最初の番号付きリストは、<steps>要素に変換されます。各ステップは非常に制限されたモデルになっています。すなわち、テキストまたはフレーズ・レベルの要素だけを含む<cmd>要素で始まらなければなりません。コマンドの後には、substepsやinfoなど、一連のブロック要素を続けることができます。infoタグには、テキストから大きなブロック・レベル要素まで、何でも入れることができます。
それぞれの<step>要素は、1つのリスト項目を処理することによって作成されます。そのリスト項目がテキストまたはフレーズしか含まない場合は、すべてがコマンドに置かれます。リスト項目がブロック・レベル要素を含んでいる場合は、最初のブロックまでのすべてのものがコマンドに置かれ、その後のリスト項目以外のものは<info>ラッパーに置かれます。唯一の例外はネストされた番号付きリストであり、これはsubstepsに置かれます。サブステップもステップと同じように処理されますが、サブステップに複数のサブステップを含めることはできません。
ステップの後にあるものはすべて、別のセクション状の要素に入ります。使用可能なタグは、result、example、およびpostreqです。このユーティリティーでは、その後の内容はすべて<result>要素に置かれます。上記のcontext要素と同様、詳細に構造化されたタスク情報は、result、example、およびpostreqセクションに分割することができます。
リスト4は、最も一般的なタスクの移行例です。この例では、いくつかの紹介材料、いくつかのステップ、およびいくつかのフォローアップ材料を含んだタスクを使用しています。
リスト4. タスク情報タイプへの移行パスの例
<html> <task id="filename">
<head>
<title>Task title</title>
</head> <title>Task title</title>
<body> <h1>Task title</h1> <taskbody>
<context>
<p>Intro paragraph</p> <p>Intro paragraph</p>
<table>...</table> <table>...</table>
</context>
<ol> <steps>
<li>step one</li> <step><cmd>step one</cmd></step>
<li>step two</li> <step><cmd>step two</cmd></step>
</ol> </steps>
<p>Text after list</p> <result><p>Text after list</p>
<p>This is summary info</p> <p>This is summary info</p>
<p>Here is what you do next</p> <p>Here is what you do next</p>
</result>
</body> </taskbody>
</html> </task>
|
その他のものへの変換
提供の変換は、基本トピックには適していますが、特定のタグに入れたい情報がある場合はどうでしょうか。
特定のパターンでの移行のオーバーライド
標準的な変換によるDITAの処理が便利な理由の1つは、オーバーライドが容易なことです。必要なときには、特定の要素の1つについて出力を変えることができ、しかも、他のものについてはデフォルトの動作を使用することができます。これは、DITAへの移行についても同様です。
移行をオーバーライドすべき事例としては、セマンティック情報を示すために頻繁にクラス属性を使用する場合があります。このような場合、クラスを照合することによって、要素をオーバーライドしたいことがあります。デフォルトのフレーズへの移行を使用するのではなく、コマンドのspanとclass値を照合して、内容を実際の<cmdname>要素に入れることができます。
もう少し複雑な例として、タスク記事用の標準テンプレートがあるとしましょう。そのテンプレートでは、ステップの最初の文は常にコマンドを含み、残りの文で結果を記述します。ただし、ステップには、コマンドと結果を区別するためのタグは含まれていません。この場合、ステップは完全なプレーン・テキストなので、移行ユーティリティーはすべてをDITAの<cmd>要素に入れます。最初の文を<cmd>に入れ、残りの情報を<stepresult>要素に入れるほうが論理的に筋が通ります。これは、移行のオーバーライドによって簡単にできます。
このオーバーライドの場合、まず、標準の移行を引き込む単純なXSLTシェルを作成します。これを単純な<xsl:import href="h2d.xsl"/>コマンドに入れます。次に、個々のステップの処理をオーバーライドします。提供の移行ユーティリティーを見ると分かるように、ステップとサブステップが同じテンプレートを使用して処理されています。リスト5は、そのテンプレートのコピーです。
リスト5. タスクのステップを処理するためのXSLTテンプレート
<xsl:template match="li" mode="steps">
<xsl:param name="steptype">step</xsl:param>
<xsl:element name="{$steptype}">
<xsl:choose>
<xsl:when test="not(p|div|ol|ul|table|dl|pre)">
<cmd><xsl:apply-templates select="*|comment()|text()"/></cmd>
</xsl:when>
<xsl:otherwise>
<cmd><xsl:apply-templates select="(./*|./text())[1]" mode="step-cmd"/></cmd>
<xsl:apply-templates select="(p|div|ol|ul|table|dl|pre|comment())[1]" mode="step-child"/>
</xsl:otherwise>
</xsl:choose>
</xsl:element>
</xsl:template>
|
これが、オーバーライドする必要があるテンプレートです。まず、同じmatchテンプレートをコンテンツなしで使用します。
<xsl:template match="li" mode="steps"> </xsl:template> |
XSLTシェルは標準の移行をインポートしますが、XSLTによって元の優先順位ではなく、新しいルール優先順位が自動的に与えられます。したがって、この時点で移行すると、ステップのすべてが消えてしまいます。次に、新しいコードを追加します。タスク・テンプレートではプレーン・テキストしか使用されていないので、元のものほど複雑にする必要はありません。サブステップや子要素を気にする必要はありません。まず、簡単にステップを作成します。少なくとも1つの文があることが分かっているので、コマンド要素を作成して、最初のピリオドの前のテキストのすべてを挿入します。削除される文のピリオドを追加するのを忘れないでください。次に、コマンドの後にコンテンツがあるかどうかをチェックします。残りのコンテンツは変数resultに入れました。この変数がコンテンツを含む場合は、<stepresult>要素に置かれます。
リスト6. タスク・ステップ処理のオーバーライドの例
<xsl:template match="li" mode="steps">
<step>
<xsl:variable name="result">
<xsl:value-of select="substring-after(.,'.')"/>
</xsl:variable>
<cmd><xsl:value-of select="substring-before(.,'.')"/>.</cmd>
<xsl:if test="string-length($result)>0">
<stepresult><xsl:value-of select="$result"/></stepresult>
</xsl:if>
</step>
</xsl:template>
|
これは、IBMのいくつかのグループで使用されているオーバーライドとほぼ同じです。これより複雑なオーバーライドが多いですが、これと同じぐらい簡単なものもあります。特に、フレーズ要素はオーバーライドが容易です。
別の特殊化DTDへの移行
トピックのすべてを基本的なコンセプト、タスク、または参照項目に分割する場合は問題ありませんが、別の特殊化したDTDに移行したい場合はどうでしょうか。その場合、やはり変換を利用できますが、リスト6の例よりもオーバーライドが複雑になります。どのくらい複雑になるかは、入力ファイルの状態と特殊化DTDの複雑さによって決まります。注意すべき点をいくつか挙げておきます。
-
このシリーズの第1部で述べたように、どのような移行についても、
DOCTYPEの追加方法を決めてください。どのような方法を選んだ場合でも、特殊化DTDも認識されるように更新してください。
- "html"を照合するテンプレートは、名前付きのテンプレートを入力パラメーターに基づいて呼び出します。たとえば、基本的なトピックは
gen-topicテンプレートで作成され、タスク・トピックはgen-taskテンプレートで作成されます。コマンド・リファレンス・トピックに変換する場合は、gen-cmdrefテンプレートを追加して、ルート要素をセットアップし、トピック内の主要な構造を作成したほうがよいでしょう。この新しいDTDではオーバーライドだけを使用するという場合は、HTML要素をオーバーライドして、それを使用して出力構造をセットアップできます。これにより、infotypeパラメーターを渡す必要がなくなります。
- この時点で、複雑さは特殊化DTDによってのみ決まります。コマンド・リファレンスに移行したい場合、基本的な参照項目と同じコンテンツ・モデルであれば、参照モデルをコピーするだけです。コマンド・リファレンスが非常に厳格なコンテンツ・モデルである場合、作業が容易になる場合と難しくなる場合があります。非常に厳格なコンテンツ・モデルとは、入力ファイルがすでに厳格なモデルに従っているので、結果の予測がつきやすく、したがってコンテンツの処理が容易になることを意味する場合があります。そうでない場合、すべてが思い通りになるように、いちいち準備しなければならないとすると、特殊化DTDにあわせて、かなり複雑な条件付コーディングが必要になります。前述のタスク構造の処理と同様、コンテンツの大部分を少数の主要構造にまとめてから並べなおすという方法を取ることもできます。
- 、多くの処理がモード付きで行われていることに気付くでしょう。これらをオーバーライドで再利用したり、少し手を加えて、セクションを特殊化セクションにすることもできます。よく使用されるモードは、次のとおりです。
-
creating-content-before-section:このモードは、ボディのコンテンツを処理するときに使用されます。単一の要素、テキスト・ノード、またはコメントを取り込みます。そのノードがセクション・レベルの見出しの前にあった場合は出力に置かれ、処理は次のノードへと続行されます。見出しが見つかると、処理は停止します。
-
add-content-to-section:このモードも最初のモードとほとんど同じですが、セクション内で一度だけ使用されます。処理は同じように行われます。見出し以外のノードは出力に置かれ、次のノードへと処理が続行されます。見出しが見つかると、処理は停止します。
-
create-section-with-following-content:このモードは、メインの見出しの後のすべての見出しで使用されます。見出しをセクションのタイトルにして、次の見出しまでのすべてのものをそのセクションに入れます。参照項目トピックを生成するときには、テーブルはセクションに入らないことに注意してください。テーブルは参照項目ボディに直接入ります。特殊化した参照項目でもこの動作を保持したい場合は、新しい情報タイプが認識されるようにadd-content-to-sectionモードを更新する必要があります。
 |
まとめ
これまでの説明で、HTMLをDITAにするメリットがお分かりいただけたのではないかと思います。今一度、要点を述べると、トピックまたはトピックの一部を今まで以上に簡単に再利用でき、複数の出力形式を生成でき、CSSファイルを切り替えるだけで成果物全体の表示形式をすばやく変更できます。まだ納得できない方は、「Why use DITA to produce HTML deliverables?」を読んでみてください。
十分に構造化されたトピックがすでにある場合は、提供の変換ツールを使ってみてください。XSLTに手を染める必要さえないことが分かると思います。ただし、数分のコーディングによって、間違いのない移行が可能であると簡単に判断できる場合もあります。いずれにしても、移行は新しいオーサリング環境への容易なパスとなることが分かるはずです。
ダウンロード | 内容 | ファイル名 | サイズ | ダウンロード形式 |
|---|
| XSLT移行スクリプトとサンプル | x-dita8bmigration.zip | 21KB | HTTP |
|---|
参考文献
著者について | 
| |
Robert D. Andersonは、1999年からIBMのInternal Information Development Workbenchに取り組んできました。SGML (IBMIDDoc) 用とXML (DITA) 用の両方の移行ツールを書いてきており、また維持管理も行ってきました。2001年からは主に、DITA用の変換ツールと、（OASISに移る前は）汎用のDITA設計に取り組んできています。連絡先はrobander@us.ibm.comです。 |
記事の評価
| 
