Part of Literate Programming in XML 05 Oct 2001 $Id: tangle.xweb,v 1.3 2001/10/06 13:39:05 nwalsh Exp $ 0.1 05 Oct 2001 ndw Initial draft. NormanWalsh The tangle.xsl stylesheet transforms an XWEB document into a source code document. This is a relatively straightforward process: starting with the top fragment, all of the source fragments are simply stitched together, discarding any intervening documentation. The resulting tangled document is ready for use by the appropriate processor.

This XWEB document contains the source for two stylesheets, tangle.xsl and xtangle.xsl. Both stylesheets produce tangled sources, the latter is a simple customization of the former for producing XML vocabularies. Each of these stylesheets performs some initialization, sets the output method appropriately, begins processing at the root template, and processes fragments, copying the content appropriately.

The tangle stylesheet produces text output. <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" exclude-result-prefixes="src" version="1.0"> <xsl:output xmlns:xsl="http://www.w3.org/1999/XSL/Transform" method="text"/> </xsl:stylesheet>

The xtangle stylesheet produces XML output. <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" exclude-result-prefixes="src" version="1.0"> <xsl:output xmlns:xsl="http://www.w3.org/1999/XSL/Transform" method="xml"/> </xsl:stylesheet>

The stylesheet initializes the processor by loading its version information (stored in a separate file because it is shared by several stylesheets) and telling the processor to preserve whitespace on all input elements. The stylesheet also constructs a key for the ID values used on fragments. Because XWEB documents do not have to be valid according to any particular DTD or Schema, the stylesheet cannot rely on having the IDs identified as type ID in the source document. <xsl:include href="VERSION"/> <xsl:preserve-space elements="*"/> <xsl:key name="fragment" match="src:fragment" use="@id"/> <xsl:param name="top" select="'top'"/>

The root template begins processing at the root of the XWEB document. It outputs a couple of informative comments and then directs the processor to transform the src:fragment element with the $top ID. Source code fragments in the XWEB document are not required to be sequential, so it is necessary to distinguish one fragment as the primary starting point. <xsl:template match="/"> <xsl:apply-templates select="key('fragment', $top)"/> </xsl:template>

In order to tangle an XWEB document, we need only copy the contents of the fragments to the result tree. Processing src:fragment elements is easy, simply copy their children: <xsl:template match="src:fragment"> <xsl:apply-templates mode="copy"/> </xsl:template>

Copying elements to the result tree can be divided into four cases: copying passthrough elements, copying fragment references, and copying everything else.

Passthrough elements contain text that is intended to appear literally in the result tree. We use XSLT disable-output-escaping to copy it without interpretation: <xsl:template match="src:passthrough" mode="copy"> <xsl:value-of disable-output-escaping="yes" select="."/> </xsl:template>

With a unique exception, copying fragment references is straightforward: find the fragment that is identified by the cross-reference and process it. The single exception arises only in the processing of src:fragref elements in the weave.xweb document. There is a single template in the weave program that needs to copy a literal src:fragref element to the result tree. That is the only time the branch is executed. <xsl:template match="src:fragref" mode="copy"> <xsl:variable name="node" select="."/> <xsl:choose> </xsl:choose> </xsl:template>

To copy a normal fragment reference, identify what the linkend attribute points to, make sure it is valid, and process it. <xsl:otherwise> <xsl:variable name="fragment" select="key('fragment', @linkend)"/> <xsl:apply-templates select="$fragment"/> </xsl:otherwise>

Make sure that the linkend attribute points to exactly one node in the source tree. It is an error if no element exists with that ID value or if more than one exists. <xsl:if test="count($fragment) != 1"> <xsl:message terminate="yes"> <xsl:text>Link to fragment "</xsl:text> <xsl:value-of select="@linkend"/> <xsl:text>" does not uniquely identify a single fragment.</xsl:text> </xsl:message> </xsl:if>

Make sure that the linkend attribute points to a src:fragment element. FIXME: this code should test the namespace name of the $fragment <xsl:if test="local-name($fragment) != 'fragment'"> <xsl:message terminate="yes"> <xsl:text>Link "</xsl:text> <xsl:value-of select="@linkend"/> <xsl:text>" does not point to a src:fragment.</xsl:text> </xsl:message> </xsl:if>

A src:fragref that specifies disable-output-escaping is treated essentially as if it was any other element. The only exception is that the disable-output-escaping attribute is not copied. Because tangle and weave are XSLT stylesheets that process XSLT stylesheets, processing src:fragref poses a unique challenge. In ordinary tangle processing, they are expanded and replaced with the content of the fragment that they point to. But when weave.xweb is tangled, they must be copied through literally. The disable-output-escaping attribute provides the hook that allows this. <xsl:when test="@disable-output-escaping='yes'"> <xsl:element name="{name(.)}" namespace="{namespace-uri(.)}"> <xsl:for-each select="@*"> <xsl:if test="not(name(.) = 'disable-output-escaping')"> <xsl:copy/> </xsl:if> </xsl:for-each> <xsl:apply-templates mode="copy"/> </xsl:element> </xsl:when>

Everything else is copied verbatim. This is a five step process: Save a copy of the context node in $node so that we can refer to it later from inside an xsl:for-each. Construct a new node in the result tree with the same qualified name and namespace as the context node. Copy the namespace nodes on the context node to the new node in the result tree. We must do this manually because the XWEB file may have broken the content of this element into several separate fragments. Breaking things into separate fragments makes it impossible for the XSLT processor to always construct the right namespace nodes automatically. Copy the attributes. Copy the children. <xsl:template match="*" mode="copy"> <xsl:variable name="node" select="."/> <xsl:element name="{name(.)}" namespace="{namespace-uri(.)}"> <xsl:copy-of select="@*"/> <xsl:apply-templates mode="copy"/> </xsl:element> </xsl:template> For non-XML source docuements, this template will never match because there will be no XML elements in the source fragments.

Copying the namespaces is a simple loop over the elements on the namespace axis, with one wrinkle. It is an error to copy a namespace node onto an element if a namespace node is already present for that namespace. The fact that we're running this loop in a context where we've constructed the result node explicitly in the correct namespace means that attempting to copy that namespace node again will produce an error. We work around this problem by explicitly testing for that namespace and not copying it. <xsl:for-each select="namespace::*"> <xsl:if test="string(.) != namespace-uri($node)"> <xsl:copy/> </xsl:if> </xsl:for-each>

In the xtangle.xsl stylesheet, we also want to preserve XML constructs (processing instructions and comments) that we encounter in the fragments. Note that many implementations of XSLT do not provide comments in the source document (they are discarded before building the tree), in which case the comments cannot be preserved. <xsl:template match="processing-instruction()" mode="copy"> <xsl:processing-instruction name="{name(.)}"> <xsl:value-of select="."/> </xsl:processing-instruction> </xsl:template> <xsl:template match="comment()" mode="copy"> <xsl:comment> <xsl:value-of select="."/> </xsl:comment> </xsl:template>