Finalized read-character-map() and apply-character-map() functions.

diff --git a/xsl/lib/lib.xweb b/xsl/lib/lib.xweb
index bb677310633c388d2e7cfd0f561bdd71644392df..98f76d720d53782ea0e60b05123a7f61c97b4204 100644 (file)
--- a/xsl/lib/lib.xweb
+++ b/xsl/lib/lib.xweb
@@ -1,6 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <book xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
-      xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+      xmlns:dyn="http://exslt.org/dynamic"
+      xmlns:saxon="http://icl.com/saxon">
 <bookinfo>
 <title>XSL Library Template Reference</title>
 <releaseinfo role="cvs">$Id$
@@ -723,21 +725,24 @@ and preserving the delimiters as text nodes between the tokens.</para>
 
 <!-- ================================================================== -->
 
-<refentry id="replace-chars-with-strings">
+<refentry id="apply-character-map">
   <refnamediv>
-    <refname>replace-chars-with-strings</refname>
-    <refpurpose>Replace (special) characters with strings</refpurpose>
+    <refname>apply-character-map</refname>
+    <refpurpose>Apply an XSLT character map</refpurpose>
   </refnamediv>
 
   <refsect1><title>Description</title>
 
-  <para>This function replaces individual characters with strings of
-  one or more characters. It is useful mainly for replacing "special"
-  chararacters or symbols. It reads in <parameter>content</parameter>,
-  the content on which to perform the character replacement, and
-  <parameter>character-mappings</parameter>, a node set of elements
-  (the names of the elements don't matter), with each element having
-  the following attributes:
+  <para>This function applies an <ulink
+  url="http://www.w3.org/TR/xslt20/#character-maps">XSLT character
+  maps</ulink>; that is, it cause certain individual characters to be
+  substituted with strings of one or more characters. It is useful
+  mainly for replacing "special" chararacters or symbols. It reads in
+  two things: <parameter>content</parameter>, the content on which to
+  perform the character replacement, and
+  <parameter>character.map.contents</parameter>, a node set of
+  elements (the names of the elements don't matter), with each element
+  having the following attributes:
   <itemizedlist>
     <listitem>
       <simpara><tag class="attribute">character</tag>, a character to
@@ -749,8 +754,8 @@ and preserving the delimiters as text nodes between the tokens.</para>
       class="attribute">character</tag> attribute</simpara>
     </listitem>
   </itemizedlist>
-  This function uses <parameter>character-mappings</parameter> to do
-  character replacement on <parameter>content </parameter>, and then
+  This function uses <parameter>character.map.contents</parameter> to
+  do character replacement on <parameter>content</parameter>, and then
   returns the modified contents.</para>
 
   <note>
@@ -763,25 +768,25 @@ and preserving the delimiters as text nodes between the tokens.</para>
     FAQ</ulink>.</para>
   </note>
 
-  <programlisting><src:fragment id='replace-chars-with-strings.frag'>
-    <xsl:template name="replace-chars-with-strings">
+  <programlisting><src:fragment id='apply-character-map.frag'>
+    <xsl:template name="apply-character-map">
       <xsl:param name="content"/>
-      <xsl:param name="character-mappings"/>
+      <xsl:param name="character.map.contents"/>
       <xsl:variable name="replaced_text">
         <xsl:call-template name="string.subst">
           <xsl:with-param name="string" select="$content" />
           <xsl:with-param name="target" 
-                          select="$character-mappings[1]/@character" />
+                          select="$character.map.contents[1]/@character" />
           <xsl:with-param name="replacement" 
-                          select="$character-mappings[1]/@string" />
+                          select="$character.map.contents[1]/@string" />
         </xsl:call-template>
       </xsl:variable>
       <xsl:choose>
-        <xsl:when test="$character-mappings[2]">
-          <xsl:call-template name="replace-chars-with-strings">
+        <xsl:when test="$character.map.contents[2]">
+          <xsl:call-template name="apply-character-map">
             <xsl:with-param name="content" select="$replaced_text" />
-            <xsl:with-param name="character-mappings"
-                            select="$character-mappings[position() > 1]" />
+            <xsl:with-param name="character.map.contents"
+                            select="$character.map.contents[position() > 1]" />
           </xsl:call-template>
         </xsl:when>
         <xsl:otherwise>
@@ -796,10 +801,10 @@ and preserving the delimiters as text nodes between the tokens.</para>
 
 <!-- ================================================================== -->
 
-<refentry id="apply-character-map">
+<refentry id="read-character-map">
 <refnamediv>
-<refname>apply-character-map</refname>
-<refpurpose>Apply an XSLT character map</refpurpose>
+<refname>read-character-map</refname>
+<refpurpose>Read in all or part of an XSLT character map</refpurpose>
 </refnamediv>
 
 <refsect1><title>Description</title>
@@ -809,49 +814,62 @@ url="http://www.w3.org/TR/xslt20/#character-maps">character
 maps</ulink> and explains how they may be used to allow a specific
 character appearing in a text or attribute node in a final results
 tree to be substituted by a specified string of characters during
-serialization. The <function>apply-character-map</function> provides a
-means for reading and using character maps with XSLT 1.0-based XSLT
-engines. It reads the character-map contents from
-<parameter>uri</parameter>, then passes contents (in full or in part,
-depending on the value of the <parameter>use.subset</parameter>
-parameter) to the
-<function>replace-chars-with-strings</function> function,
-along with <parameter>content</parameter>, the contents on which to
+serialization. The <function>read-character-map</function> function
+provides a means for reading and using character maps with XSLT
+1.0-based tools.</para>
+
+<para>It reads the character-map contents from
+<parameter>uri</parameter> (in full or in part, depending on the value
+of the <parameter>use.subset</parameter> parameter), then passes those
+contents to the <function>apply-character-map</function> function,
+along with <parameter>content</parameter>, the data on which to
 perform the character substition.</para>
 
 <para>Using the character map "in part" means that it uses only those
-<tag>output-character</tag> elements that have a <tag
-class="attribute" >class</tag> attribute whose value matches that of
-the <parameter>subset.name</parameter>.</para>
+<tag>output-character</tag> elements that match the XPATH expression
+given in the value of the <parameter>subset.profile</parameter>
+parameter. The current implementation of that capability here relies
+on the <function>evaluate</function> extension XSLT function.</para>
 
-<programlisting><src:fragment id='apply-character-map.frag'>
-  <xsl:template name="apply-character-map">
-    <xsl:param name="content"/>
+<programlisting><src:fragment id='read-character-map.frag'>
+  <xsl:template name="read-character-map">
     <xsl:param name="use.subset"/>
-    <xsl:param name="subset.name"/>
+    <xsl:param name="subset.profile"/>
     <xsl:param name="uri"/>
     <xsl:choose>
       <xsl:when test="$use.subset != 0">
-        <xsl:call-template name="replace-chars-with-strings">
-          <xsl:with-param name="content" select="$content"/>
-          <xsl:with-param name="character-mappings"
-                          select="document($uri)//*[local-name()='output-character']
-                                  [@*[local-name() = 'class'] = $subset.name]"/>
-        </xsl:call-template>
-      </xsl:when>
-      <xsl:otherwise>
-        <xsl:call-template name="replace-chars-with-strings">
-          <xsl:with-param name="content" select="$content"/>
-          <xsl:with-param name="character-mappings"
-                          select="document($uri)//*[local-name()='output-character']"/>
-        </xsl:call-template>
+        <!-- use a subset of the character map instead of the full map -->
+        <xsl:choose>
+          <!-- xsltproc and Xalan both support dyn:evaluate() -->
+          <xsl:when test="function-available('dyn:evaluate')">
+            <xsl:copy-of select="document($uri)//*[local-name()='output-character']
+                                 [dyn:evaluate($subset.profile)]"/>
+          </xsl:when>
+          <!-- Saxon has its own evaluate() & doesn't support dyn:evaluate() -->
+          <xsl:when test="function-available('saxon:evaluate')">
+            <xsl:copy-of select="document($uri)//*[local-name()='output-character']
+                                 [saxon:evaluate($subset.profile)]"/>
+          </xsl:when>
+          <xsl:otherwise>
+            <xsl:message terminate="yes"
+>
+Error: To process character-map subsets, you must use an XSLT engine
+that supports the evaluate() XSLT extension function. Your XSLT engine
+does not support it.
+</xsl:message>
+          </xsl:otherwise>
+        </xsl:choose>
+        </xsl:when>
+        <xsl:otherwise>
+          <!-- value of $use.subet is non-zero, so use the full map -->
+        <xsl:copy-of select="document($uri)//*[local-name()='output-character']"/>
       </xsl:otherwise>
     </xsl:choose>
   </xsl:template>
-
 </src:fragment></programlisting>
 </refsect1>
 </refentry>
+
 </reference>
 
 <!-- ==================================================================  -->
@@ -999,8 +1017,8 @@ around these functions.</para>
 <src:fragref linkend="comment-escape-string"/>
 <src:fragref linkend="comment-escape-string.recursive"/>
 <src:fragref linkend="str.tokenize.keep.delimiters.frag"/>
-<src:fragref linkend="replace-chars-with-strings.frag"/>
 <src:fragref linkend="apply-character-map.frag"/>
+<src:fragref linkend="read-character-map.frag"/>
 <src:fragref linkend="count.uri.path.depth.frag"/>
 <src:fragref linkend="trim.common.uri.paths.frag"/>