This is the mail archive of the
xsl-list@mulberrytech.com
mailing list .
Documenting xsl code.
- To: "'xsl-list at mulberrytech dot com'" <xsl-list at mulberrytech dot com>
- Subject: Documenting xsl code.
- From: "Pawson, David" <DPawson at rnib dot org dot uk>
- Date: Mon, 10 Jul 2000 13:41:18 +0100
- Cc: "'xsllib at ejbdevelopers dot com'" <xsllib at ejbdevelopers dot com>
- Reply-To: xsl-list at mulberrytech dot com
Since the proceedings on this list a week or two back,
David Carlisle, Warren Hedley and myself have
worked out a starting point.
Three files below.
1. A 'self documented stylesheet' (doc.xsl)
2. A stylesheet (doc-doc.xsl), which works on doc.xsl
to extract the documentation in the doc namespace
3. A stylesheet doc-logic.xsl, which works on the doc.xsl
to extract the code.
Usage:
1. To extract the code
(xslt processor) doc.xsl doc-logic.xsl op.html \
"logic-ns=http://www.dpawson.co.uk" \
"doc-ns=http://org.hedley.html"
These are the namespaces used in doc.xsl, but use what you will.
2. To extract the documentation.
(xslt processor) doc.xsl doc-doc.xsl op.html \
"logic-ns=http://www.dpawson.co.uk" \
"doc-ns=http://org.hedley.html"
To do.
1. Add coloring (preferably via CSS) to any wanted elements in doc-doc
2. Generalise to any namespaces for any purpose.
Enjoy and let us know what you think.
Regards, DaveP, on behalf of.
1. doc.xsl
<?xml version="1.0"?>
<!-- -->
<!-- This is the 'source document' -->
<!-- Containing both documentation and 'code' -->
<logic:stylesheet
xmlns:doc="http://org.hedley.html"
xmlns:logic="http://www.dpawson.co.uk"
>
<doc:h1>Root Element</doc:h1>
<doc:p>My root element doesn't really do anything useful.</doc:p>
<logic:output method="xml" indent="yes"/>
<doc:h3>Variable <doc:i>root</doc:i> holds the src tree</doc:h3>
<logic:variable name="root" select="/"/>
<logic:template match="/">
<logic:apply-templates/>
</logic:template>
<doc:hr/>
<doc:h2>Main processing.</doc:h2>
<doc:p>This template uses a pull technique to extract all required
elements from the source document required by the output xml file</doc:p>
<doc:p>Process all the related list section elements</doc:p>
<logic:template match="doc">
<elems id="h31">
<logic:for-each select="listrelsects/listitem">
<elem><logic:copy-of select="."/></elem>
</logic:for-each>
</elems>
</logic:template>
<doc:hr/>
<doc:h3>Ignore remaining elements</doc:h3>
<logic:template match="*"/>
</logic:stylesheet>
================================================================
2. doc-logic.xsl
<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
>
<!--
A command line might look like this
xslt-processor \
doc.xsl \ # in
doc-logic.xsl \ # transform
logic_ns=http://www.dpawson.co.uk \ # the logic namespace
doc_ns=http://org.hedley.html # the documentation namespace
e.g. sax doc.xsl doc-logic.xsl op.xsl "logic_ns=http://www.dpawson.co.uk"
\
output_ns="org.hedley.html"
-->
<!--
This one outputs basic code to perform the styling.
-->
<xsl:param name="logic_ns" select="'***'" />
<xsl:param name="doc_ns" select="'***'" />
<xsl:variable name="xsl_ns"
select="'http://www.w3.org/1999/XSL/Transform'" />
<xsl:output method="xml" indent="yes"/>
<xsl:strip-space elements="*"/>
<xsl:template match="/">
<xsl:message>Param=<xsl:value-of select="$doc_ns"/>
</xsl:message>
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="*" priority="2">
<xsl:choose>
<!-- Documentation namespace, dump -->
<xsl:when test="namespace-uri(.) = $doc_ns">
<xsl:message>Doc. <xsl:value-of select="namespace-uri()"/>
</xsl:message>
</xsl:when>
<!-- output, logic namespace -->
<xsl:when test="namespace-uri()=$logic_ns">
<xsl:element name="xsl:{local-name()}" namespace="{$xsl_ns}">
<xsl:copy-of select="@*"/>
<xsl:apply-templates/>
</xsl:element>
</xsl:when>
<!-- null namespace -->
<xsl:when test="namespace-uri()=''">
<xsl:copy>
<xsl:copy-of select="@*"/>
<xsl:apply-templates/>
</xsl:copy>
</xsl:when>
<xsl:otherwise>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>
==============================
3. doc-doc.xsl
- Tks to David C for the 'hard-sums' code :-)
<?xml version="1.0"?>
<!-- Update
7 July 2000. Added null processing for stylesheet element,
as being redundant.
-->
<!--
A command line might look like this
sax doc.xsl doc-doc.xsl op.xml "doc_ns=http://org.hedley.html"
"logic_ns=http://www.dpawson.co.uk"
-->
<!DOCTYPE xsl:stylesheet [
<!ENTITY sp "<xsl:text> </xsl:text>">
<!ENTITY dot "<xsl:text>.</xsl:text>">
<!ENTITY nbsp " ">
<!ENTITY nl "
"><!--new line-->
<!ENTITY pound "£"><!-- # POUND SIGN -->
]>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
>
<!--
This one outputs basic code to perform the styling.
-->
<xsl:param name="logic_ns" select="'***'" />
<xsl:param name="output_ns" select="'***'" />
<xsl:param name="doc_ns" select="doc-format"/>
<xsl:variable name="xsl_ns"
select="'http://www.w3.org/1999/XSL/Transform'" />
<xsl:output method="xml" indent="yes"/>
<xsl:template match="/">
<html>
<head><title>Documentation</title></head>
<body>
<xsl:apply-templates/>
</body>
</html>
</xsl:template>
<xsl:template match="*" priority="2">
<xsl:choose>
<!-- Document Namespace. -->
<xsl:when test="namespace-uri(.) = $doc_ns">
<xsl:element name="{local-name(.)}">
<xsl:copy-of select="@*" />
<xsl:apply-templates />
</xsl:element>
</xsl:when>
<xsl:when test="namespace-uri()=$logic_ns">
<xsl:if test= "not(local-name()='stylesheet')">
<pre>
<xsl:apply-templates mode="verb" select="."/>
</pre>
</xsl:if>
<xsl:apply-templates/>
</xsl:when>
<xsl:when test="namespace-uri()=''"/>
<pre>
<xsl:apply-templates mode="verb" />
</pre>
<xsl:apply-templates />
<xsl:otherwise>
<xsl:apply-templates />
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Copyright 1999 David Carlisle
Render XML in an HTML pre element. -->
<!-- verb mode -->
<!-- Does not really give verbatim copy of the file as that
information not present in the parsed document, but should
give something that renders in HTML as a well formed XML
document that would parse to give same XML tree as the original
-->
<!-- DaveP. Added prefix and postfix to replace logic_ns prefix
with xsl:
Called from both empty elements and those with content.
-->
<xsl:template name="prefix">
<xsl:choose>
<xsl:when test="namespace-uri(.)=$logic_ns">
<xsl:value-of select="concat('<xsl:',local-name(.))"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="concat('<',name(.))"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template name="postfix">
<xsl:choose>
<xsl:when test="namespace-uri(.)=$logic_ns">
<xsl:value-of select="concat('</xsl:',local-name(.),'>')"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="concat('</',name(.),'>')"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- non empty elements and other nodes. -->
<xsl:template mode="verb"
match="*[*]|*[text()]|*[comment()]|*[processing-instruction()]">
<xsl:call-template name="prefix"/>
<!-- <xsl:value-of select="concat('<',name(.))"/> -->
<xsl:apply-templates mode="verb" select="@*"/>
<xsl:text>></xsl:text>
<xsl:apply-templates mode="verb"/>
<xsl:call-template name="postfix"/>
<!-- <xsl:value-of select="concat('</',name(.),'>')"/> -->
</xsl:template>
<!-- empty elements -->
<xsl:template mode="verb" match="*">
<!-- <xsl:value-of select="concat('<',name(.))"/> -->
<xsl:call-template name="prefix"/>
<xsl:apply-templates mode="verb" select="@*"/>
<xsl:text>/></xsl:text>
</xsl:template>
<!-- attributes
Output always surrounds attribute value by "
so we need to make sure no literal " appear in the value -->
<xsl:template mode="verb" match="@*">
<xsl:value-of select="concat(' ',name(.),'=')"/>
<xsl:text>"</xsl:text>
<xsl:call-template name="string-replace">
<xsl:with-param name="from" select="'"'"/>
<xsl:with-param name="to" select="'&quot;'"/>
<xsl:with-param name="string" select="."/>
</xsl:call-template>
<xsl:text>"</xsl:text>
</xsl:template>
<!-- pis -->
<xsl:template mode="verb" match="processing-instruction()">
<xsl:value-of select="concat('<?',name(.),' ',.,'?>')"/>
</xsl:template>
<!-- only works if parser passes on comment nodes -->
<xsl:template mode="verb" match="comment()">
<xsl:value-of select="concat('<!--',.,'-->')"/>
</xsl:template>
<!-- text elements
need to replace & and < by entity references
do > as well, just for balance -->
<xsl:template mode="verb" match="text()">
<xsl:call-template name="string-replace">
<xsl:with-param name="to" select="'&gt;'"/>
<xsl:with-param name="from" select="'>'"/>
<xsl:with-param name="string">
<xsl:call-template name="string-replace">
<xsl:with-param name="to" select="'&lt;'"/>
<xsl:with-param name="from" select="'<'"/>
<xsl:with-param name="string">
<xsl:call-template name="string-replace">
<xsl:with-param name="to" select="'&amp;'"/>
<xsl:with-param name="from" select="'&'"/>
<xsl:with-param name="string" select="."/>
</xsl:call-template>
</xsl:with-param>
</xsl:call-template>
</xsl:with-param>
</xsl:call-template>
</xsl:template>
<!-- end verb mode -->
<!-- replace all occurences of the character(s) `from'
by the string `to' in the string `string'.-->
<xsl:template name="string-replace" >
<xsl:param name="string"/>
<xsl:param name="from"/>
<xsl:param name="to"/>
<xsl:choose>
<xsl:when test="contains($string,$from)">
<xsl:value-of select="substring-before($string,$from)"/>
<xsl:value-of select="$to"/>
<xsl:call-template name="string-replace">
<xsl:with-param name="string"
select="substring-after($string,$from)"/>
<xsl:with-param name="from" select="$from"/>
<xsl:with-param name="to" select="$to"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$string"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list