Documenting xsl code.

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 "&#160;">
<!ENTITY nl "&#xa;"><!--new line-->
<!ENTITY  pound	"&#x00A3;"><!--	# 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('&lt;xsl:',local-name(.))"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:value-of select="concat('&lt;',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('&lt;/xsl:',local-name(.),'&gt;')"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:value-of select="concat('&lt;/',name(.),'&gt;')"/>
    </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('&lt;',name(.))"/> -->
   <xsl:apply-templates mode="verb" select="@*"/>
   <xsl:text>&gt;</xsl:text>
   <xsl:apply-templates mode="verb"/>
<xsl:call-template name="postfix"/>
<!-- <xsl:value-of select="concat('&lt;/',name(.),'&gt;')"/> -->
 </xsl:template>

<!-- empty elements -->
<xsl:template mode="verb" match="*">

  <!--  <xsl:value-of select="concat('&lt;',name(.))"/> -->
    <xsl:call-template name="prefix"/>

  <xsl:apply-templates mode="verb" select="@*"/>
  <xsl:text>/&gt;</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="'&quot;'"/>
    <xsl:with-param name="to" select="'&amp;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('&lt;?',name(.),' ',.,'?&gt;')"/>
</xsl:template>

<!-- only works if parser passes on comment nodes -->
<xsl:template mode="verb" match="comment()">
  <xsl:value-of select="concat('&lt;!--',.,'--&gt;')"/>
</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="'&amp;gt;'"/>
    <xsl:with-param name="from" select="'&gt;'"/> 
    <xsl:with-param name="string">
      <xsl:call-template name="string-replace">
        <xsl:with-param name="to" select="'&amp;lt;'"/>
        <xsl:with-param name="from" select="'&lt;'"/> 
        <xsl:with-param name="string">
          <xsl:call-template name="string-replace">
            <xsl:with-param name="to" select="'&amp;amp;'"/>
            <xsl:with-param name="from" select="'&amp;'"/> 
            <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