This is the mail archive of the
xsl-list@mulberrytech.com
mailing list .
Re: Documenting xsl code.
- To: XSL-List at mulberrytech dot com
- Subject: Re: Documenting xsl code.
- From: "Anthony B. Coates, ESL +61 2 9373 7972 Sydney" <tony dot coates at reuters dot com>
- Date: Wed, 26 Jul 2000 04:04:38 +0000 (GMT)
- Autoforwarded: false
- Disclose-recipients: prohibited
- Hop-count: 2
- Reply-To: xsl-list at mulberrytech dot com
- Sensitivity: Company-Confidential
Apologies that I didn't respond to this thread earlier, I was moving half-way
around the world ...
I was glad to see that some people were thinking of literate programming (and
even FunnelWeb, a program I worked on myself for a while) when considering how
to add documentation to XSLT stylesheets. While a Javadoc-style solution may
be OK for some uses, Javadoc is something different to a literate program.
Javadoc is need for hyperlinking between lots of simple items in a large API,
but falls far short of a good literate program for describing how a piece of
code works. XSLT templates can be very difficult to interpret for beginners,
so every bit of explanation is a very good thing.
I have been working (albeit slowly) on a system for doing literate programming
from XML source documents. I call the tool "xmLP"; it is still at an "alpha"
stage, but nonetheless does both "weave" (generate documentation) and "tangle"
(assemble the product source files). At the bottom of this message is a sample
of the documentation produced (currently) by "xmLP". This is based heavily on
my FunnelWeb experience.
I don't have the "xmLP" sources on the Web at present (give me a week or two),
but if you are really interested, reply to me early by e-mail and I will send
you a copy. There are just two XSLT stylesheets, one to tangle, one to weave.
They work with Xalan, and haven't been tested as yet with other XSLT engines.
I would be interested to get your replies as to what you do/don't like about
the "xmLP" documentation (do remember that what is attached is a rather potted
example, so forgive me that the content is flimsy).
Cheers,
Tony.
PS If you have questions about literate programming & XML, you could do worse
than join the (very low volume) "xml-litprog-l" list:
http://www.egroups.com/group/xml-litprog-l
==== xmLP-xslt.html ====
<HTML xmlns:lp="http://www.litprog.org/xmLP/alpha-2000-04-09/">
<HEAD>
<TITLE>A Gentle Intro to XSLT</TITLE>
<LINK xmlns="http://www.w3.org/TR/REC-html40" TYPE="text/css" SRC="xmLPdoc.css"
REL="stylesheet" HREF="xmLPdoc.css"></HEAD>
<BODY>
<H1>
A Gentle Introduction to XSL Transformations (XSLT)
</H1>
<HR>
<H1>Table of Contents</H1>
<H2 xmlns="http://www.w3.org/TR/REC-html40"><A href="#1%20About%20%22xmLP%22">1
About "xmLP"</A></H2><H2 xmlns="http://www.w3.org/TR/REC-html40"><A
href="#2%20Overview">2 Overview</A></H2><H2
xmlns="http://www.w3.org/TR/REC-html40"><A
href="#3%20A%20Sample%20XML%20File">3 A Sample XML File</A></H2><H2
xmlns="http://www.w3.org/TR/REC-html40"><A
href="#4%20Generating%20HTML%20Output">4 Generating HTML Output</A></H2><H2
xmlns="http://www.w3.org/TR/REC-html40"><A href="#5%20Running%20%22xmLP%22">5
Running "xmLP"</A></H2><H2 xmlns="http://www.w3.org/TR/REC-html40"><A
href="#6%20List%20of%20Macros">6 List of Macros</A></H2><H2
xmlns="http://www.w3.org/TR/REC-html40"><A href="#7%20List%20of%20Files">7 List
of Files</A></H2>
<HR>
<H1 xmlns="http://www.w3.org/TR/REC-html40"><A NAME="1%20About%20%22xmLP%22">1
About "xmLP"</A></H1>
<P>
This document is a literate program created using the prototype
literate programming tool "xmLP". Literate programming
tools allow code and documentation to be interspersed in the one file.
For "xmLP", the source file is written in XML, and the
documentation is created in XML or HTML using the instructions in an
XSL transformation file. Code sections look like the following:
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-z-macro-def"><A
NAME="xmLP[1]PLmx"></A><DL><DT><EM><lp:name>Example code definition</lp:name>
[1] =</EM></DT><DD><PRE><code, typeset differently from descriptive
text></PRE></DD></DL><H5><BR>This macro is NEVER invoked.</H5></DIV>
<P>
Code sections can also be additive, as with the two following examples:
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-z-macro-def"><A
NAME="xmLP[2]PLmx"></A><DL><DT><EM><lp:name>Additive code definition
example</lp:name> [2] +=</EM></DT><DD><PRE><first part of the
code></PRE></DD></DL><H5>This macro is defined in definitions <A
HREF="#xmLP[2]PLmx">2</A> <A HREF="#xmLP[3]PLmx">3</A>.<BR>This macro is NEVER
invoked.</H5></DIV>
<P></P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-z-macro-def"><A
NAME="xmLP[3]PLmx"></A><DL><DT><EM><lp:name>Additive code definition
example</lp:name> [3] +=</EM></DT><DD><PRE><second part of the
code></PRE></DD></DL><H5>This macro is defined in definitions <A
HREF="#xmLP[2]PLmx">2</A> <A HREF="#xmLP[3]PLmx">3</A>.<BR>This macro is NEVER
invoked.</H5></DIV>
<H1 xmlns="http://www.w3.org/TR/REC-html40"><A NAME="2%20Overview">2
Overview</A></H1>
<P>
The XSL transformation language (XSLT) is a scripting language that transforms
XML files
into XML, HTML, or text, based on patterns. Whenever a pattern is recognised,
a matching
transformation is performed. This differs from more traditional procedural
languages,
where actions are performed one after the other in a more deterministic manner.
Besides XSLT, other existing pattern matching languages are Prolog and
Mathematica.
</P>
<P>
All of this is a bit vague without a concrete example, so let us start with
one.
</P>
<H1 xmlns="http://www.w3.org/TR/REC-html40"><A
NAME="3%20A%20Sample%20XML%20File">3 A Sample XML File</A></H1>
<P>
For this document, the following sample XML file will be used. It is an RDF
file
(<A xmlns="http://www.w3.org/TR/REC-html40"
HREF="http://www.w3.org/TR/REC-rdf-syntax">Resource Description Framework</A>)
which describes the properties (name/value pairs) of some objects. Be assured
that no understanding of RDF is required to understand this document. However,
it will
be assumed that the RDF properties are to be displayed using HTML, which is not
an
unlikely scenario.
</P>
<P>
Without further ado, the sample XML (RDF) is as follows:
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-file-def"><A
NAME="xmLPfile[1]elifPLmx"></A><DL><DT><EM>animals.rdf [1]
=</EM></DT><DD><PRE><?xml version="1.0"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:s="http://dummy.org/xmLP-RDF-sample"
>
<rdf:Description about="http://dummy.org/animal/octopus">
<s:Name>Octopus</s:Name>
<s:LegCount>8</s:LegCount>
<s:Habitat>Sea &amp; Ocean</s:Habitat>
<s:Carnivore>True</s:Carnivore>
</rdf:Description>
<rdf:Description about="http://dummy.org/animal/elephant">
<s:Name>Elephant</s:Name>
<s:LegCount>4</s:LegCount>
<s:Habitat>Africa &amp; Asia</s:Habitat>
<s:Carnivore>False</s:Carnivore>
</rdf:Description>
</rdf:RDF></PRE></DD></DL><H5>This is an output file.</H5></DIV>
<P>
The XML (RDF) sample contains the following information:
</P>
<OL>
<LI>an octopus has 8 legs, lives in the sea and ocean, and is a
carnivore;</LI>
<LI>an elephant has 4 legs, lives in Africa and Asia, and is not a
carnivore.</LI>
</OL>
<H1 xmlns="http://www.w3.org/TR/REC-html40"><A
NAME="4%20Generating%20HTML%20Output">4 Generating HTML Output</A></H1>
<P>
To generate HTML output, the XSLT stylesheet must contain an appropriate
"<KBD>xsl:output</KBD>" tag.
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-macro-def"><A
NAME="xmLP[4]PLmx"></A><DL><DT><EM><lp:name>HTML Output Tag</lp:name> [4]
=</EM></DT><DD><PRE><xsl:output method="html"
indent="no"/></PRE></DD></DL><H5><BR>This macro is invoked in files <A
HREF="#xmLPfile[2]elifPLmx">2</A>.</H5></DIV>
<P>
Assume that the properties of each object (animal) is to be put into a separate
HTML
table. In the RDF file, each separate object has a separate
"<KBD>rdf:Description</KBD>"
tag, so this can be used as the pattern to generate the HTML "<KBD>TABLE</KBD>"
tag. A
suitable XSLT "<KBD>xsl:template</KBD>" pattern is
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-macro-def"><A
NAME="xmLP[5]PLmx"></A><DL><DT><EM><lp:name>rdf:Description template</lp:name>
[5] =</EM></DT><DD><PRE><xsl:template match="rdf:Description">
<P>
<TABLE BORDER="2" WIDTH="60%">
<xsl:apply-templates/>
</TABLE>
</P>
</xsl:template></PRE></DD></DL><H5><BR>This macro is invoked in files <A
HREF="#xmLPfile[2]elifPLmx">2</A>.</H5></DIV>
<P>
This template (pattern) does the following: when and if an
"<KBD>rdf:Description</KBD>"
tag is encountered, it is replaced by an HTML "<KBD>TABLE</KBD>" tag (inside a
"<KBD>P</KBD>" tag. The XSLT "<KBD>xsl:apply-templates</KBD>" tag indicates
that pattern
matching should be done recursively on anything between
"<KBD><rdf:Description></KBD>" and its matching closing tag
"<KBD></rdf:Description></KBD>". This is very important; if the
"<KBD>xsl:apply-templates</KBD>" tag was left out of the template, all that
would be
generated in the output HTML file would be
"<KBD><TABLE></TABLE></KBD>", i.e.
a rather boring table with neither rows nor columns.
</P>
<P>
As each property is encountered, a table row should be generated for it showing
its name
and its value. A simple (but not scalable) way to deal with this is to create
a template
for each property. For the "<KBD>Name</KBD>" property, a suitable template
(pattern) is
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-macro-def"><A
NAME="xmLP[6]PLmx"></A><DL><DT><EM><lp:name>s:Name template</lp:name> [6]
=</EM></DT><DD><PRE><xsl:template match="s:Name">
<TR>
<TH WIDTH="33%">Name</TH>
<TD WIDTH="*"><xsl:value-of select="text()"/></TD>
</TR>
</xsl:template></PRE></DD></DL><H5><BR>This macro is invoked in files <A
HREF="#xmLPfile[2]elifPLmx">2</A>.</H5></DIV>
<P>
This creates a heading column with the name of the property ("Name"), and a
normal column
with the value of the property. The "<KBD>xsl:value-of</KBD>" tag is used to
get a
value from the source document, and "<KBD>text()</KBD>" returns the text of the
<EMPH>current</EMPH> tag. As the template is executing, the
<EMPH>current</EMPH> tag is
"<KBD>s:Name</KBD>", which is exactly what we want the text of.
</P>
<P>
The other property tags are handled similarly.
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-macro-def"><A
NAME="xmLP[7]PLmx"></A><DL><DT><EM><lp:name>s:LegCount template</lp:name> [7]
=</EM></DT><DD><PRE><xsl:template match="s:LegCount">
<TR>
<TH>Leg Count</TH>
<TD><xsl:value-of select="text()"/></TD>
</TR>
</xsl:template></PRE></DD></DL><H5><BR>This macro is invoked in files <A
HREF="#xmLPfile[2]elifPLmx">2</A>.</H5></DIV>
<P></P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-macro-def"><A
NAME="xmLP[8]PLmx"></A><DL><DT><EM><lp:name>s:Habitat template</lp:name> [8]
=</EM></DT><DD><PRE><xsl:template match="s:Habitat">
<TR>
<TH>Habitat</TH>
<TD><xsl:value-of select="text()"/></TD>
</TR>
</xsl:template></PRE></DD></DL><H5><BR>This macro is invoked in files <A
HREF="#xmLPfile[2]elifPLmx">2</A>.</H5></DIV>
<P></P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-macro-def"><A
NAME="xmLP[9]PLmx"></A><DL><DT><EM><lp:name>s:Carnivore template</lp:name> [9]
=</EM></DT><DD><PRE><xsl:template match="s:Carnivore">
<TR>
<TH>Carnivore?</TH>
<TD><xsl:value-of select="text()"/></TD>
</TR>
</xsl:template></PRE></DD></DL><H5><BR>This macro is invoked in files <A
HREF="#xmLPfile[2]elifPLmx">2</A>.</H5></DIV>
<P>
Finally, the HTML page will need the usual "<KBD>HTML</KBD>",
"<KBD>HEAD</KBD>",
and "<KBD>BODY</KBD>" tags to make it complete, and these can be added by
adding
a template for the root of the source document, which is represented by a
single
forward slash ("<KBD>/</KBD>").
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-macro-def"><A
NAME="xmLP[10]PLmx"></A><DL><DT><EM><lp:name>Document root template</lp:name>
[10] =</EM></DT><DD><PRE><xsl:template match="/">
<HTML>
<HEAD>
<TITLE>RDF Properties</TITLE>
</HEAD>
<BODY>
<xsl:apply-templates/>
</BODY>
</HTML>
</xsl:template></PRE></DD></DL><H5><BR>This macro is invoked in files <A
HREF="#xmLPfile[2]elifPLmx">2</A>.</H5></DIV>
<P>
Note that an XSLT "<KBD>xsl:apply-templates</KBD>" tag is required to make sure
that
the other templates are called as their patterns are encountered.
</P>
<P>
Finally, the XSLT stylesheet is assembled as follows:
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-file-def"><A
NAME="xmLPfile[2]elifPLmx"></A><DL><DT><EM>rdf2html1.xsl [2]
=</EM></DT><DD><PRE><?xml version="1.0"?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:lp="http://www.litprog.org/xmLP/alpha-2000-04-09/"
xmlns="http://www.w3.org/TR/REC-html40"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:s="http://dummy.org/xmLP-RDF-sample"
version="1.0"
>
<I><A HREF="#xmLP[4]LPmx">HTML Output Tag</A></I>
<I><A HREF="#xmLP[10]LPmx">Document root template</A></I>
<I><A HREF="#xmLP[5]LPmx">rdf:Description template</A></I>
<I><A HREF="#xmLP[6]LPmx">s:Name template</A></I>
<I><A HREF="#xmLP[7]LPmx">s:LegCount template</A></I>
<I><A HREF="#xmLP[8]LPmx">s:Habitat template</A></I>
<I><A HREF="#xmLP[9]LPmx">s:Carnivore template</A></I>
</xsl:stylesheet></PRE></DD></DL><H5>This is an output file.</H5></DIV>
<H1 xmlns="http://www.w3.org/TR/REC-html40"><A
NAME="5%20Running%20%22xmLP%22">5 Running "xmLP"</A></H1>
<P>
To run "xmLP", you need an XSLT engine. In particularly, "xmLP" has only been
tested
with the Java version of Apache's "Xalan" XSLT engine (formerly "LotusXSL").
To run
Xalan, your Java <KBD>CLASSPATH</KBD> should contain "<KBD>xalan.jar</KBD>" and
"<KBD>xerces.jar</KBD>". Xalan is then invoked using
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-macro-def"><A
NAME="xmLP[11]PLmx"></A><DL><DT><EM><lp:name>Xalan</lp:name> [11]
M=</EM></DT><DD><PRE>java
org.apache.xalan.xslt.Process</PRE></DD></DL><H5><BR>This macro is invoked in
macros <A HREF="#xmLP[12]PLmx">12</A> <A HREF="#xmLP[13]PLmx">13</A> <A
HREF="#xmLP[14]PLmx">14</A> <A HREF="#xmLP[15]PLmx">15</A>.</H5></DIV>
<P>
and so the full command line is
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-z-macro-def"><A
NAME="xmLP[12]PLmx"></A><DL><DT><EM><lp:name>Xalan command line</lp:name> [12]
=</EM></DT><DD><PRE><I><A HREF="#xmLP[11]LPmx">Xalan</A></I> -IN
<xml-source> -XSL <xsl-stylesheet> -OUT
<output-file></PRE></DD></DL><H5><BR>This macro is NEVER
invoked.</H5></DIV>
<P>
To generate this documentation, the command is
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-z-macro-def"><A
NAME="xmLP[13]PLmx"></A><DL><DT><EM><lp:name>Documentation command
line</lp:name> [13] =</EM></DT><DD><PRE><I><A
HREF="#xmLP[11]LPmx">Xalan</A></I> -IN xmlp-xslt.xml -XSL xmLPweave.xsl -OUT
xmlp-xslt.html</PRE></DD></DL><H5><BR>This macro is NEVER invoked.</H5></DIV>
<P>
To generate the RDF file and the stylesheet which generates a matching HTML
page, the
command is
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-z-macro-def"><A
NAME="xmLP[14]PLmx"></A><DL><DT><EM><lp:name>Product files command
line</lp:name> [14] =</EM></DT><DD><PRE><I><A
HREF="#xmLP[11]LPmx">Xalan</A></I> -IN xmlp-xslt.xml -XSL
xmLPtangle.xsl</PRE></DD></DL><H5><BR>This macro is NEVER invoked.</H5></DIV>
<P>
To run the product XSLT stylesheet on the RDF file and produce the matching
HTML page,
the command is
</P>
<DIV xmlns="http://www.w3.org/TR/REC-html40" CLASS="xmlp-z-macro-def"><A
NAME="xmLP[15]PLmx"></A><DL><DT><EM><lp:name>RDF sample command line</lp:name>
[15] =</EM></DT><DD><PRE><I><A HREF="#xmLP[11]LPmx">Xalan</A></I> -IN
animals.rdf -XSL rdf2html1.xsl -OUT animals.html</PRE></DD></DL><H5><BR>This
macro is NEVER invoked.</H5></DIV>
<P>
That, then, is a very quick and potted introduction to how XSLT stylesheets are
constructed. There are many powerful features that have not been mentioned
here,
so keep reading about XSLT and you will discover what a useful tool it is.
</P>
<HR>
<H1 xmlns="http://www.w3.org/TR/REC-html40"><A NAME="6%20List%20of%20Macros">6 List of
Macros</A></H1>
<OL xmlns="http://www.w3.org/TR/REC-html40"><LI><A href="#xmLP[1]PLmx">Example
code definition</A> [never invoked]</LI><LI><A href="#xmLP[2]PLmx">Additive
code definition example</A> [#1/2] [never invoked]</LI><LI><A
href="#xmLP[3]PLmx">Additive code definition example</A> [#2/2] [never
invoked]</LI><LI><A href="#xmLP[4]PLmx">HTML Output Tag</A></LI><LI><A
href="#xmLP[5]PLmx">rdf:Description template</A></LI><LI><A
href="#xmLP[6]PLmx">s:Name template</A></LI><LI><A
href="#xmLP[7]PLmx">s:LegCount template</A></LI><LI><A
href="#xmLP[8]PLmx">s:Habitat template</A></LI><LI><A
href="#xmLP[9]PLmx">s:Carnivore template</A></LI><LI><A
href="#xmLP[10]PLmx">Document root template</A></LI><LI><A
href="#xmLP[11]PLmx">Xalan</A></LI><LI><A href="#xmLP[12]PLmx">Xalan command
line</A> [never invoked]</LI><LI><A href="#xmLP[13]PLmx">Documentation command
line</A> [never invoked]</LI><LI><A href="#xmLP[14]PLmx">Product files command
line</A> [never invoked]</LI><LI><A href="#xmLP[15]PLmx">RDF sample command
line</A> [never invoked]</LI></OL>
<HR>
<H1 xmlns="http://www.w3.org/TR/REC-html40"><A NAME="7%20List%20of%20Files">7
List of Files</A></H1>
<OL xmlns="http://www.w3.org/TR/REC-html40"><LI><A
href="#xmLPfile[1]elifPLmx">animals.rdf</A></LI><LI><A
href="#xmLPfile[2]elifPLmx">rdf2html1.xsl</A></LI></OL>
</BODY>
</HTML>
==== xmLPdoc.css ====
BODY {
background-color:white;
text-color:black;
}
H1 {
text-align:center;
}
H2, H3, H4, H5, ADDRESS {
text-align:left;
}
H1, H2 {
color:darkgreen;
}
H3, H4, B {
color:darkred;
}
DT {
font-style:bold;
}
H1 {
font-size:24pt;
}
H2 {
font-size:18pt;
}
H3 {
font-size:16pt;
}
H4 {
font-size:14pt;
}
P, PRE, UL, OL, DL {
font-size:12pt;
}
.xmlp-macro-def, .xmlp-z-macro-def, .xmlp-file-def {
border-color:darkblue;
border-style:ridge;
border-width:2;
padding:20;
}
.xmlp-macro-def {
background-color:lightyellow;
}
.xmlp-z-macro-def {
background-color:lightblue;
}
.xmlp-file-def {
background-color:pink;
}
.xmlp-error {
color:red;
}
.xmlp-warning {
color:orange;
}
==== end ====
========
Anthony B. Coates
XML Architecture & Design
Research and Standards Group
Reuters Plc, London.
tony.coates@reuters.com
========
-----------------------------------------------------------------
Visit our Internet site at http://www.reuters.com
Any views expressed in this message are those of the individual
sender, except where the sender specifically states them to be
the views of Reuters Ltd.
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list