Leider gibt es für XSLT keine standardisierten oder auch nur weitverbreiteten Regeln für die Dokumentation der Stylesheets. Ein Grund dafür könnte sein, dass einfach zu bedienende Werkzeuge nicht verfügbar sind. Für die Bespiele auf dieser Website habe ich mir noch einmal ein paar Ansätze angeschaut und mich dann für XSLStyle™ von G. Ken Holman entschieden, weil a) dieses Tool als XSL-Transformation direkt auf das Stylesheet selbst angewandt werden kann und b) XSLStyle™ auch noch ein paar Tests auf guten Programmierstil durchführt.

<OxygenXML/>-Transformations-Szenario für XSLStyle™

Die Dokumentation erfolgt über Elemente im http://www.CraneSoftwrights.com/ns/xslstyle-Namensraum, die unmittelbar vor dem zu dokumentierenden XSL-Element stehen. XSLStyle™ kann bei fehlender Dokumentation warnen. Weil bei mir das von XSLStyle™ vorgegebene Präfix xs: immer für den http://www.w3.org/2001/XMLSchema-Namensraum steht, habe ich das Präfix doc: verwendet.

Innerhalb der XSLStyle™-Elemente kann die Dokumentation in beliebigem Markup erfolgen, G. Ken Holman gibt Stylesheets für DocBook und DITA mit. Ich habe mich pragmatisch für DocBook entschieden, weil ich damit aus einem früheren Projekt etwas Erfahrung habe. Es steht ein großer Teil des DocBook-Vokabulars zur Verfügung; nachdem meine Experimente mit einem recht elaboriertem Markup (wie refentry und funcsynopsis) primär aufgeblähten Code hervorgebracht haben, schien mir eine stark vereinfachte Version jedoch die bessere Variante. Der Code aus einem der letzten Posts zum Dateien-Testen sieht mit Dokumentation so aus:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet
	version="2.0"
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns:xs="http://www.w3.org/2001/XMLSchema"
	xmlns:misc="http://www.expedimentum.org/XSLT/Misc"
	xmlns:saxon="http://saxon.sf.net/"
	xmlns:doc="http://www.CraneSoftwrights.com/ns/xslstyle"
	xmlns:docv="http://www.CraneSoftwrights.com/ns/xslstyle/vocabulary"
	exclude-result-prefixes="doc docv"
	extension-element-prefixes="saxon"
	>
	<!--  -->
	<doc:doc filename="files.xsl" internal-ns="docv" global-ns="doc misc" vocabulary="DocBook" info="$Revision: 29 $, $Date: 2009-05-03 02:11:03 +0200 (So, 03 Mai 2009) $">
		<doc:title>Dateien und Dateisystem</doc:title>
		<para>Dieses Stylesheet enthält Funktionen rund um das Dateisystem.</para>
		<para>Dieses Stylesheet unterliegt  mangels Schöpungshöhe keinen urheberrechtlichen Beschränkungen.</para>
		<revhistory>
			<revision>
				<revnumber>0.28</revnumber>
				<date>2008-05-03</date>
				<authorinitials>Stf</authorinitials>
				<revremark>erste Version mit Dokumentation</revremark>
			</revision>
		</revhistory>
	</doc:doc>
	<!--  -->
	<!-- __________     misc:file-exist()     __________ -->
	<doc:function>
		<doc:param name="href"><para>Pfad zur zu überprüfenden Datei (URI-encoded)</para></doc:param>
		<para>Diese Funktion überprüft, ob die angegebene Datei vorhanden ist. Das Ergebnis ist ein Wahrheitswert 
			(<code>xs:boolean</code>, <code>true()</code> oder <code>false()</code>). 
			<emphasis role="bold">Achtung!</emphasis> Diese Funktion erfordert bei Ausführung Saxon, 
			da die Saxon-spezifische Erweiterung <code>saxon:file-last-modified()</code>  verwendet wird.</para>
	</doc:function>
	<xsl:function name="misc:file-exists" as="xs:boolean">
		<xsl:param name="href" as="xs:string?"/>
		<xsl:value-of select="boolean(normalize-space(string(saxon:file-last-modified($href))))"/>
	</xsl:function>
	<!--  -->
</xsl:stylesheet>

Damit XSLStyle™ eine Dokumentation ausgibt, müssen der http://www.CraneSoftwrights.com/ns/xslstyle und ein weiter Namensraum für interne Zwecke (http://www.CraneSoftwrights.com/ns/xslstyle/vocabulary) im zu dokumentierenden Stylesheet deklariert werden. Außerdem erwartet XSLStyle™ am Anfang der Dokumentation ein <doc:doc/>-Element mit Basisinformationen, fehlt es (oder auch nur einzelne Attribute), gibt es bei mir merkwürdige Effekte.

Das vollständige Beispiel habe ich unter http://www.expedimentum.org/example/xslt/files.xsl abgelegt, die resultierende Dokumentation liegt unter http://www.expedimentum.org/example/xslt/doc/files.html. Hier bzw. hier gibt es ein etwas umfangreicheres Beispiel mit importierten Stylesheets.

Zum Schluss folgt noch eine Sammlung zufälliger Links zur XSL-Dokumentation, die bei der Recherche entstanden ist. Falls XSLStyle™ nicht passt, findet sich sicher eine geignetere Lösung. Mir hat XSLTdoc relativ gut gefallen, und mit einem Ant-Script lässt sich auch die umständliche Handhabung bändigen, leider lässt es sich nicht direkt als Transformation auf das zu dokumentierende Stylesheet anwenden.

• http://www.dpawson.co.uk/xsl/sect2/documentation.html: XSL-Dokumentation in den XSLT FAQ (englisch)
• http://www.bacman.net/apps/XSLdoc/: XSLdoc, ähnlich JavaDoc (englisch)
• http://xsltsl.sourceforge.net/docbook-extensions.html: DocBook Extensions For XSLT Stylesheet Documentation – Stylesheets in DocBook dokumentieren (englisch)
• http://www.linkwerk.com/pub/xslt/lib/xsltdoc/: xsltdoc — Literate XSLT Programming based on Namespaces (deutsch)
• http://www.pnp-software.com/XSLTdoc/: XSLTdoc – A Code Documentation Tool for XSLT (englisch)
• http://www.devx.com/getHelpOn/10MinuteSolution/20343/0/page/1: Document Your XSLT – eine ähnliche Lösung wie XSLTDoc (englisch)
• http://www.kanzaki.com/parts/xsltdoc.xsl: XSLT Stylesheet description stylesheet – ein weiteres Stylesheet, mit generischer Dokumentation

siehe auch: Florent Georges: XSLStyle and oXygen (englisch)

XSLT bietet recht wenig Möglichkeiten, mit der Außenwelt zu kommunizieren. Informationen über die Umwelt zur Laufzeit des Stylesheets lassen sich mit Bordmitteln nur in sehr geringem Umfang ermitteln, Wirkungen nur über die Dateiausgabe erzielen. Dies mag daher kommen, dass das funktionale Paradigma von XSLT Seiteneffekte verbietet, führt aber in der Praxis gelegentlich zu merkwürdigen Verrenkungen. Beispielsweise habe ich öfters das Problem, Stylesheets abhängig von der Existenz einer externen Datei aufzurufen. Bisher habe ich dazu in einer externen Anwendung ein XML mit Informationen zum Dateisystem erzeugt und dieses dann im XSLT ausgewertet. Das funktioniert ganz gut mit statischen Daten, bei häufigen Änderungen im Dateisystem ist dieses Verfahren aber zu umständlich.

XPath 2.0 bietet mit doc-available() zwar eine dedizierte Funktion, diese liefert aber nur bei der Existenz eines wohlgeformten XML-Dokumentes ein true(). Ebenso hängt ein logisches wahr bei unparsed-text-available() von der Existenz eines Textes ab. Was aber, wenn ich wissen will, ob eine Bild-Datei (nein, nicht SVG ;-)) oder eine leere Datei existiert? Die wenigen Lösungsvorschläge verweisen auf xslt-externe Erweiterungsfunktionen. Diese setzen in der Regel die Existenz von Java und manchmal auch zusätzliche Java-Klassen voraus, was die Weiterverwendung vorhandener Stylesheets auf verschiedenen Rechnern erheblich erschwert.

Da in meiner Umgebung ohnehin meist Saxon eingesetzt wird, bietet es sich an, die Saxon-eigenen Erweiterungsfunktionen zu benutzen. Zwar bietet Saxon nicht den gesuchten Test, aber mit file-last-modified() eine Funktion, die einen Leerstring zurückgibt, wenn die Datei nicht vorhanden ist. Damit war die gesuchte Funktion schnell geschrieben:

<xsl:function name="misc:file-exists" as="xs:boolean" xmlns:saxon="http://saxon.sf.net/" extension-element-prefixes="saxon">
	<xsl:param name="href" as="xs:string?"/>
	<xsl:value-of select="boolean(normalize-space(string(saxon:file-last-modified($href))))"/>
</xsl:function>

Zu beachten ist, dass diese Funktion nur mit Saxon funktioniert und keine Fehlerbehandlung stattfindet. Außerdem muss der Parameter URI-codiert werden (z.B. Leerzeichen durch %20 ersetzen). Es gibt also noch genug Raum für Optimierungen.

Nachtrag: Diese Funktion ist nun in der Beispielsammlung abgelegt.

Nachtrag II: saxon:file-last-modified() ist spezifisch für Saxon 9.1. In Saxon 9.2 PE/EE wurde diese Funktion in saxon:last-modified() integriert, in Saxon HE stehen keine Erweiterungsfunktionen zur Verfügung (vgl. Post von Michael Kay auf der Saxon-Mailingliste). Ich habe das Stylesheet entsprechend aktualisiert.

Nachtrag III: Eine Lösung unter Verwendung von Java, die weniger prozessorabhängig ist, habe ich hier beschrieben.

Nachtrag IV: Ich habe die verschiedenen Lösungen in der XSLT-SB zusammengeführt. Der Code kann in der Beispielsammlung eingesehen werden.

Für ein Projekt stand ich vor der Aufgabe, a) einen String darauf zu testen, ob er eine römische Zahl ist und b) und diesen String dann in einen Integer zu konvertieren. Ich kannte mich mit römischen Zahlen nicht wirklich aus, also erst einmal in der Wikipedia nachschlagen. Dabei lernte ich gleich, dass „römische Zahlen“ auf englisch „roman numerals“ heißen – gut, dass konnte ich in der anschließenden Google-Suche gebrauchen.

Im ersten Anlauf fand ich in Sal Manganos XSLT Cookbook eine angestaubte XSLT 1.0-Lösung, die mir überhaupt nicht gefiel. Der Test auf römische Zahlen ist ein Test auf gültige Zeichen, und anschließend wird mangels Funktionen eine Menge mit rekursiven Templates gemacht. Mit XSLT 2.0 muss das doch eleganter gehen. Die freche Lösung – allerdings ohne Gültigkeitstest – liefert Mukul Gandhi in der segensreichen xsl-Mailing-Liste ab. Er zählt solange von 1 bis 10000, bis das Ergebnis von <xsl:number/> gleich dem Input-String ist:

<xsl:stylesheet
	version="2.0"
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns:xs="http://www.w3.org/2001/XMLSchema"
	xmlns:num="http://whatever">
	<!--  -->
	<xsl:output method="text"/>
	<!--  -->
	<xsl:variable name="max" select="10000"/>
	<!--  -->
	<xsl:template match="/">
		<xsl:call-template name="RomanToInteger">
			<xsl:with-param name="roman_number" select="'IIX'"/>
		</xsl:call-template>
	</xsl:template>
	<!--  -->
	<xsl:template name="RomanToInteger">
		<xsl:param name="roman_number"/>
		<xsl:for-each select="1 to $max">
			<xsl:if test="num:toRoman(.) = $roman_number">
				<xsl:value-of select="."/>
			</xsl:if>
		</xsl:for-each>
	</xsl:template>
	<!--  -->
	<xsl:function name="num:toRoman" as="xs:string">
		<xsl:param name="value" as="xs:integer"/>
		<xsl:number value="$value" format="I"/>
	</xsl:function>
	<!--  -->
</xsl:stylesheet>

Nachteil 1: Bei großen Zahlen kann dieser Algorithmus nicht effektiv sein. Nachteil 2: Die Beschränkung auf 10000 ist ein Schutz vor ungültigen Eingaben und der daraus resultierenden Endlosschleife, größere Zahlen sind aber vorstellbar. Also selbst entwickeln.

a) einen String darauf testen, ob er eine gültige römische Zahl ist

Der von Mangano angebotene Test auf die gültigen Zeichen „I“, „V“, „X“, „L“, „C“, „D“, „M“, „i“, „v“, „x“, „l“, „c“, „d“, „m“ ist nicht ausreichend, weil damit auch ungültige Kombinationen wie „IIX“ möglich sind (die unter anderem Mukul Gandhis Algorithmus bis zum Abbruch laufen lassen). Besser ist ein regulärer Ausdruck, dank Google gefunden bei regexlib.com:

<xsl:function name="misc:IsRomanNumeral" as="xs:boolean">
	<xsl:param name="Input" as="xs:string?"/>
	<xsl:variable name="temp" as="xs:string?" select="normalize-space(upper-case($Input))"/>
	<xsl:value-of select="not(matches($temp,'(([IXCM])2{3,})|[^IVXLCDM]|([IL][LCDM])|([XD][DM])|(V[VXLCDM])|(IX[VXLC])|(VI[VX])|(XC[LCDM])|(LX[LC])|((CM|DC)[DM])|(I[VX]I)|(X[CL]X)|(C[DM]C)|(I{2,}[VX])|(X{2,}[CL])|(C{2,}[DM])'))"/>
</xsl:function>

In der Variablen $temp wird der eingegebene String vorbereitet. Da der reguläre Ausdruck auf ungültige Kombinationen testet, war noch ein zusätzliches not() notwendig.

b) einen String mit einer römischen Zahl in einen Integer umwandeln

In der Wikipedia ist der Algorithmus beschrieben: Die Buchstaben werden durch ihre Integer-Werte ersetzt (dafür nehme ich eine Hilfsfunktion) und dann aufaddiert. Eine Ausnahme ist die Subtraktionsschreibweise. Vereinfacht: Steht genau eine kleinere Ziffer vor einer größeren, wird deren Wert von der Summe abgezogen. Ich setze das geradlinig um:

<xsl:function name="misc:GetIntegerFromRomanNumeral" as="xs:integer">
	<xsl:param name="Input" as="xs:string?"/>
	<xsl:variable name="temp" as="xs:string?" select="normalize-space(upper-case($Input))"/>
	<xsl:choose>
		<xsl:when test="misc:IsRomanNumeral($temp)">
			<xsl:variable name="Values" as="xs:integer*">
				<xsl:for-each select="for $i in 1 to string-length($temp) return $i">
					<xsl:variable name="CharValue" as="xs:integer"
						select="misc:GetIntegerFromRomanNumberChar(substring($temp, position(), 1))"/>
					<xsl:variable name="NextCharValue" as="xs:integer"
						select="misc:GetIntegerFromRomanNumberChar(substring($temp, position() + 1, 1) )"/>
					<xsl:choose>
						<xsl:when test="$CharValue lt $NextCharValue">
							<xsl:value-of select="- $CharValue"/>
						</xsl:when>
						<xsl:otherwise>
							<xsl:value-of select="$CharValue"/>
						</xsl:otherwise>
					</xsl:choose>
				</xsl:for-each>
			</xsl:variable>
			<xsl:value-of select="sum($Values)"/>
		</xsl:when>
		<xsl:otherwise>0</xsl:otherwise>
	</xsl:choose>
</xsl:function>
<!--  -->
<xsl:function name="misc:GetIntegerFromRomanNumberChar" as="xs:integer">
	<xsl:param name="Input" as="xs:string?"/>
	<xsl:variable name="temp" as="xs:string?" select="upper-case(normalize-space($Input))"/>
	<xsl:choose>
		<xsl:when test="$temp = 'I' ">1</xsl:when>
		<xsl:when test="$temp = 'V' ">5</xsl:when>
		<xsl:when test="$temp = 'X' ">10</xsl:when>
		<xsl:when test="$temp = 'L' ">50</xsl:when>
		<xsl:when test="$temp = 'C' ">100</xsl:when>
		<xsl:when test="$temp = 'D' ">500</xsl:when>
		<xsl:when test="$temp = 'M' ">1000</xsl:when>
		<xsl:otherwise>0</xsl:otherwise>
	</xsl:choose>
</xsl:function>

In der Variablen $Values wird für jedes Zeichen des Strings ein Wert erzeugt, am Ende enthält die Variable eine Sequenz von Werten. Diese Sequenz wird mit sum() einfach aufaddiert. Ein Test, ob bei $NextCharValue das nächste Zeichen hinter dem letzen Zeichen liegt, ist hier übrigens nicht notwendig, weil in diesem Fall substring() einen Leerstring zurückgibt, dessen Wert in misc:GetIntegerFromRomanNumberChar() als 0 definiert ist.

Nachtrag: Diese Funktionen sind nun in der Beispielsammlung abgelegt.