レベル: 初級 Uche Ogbuji (uche@ogbuji.net), Consultant, Fourthought, Inc.
2001年 2月 01日 Uche Ogbuji氏は、Resource Description Framework (RDF)を使用してXSLTスタイル・シートの文書化を行なう方法を紹介し、この構造化された文書で構成できるきわめて有用な応用例をいくつか説明します。この記事は、XSLTとRDFに関する基本的な知識を前提としています。
他のプログラミング・システムと同じく、XSLTスタイル・シートにおいても、良質の文書化は重要です。適切なXMLコメントを追加すれば、スタイル・シートを文書化できます。しかし、コメントを構造化すれば (Javadocのアプローチに似ている)、ドキュメンテーションを自動的に生成することも可能になります。
残念ながら、文書化のためにコメントを利用することには、いくつかのデメリットがあります。1つの点として、コメントは、XMLプロセッサーによる処理で失われることがあります。コメントおよび処理命令についてのXSLTのデフォルトの処理は、それらを無視することだからです。別の点として、構造化されたコメントを利用してドキュメンテーションを生成したり、対話式の相互参照やコード・ブラウザーなどを作成したりすることにした場合、その構造化されたコメントのための構文規則を考案しなければなりません。XMLは、結局のところデータ・フォーマット言語なので、XMLを利用して構造化されたコメントの形式を作成することは可能です。ただし、混乱を引き起こさないようなインプリメントが大切です。
都合の良いことに、XSLTには外部マークアップのためのメカニズムがあり、状況に応じて外部マークアップをプロセッサーに無視させることができます。あるいは、そのメカニズムを特定のプロセッサーでは特別なものとして扱い、他のプロセッサーでは無視する、ということも可能です。重要な要件は、その特別なマークアップをXSLTとは別の名前空間に定義するということです (そして、現実には、XSLT変換の入力や結果で使われる他のすべての名前空間とも異なる名前空間にするべきです)。
ここまでくると、あとは、マークアップ・ベースのコメントのための名前空間とボキャブラリーを選ぶだけです。Resource Description Framework (RDF) は、W3Cによって提供されている標準的なメカニズムで、ちょうどこの目的に適しています。Webリソースに関連したメタデータを記述するための規格なのです。コードのコメントはまさにメタデータであり、RDFは、コメントを十分に利用するのに必要な表現力とサポートを備えています。
最上位レベルのドキュメンテーション
最も簡単なアプローチは、変換スタイルシートの最上位レベルにのみドキュメンテーションを置くことです。その場合、XSLTプロセッサーは、変換スタイル・シートの最上位レベルにあるXSLT以外の名前空間の要素を無視する必要があります。
リスト1にあるコード例は、フィボナッチ数列 (1、1、2、3、5、8、13、21、34、55、89、144...) を生成します。(コンピューター・サイエンスの分野で例としてよく取り上げられるこの数列を初めて見る読者のために説明を加えると、フィボナッチ数列とは、「1、1」で始まる数列で、次の数値は、先行する2つの数値の和として計算されます。)この変換スタイル・シートは、生成される数値の上限を設定する最上位レベルのパラメーターをとります。そして、RDFと、私が選んだボキャブラリーを使って、コメントが付けられています。
リスト1. RDFドキュメンテーションが組み込まれた変換スタイル・シート
<?xml version="1.0"?>
<xsl:transform
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/elements/1.1"
xmlns:doc="http://schemas.uche.ogbuji.net/rdfexample/"
version="1.0"
>
<rdf:Description
about="http://uche.ogbuji.net/articles/xsldoctip/fibonacci.xslt">
<dc:Creator>Uche Ogbuji</dc:Creator>
<dc:Date>2001-01-27</dc:Date>
<dc:Description>A Fibonacci series generator</dc:Description>
<dc:Subject>Fibonacci</dc:Subject>
<doc:OutputMethod>text</doc:OutputMethod>
<doc:Param>
<doc:Name>upper-bound</doc:Name>
<doc:Default>200</doc:Default>
<doc:Description>The highest number generated
will be lesser than this value.</doc:Description>
</doc:Param>
</rdf:Description>
<xsl:output method="text"/>
<xsl:param name="upper-bound" select="200"/>
<rdf:description ID="tpl1" doc:construct="template">
<doc:Match>/</doc:Match>
<doc:Description>Initiates the fibonacci generation,
producing the initial 1 and 1 of the series.</doc:Description>
</rdf:description>
<xsl:template match="/">
<xsl:text>1 1</xsl:text>
<xsl:call-template name="fibonacci-next">
<xsl:with-param name="n1" select="1"/>
<xsl:with-param name="n2" select="1"/>
</xsl:call-template>
</xsl:template>
<rdf:description ID="fibonacci-next" doc:construct="template">
<doc:Name>fibonacci-next</doc:Name>
<doc:Description>
Print the next number in the fibonacci series.
</doc:Description>
<doc:Param>
<doc:Name>n1</doc:Name>
<doc:Description>The second to last number generated.</doc:Description>
</doc:Param>
<doc:Param>
<doc:Name>n2</doc:Name>
<doc:Description>The last number generated.</doc:Description>
</doc
</rdf:description>
<xsl:template name="fibonacci-next">
<xsl:param name="n1"/>
<xsl:param name="n2"/>
<xsl:variable name="next" select="$n1 + $n2"/>
<xsl:if test="$next < $upper-bound">
<xsl:text> </xsl:text>
<xsl:value-of select="$next"/>
<xsl:call-template name="fibonacci-next">
<xsl:with-param name="n1" select="$n2"/>
<xsl:with-param name="n2" select="$next"/>
</xsl:call-template>
</xsl:if>
</xsl:template>
</xsl:transform>
|
まず、transformルート要素に名前空間が追加されていることに注目してください (リスト1で赤色のテキストになっている)。RDF名前空間、Dublin Core名前空間、そして変換スタイル・シートを文書化するためのカスタム名前空間があります (参考文献 を参照)。
さらに、変換スタイル・シートの見出しとして、RDFによる記述を追加しておきました (リスト1で青色のテキストになっている)。このRDF記述は、変換ファイルそのものに関する説明になっており、その変換ファイルがhttp://uche.ogbuji.net/articles/xsldoctip/fibonacci.xslt というURLから入手できることを前提としています。この記述にある最初のいくつかのステートメントでは、Dublin Core (DC) ボキャブラリーを指定して、このファイルの著者や所有権を表現するDCドメインを示しています。このように記述することの利点は、この変換ファイルを、一般的なDCメタデータの要素セットでマークアップされた他の文書と一緒に、統一的に登録して分類できるところにあります。
その後に、変換スタイル・シートを文書化するためのカスタム・ボキャブラリーのステートメントがいくつか続きます。1つのステートメントは、この変換でテキスト出力が生成されることを定義しています。その後のステートメントは、最上位レベルのupper-bound パラメーターの名前やデフォルト値に関するコメントになっています。
各テンプレートの前にも、ドキュメンテーションのブロックを置きました(リスト1で緑色のテキストになっている)。それぞれのドキュメンテーションには、RDFのIDを含めました。ドキュメンテーションそのものを最良の情報源にするためです。文書化の対象になるテンプレートが名前付きのテンプレートであれば、その名前をIDとして使用します。そうでない場合は、汎用的な一意のIDを作ります (この例では、tpl1)。doc:construct="template" という表記は、文書化の対象になる構成要素を示しています。もちろん、ドキュメンテーションのブロックと変換スタイル・シートの要素を結び付けるために、別の方法を用いてもかまいません。たとえば、RDFタイプを使用してタイプを示し、XPointerを使用してテンプレートを表す実際のXML要素を参照することができます。
ドキュメンテーション・ブロックには、テンプレートのname 属性またはmatch 属性のいずれかを組み込み、テンプレートの自由な説明文を記入するdescription要素を組み込みます。さらに、パラメーターがある場合は、その名前と説明を記述します。
ここで紹介した方式全体は、1つの可能性を示すものに過ぎません。RDFは柔軟性が高いため、ドキュメンテーションをどこに置くか、ドキュメンテーションのブロックを変換スタイル・シートの要素にどのように結び付けるかなどについて、それこそ無数の種類の方式を利用できます。ドキュメンテーションの内容をもっと豊富にすることも、逆にもっと簡潔にする (たとえば、個々のテンプレートのコメントをすべて、変換ファイルについて説明するメインの要素に含めてしまう) ことも可能です。
個々の命令について文書化する
これまでは、最上位レベルにドキュメンテーションを置く方法だけを紹介しました。テンプレートの内側やその他の場所など、XSLT命令と拡張要素だけが許されている場所にドキュメンテーションを置くには、ドキュメンテーションの名前空間を拡張名前空間として指定することができます。
リスト2の例では、見やすくするために、最上位のドキュメンテーションの一部を省略してあります。
リスト2. 同じスタイル・シートに組み込みドキュメンテーションを追加する
<?xml version="1.0"?>
<xsl:transform
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/elements/1.1"
xmlns:doc="http://schemas.uche.ogbuji.net/rdfexample/"
version="1.0"
extension-element-prefixes="doc"
>
<xsl:output method="text"/>
<xsl:param name="upper-bound" select="200"/>
<xsl:template match="/">
<xsl:text>1 1</xsl:text>
<xsl:call-template name="fibonacci-next">
<xsl:with-param name="n1" select="1"/>
<xsl:with-param name="n2" select="1"/>
</xsl:call-template>
</xsl:template>
<rdf:description ID="fibonacci-next" doc:construct="template">
<doc:Name>fibonacci-next</doc:Name>
<doc:Description>
Prints the next number in the Fibonacci series.
</doc:Description>
</rdf:description>
<xsl:template name="fibonacci-next">
<xsl:param name="n1" select="1"/>
<xsl:param name="n2" select="1"/>
<doc:InlineComment>$next is the number
generated from the parameters by addition</doc:InlineComment>
<xsl:variable name="next" select="$n1 + $n2"/>
<doc:InlineComment>The termination condition:
stop when $next exceeds the upper bound</doc:InlineComment>
<xsl:if test="$next < $upper-bound">
<xsl:text> </xsl:text>
<xsl:value-of select="$next"/>
<doc:InlineComment>The recursive call</doc:InlineComment>
<xsl:call-template name="fibonacci-next">
<xsl:with-param name="n1" select="$n2"/>
<xsl:with-param name="n2" select="$next"/>
</xsl:call-template>
</xsl:if>
</xsl:template>
</xsl:transform>
|
リスト2に掲載した2番目の例では、ルート要素のextension-elements-prefixes 属性に注目してください。この設定により、ドキュメンテーション用のカスタム名前空間に属する命令要素が、拡張要素として取り分けられます。これには、便利な効果があります。XSLTプロセッサーは、処理方法がわからない拡張要素を無視してくれるのです (フォールバックが指定されている場合を除く)。
追加したドキュメンテーションは、fibonacci-next テンプレート内のインラインに置かれています。今回はRDF形式でないことに注目してください。インラインのコメントにRDFを使うのはおそらく行き過ぎで、冗長になりすぎるでしょう。しかし、リスト2では、RDFで使用したのと同じカスタム名前空間を使用しています。これにより、豊富な機能を持つドキュメンテーション・システムにおいて、インラインのドキュメンテーションを最上位レベルのドキュメンテーションと同じ仕方で管理するのが容易になります。たとえば、どちらも同じ色で強調表示したりできるわけです。
結論
文書化に最上位の要素を使用すると、ドキュメンテーションを十分に構造化するのに役立ち、一般的なXML処理によってドキュメンテーションを維持管理できるようになります。文書化の方式としてRDFを使用すると、プログラマーやコード・リポジトリーが、RDFの照会やビジュアライズ (表示) やその他の操作を実行するための多くの新しいツールを利用できます。RDFがかなり冗長なのは確かですが、率直に言って、XMLそのものも冗長ではないでしょうか?
おそらく、XSLTを文書化するこのアプローチを利用する最善の方法は、この記事で私が例として用いた方式を、単なる出発点として利用することでしょう。XSLTとRDFの柔軟性をもってすれば、この方式を読者のニーズに合わせて大幅に改良し、ついには最初に例とは似ても似つかないものにすることさえ可能なはずです。
参考文献
- W3CのXSL のページには、XSLTの仕様、チュートリアル、各種の関連記事、XSLTのインプリメンテーションなど、XSLTに関連した多くの有用なリソースへのリンクが掲載されています。
- xml.comには、RDFのチュートリアルがあります。
- この記事のサンプルで使用したXSLTプロセッサー4XSLTは、Python開発者向けに私の会社が公開しているオープン・ソースのXMLツール・セット4Suite に含まれています。
- フィボナッチ数列についてもっと知りたいという読者は、Fibonacci Numbers and the Golden Section という、そのテーマに関する包括的な情報サイトを読破できることでしょう。
著者について  | 
| | Uche Ogbuji氏は、Fourthought, Inc. のコンサルタント兼共同設立者です。この会社は、企業のナレッジ・マネジメントのためのXMLソリューションを専門とするソフトウェア・ベンダー兼コンサルタント会社です。Fourthoughtでは、XML、RDF、およびナレッジ・マネジメント・アプリケーション用のオープン・ソース・プラットフォームである4Suiteを開発しています。Ogbuji氏は、ナイジェリア出身のコンピューター・エンジニア兼ライターで、現在は、米国コロラド州ボールダーに住み、そこで働いています。Ogbuji氏の連絡先はuche.ogbuji@fourthought.com です。 |
記事の評価
| 
