This is the mail archive of the
xsl-list@mulberrytech.com
mailing list .
Self documentation, tangle and weave, *an* answer
- To: "'xsl-list at mulberrytech dot com'" <xsl-list at mulberrytech dot com>
- Subject: Self documentation, tangle and weave, *an* answer
- From: "Pawson, David" <DPawson at rnib dot org dot uk>
- Date: Tue, 4 Jul 2000 13:13:44 +0100
- Reply-To: xsl-list at mulberrytech dot com
Below is one answer to self documentation.
I personally am not convinced its right in an xml world.
I prefer even namespaces to line noise ;-)
It uses a literate programming tool called funnelweb,
from http://www.ross.net/funnelweb/
The documentation and stylesheet are intermingled, then
funnelweb extracts documentation (html or tex), and
the actual stylesheet for use.
In deference to our spamming friends I include
two files, rather than attaching them.
firstly the source file.
then the html output, should you want to see it.
Sorry its such a long file Tony.
Regards, DaveP
@a@<Overview@> this stylsheet demonstrates the action of the key function.
@b@<entities@>Additional entities are added for general use.
These are the space, a dot, a non-breaking space and a new line.
@$@<stylesheet@>==@{
<!DOCTYPE xsl:stylesheet [
<!ENTITY sp "<xsl:text> </xsl:text>">
<!ENTITY dot "<xsl:text>.</xsl:text>">
<!ENTITY nbsp " ">
<!ENTITY nl "
"><!--new line-->
]>
@}
@$@<root@>==@{
<xsl:transform
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0"
>
@}
@$@<op@>==@{
<xsl:output
method="text"
encoding="utf-8"
indent="yes"/>
@}
@c@<create key@> Create the key.
Give it some name.
give it a pattern to search for - it searches
the whole document but you don't need to specify
a full path unless you want to.
Give it a pattern to use for comparison when using
the key() function. This specifies the idref
attribute which is a child of elements a or b or c.
@c@<Which form@> This form is better if you need to change the use
attribute for each element. It could be idref with element a,
forward-link with element b etc.
Remember that the use attribute is the content that is
matched on, relative to the 'match' attribute which
specifies the pattern to search for.@+
<xsl:key name="caller" match="a" use="@@idref"/>@+
<xsl:key name="caller" match="b" use="@@idref"/>@+
<xsl:key name="caller" match="c" use="@@idref"/>@+
@$@<template1@>==@{
<xsl:key name="caller" match="a|b|c" use="@@idref"/>
<xsl:template match="/doc">
<xsl:apply-templates/>
</xsl:template>
@}
@b@<abc@> The remainder of the input elements are handled by
this template.
@c@<layout@>Excuse the layout, this to produce output that is clear.
Same version is below, in comments, with fuller explanation.
@$@<template2@>==@{
<xsl:template match="a|b|c">
<xsl:variable name="here" select="@@id"/>
<xsl:value-of select="@@id"/> is called by (<xsl:choose><xsl:when
test="(key('caller',$here))/@@id"><xsl:for-each
select="key('caller',$here)/@@id"> <xsl:value-of
select="."/> <xsl:if
test="not(position()=last())">,&sp;
</xsl:if>
</xsl:for-each>
</xsl:when>
<xsl:otherwise> None </xsl:otherwise></xsl:choose>)
&sp;&sp;&sp; <xsl:apply-templates/>
</xsl:template>
</xsl:transform>
@}
@O@<keys.xsl@>@{@<templates@>@+@}
@$@<templates@>==@{@<stylesheet@> @<root@>@<op@>@-
@<template1@> @<template2@> @}
==============================
<HTML>
<!--------------------------------------------------------------------------
--->
<!-- START OF AUTOMATICALLY GENERATED HTML FILE
-->
<!--------------------------------------------------------------------------
--->
<!--
-->
<!-- This HTML file was generated by the FunnelWeb literate programming
-->
<!-- preprocessor. You can display this file using popular web browsers
-->
<!-- such as Netscape Navigator and Microsoft Internet Explorer.
-->
<!--
-->
<!-- FunnelWeb is a preprocessor that allows programmers to weave programs
-->
<!-- and their documentation together in a single document. The FunnelWeb
-->
<!-- program analyses such documents producing both program files and
-->
<!-- typeset documentation such as this HTML file.
-->
<!--
-->
<!-- FunnelWeb was created by Ross N. Williams (www.ross.net) and is
-->
<!-- available free of charge under a GNU General Public Licence.
-->
<!-- The FunnelWeb website can be found at http://www.ross.net/funnelweb/
-->
<!--
-->
<!--------------------------------------------------------------------------
--->
<HEAD>
<TITLE>Package keys</TITLE>
<STYLE TYPE="text/css">
<!--
A {text-decoration: none}
H1 { font-family: sans-serif; font-size: large }
H2 { font-family: sans-serif; font-size: medium; font-weight: bold }
H3 { font-family: sans-serif; font-size: medium }
H4 { font-family: sans-serif; font-size: small }
H5 { font-family: sans-serif; font-size: small }
// -->
</STYLE>
</HEAD>
<BODY BGCOLOR=#FFFFFF TEXT=#000000 LINK=#CC0033 VLINK=#CC0033 ALINK=#CC0000>
<P><HR SIZE=4 NOSHADE><P><A NAME="sec_1"></A>
<H1>1. Overview</H1>
<P><TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD WIDTH=400>
this stylsheet demonstrates the action of the key function.
<P>
<P>
<P></TD></TR></TABLE>
<P><HR SIZE=2 NOSHADE><P><A NAME="sec_1.1"></A>
<H2>1.1. entities</H2>
<P><TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD WIDTH=400>
Additional entities are added for general use.
These are the space, a dot, a non-breaking space and a new line.
<P></TD></TR></TABLE>
<FONT COLOR=#CC0033>
<P><A NAME="1"></A>1. <A HREF="#7">stylesheet</A>={<FONT
COLOR=#000033><TT><BR>
<!DOCTYPE xsl:stylesheet [<BR>
<!ENTITY sp "<xsl:text> </xsl:text>"><BR>
<!ENTITY dot "<xsl:text>.</xsl:text>"><BR>
<!ENTITY nbsp "&#160;"><BR>
<!ENTITY nl "&#xa;"><!--new line--><BR>
]><BR>
</TT>
</FONT>}<BR>
</FONT>
<FONT SIZE=1>This macro is invoked in definition <A
HREF="#7">7</A>.</FONT><BR>
<FONT COLOR=#CC0033>
<P><A NAME="2"></A>2. <A HREF="#7">root</A>={<FONT COLOR=#000033><TT><BR>
<xsl:transform<BR>
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"<BR>
version="1.0"<BR>
><BR>
</TT>
</FONT>}<BR>
</FONT>
<FONT SIZE=1>This macro is invoked in definition <A
HREF="#7">7</A>.</FONT><BR>
<FONT COLOR=#CC0033>
<P><A NAME="3"></A>3. <A HREF="#7">op</A>={<FONT COLOR=#000033><TT><BR>
<xsl:output<BR>
method="text"<BR>
encoding="utf-8"<BR>
<BR>
indent="yes"/><BR>
</TT>
</FONT>}<BR>
</FONT>
<FONT SIZE=1>This macro is invoked in definition <A
HREF="#7">7</A>.</FONT><BR>
<P><HR SIZE=3><P><A NAME="sec_1.1.1"></A>
<H3>1.1.1. create key</H3>
<P><TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD WIDTH=400>
Create the key.
<P>Give it some name.
give it a pattern to search for - it searches
the whole document but you don't need to specify
a full path unless you want to.
Give it a pattern to use for comparison when using
the key() function. This specifies the idref
attribute which is a child of elements a or b or c.
<P></TD></TR></TABLE>
<P><HR SIZE=3><P><A NAME="sec_1.1.2"></A>
<H3>1.1.2. Which form</H3>
<P><TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD WIDTH=400>
This form is better if you need to change the use
attribute for each element. It could be idref with element a,
forward-link with element b etc.
Remember that the use attribute is the content that is
matched on, relative to the 'match' attribute which
specifies the pattern to search for.
<P> <xsl:key name="caller" match="a" use="@idref"/>
<P> <xsl:key name="caller" match="b" use="@idref"/>
<P> <xsl:key name="caller" match="c" use="@idref"/>
<P>
<P>
<P></TD></TR></TABLE>
<FONT COLOR=#CC0033>
<P><A NAME="4"></A>4. <A HREF="#7">template1</A>={<FONT
COLOR=#000033><TT><BR>
<BR>
<xsl:key name="caller" match="a|b|c" use="@idref"/&g
t;<BR>
<BR>
<BR>
<xsl:template match="/doc"><BR>
<xsl:apply-templates/><BR>
</xsl:template><BR>
</TT>
</FONT>}<BR>
</FONT>
<FONT SIZE=1>This macro is invoked in definition <A
HREF="#7">7</A>.</FONT><BR>
<P><HR SIZE=2 NOSHADE><P><A NAME="sec_1.2"></A>
<H2>1.2. abc</H2>
<P><TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD WIDTH=400>
The remainder of the input elements are handled by
this template.
<P></TD></TR></TABLE>
<P><HR SIZE=3><P><A NAME="sec_1.2.1"></A>
<H3>1.2.1. layout</H3>
<P><TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD WIDTH=400>
Excuse the layout, this to produce output that is clear.
Same version is below, in comments, with fuller explanation.
<P></TD></TR></TABLE>
<FONT COLOR=#CC0033>
<P><A NAME="5"></A>5. <A HREF="#7">template2</A>={<FONT
COLOR=#000033><TT><BR>
<xsl:template match="a|b|c"><BR>
<BR>
<xsl:variable name="here" select="@id"/><BR>
<xsl:value-of select="@id"/> is called by (&l
t;xsl:choose><xsl:when<BR>
test="(key('caller',$here))/@id"><xsl:for-each<BR>
select="key('caller',$here)/@id"> <xsl:value-of
<BR>
select="."/> <xsl:if<BR>
test="not(position()=last())">,&sp;<BR>
</xsl:if><BR>
</xsl:for-each><BR>
</xsl:when><BR>
<BR>
<xsl:otherwise> None </xsl:otherwise></xsl:choose&g
t;)<BR>
&sp;&sp;&sp; <xsl:apply-templates/><BR>
<BR>
</xsl:template><BR>
<BR>
<BR>
</xsl:transform><BR>
</TT>
</FONT>}<BR>
</FONT>
<FONT SIZE=1>This macro is invoked in definition <A
HREF="#7">7</A>.</FONT><BR>
<FONT COLOR=#CC0033>
<P><A NAME="6"></A><B>6. File:</B> keys.xsl={<FONT COLOR=#000033><A
HREF="#7">templates</A><TT><BR>
</TT>
</FONT>}<BR>
</FONT>
<FONT SIZE=1>This macro is attached to an output file.</FONT>
<FONT COLOR=#CC0033>
<P><A NAME="7"></A>7. <A HREF="#6">templates</A>={<FONT COLOR=#000033><A
HREF="#1">stylesheet</A><TT> </TT>
<A HREF="#2">root</A><A HREF="#3">op</A><TT> </TT>
<A HREF="#4">template1</A><TT> </TT>
<A HREF="#5">template2</A><TT> </TT>
</FONT>}<BR>
</FONT>
<FONT SIZE=1>This macro is invoked in definition <A
HREF="#6">6</A>.</FONT><BR>
<P>
<HR SIZE=4 NOSHADE>
<CENTER><B>End Of File</B></CENTER>
<HR SIZE=4 NOSHADE>
</BODY>
<!--------------------------------------------------------------------------
--->
<!-- END OF AUTOMATICALLY GENERATED HTML FILE
-->
<!--------------------------------------------------------------------------
--->
</HTML>
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list