ステップ4：どのように？
最後に、プログラムの動作方法についてもいくつかオプションを指定する必要があります。
- 処理対象のサブディレクトリ――
sourcePath内のどのサブディレクトリをXmlTransformで処理するかを、dirListオプションを使用して明示的に指定します。この文字列はsub1, sub1/subsub1, sub2, sub3のように、サブディレクトリ名（sourcePathより下の部分）をコンマまたはセミコロンで区切って指定します。省略するとsourcePath自体が処理されます（サブディレクトリは処理されません）。
- プレビューモード――XmlTransformの使い方に慣れるまで、あるいは新しく設定したオプションを確認したい場合などは、プログラムの処理内容を実際に動作させずにチェックできます。この制御は
enableフラグで行います（デフォルト値はTrue）。enableをFalseにセットすると、XmlTransformは実際には動作せずに、実行する処理の内容をレポートします。
- 節約モード――XmlTransformは節約家なので必要なことしかしません。つまり、前回実行した際の処理を追跡して、それ以降に変更されたファイルだけを検証または変換します。これを変更し、すべてのファイルを強制的に処理する場合は
processAllフラグを使用します。デフォルト値はFalseです。
- サブディレクトリの深さの追跡――高度な目的に使用するオプションです。XmlTransformで処理するサブディレクトリの深さを追跡します。これを利用すると、位置情報を必要とするアクションやパスを定義できます。たとえば、HTMLを出力ファイルとして生成するとき、インクルードされるファイルへの相対パスを指定したい場合に、追跡した深さを使用して"../../.."などの文字列を正しく生成し、ファイル名の先頭に付加することができます。以下に、このようなパスを正確に生成する簡単なXSLを示します。
<xsl:template name="buildpath"> <xsl:param name="level"></xsl:param> <xsl:if test="$level > 0">../<xsl:call-template name="buildpath"> <xsl:with-param name="level"> <xsl:value-of select="$level - 1"/> </xsl:with-param> </xsl:call-template> </xsl:if> </xsl:template>
startDepthオプション（デフォルト値は0）を使用して、ルート（sourcePath）と参照先のインクルードファイルの場所の間のオフセットを指定できます。たとえば、インクルードファイルがHTMLファイルの1つ上のディレクトリに含まれる場合は、startDepthに1を指定して、上記のXSL関数でパスに".."を1つ追加するよう指示します。ここで注意したいのは、XmlTransformが処理対象のサブディレクトリの深さをXSL変換に渡すときには、levelパラメータを使用して、この開始位置までのオフセットとして渡すという点です。XSL内で
call-template要素を使用するとき、先の例のパス文字列を作成するために$levelを引数として渡しているのはこのためです。これは一例に過ぎません。$levelパラメータには他の使い方もあります。たとえば、XSL内で現在のレベルに応じて異なるテンプレートを呼び出すことなども可能です。- カスタムなXSLパラメータの定義――高度な目的に使用するオプションです。現在のサブディレクトリレベルをパラメータとしてXSLに渡せるのと同様に、
xslParmListオプションを使用すれば、XSLにユーザー定義の値を渡すこともできます。これには、パラメータをコンマまたはセミコロンで区切って設定します。各パラメータは「名前:値」の形式で設定する必要があり、値にコンマやセミコロンを含めることはできません。これは著作権の日付やリリースのバージョン番号などの値（例：xslParmList=copyright:2006,relVersion:v1.2）を渡す場合に便利です。
また、前述のように、XmlTransformはジェネレータIDの文字列を作成します。この文字列は前述の目次ファイルの上書きを防ぐ仕組みの中で自動的に利用できます。このパラメータにアクセスするには、最初に以下の行をXSLに含めます。
<xsl:param name="generator"/>
続いて、HTMLやXHTMLを作成する場合であれば以下のように定義します。
<meta content="{$generator}" name="myGenerator"/>
XmlTransformのオプションは数が多く、また、出力結果からオプションの効果を見て取ることが難しいため、習得までの道のりは非常に険しいと言えます。しかし、何か苦労している問題があるなら、XmlTransformで解決できないか調べてみてください。時間を大幅に節約できるかもしれません。筆者はもともとXmlTransformを自身のオープンソースのWebサイトで静的なページを生成するために使用していました。ページをHTMLではなくカスタムなXMLダイアレクトで手早く作成でき、ヘッダ、フッタ、ページのリンク、著作権日付などを見栄え良く自動作成してくれるからです。
しかし、XmlTransformが便利なのはそれだけではありません。たとえば、C#のNdocや、JavaのJavaDocと同種のSQLドキュメントジェネレータとしても利用できます。「Add Custom XML Documentation Capability To Your SQL Code」の記事には、XmlTransformを使用したSQLドキュメントの作成方法が詳しく説明されています。この記事では、今回紹介したのと同じサンプルソースファイルが使用されているので、XmlTransformを別の方法で試してみるとよいでしょう。
リスト1 XSLTナビゲーション
<xsl:template name="navArrows"> <xsl:if test="$nextLink or $prevLink"> <span class="headerFont" style="margin-left:10px"> <xsl:attribute name="title"> Shortcut keys in Internet Explorer:<xsl:text> </xsl:text>1=First, 2=Previous, 3=Next, 4=Last, 5=Up </xsl:attribute> NAVIGATION: </span> <span> <xsl:if test="$firstLink"> <a href="{$firstLink}"> <img height="14" width="14" alt="first page in section" src="/image/firstButton.gif" /> </a> </xsl:if> <xsl:choose> <xsl:when test="$prevLink"> <a href="{$prevLink}"> <img height="14" width="14" alt="previous page" src="/image/prevButton.gif" /> </a> </xsl:when> <xsl:otherwise> <img alt="" width="14" height="14" src="/image/dot_clear.gif" /> </xsl:otherwise> </xsl:choose> <xsl:choose> <xsl:when test="$upLink"> <a href="{$upLink}"> <img height="14" width="14" alt="up one level" src="/image/upButton.gif" /> </a> </xsl:when> <xsl:otherwise> <img alt="" width="14" height="14" src="/image/dot_clear.gif" /> </xsl:otherwise> </xsl:choose> <xsl:choose> <xsl:when test="$nextLink"> <a href="{$nextLink}"> <img height="14" width="14" alt="next page" src="/image/nextButton.gif" /> </a> </xsl:when> <xsl:otherwise> <img alt="" width="14" height="14" src="/image/dot_clear.gif" /> </xsl:otherwise> </xsl:choose> <xsl:if test="$finalLink"> <a href="{$finalLink}"> <img height="14" width="14" alt="final page in section" src="/image/finalButton.gif" /> </a> </xsl:if> </span> </xsl:if> </xsl:template>
リスト2 XmlTransformのパラメータ
// switches indicate what to process --generateContents=true --xslTransform=true --validateInputToSchema=false --validateOutputToSchema=false // root of source xml tree --sourcePath=/devx/sqlDoc/sqlDocProject/XMLsrc // root of target html tree --targetPath=/devx/sqlDoc/sqlDocProject/api/sql --inExtension=xml --outExtension=html // Comma-separated list of directories in source tree to process. // Omit if processing everything (e.g. ".") // --dirList=. // name of XSLT file within each directory of dirList --xslName=translate.xsl // ignore datestamps if true --processAll=false // can opt to report on what will happen with a false value --enable=true // directories from the tree top back to relative root --startDepth=0 // xsl parms passed via comma-separated list of "name:val" entries --xslParmList=revdate:2007.11.01,copyright:2007,relVersion:0.95 // flag to indicate to put contents in parent or in same directory --contentsToParent=false // where to add a list of group files in a contents file --groupPlaceHolder=cc:files // where to put generator information in contents file --generatorNode=cc:generator // where to find the group identifier in each file --groupIdXpath=cc:cleanCodeDoc/cc:head/cc:group // bit combination of xxxx_DIAG values to enable DIAG_LEVEL=0x81a // to show all module versions VERSION_DIAG=0x800 // to show all configuration options INPUTOPTIONS_DIAG=0x400 XMLTRANSFORM_A_DIAG=0x2 XMLTRANSFORM_B_DIAG=0x4 XMLTRANSFORM_C_DIAG=0x8 XMLTRANSFORM_D_DIAG=0x10 XMLTRANSFORM_E_DIAG=0x20 XMLTRANSFORM_F_DIAG=0x40 // log and stdout OUTPUT_DIAG=9 // log and stderr OUTPUT_ERR=0xA
