XSLT 3.0デバッグまわり Advent Calendar 2025 の5日目。
今までのXSLTでのドキュメント
コメント（非xsl:comment）
つまり<!--と-->で囲ってコメントをする。
<!-- hogeのためのテンプレート -->
<xsl:template name="mytemplate">
...
</xsl:template>
正しい使い方であるのですが、問題は多分2点。
- 大規模にテンプレートごとコメントアウトを行いたいときなどに邪魔
- ドキュメントのための記法は定式化されていないので、綺麗なドキュメントを得るにはオレオレ処理系を実装する必要がある
前者は次のようなとき。コメントの開始と終了が被って不正なXMLになる。
<!-- 確認のためコメントアウト
<!-- hogeのためのテンプレート -->
<xsl:template name="mytemplate">
...
</xsl:template>
...
-->
http://www.oxygenxml.com/ns/doc/xslの要素で書く
Oxygen XMLを使っている場合、ドキュメント用の語彙が用意されていて、しかもドキュメント生成機能を使ったときその部分も良い感じにしてくれるし、importやparamなど、自分で書かなくてもXSLT構造を良い感じにしてくれます。
欠点は勿論Oxygenがないとドキュメント化ができない、基、自分で処理を書かなければいけないことです。まあ自分で何とかできる道筋が立て易いのはXMLを使って書く言語ならではですが。
独自名前空間の独自要素で書く
↑のOxygenの名前空間の語彙で書く方法ですが、Oxygenだけ特別なことができるとかではなくて、XSLT処理系は独自の名前空間の要素を無視します。処理系を改造しているとまた別（Saxoだと有償のPE以上が要るはず）ですが、「XSLTの処理としては無視される」ので、処理対象のXMLとして読み込むときに良い感じになるようにすれば、Oxygenと同様のドキュメント機能は実装できる、理論上は。まあRELAX NG処理系をXSLTで実装するよりは明らかにeasyではあるはず。
後述のxsl:noteに近いのですが、その部分のspecificationに↑の欠点が挙げられています。
- 基本的にトップレベル（
<xsl:stylesheet>などルート直下）にしか書けない - 独自名前空間を使うことはコードのセマンティクスに変更を起こしている
XSLT 4.0のxsl:note
XSLT 4.0は現在draftで、たとえばStreamabilityなんかをdropする考えがKay博士から出たり安定していませんが、xsl:noteはほぼ確実に入るはずです。
ということで重要なポイントは次の通り；
- XSLT名前空間
- ルート要素の外でなければ、どこにでも（
xsl:templateの中などでも）書いてよい
XSLT処理系はこの要素とその内容を無視する（XML整形式は崩れないよう保つ必要がある）ので、プログラミング言語ありがちな独自フックは書けません。
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="4.0">
<xsl:note attribute-mo="jiyuu">いえーい</xsl:note>
<xsl:template name="hoge">
<xsl:note xmlns:html="http://www.w3.org/1999/xhtml">こういうところにも<html:strong>書ける</html:strong></xsl:note>
...
</xsl:template>
</xsl:stylesheet>
参考資料
組版・ドキュメントに関連する記事を投稿するコミュニティ、を予定しています。 文章表現よりはマークアップ・文章構造・自動組版に焦点を絞れると他コミュニティと差別化できると思っていますが如何。
Discussion