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.
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.
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.
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.
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.
Comments can be made in a number of situations
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.
Find all the child parameters for a named template
Find all the calling parameters for a called template
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.
x:do-content-and-post (xst:template)
Handle the content for a given element and post-process it
Handle the content for a given element
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.
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.
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.
Report an error (non-fatal).
Parameter
msg as="xsd:string?"
The message to report
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.
Exit if there are any problems detected, as indicated by a non-empty debug string.
x:check-verbatim
(Error reporting - Crane-LiterateXSLT.xsl
)x:conditional-attribute-evaluation
(Attribute processing - Crane-LiterateXSLT.xsl
)x:context
(Error reporting - Crane-LiterateXSLT.xsl
)x:copy-specific-attributes
(Attribute processing - Crane-LiterateXSLT.xsl
)x:copy-verbatim
(Verbatim processing - Crane-LiterateXSLT.xsl
)xi:debug
(Error reporting - Crane-LiterateXSLT.xsl
)x:debug-exit
(Error reporting - Crane-LiterateXSLT.xsl
)x:do-attributes
(Attribute processing - Crane-LiterateXSLT.xsl
)x:do-comment
(Result element handling - Crane-LiterateXSLT.xsl
)x:do-content
(Content replacement facilities - Crane-LiterateXSLT.xsl
)x:do-content-and-post
(Content replacement facilities - Crane-LiterateXSLT.xsl
)