lib/docbook/common/charmap.xsl

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