This is the mail archive of the xsl-list@mulberrytech.com mailing list .


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Self documentation, tangle and weave, *an* answer


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 "&#160;">
<!ENTITY nl "&#xa;"><!--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>
&lt;!DOCTYPE&nbsp;xsl:stylesheet&nbsp;[<BR>
&lt;!ENTITY&nbsp;sp&nbsp;"&lt;xsl:text&gt;&nbsp;&lt;/xsl:text&gt;"&gt;<BR>
&lt;!ENTITY&nbsp;dot&nbsp;"&lt;xsl:text&gt;.&lt;/xsl:text&gt;"&gt;<BR>
&lt;!ENTITY&nbsp;nbsp&nbsp;"&amp;#160;"&gt;<BR>
&lt;!ENTITY&nbsp;nl&nbsp;"&amp;#xa;"&gt;&lt;!--new&nbsp;line--&gt;<BR>
]&gt;<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>
&lt;xsl:transform<BR>
&nbsp;xmlns:xsl="http://www.w3.org/1999/XSL/Transform"<BR>
&nbsp;version="1.0"<BR>
&gt;<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>
&lt;xsl:output<BR>
&nbsp;&nbsp;method="text"<BR>
&nbsp;&nbsp;encoding="utf-8"<BR>
<BR>
indent="yes"/&gt;<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>  &lt;xsl:key name="caller" match="a" use="@idref"/&gt;

<P>  &lt;xsl:key name="caller" match="b" use="@idref"/&gt;

<P>  &lt;xsl:key name="caller" match="c" use="@idref"/&gt;

<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>
&nbsp;&lt;xsl:key&nbsp;name="caller"&nbsp;match="a|b|c"&nbsp;use="@idref"/&g
t;<BR>
<BR>
&nbsp;<BR>
&nbsp;&lt;xsl:template&nbsp;match="/doc"&gt;<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&lt;xsl:apply-templates/&gt;<BR>
&nbsp;&nbsp;&lt;/xsl:template&gt;<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>
&nbsp;&nbsp;&lt;xsl:template&nbsp;match="a|b|c"&gt;<BR>
<BR>
&lt;xsl:variable&nbsp;name="here"&nbsp;select="@id"/&gt;<BR>
&lt;xsl:value-of&nbsp;select="@id"/&gt;&nbsp;is&nbsp;called&nbsp;by&nbsp;(&l
t;xsl:choose&gt;&lt;xsl:when<BR>
test="(key('caller',$here))/@id"&gt;&lt;xsl:for-each<BR>
&nbsp;&nbsp;&nbsp;select="key('caller',$here)/@id"&gt;&nbsp;&lt;xsl:value-of
<BR>
&nbsp;&nbsp;&nbsp;select="."/&gt;&nbsp;&lt;xsl:if<BR>
&nbsp;&nbsp;test="not(position()=last())"&gt;,&amp;sp;<BR>
&nbsp;&nbsp;&nbsp;&lt;/xsl:if&gt;<BR>
&nbsp;&nbsp;&lt;/xsl:for-each&gt;<BR>
&nbsp;&lt;/xsl:when&gt;<BR>
<BR>
&lt;xsl:otherwise&gt;&nbsp;None&nbsp;&lt;/xsl:otherwise&gt;&lt;/xsl:choose&g
t;)<BR>
&amp;sp;&amp;sp;&amp;sp;&nbsp;&lt;xsl:apply-templates/&gt;<BR>
<BR>
&nbsp;&nbsp;&lt;/xsl:template&gt;<BR>
<BR>
<BR>
&lt;/xsl:transform&gt;<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>&nbsp;</TT>
<A HREF="#2">root</A><A HREF="#3">op</A><TT>&nbsp;</TT>
<A HREF="#4">template1</A><TT>&nbsp;</TT>
<A HREF="#5">template2</A><TT>&nbsp;&nbsp;</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

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]