LiterateXSLT™ - synthesizing XSLT stylesheets


Table of Contents

1. LiterateXSLT™ - synthesizing XSLT stylesheets - Crane-LiterateXSLT.xsl
1.1. Keys for quick access
1.2. Building the result stylesheet
1.3. Handle all text processing
1.4. Result element handling
1.5. Attribute processing
1.6. Content replacement facilities
1.7. Variable processing
1.8. Verbatim processing
1.9. Error reporting
2. Index

1. LiterateXSLT™ - synthesizing XSLT stylesheets - Crane-LiterateXSLT.xsl

Filename: Crane-LiterateXSLT.xsl

$Id: Crane-LiterateXSLT.xsl,v 1.62 2019/04/18 02:36:29 admin Exp $

A XSLT stylesheet to create an XSLT from an annotated prototypical result instance.

This document is the stylesheet documentation for the LiterateXSLT™ environment, not the user documentation. See readme-Crane-LiterateXSLT.html for the user documentation.

Copyright (C) - Crane Softwrights Ltd.
              - http://www.CraneSoftwrights.com/links/res-lxslts.htm

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, 
  this list of conditions and the following disclaimer. 
- Redistributions in binary form must reproduce the above copyright notice, 
  this list of conditions and the following disclaimer in the documentation 
  and/or other materials provided with the distribution. 
- The name of the author may not be used to endorse or promote products 
  derived from this software without specific prior written permission. 

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN 
NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Note: for your reference, the above is the "Modified BSD license", this text
      was obtained 2003-07-26 at http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5

Note this is an XSLT 2.0 adaptation of an XSLT 1.0 original stylesheet so may not take advantage of all XSLT 2.0 facilities available.

stylesheet-prefix="xsl" result-prefix="xst" (xst:namespace-alias)

When using XSLT 1.0 processor, the prefix in this stylesheet cannot be "xsl" and still have the result stylesheet using the "xsl" prefix, thus this aliasing is required, and XSLT is referenced in this stylesheet using the "xst" prefix.

elements="*" (xst:strip-space)

Presume all indentation in the input is cosmetic and that the user has used xml:space= to preserve significant white-space.

elements="xst:text" (xst:preserve-space)

Of course any embedded XSLT text instructions must presume to preserve white-space-only text nodes.

xi:in select="/" as="document-node()" (xst:variable)

Be able to refer to the source document when in a literal.

1.1. Keys for quick access

x:templates match="*[ @x:match | @x:name | @x:content-name ]" use="'all'" (xst:key)

All those elements that create template rules in the result

x:variables match="@x:content-variable" use="'all'" (xst:key)

All those elements that create global variables in the result.

x:verbatims match="x:verbatim" use="@label" (xst:key)

All declared chunks of verbatim XSLT code.

x:sets match="*[ @x:set ]" use="'all'" (xst:key)

All declared attribute sets.

1.2. Building the result stylesheet

match="/" (xst:template)

Where all processing begins

x:make-template-rule (xst:template)

Make a template rule for one of the annotated result elements that need one. The current node is the annotated result element.

Parameter name as="xsd:string?"

The name of the template rule, or empty for no name.

Parameter content as="xsd:boolean"

The content of the template rule.

1.3. Handle all text processing

match="text()[ancestor::*[@xml:space][1][@xml:space='preserve']]" (xst:template)

Any text node in the influence of xml:space="preserve" goes out as it is. The output isn't indented, so no wrapping is required.

match="text()[ancestor::*[@xml:space][1][@xml:space='preserve'] [tokenize(@x:lose,'\s+')='xml:space']]" priority="1" (xst:template)

Any text node in the influence of xml:space="preserve" where the xml:space attribute is not preserved needs to go out with a text instruction.

match="text()" (xst:template)

Implicit text node put into a wrapper because the stylesheet may be indented

match="xst:text" (xst:template)

An existing <xsl:text> instruction needs to be preserved.

1.4. Result element handling

x:do-comment (xst:template)

Comments can be made in a number of situations

match="*" (xst:template)

At this point a result tree element is being acted on, which may produce many different results.

Parameter making-a-template as="xsd:boolean" tunnel="yes"

An indication this is being called in order to reconstitute the element as part of making a template.

x:process-literate-attributes (xst:template)

At this point the condition for the generation of the result tree element has been tested so now it is time to interpret the rest.

Parameter making-a-template as="xsd:boolean" tunnel="yes"

An indication this is being called in order to reconstitute the element as part of making a template.

x:reproduce-element (xst:template)

At this point the current node needs to be replicated in the stylesheet, but that doesn't happen when the current node is <x:branch, in which case only the content is handled.

x:params (xst:template)

Find all the child parameters for a named template

x:with-params (xst:template)

Find all the calling parameters for a called template

1.5. Attribute processing

x:build-attribute-sets (xst:template)

Building attribute sets from collections of attributes in the input. This is done at the start of processing before the elements are pushed through the template rules.

match="@*" mode="x:build-one-attribute" (xst:template)

Copy a single attribute to the result using an instruction instead of a literal result attribute. This satisfies the building of attribute sets as well as the reconsitition of prototypical attributes.

x:do-attributes (xst:template)

Copy attributes from the input

x:copy-specific-attributes (xst:template)

Copy the attributes for the current element node to the result using a literal result attribute for the fixed values and an instruction for the calculated values.

Parameter attributes as="attribute()*"

The non-literate source tree attributes to copy. Use literal result attributes for fixed values and attribute instructions for calculations.

x:conditional-attribute-evaluation (xst:template)

Check that the calculated attribute to be added needs to be non-empty. The current node is an attribute node, either the attribute being overridden, or the calculation attribute.

While there are convenient XSLT 2.0 ways of doing this, to be portable with XSLT 1.0 it must be done in a cumbersome fashion.

Parameter name as="xsd:string"

The name of the attribute to be added

Parameter calculation as="attribute()"

How the value of the attribute is calculated.

1.6. Content replacement facilities

x:do-content-and-post (xst:template)

Handle the content for a given element and post-process it

x:do-content (xst:template)

Handle the content for a given element

1.7. Variable processing

Variables can be declared at either a local or global scope.

match="x:global-variable | x:param | x:with-param" (xst:template)

Do nothing when encountering a global variable or parameter because it has already been processed before it is encountered

x:local-variable match="x:local-variable" (xst:template)

When encountering a local variable, declare it in its context.

1.8. Verbatim processing

All of the content in a verbatim element should be stylesheet content, so copying the stylesheet content into the result stylesheet should be preserved as is (no special handling of xml:space).

match="x:verbatim" (xst:template)

Do nothing with actual verbatim elements encountered in order, as they are only used by reference.

x:copy-verbatim (xst:template)

Now is the time to pull in the labeled verbatim content.

Parameter names as="xsd:string*"

The list of named verbatim chunks to be pulled in.

match="comment()|processing-instruction()" mode="x:copy-verbatim" (xst:template)

Preserve any annotations

match="*" mode="x:copy-verbatim" (xst:template)

Reconstitute any verbatim elements.

match="text()" mode="x:copy-verbatim" (xst:template)

Preserve all text nodes because this is stylesheet content, not result content.

1.9. Error reporting

match="x:message[string(@condition)]" (xst:template)

When encountering a conditional message, test the condition.

match="x:message" (xst:template)

When encountering an unconditional message, report it.

x:error (xst:template)

Report an error (non-fatal).

Parameter msg as="xsd:string?"

The message to report

x:context (xst:template)

Report a document context suitable for XPath searching

x:verbatim-refs match="@x:prefix | @x:suffix | @x:infix " use="'all'" (xst:key)

Track references to verbatim content.

x:sees match="@x:see[. != '']" use="'all'" (xst:key)

Track see-also references.

x:templates-with-matches match="*[ @x:match ]" use="@x:name" (xst:key)

Track templates that have match attributes by their name.

x:sets-unique match="@x:set" use="." (xst:key)

Track references to attribute sets.

x:variables-unique match="@x:content-variable" use="." (xst:key)

Track the creation of variables.

xi:debug as="xsd:string*" (xst:variable)

Various checks of input criteria. Should any fail each that do will leave a breadcrumb in the variable. If the variable is then non-empty there must have been an error reported.

x:check-verbatim (xst:template)

Check a set of verbatim chunk names for being resolvable.

Parameter names as="xsd:string*"

The list of names.

x:debug-exit (xst:template)

Exit if there are any problems detected, as indicated by a non-empty debug string.

2. Index

B C D E I L M P R S T V W

B

C

D

E

I

L

M

P

R

S

T

V

W