This document: revision 13 April 2004
for NeumesXSLT_utils.xsl version 2.2.b

 XSLT Utilities for NeumesXML


General Information

The XSLT (XML Stylesheet Language Transformations) utilities documented here are defined in the file NeumesXSLT_utils.xsl. These utilities were designed for manipulating the content of NeumesXML files (for details, see the NEUMES Project Web site). The utilities may be reused in new XSL Transformations for NeumesXML, subject to licensing restrictions stated within the NeumexXSLT_utils.xsl file.

Each of the utilities is an XSLT template that can be invoked inside an XSLT Transformation via an XSL call-template element. The NeumexXSLT_utils.xsl source code is compatible with Version 1.0 of the XSLT specification and should be forward-compatible to later versions of XSLT.

Click here to download the source code of NeumesXSLT_utils.xsl in ZIP format. Please read and conform to the licensing restrictions, which are stated in a comments section near the top of the source code. Please note that the source code and this documentation are currently in beta-test and are subject to change at any time.

Usage Notes

Normally the NeumexXSLT_utils.xsl file is included in a containing XSLT file by directive, as follows.
<xsl:include href="http://purl.oclc.org/NEUMES/ref/NeumesXSLT_utils.xsl"/>
The containing XSLT file also must declare the NEUMES character entity set, as follows.
<!DOCTYPE NeumesXML [
<!ENTITY % NEUMES SYSTEM "http://purl.oclc.org/NEUMES/ref/NEUMES_characters.xml">
%NEUMES;
]>
The above declaration must precede the XSLT stylesheet declaration in the containing XSLT file.

Index of Templates

GetTonalMvmtBounds
AggregateHeights
LookupMovement
MapGlyphImage
ComputeHeight
LookupCF
EscQuot
EscApos



XSLT template: GetTonalMvmtBounds

Get Tonal Movement Bounds
This template finds the lower bound and the upper bound of cumulative tonal movement in this <transcription>, as compared to the first tone in the initial glyph of the <transcription>.
These data typically are used as a "floor" and "ceiling" in establishing a baseline offset (in pixels) of the initial glyph for a visualization of the transcription, but these data may be used for analytical purposes (viz, ambitus), and so on.

Signature
	<xsl:template name="GetTonalMvmtBounds">
		<xsl:param name="neumeNodeList" select="//nxm:neume"/>
		<xsl:param name="tonalMvmtAggregate" select="0"/>
		<xsl:param name="tonalMvmtFloor" select="0"/>
		<xsl:param name="tonalMvmtCeiling" select="0"/>
Preconditions
"neumeNodeList" is a context node-set that is a list of the <neume> nodes.
"tonalMvmtAggregate" is initially 0.
"tonalMvmtFloor" is initially 0.
"tonalMvmtFloor" is initially 0.
Usage notes: The template sets these values by default, and so they do not need to be specified in a call to the template (see ¶ Example of Use). If, however, these values are set explicitly in a call to the template, then the "neumeNodeList" may be any list of <neume> nodes; the initial numerical values may be changed from what is stated above, but this is not recommended and should be done only with caution.

Postconditions
Template generates a multi-valued, comma-delimited string consisting of two numbers:
(a) the first number equals the lowest tonal movement below the tone of the first neumatic symbol in the transcription ("the global movement floor");
(b) the second number equals the highest tonal movement above the tone of the first neumatic symbol in the transcription ("the global movement ceiling").
The unit of measure for these numbers is approximately equivalent to the musical interval of a major second.
The global aggregate movement can be simply computed as the difference between these two numbers.

Dependencies
This template calls the "AggregateHeights" template [q.v., this document].

Example of Use
<xsl:variable name="multiVal"> <!--a multi-valued string is generated-->
	<xsl:call-template name="GetTonalMvmtBounds"/>
</xsl:variable>
<!-- unpack *multiVal* (is comma-delimited): -->
<xsl:variable name="movementFloor" select="substring-before($multiVal, ',')"/>
<xsl:variable name="movementCeiling" select="substring-after($multiVal, ',')"/>
Internal Algorithm
Template does node-traversal using tail recursion. Maintains state of "floor" for lowest tonal movement and "ceiling" for highest tonal movement, as measured from the first "tone" of the initial glyph in the transcription. Also, maintains "movement aggregate", which is a cursor to the current, cumulative movement. For each <neume> node in the node list, *AggregateHeights* template is dispatched to compute the local aggregate movement, local floor, and local ceiling of that <neume>. If the <neume> contains a Tonal Movement of [UNK], then the cumulative movement is reset to 0, and the local aggregate movement since the last [UNK] becomes the new cumulative movement; in these cases, the cumulative movement cursor is not added to the local floor and local ceiling for purposes of comparing to the global floor and global ceiling. Otherwise (ie, no [UNK] in the <neume>), the local aggregate movement is added to the global aggregate movement, and both the local floor and local ceiling are added to the global aggregate movement for purposes of comparing to the global floor and global ceiling.



XSLT template: AggregateHeights

Aggregate Heights
This template parses a NEUMES character sequence, and computes the aggregate Tonal Movement, the lowest Tonal Movement, and the highest Tonal Movement in the sequence. Typically the sequence is the content of one <neume> node. If the sequence contains an [UNK] character (ie, unknown tonal movement), then a flag is set in the generated value string.

Signature
	<xsl:template name="AggregateHeights">
		<xsl:param name="sequenceToParse" select="text()"/>
		<xsl:param name="localMvmtAggregate" select="0"/>
		<xsl:param name="localMvmtFloor" select="0"/>
		<xsl:param name="localMvmtCeiling" select="0"/>
		<xsl:param name="resetFlag" select="''"/>
Preconditions
"sequenceToParse" is the text() of the current context node, typically a <neume> node.
"localMvmtAggregate" is initially 0.
"localMvmtFloor" is initially 0.
"localMvmtCeiling" is initially 0.
"resetFlag" is initially '' (ie, an empty string).
Usage notes: The template sets these values by default, and so they do not need to be specified in a call to the template (see ¶ Example of Use). In particular, the "sequenceToParse" parameter selects by default the text() of the current context node. If, however, the parameter values are set explicitly in a call to the template, then the "sequenceToParse" may be any character sequence; the initial numerical values may be changed from what is stated above, but this is not recommended and should be done only with caution.

Postconditions
Template generates a comma-delimited, multi-valued string by the following expression. concat($localMvmtAggregate, ',', $localMvmtFloor, ',', $localMvmtFloor, ',', $resetFlag)
If an [UNK] Tonal Movement character is present in the parsed string, then "resetFlag" is set to the value "888" (otherwise it remains empty), and "localMvmtAggregate" is set to the aggregate tonal movement (if any, otherwise 0) since the last [UNK] tonal movement in the string. In any case, "localMvmtFloor" and "localMvmtCeiling" record the tonal movement within the parsed string, but the local tonal cursor is reset to 0 wherever an [UNK] character appears in the string.

Dependencies
This template calls the "LookupMovement" template [q.v., this document].

Example of Use
<xsl:variable name="multiVal">
	<xsl:call-template name="AggregateHeights">
		<xsl:with-param name="sequenceToParse"
			select="self::nxm:neume[1]/text()"/>
		<xsl:with-param name="localMvmtAggregate" select="0"/>
		<xsl:with-param name="localMvmtFloor" select="0"/>
		<xsl:with-param name="resetFlag" select="''"/>
	</xsl:call-template>
</xsl:variable>
Internal Algorithm
Recursive template parses character-by-character the entire NEUMES subsequence of one <neume>. Assumes all Tonal Movement characters in the sequence are for neumatic glyphs. (Template should not be called for <rubric> nodes.) Remark that each tone in a multi-tone glyph has an individual Tonal Movement specifier. Where a Tonal Movement is [UNK], the cumulative movement at that point is reset to 0. Recursion stops at empty string, not at [END] character.



XSLT template: LookupMovement

Lookup Tonal Movement
This template translates from a NEUMES Tonal Movement character to a positive or negative integer representing a number of "steps" upward or downward. A "step" is approximately equivalent to the musical interval of a major second.

Signature
	<xsl:template name="LookupMovement">
		<xsl:param name="ThisChar"/>
Preconditions
"ThisChar" is a NEUMES Tonal Movement character.

Postconditions
Generates a positive or negative integer. If "ThisChar" is [no_preced], then a value of 0 is generated. If it is [UNK], then a value of 888 is generated. As a warning against improper call, if it is not a Tonal Movement character, then a value of 999 is generated.
Remarks: The preferred mapping from [up], [up_little], and [up_lot] (and their dn converses) to a number of "steps" is currently under advisement and is subject to change.

Dependencies
None.

Example of Use
<xsl:variable name="Movement">
	<xsl:call-template name="LookupMovement">
		<xsl:with-param name="ThisChar" select="$ThisChar"/>
	</xsl:call-template>
</xsl:variable>
Internal Algorithm
Simple <choose> lookup.



XSLT template: MapGlyphImage

Map Glyph Image
This template maps from a NEUMES character of a neumatic glyphs to a .gif filename. The mapping includes logic for substitute style glyphs. "SubStyle" can be a Substitute Style or a Qualifier specifier.

Signature
	<xsl:template name="MapGlyphImage">
		<xsl:param name="CharToShow"/>
		<xsl:param name="SubStyle"/> <!--Substitute Style-->
Preconditions
"CharToShow" is a NEUMES neumatic glyph character, typically read from a NeumesXML transcription file.
"SubStyle" is a NEUMES Substitute Style character or Qualifier character that modifies "CharToShow"; typically this follows immediately after "CharToShow" in a transcription file (possibly with an intervening CF); it may be an empty string to indicate that no Substitute Style is specified.

Postconditions
Generates a string containing a filename (typically ending in ".gif") corresponding to the standard, stylized image of the "CharToShow". (Typically, the currently-selected notational family determines the location from which this standard image is retrieved.)

Dependencies
None.

Example of Use
<xsl:call-template name="MapGlyphImage">
	<xsl:with-param name="CharToShow" select="$CharToShow"/>
	<xsl:with-param name="SubStyle">
		<xsl:choose>
		<xsl:when test="contains('&SubstituteStyles;', $ThirdChar) or
			contains('&Qualifiers;', $ThirdChar)">
			<xsl:value-of select="$ThirdChar"/>
		</xsl:when>
		<xsl:when test="contains('&SubstituteStyles;', $SecondChar) or
			contains('&Qualifiers;', $SecondChar)">
			<xsl:value-of select="$SecondChar"/>
		</xsl:when>
		<xsl:otherwise>
			<xsl:value-of select="'&ObjReplace;'"/>
		</xsl:otherwise>
		</xsl:choose>
	</xsl:with-param>
</xsl:call-template>
Internal Algorithm
Simple, two-tiered <choose> lookup.
[Note: template may be expanded to get image dimensions from a manifest file.]


XSLT template: ComputeHeight

Compute Height
This template computes the "leading" movement and the "internal" movement of one neumatic glyph. Typically this template is called once for each glyph in a <neume> node. The "leading" movement is the tonal movement from the previous neumatic glyph to the beginning of this glyph. Because a neumatic glyph can span more than one tone, the "internal" movement is the sum of movements within the glyph (excluding the leading movement). Tonal movement is measured in terms of "steps," where a "step" is approximately equal to the musical interval of a major second. This template generates a multi-valued, comma-delimited string containing two integers (which can be positive or negative) for the "leading" movement and the "internal" movement.

Signature
	<xsl:template name="ComputeHeight">
		<xsl:param name="sequenceToParse"/>
		<xsl:param name="leadingMvmt" select="999"/>
		<xsl:param name="internalMvmt" select="0"/>
Preconditions
"sequenceToParse" is a string of NEUMES characters.
"leadingMvmt" is initially 999.
"internalMvmt" is initially 0.
Usage notes: The "leadingMvmt" and "internalMvmt" are set initially by the template by default, and so they do not need to be specified in a call to the template (see ¶ Example of Use). The "sequenceToParse" parameter, however, must be set by the caller. The "leadingMvmt" and "internalMvmt" parameters may be set explicitly in a call to the template, but this is not recommended and should be done only with caution.

Postconditions
Template generates a comma-separated string containing the leading movement (tonal movement from the previous glyph) and the internal movement (sum of internal movement in a multi-tone glyph). If the generated value for leading movement is 888, this means that the initial tone of the glyph is [UNK]. If the character sequence passed to the template contains more than one neumatic glyph, only the first glyph is used for the movement computation.

Dependencies
This template calls the "LookupMovement" template [q.v., this document].

Example of Use
<xsl:variable name="returnValues">
	<xsl:call-template name="ComputeHeight">
		<xsl:with-param name="sequenceToParse" select="$sequenceToParse"/>
	</xsl:call-template>
</xsl:variable>
<xsl:variable name="leadingMvmt" select="substring-before($returnValues, ',')"/>
<xsl:variable name="internalMvmt" select="substring-after($returnValues, ',')"/>
Internal Algorithm
Recursive template parses character-by-character the NEUMES sequence of one glyph. Recursion stops at first [END] character found in the sequence. "leadingMvmt" value of 999 is a flag indicating that the leading movement has not yet been set; once this has changed to a value other than 999, subsequent tonal movement is aggregated to "internalMvmt." Note that each tone in a multi-tone glyph has an individual tonal movement specifier. Template generates a comma-delimited string containing the "leadingMvmt" (ie, tonal movement from the previous glyph) and the "internalMvmt" (ie, sum of internal movement in a multi-tone glyphs, else 0). If initial tone of the glyph is [UNK], then the value of "leadingMvmt" is set to 888.



XSLT template: LookupCF

Lookup Certainty Factor
This template translates from a NEUMES Certainty Factor character to a positive or negative integer.

Signature
	<xsl:template name="LookupCF">
		<xsl:param name="CF"/>
Preconditions
"CF" is a NEUMES Certainty Factor character.

Postconditions
Generates a positive or negative integer in the range [-10,10] corresponding the the Certainty Factor. If "CF" is not a NEUMES Certainty Factor, then a value of 10 is generated.

Dependencies
None.

Example of Use
<xsl:call-template name="LookupCF">
	<xsl:with-param name="CF" select="$CF"/>
</xsl:call-template>
Internal Algorithm
Simple <choose> lookup. Defaults to a value of 10. Character [CF_u00] maps to 0 (not to -0).


XSLT template: EscQuot

Escape Quotes
This template replaces each occurrence of the double-quote character ["] (ie, ASCII codepoint #034) in a string by an equivalent escaped sequence [\"]. Typically this is used to disambiguate the nesting of double-quotes in an output string, such as for a JavaScript document.write() instruction in an XSLT file.

Signature
	<xsl:template name="EscQuot">
		<xsl:param name="passString"/>
Preconditions
"passString" is a character string; it can be an empty string.

Postconditions
Generates a string equivalent to "passString" with all its occurrences of the double-quote character (ie, ASCII codepoint #034) replaced by an escaped double-quote character.

Dependencies
None.

Example of Use
<xsl:variable name="userComment" select="self::node()/@description"/>
	<xsl:variable name="noQuot">
		<xsl:call-template name="EscQuot">
			<xsl:with-param name="passString" select="$userComment"/>
		</xsl:call-template>
	</xsl:variable>
<xsl:/variable>
Internal Algorithm
Template calls itself recursively, isolating the first occurrence of double-quote by the substring-before and substring-after functions. The double-quote character is defined as a variable, and this variable is used in the substring expressions in order to work around the syntax ambiguity problem.


XSLT template: EscApos

Escape Apostrophes
This template replaces each occurrence of the apostrophe character ['] (ie, ASCII codepoint #039) in a string by an equivalent escaped sequence [\']. Typically this is used to disambiguate the nesting of single-quotes in an output string, such as for a JavaScript document.write() instruction in an XSLT file.

Signature
	<xsl:template name="EscApos">
		<xsl:param name="passString"/>
Preconditions
"passString" is a character string; it can be an empty string.

Postconditions
Generates a string equivalent to "passString" with all its occurrences of the apostrophe character (ie, ASCII codepoint #039) replaced by an escaped apostrophe character.

Dependencies
None.

Example of Use
<xsl:variable name="userComment" select="self::node()/@description"/>
	<xsl:variable name="noApos">
		<xsl:call-template name="EscApos">
			<xsl:with-param name="passString" select="$userComment"/>
		</xsl:call-template>
	</xsl:variable>
<xsl:/variable>
Internal Algorithm
Template calls itself recursively, isolating the first occurrence of apostrophe by the substring-before and substring-after functions. The aspostrophe character is defined as a variable, and this variable is used in the substring expressions in order to work around the syntax ambiguity problem.


Copyright © 2004 Louis W. G. Barton. All rights reserved.