単一ソース・ドキュメンテーションとは

連載の第 1 回で説明したように、文書を作成する際に XML (およびその概念の由来となっている SGML (Standard Generalized Markup Language)) を使用すれば、文書の内容 (コンテンツ: 文書に含まれる実際の語句やデータ) を表示 (プレゼンテーション: 特定の出力フォーマットや、特定の出力デバイスで表示する方法) とは切り離すことができます。この分離によって、文書の作成者は、情報が最終的にどのように使用あるいは表示されるかを気にせずに、文書の内容そのものに専念できるようになります。第 2 回では、XML 文書を小さな情報ユニットに編成 (チャンキング) するために使用できるさまざまなメカニズムについて検討しました。これらの情報のチャンクをさまざまに組み合わせたり、同じ情報のチャンクを異なる順序でつなぎ合わせたりすることによって、規模の大きな文書や、異なる読者を対象とした文書を作成することができます。

XML は、ソフトウェアに依存することなく、情報の再利用を容易にする文書作成環境となりますが、XML に当然求められることは、特定の対象読者や出力フォーマットに応じて情報をカスタマイズすることができ、文書の内容が変更できることです。複数の対象読者または出力フォーマットの要件を一式の入力ファイルで満たせることから、このような形での情報の再利用は一般に、単一ソース・ドキュメンテーションと呼ばれています。単一ソースの要件の一部は、異なるフォーマットで出力を生成するツールによって自動的に対処されます。例えば外部リソースへのリンクが含まれる (<ulink> 要素を使用した) DocBook XML 文書の場合、PDF 出力を生成すると、外部リソースへのハイパーリンクと実際の URL の両方が出力に組み込まれる一方、同じ XML 文書から HTML 出力を生成すると、その出力にはリンクだけが組み込まれるといった具合です。

単一の要素を出力フォーマットに応じて異なる方法で変換することは、単一ソース・ドキュメンテーションに向けての適切な一歩となります。しかし、それだけでは文書の内容をその表示要件の枠を超えてカスタマイズすることはできません。最近の文書作成に対する要件としては、対象とする出力フォーマットに応じて文書の実際の内容そのものをカスタマイズ可能であることが、かなり一般的になっています。幸い、この要件に簡単に対応する方法があります。それは、事前処理を行うと同時に、DocBook XML などの文書作成用フォーマットが持つ設計上の柔軟性を利用することです。

上に戻る

DocBook の要素と属性

XML 要素は、要素のインスタンスに関する追加情報を提供するために、属性と呼ばれる名前と値のペアを使用します。通常、XML 文書内にある同じ要素のインスタンスを一意に識別するには、属性が使われ、ある要素のインスタンスに専用の振る舞いを識別するのにも属性が使われます。属性は要素のスコープ内に含まれ、以下の形を取ります。

<attribute_name="value">

XML 要素に最もよく使われる属性の一例として、id 属性は XML 要素の特定インスタンスを以下のようにして一意に識別します。

<section id="introduction">

XML 文書内では、id 属性は <xref> や <link> などの要素によって相互参照をサポートします。以下は、上記の例で使用した <section> 要素を参照する例です。

<xref linkend="introduction"/>
<link linkend="introduction">introduction to this document</link>

要素専用の振る舞いを識別する属性の例としては、<emphasis> 要素の role 属性があります。

<emphasis role="bold">example</emphasis>

<emphasis> 要素内に含まれる内容は、一般に PDF や HTML などの表示フォーマットでは斜体でレンダリングされます。role="bold" 属性を指定すると、この要素のレンダリング方法は斜体ではなく太字に変更されます。

上に戻る

文書のカスタマイズに考えられる代替手段

これまで、文書の生成に重点を置くマークアップ言語では、そのサポートする要素一式のカスタマイズにもある程度対応してきました。特定ツールのなかで特化した方法で使用できるカスタム要素の作成は、SGML の前身である GML (Generalized Markup Language) の機能でした (詳細は「参考文献」を参照)。それぞれの頭辞語からわかるように、GML と SGML の主な違いは、SGML では特定の文書型定義に含まれる一連の要素を標準化していることです。

SGML 文書とその後の XML 文書の型は、事前定義された標準の要素一式を使用するように設計されているとは言え、これらの要素を定義する外部リソースを参照することによって、カスタム要素定義を追加することもできます。しかし、カスタム要素の定義を既存の DTD やスキーマに追加するという考えは、通常は好ましくありません。それにはさまざまな理由がありますが、最も重要な理由としては以下のものが挙げられます。

• 文書が標準以外の要素を使用すると、DocBook や DITA などの標準の文書型に適合しなくなるため。
• DTD またはスキーマを拡張すると、デフォルトの DTD またはスキーマを使用する他の機関や企業と文書を交換できる可能性が限られてしまうため。非標準要素の定義も併せて交換したとしても、文書を正常に交換するためには、カスタマイズがさらに必要となります。
• 新規要素をサポートさせるために、標準文書型を操作するように設計されたツールを拡張しなければならなくなるため。オープンソースのツールであれば比較的簡単に拡張できますが、独自仕様のクローズド・ソース・ツールでは、拡張は不可能です。

この記事では、事前処理のステップによって、特定の対象読者や出力フォーマットには適用されない条件付きテキストを除外する方法を説明します。一部のグラフィカル XML 文書作成用ツールではこれと同等のソリューションを提供するために、ユーザーが出力生成プロセス中に使用する変数を設定できるようにしていますが、この記事では特定の文書作成用ツールがサポートするメカニズムに限った方法ではなく、それよりも一般的な事前処理手法に焦点を当てます。この方法であれば、広範なオープンソースの XML 文書作成用ツールで使用することができます。

上に戻る

DocBook 要素の共通属性

ご想像のとおり、それぞれの XML 要素の属性は、その特定の XML 要素のタイプや用途に応じて異なります。その一方、XML 文書作成用スキーマや、この連載で焦点としている DocBook 文書型などの DTD でも、共通属性を一式、定義しています (詳細は「参考文献」を参照)。これらの共通属性はあらゆる XML 要素で使用可能であり、通常は、特定の要素の表示に固有の情報やターゲットに固有の情報を識別するために使用されます。これらの共通属性には以下のものがあります。

• arch: この属性が指定されている要素の内容が適用されるコンピューター・システムまたはプロセッサーのアーキテクチャーを識別します。
• audience: この属性が指定されている要素の内容が適用される対象読者を識別します。
• condition: アプリケーション固有のローカル・コンテンツのカスタマイズに使用します。
• os: この属性が指定されている要素の内容が適用されるコンピューター・オペレーティング・システムを識別します。
• revision: この属性が指定されている要素の内容が適用される特定のソフトウェアまたは文書のリビジョンを識別します。
• vendor: この属性が指定されている要素の内容が適用されるハードウェアまたはソフトウェアのベンダーを識別します。

これらの属性のどれに対しても有効な値を定義した上で、その特定の属性に対して他の値を持つ要素を破棄するプリプロセッサーを実装することで、簡単に文書に条件を設定することができます。カスタマイズにどの属性を使うかは完全に文書の作成者に委ねられますが、通常は、これらの属性のうち、どの属性が、条件を設定する要素のタイプに最適であるか、またカスタマイズの目的に最適であるかによって左右されます。この記事では、指定された出力/表示フォーマットに対して一般的な条件を設定する例として、汎用的な condition 属性を使用します。

この後の 2 つのセクションでは、このセクションで説明したような属性を使用して、特定の要素を識別したり、要素に含まれるコンテンツのフラグメントを条件付きで識別したりする方法を説明します。

上に戻る

要素全体を条件付きにする

前のセクションで説明した共通属性は、特定の対象読者または出力フォーマットに関連付ける必要がある文書の部分を容易に識別する手段となります。このセクションでは condition 属性を例として用いますが、サイトでその属性がすでに使用されているのでない限り、前のセクションで説明した共通属性のどれを使っても構いません。

条件付きの要素によくあるタイプは、別の表示フォーマットで使用するように設定されたときに、文書内に表示されるようになるテキストを含んだ要素です。例えば、オンラインで使用するように設計された文書には、読者がナビゲートしやすいように各セクションの終わりに次のセクションへのリンクが記載されていることがよくあります。例えば、以下のようなリンクです。

<para>
To proceed to the next section of this tutorial, click
<link linkend="link-to-next-section">here</link>.
</para>

この情報はオンライン文書では役に立ちますが、これと同じ文書を Adobe® PostScript® や PDF 文書のフォーマットにする場合には、この情報は冗長であるだけでなく、混乱を招くことになります。文書がオンラインでの表示用に設定されている場合にだけ、文書のこの部分を使用するものとして識別するには、以下の例に示すように、<para> 要素に condition="online" 属性を追加します。

<para condition="online">
To proceed to the next section of this tutorial, click
<link linkend="link-to-next-section">here</link>.
</para>

上に戻る

文書のフォーマット設定プロセスに事前処理を追加する

前のセクションで説明したように、特定の要素に属性を追加するだけで文書作成用ツールには十分というのであれば話は簡単ですが、ほとんどの場合、そうはいきません。この類の条件設定を利用するには、別の表示フォーマットに文書のフォーマットを設定するときには、文書の中で条件に当てはまらない部分を破棄する小さな XSL スクリプトを作成する必要があります。リスト 1 に、condition 属性が print 以外の値に設定されている要素を破棄する XSL スクリプトの例を記載します。

	
      <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
                         xmlns:xi="http://www.w3.org/2003/XInclude">
      <xsl:output method="xml" omit-xml-declaration="yes" indent="yes"/>
      <xsl:preserve-space elements="*"/>

      <xsl:template match="*|@*">
        <xsl:variable name="_element">
          <xsl:value-of select="name()" />
        </xsl:variable>
        <xsl:variable name="_condition">
          <xsl:value-of select="@condition" />
        </xsl:variable>
        <xsl:choose>
          <xsl:when test="$_condition = ''">
            <xsl:copy>
              <xsl:apply-templates select="@* | * | text() | comment()" />
            </xsl:copy>
          </xsl:when>
          <xsl:when test="$_condition = 'print'">
            <xsl:copy>
              <xsl:apply-templates select="@*|node()" />
            </xsl:copy>
          </xsl:when>
          <xsl:otherwise>
            <xsl:message> Skipping <xsl:value-of select="$_element"/></xsl:message>
          </xsl:otherwise>
        </xsl:choose>
      </xsl:template>

    </xsl:stylesheet>

注: このスクリプトは読み易さを意図して記述されており、簡潔さを意図したものではないため、単純化することができます。

リスト 1 のスクリプトは前述の例を引き継いでおり、要素の condition 属性が印刷以外の出力フォーマットをターゲットとしている場合、その要素を識別して破棄します。このターゲット設定によって、前の「オンライン専用」の例に記載された内容は、その condition 属性の値が online であることから削除されます。スクリプトの最初の部分では各要素を処理し、その要素に関連付けられた変数に要素の名前および condition 属性の値を割り当てます。スクリプトの残りの部分では、condition 属性の値を基準とした条件で要素の内容を出力します。condition 属性が存在しない場合、あるいはこの属性の値が print である場合には、その要素がスクリプトの出力にコピーされます。condition 属性にその他の値が設定されていると、それに関連付けられた要素が出力内で抑止された上で処理が続行されます。

このようなスクリプトを簡単に文書生成プロセスに統合するには、Makefile の PDF または PostScript 文書を生成する部分にこのスクリプトを追加してください。そして、このスクリプトを使用して入力文書を処理し、その出力をファイルにリダイレクトした上で、ファイルのフォーマットを適切に設定するようにします。

リスト 2 に記載する XSL スクリプトは上記と同じですが、condition 属性が online 以外の値になっている要素を破棄するようにカスタマイズされています。オンライン文書を作成する際の Makefile ターゲットにこのスクリプトを追加すれば、前のコード・サンプルに記載されているような要素をオンライン専用として組み込むことができます。

	
      <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
                         xmlns:xi="http://www.w3.org/2003/XInclude">
      <xsl:output method="xml" omit-xml-declaration="yes" indent="yes"/>
      <xsl:preserve-space elements="*"/>

      <xsl:template match="*|@*">
        <xsl:variable name="_element">
          <xsl:value-of select="name()" />
        </xsl:variable>
        <xsl:variable name="_condition">
          <xsl:value-of select="@condition" />
        </xsl:variable>
        <xsl:choose>
          <xsl:when test="$_condition = ''">
            <xsl:copy>
              <xsl:apply-templates select="@* | * | text() | comment()" />
            </xsl:copy>
          </xsl:when>
          <xsl:when test="$_condition = 'online'">
            <xsl:copy>
              <xsl:apply-templates select="@*|node()" />
            </xsl:copy>
          </xsl:when>
          <xsl:otherwise>
            <xsl:message> Skipping <xsl:value-of select="$_element"/></xsl:message>
          </xsl:otherwise>
        </xsl:choose>
      </xsl:template>

    </xsl:stylesheet>

リスト 1 とリスト 2 の XSL コードを比較すると、その唯一の違いは 1 つの語句だけです。このことから、双方のコードは、XSL つまりは xsltproc に提供されたパラメーター (stringparam) のサポートによる単純化の対象としては最適な候補となります。上記の例はわかりやすさを目的とした例であり、この記事は簡潔な XSL を作成するための短期集中コースではないので、この単純化については読者の皆さんの演習として残しておきます。

上に戻る

コンテンツのフラグメントを条件付きにする

前のセクションでの例は、属性の値に応じて要素全体を組み込むか、または除外するかを制御するには最適ですが、大抵の条件付き XML 文書では、別の要素に含まれるテキストの部分にも条件を設定する必要があります。最も頻繁に必要となるのは、パラグラフ内の特定のコンテンツをカスタマイズすることです。このようなカスタマイズは、以下の 2 つの方法で簡単に行えます。

• パラグラフ内に表示可能な要素に条件を設定する
• <phrase> 要素を使用して、パラグラフ内のテキストの部分に条件を設定する

パラグラフ内に表示可能な要素に条件を設定するには、パラグラフ内の該当する要素に、条件を設定するための属性と適切な値を追加します。例えば、リスト 3 に記載する文書フラグメントには、パラグラフ内に条件付き <mediaobject> 要素があります (読みやすいようにフォーマットを変更してあります)。

	
    <para>
      To create a new file, click the <emphasis
      role="bold">Add</emphasis> icon 
      (<mediaobject>
          <imageobject audience="online">
               <imagedata fileref="add.gif"/>
          </imageobject>
          <imageobject audience="print">
               <imagedata fileref="../../images/add.gif" />
          </imageobject>
        </mediaobject>)
      beside the <emphasis role="bold">New File</emphasis> menu entry.
    </para>

ここでは主に例として使用していますが、<mediaobject> 要素に条件を設定すると、それぞれの表示フォーマットに応じた異なるパスでグラフィックの位置を指定することができます。上記の場合、オンライン文書では特定の Web サーバーまたは仮想 Web サーバー上のグラフィックの保管場所にあるグラフィックを見つける一方、印刷文書ではフォーマット設定用の特定ディレクトリーにあるグラフィックを見つけます。

条件付きテキストのセクションを識別するために <phrase> 要素を使用すると、さらに興味深いことになります。<phrase> 要素では、パフグラフよりも小さい特定の範囲またはスパンのテキストを識別できるため、文書に条件を設定するには申し分ありません。リスト 4 (読みやすいようにフォーマットを変更してあります) に、単語に条件を設定することによって、それぞれの表示フォーマットに一層特化した文書にする例を記載します。

	
    <p>
       See the 
         <link linkend="target-id">
              introduction to this 
              <phrase audience="online">portion</phrase>
              <phrase audience="print">chapter</phrase>
              of the documentation
         </link>
       for more information.
    </p>

上に戻る

まとめ

XML の強力さと柔軟性、一連の既存の標準、そして XML 文書を操作、変換するための豊富なツール・セットによって、文書を作成および管理するための強力な環境が提供されます。この記事で説明した属性および手法を使用すれば、特定の対象読者やコンピューター・システム、あるいは表示フォーマットに応じて異なる内容が含まれる条件付き文書を作成するのは簡単です。そして単純な事前処理ステージを追加するか、あるいは文書生成プロセスで使用するための変数を設定することで、特殊化された出力を生成する単一ソース・ドキュメンテーションを作成し、保守することができます。この機能は、文書の開発および保守を単純化しながらも、その文書の特定ユーザーの要件にできる限り対応するという、文書作成に伴う従来からの問題に極めて有効かつ柔軟なソリューションを提供します。

上に戻る

ダウンロード

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

参考文献

学ぶために

• 「XML での文書生成と情報の再利用: 第 1 回 XML を使用した文書のパブリッシング」(William von Hagen 著、developerWorks、2009年3月): UNIX® または Linux™ システムで XML パブリッシング・システムを簡単にアセンブルしてください。無料のオープンソース・パッケージを XML と組み合わせることで効率的に情報を再利用し、1 つのソース文書のセットからさまざまなフォーマットの文書を生成できるようになります。
  
  
• 「XML での文書生成と情報の再利用: 第 2 回 XML 文書の情報再利用」(William von Hagen 著、developerWorks、2009年3月): XML 文書およびその一部を再利用するために構造化しましょう。この 3 回連載の第 2 回では、XInclude を使って外部文書を組み込み、XPointer を使って他の文書の小さなフラグメントを大きな文書に組み込む方法を説明しています。
  
  
• DocBook: The Definitive Guide: SGML と XML での DocBook マークアップについての情報を網羅しているガイドです。このガイドの全文はオンラインでも見られますが、DocBook でのパブリッシング作業に真剣に取り組むつもりであれば、一冊購入する価値はあります。
  
  
• DocBook XSL: The Complete Guide: DocBook スタイルシートとパブリッシングについての最も信頼できる情報を入手してください。このガイドも同じく、全文がオンラインで見られますが、DocBook でのパブリッシング作業に真剣に取り組むつもりであれば一冊購入する価値があります。
  
  
• Common attributes: DocBook XML の共通要素のリストを参照してください。
  
  
• GML: Generalized Markup Language に関するウィキペディアのエントリーを読んでください。
  
  
• IBM XML 認定: XML や関連技術の IBM 認定技術者になる方法について調べてください。
  
  
• XML Technical library: 広範な技術に関する記事とヒント、チュートリアル、標準、そして IBM Redbooks については、developerWorks XML ゾーンを参照してください。
  
  
• developerWorks の Technical events and webcasts: これらのセッションで最新情報を入手してください。
  
  
• Technology bookstore: XML、DocBook、その他の技術に関する本を参照してください。
  
  
• developerWorks podcasts: ソフトウェア開発者向けの興味深いインタービューとディスカッションを聞いてください。
  
  

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

• DocBook DTD: 最新バージョンをダウンロードして、早速使い始めてください。
  
  
• DocBook XSL スタイルシート: 最新リリースをダウンロードしてください (DocBook Project site > file releases の順に進み、docbook-xsl を選択します)。
  
  
• nXML mode: Emacs テキスト・エディターで XML 文書を編集する予定であれば (そうすべきです)、Emacs 対応 XML mode の最新バージョンをダウンロードしてください。
  
  
• IBM 製品の評価版: DB2®、Lotus®、Rational®、Tivoli®、および WebSphere® のアプリケーション開発ツールとミドルウェア製品を体験するには、IBM SOA Sandbox のオンライン試用版をダウンロードするか、検討してみてください。
  
  

議論するために

• XML ゾーンのディスカッション・フォーラム: XML 関連のフォーラムに参加してください。
  
  
• developerWorks XML zone: Share your thoughts: この記事についてのご意見、ご感想をお寄せください。このフォーラムを管理する XML ゾーンの編集チームは、読者からの投稿をお待ちしています。
  
  
• developerWorks blogs: developerWorks blogs から developerWorks コミュニティーに加わってください。
  
  

著者について

この記事を評価する

コメント

上に戻る

目次

• 単一ソース・ドキュメンテーションとは
• DocBook の要素と属性
• 文書のカスタマイズに考えられる代替手段
• DocBook 要素の共通属性
• 要素全体を条件付きにする
• 文書のフォーマット設定プロセスに事前処理を追加する
• コンテンツのフラグメントを条件付きにする
• まとめ
• ダウンロード
• 参考文献
• 著者について
• コメント