doc/xslt/common/charmap.xsl

   1 <?xml version='1.0'?>
   2 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   3                 xmlns:doc="http://nwalsh.com/xsl/documentation/1.0"
   4                 xmlns:dyn="http://exslt.org/dynamic"
   5                 xmlns:saxon="http://icl.com/saxon"
   6                 xmlns:xlink="http://www.w3.org/1999/xlink"
   7                 exclude-result-prefixes="doc dyn saxon"
   8                 version='1.0'>
   9
  10 <!-- ********************************************************************
  11      $Id: charmap.xsl 7266 2007-08-22 11:58:42Z xmldoc $
  12      ********************************************************************
  13
  14      This file is part of the XSL DocBook Stylesheet distribution.
  15      See ../README or http://docbook.sf.net/release/xsl/current/ for
  16      copyright and other information.
  17
  18      ******************************************************************** -->
  19 <doc:reference xmlns="" xml:id="charmap">
  20   <info>
  21     <title>Common » Character-Map Template Reference</title>
  22     <releaseinfo role="meta">
  23       $Id: charmap.xsl 7266 2007-08-22 11:58:42Z xmldoc $
  24     </releaseinfo>
  25   </info>
  26   <!-- * yes, partintro is a valid child of a reference... -->
  27   <partintro xml:id="partintro">
  28     <title>Introduction</title>
  29     <para>This is technical reference documentation for the
  30       character-map templates in the DocBook XSL Stylesheets.</para>
  31     <note>
  32       <para>These templates are defined in a separate file from the set
  33         of “common” templates because some of the common templates
  34         reference DocBook XSL stylesheet parameters, requiring the
  35         entire set of parameters to be imported/included in any
  36         stylesheet that imports/includes the common templates.</para>
  37       <para>The character-map templates don’t import or include
  38         any DocBook XSL stylesheet parameters, so the
  39         character-map templates can be used without importing the
  40         whole set of parameters.</para>
  41     </note>
  42     <para>This is not intended to be user documentation. It is
  43       provided for developers writing customization layers for the
  44       stylesheets.</para>
  45   </partintro>
  46 </doc:reference>
  47
  48 <!-- ===================================== -->
  49 <doc:template name="apply-character-map" xmlns="">
  50   <refpurpose>Applies an XSLT character map</refpurpose>
  51   <refdescription id="apply-character-map-desc">
  52     <para>This template applies an <link
  53       xlink:href="http://www.w3.org/TR/xslt20/#character-maps"
  54       >XSLT character map</link>; that is, it causes certain
  55       individual characters to be substituted with strings of one
  56       or more characters. It is useful mainly for replacing
  57       multiple “special” characters or symbols in the same target
  58       content. It uses the value of
  59       <parameter>map.contents</parameter> to do substitution on
  60       <parameter>content</parameter>, and then returns the
  61       modified contents.</para>
  62     <note>
  63       <para>This template is a very slightly modified version of
  64         Jeni Tennison’s <function>replace_strings</function>
  65         template in the <link
  66           xlink:href="http://www.dpawson.co.uk/xsl/sect2/StringReplace.html#d9351e13"
  67           >multiple string replacements</link> section of Dave Pawson’s
  68         <link xlink:href="http://www.dpawson.co.uk/xsl/index.html"
  69           >XSLT FAQ</link>.</para>
  70       <para>The <function>apply-string-subst-map</function>
  71         template is essentially the same template as the
  72         <function>apply-character-map</function> template; the
  73         only difference is that in the map that
  74         <function>apply-string-subst-map</function> expects, <tag
  75           class="attribute">oldstring</tag> and <tag
  76           class="attribute">newstring</tag> attributes are used
  77         instead of <tag class="attribute">character</tag> and <tag
  78           class="attribute">string</tag> attributes.</para>
  79     </note>
  80   </refdescription>
  81   <refparameter id="apply-character-map-params">
  82     <variablelist>
  83       <varlistentry><term>content</term>
  84         <listitem>
  85           <para>The content on which to perform the character-map
  86             substitution.</para>
  87         </listitem>
  88       </varlistentry>
  89       <varlistentry><term>map.contents</term>
  90         <listitem>
  91           <para>A node set of elements, with each element having
  92             the following attributes:
  93             <itemizedlist>
  94               <listitem>
  95                 <simpara><tag class="attribute">character</tag>, a
  96                   character to be replaced</simpara>
  97               </listitem>
  98               <listitem>
  99                 <simpara><tag class="attribute">string</tag>, a
 100                   string with which to replace <tag
 101                     class="attribute">character</tag></simpara>
 102               </listitem>
 103             </itemizedlist>
 104           </para>
 105         </listitem>
 106       </varlistentry>
 107     </variablelist>
 108   </refparameter>
 109 </doc:template>
 110 <xsl:template name="apply-character-map">
 111   <xsl:param name="content"/>
 112   <xsl:param name="map.contents"/>
 113   <xsl:variable name="replaced_text">
 114     <xsl:call-template name="string.subst">
 115       <xsl:with-param name="string" select="$content" />
 116       <xsl:with-param name="target"
 117         select="$map.contents[1]/@character" />
 118       <xsl:with-param name="replacement"
 119         select="$map.contents[1]/@string" />
 120     </xsl:call-template>
 121   </xsl:variable>
 122   <xsl:choose>
 123     <xsl:when test="$map.contents[2]">
 124       <xsl:call-template name="apply-character-map">
 125         <xsl:with-param name="content" select="$replaced_text" />
 126         <xsl:with-param name="map.contents"
 127           select="$map.contents[position() > 1]" />
 128       </xsl:call-template>
 129     </xsl:when>
 130     <xsl:otherwise>
 131       <xsl:value-of select="$replaced_text" />
 132     </xsl:otherwise>
 133   </xsl:choose>
 134 </xsl:template>
 135
 136 <!-- ===================================== -->
 137 <doc:template name="read-character-map" xmlns="">
 138   <refpurpose>Reads in all or part of an XSLT character map</refpurpose>
 139   <refdescription id="read-character-map-desc">
 140     <para>The XSLT 2.0 specification describes <link
 141         xlink:href="http://www.w3.org/TR/xslt20/#character-maps"
 142         >character maps</link> and explains how they may be used
 143       to allow a specific character appearing in a text or
 144       attribute node in a final result tree to be substituted by
 145       a specified string of characters during serialization. The
 146       <function>read-character-map</function> template provides a
 147       means for reading and using character maps with XSLT
 148       1.0-based tools.</para>
 149     <para>This template reads the character-map contents from
 150       <parameter>uri</parameter> (in full or in part, depending on
 151       the value of the <parameter>use.subset</parameter>
 152       parameter), then passes those contents to the
 153       <function>apply-character-map</function> template, along with
 154       <parameter>content</parameter>, the data on which to perform
 155       the character substitution.</para>
 156     <para>Using the character map “in part” means that it uses only
 157       those <tag>output-character</tag> elements that match the
 158       XPath expression given in the value of the
 159       <parameter>subset.profile</parameter> parameter. The current
 160       implementation of that capability here relies on the
 161       <function>evaluate</function> extension XSLT function.</para>
 162   </refdescription>
 163   <refparameter id="read-character-map-params">
 164     <variablelist>
 165       <varlistentry><term>use.subset</term>
 166         <listitem>
 167           <para>Specifies whether to use a subset of the character
 168             map instead of the whole map; boolean
 169             <literal>0</literal> or <literal>1</literal></para>
 170         </listitem>
 171       </varlistentry>
 172       <varlistentry><term>subset.profile</term>
 173         <listitem>
 174           <para>XPath expression that specifies what subset of the
 175             character map to use</para>
 176         </listitem>
 177       </varlistentry>
 178       <varlistentry><term>uri</term>
 179         <listitem>
 180           <para>URI for a character map</para>
 181         </listitem>
 182       </varlistentry>
 183     </variablelist>
 184   </refparameter>
 185 </doc:template>
 186 <xsl:template name="read-character-map">
 187   <xsl:param name="use.subset"/>
 188   <xsl:param name="subset.profile"/>
 189   <xsl:param name="uri"/>
 190   <xsl:choose>
 191     <xsl:when test="$use.subset != 0">
 192       <!-- *use a subset of the character map instead of the full map -->
 193       <xsl:choose>
 194         <!-- * xsltproc and Xalan both support dyn:evaluate() -->
 195         <xsl:when test="function-available('dyn:evaluate')">
 196           <xsl:copy-of select="document($uri)//*[local-name()='output-character']
 197             [dyn:evaluate($subset.profile)]"/>
 198         </xsl:when>
 199         <!-- * Saxon has its own evaluate() and doesn't support dyn:evaluate() -->
 200         <xsl:when test="function-available('saxon:evaluate')">
 201           <xsl:copy-of select="document($uri)//*[local-name()='output-character']
 202             [saxon:evaluate($subset.profile)]"/>
 203         </xsl:when>
 204         <xsl:otherwise>
 205           <xsl:message terminate="yes"
 206 >
 207 Error: To process character-map subsets, you must use an XSLT engine
 208 that supports the evaluate() XSLT extension function. Your XSLT engine
 209 does not support it.
 210           </xsl:message>
 211         </xsl:otherwise>
 212       </xsl:choose>
 213     </xsl:when>
 214     <xsl:otherwise>
 215       <!-- *value of $use.subset is non-zero, so use the full map -->
 216       <xsl:copy-of select="document($uri)//*[local-name()='output-character']"/>
 217     </xsl:otherwise>
 218   </xsl:choose>
 219 </xsl:template>
 220
 221 </xsl:stylesheet>