doc/xslt/common/charmap.xml

   1 <?xml version="1.0"?>
   2
   3 <reference xml:id="charmap">
   4   <info>
   5     <title>Common » Character-Map Template Reference</title>
   6     <releaseinfo role="meta">
   7       $Id: charmap.xsl 7266 2007-08-22 11:58:42Z xmldoc $
   8     </releaseinfo>
   9   </info>
  10
  11   <partintro xml:id="partintro">
  12     <title>Introduction</title>
  13
  14 <para>This is technical reference documentation for the
  15       character-map templates in the DocBook XSL Stylesheets.</para>
  16
  17     <note>
  18
  19 <para>These templates are defined in a separate file from the set
  20         of “common” templates because some of the common templates
  21         reference DocBook XSL stylesheet parameters, requiring the
  22         entire set of parameters to be imported/included in any
  23         stylesheet that imports/includes the common templates.</para>
  24
  25
  26 <para>The character-map templates don’t import or include
  27         any DocBook XSL stylesheet parameters, so the
  28         character-map templates can be used without importing the
  29         whole set of parameters.</para>
  30
  31     </note>
  32
  33 <para>This is not intended to be user documentation. It is
  34       provided for developers writing customization layers for the
  35       stylesheets.</para>
  36
  37   </partintro>
  38
  39 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.apply-character-map">
  40 <refnamediv>
  41 <refname>apply-character-map</refname>
  42 <refpurpose>Applies an XSLT character map</refpurpose>
  43 </refnamediv>
  44 <refsynopsisdiv>
  45 <synopsis>&lt;xsl:template name="apply-character-map"&gt;
  46 &lt;xsl:param name="content"/&gt;
  47 &lt;xsl:param name="map.contents"/&gt;
  48   ...
  49 &lt;/xsl:template&gt;</synopsis>
  50 </refsynopsisdiv>
  51 <refsect1><title>Description</title>
  52
  53 <para>This template applies an <link xlink:href="http://www.w3.org/TR/xslt20/#character-maps">XSLT character map</link>; that is, it causes certain
  54       individual characters to be substituted with strings of one
  55       or more characters. It is useful mainly for replacing
  56       multiple “special” characters or symbols in the same target
  57       content. It uses the value of
  58       <parameter>map.contents</parameter> to do substitution on
  59       <parameter>content</parameter>, and then returns the
  60       modified contents.</para>
  61
  62     <note>
  63
  64 <para>This template is a very slightly modified version of
  65         Jeni Tennison’s <function>replace_strings</function>
  66         template in the <link xlink:href="http://www.dpawson.co.uk/xsl/sect2/StringReplace.html#d9351e13">multiple string replacements</link> section of Dave Pawson’s
  67         <link xlink:href="http://www.dpawson.co.uk/xsl/index.html">XSLT FAQ</link>.</para>
  68
  69
  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 class="attribute">oldstring</tag> and <tag class="attribute">newstring</tag> attributes are used
  75         instead of <tag class="attribute">character</tag> and <tag class="attribute">string</tag> attributes.</para>
  76
  77     </note>
  78   </refsect1><refsect1><title>Parameters</title>
  79
  80 <variablelist>
  81       <varlistentry><term>content</term>
  82         <listitem>
  83
  84 <para>The content on which to perform the character-map
  85             substitution.</para>
  86
  87         </listitem>
  88       </varlistentry>
  89       <varlistentry><term>map.contents</term>
  90         <listitem>
  91
  92 <para>A node set of elements, with each element having
  93             the following attributes:
  94
  95 <itemizedlist>
  96               <listitem>
  97                 <simpara><tag class="attribute">character</tag>, a
  98                   character to be replaced</simpara>
  99               </listitem>
 100               <listitem>
 101                 <simpara><tag class="attribute">string</tag>, a
 102                   string with which to replace <tag class="attribute">character</tag></simpara>
 103               </listitem>
 104             </itemizedlist>
 105
 106           </para>
 107
 108         </listitem>
 109       </varlistentry>
 110     </variablelist>
 111
 112   </refsect1></refentry>
 113
 114 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.read-character-map">
 115 <refnamediv>
 116 <refname>read-character-map</refname>
 117 <refpurpose>Reads in all or part of an XSLT character map</refpurpose>
 118 </refnamediv>
 119 <refsynopsisdiv>
 120 <synopsis>&lt;xsl:template name="read-character-map"&gt;
 121 &lt;xsl:param name="use.subset"/&gt;
 122 &lt;xsl:param name="subset.profile"/&gt;
 123 &lt;xsl:param name="uri"/&gt;
 124   ...
 125 &lt;/xsl:template&gt;</synopsis>
 126 </refsynopsisdiv>
 127 <refsect1><title>Description</title>
 128
 129 <para>The XSLT 2.0 specification describes <link xlink:href="http://www.w3.org/TR/xslt20/#character-maps">character maps</link> and explains how they may be used
 130       to allow a specific character appearing in a text or
 131       attribute node in a final result tree to be substituted by
 132       a specified string of characters during serialization. The
 133       <function>read-character-map</function> template provides a
 134       means for reading and using character maps with XSLT
 135       1.0-based tools.</para>
 136
 137
 138 <para>This template reads the character-map contents from
 139       <parameter>uri</parameter> (in full or in part, depending on
 140       the value of the <parameter>use.subset</parameter>
 141       parameter), then passes those contents to the
 142       <function>apply-character-map</function> template, along with
 143       <parameter>content</parameter>, the data on which to perform
 144       the character substitution.</para>
 145
 146
 147 <para>Using the character map “in part” means that it uses only
 148       those <tag>output-character</tag> elements that match the
 149       XPath expression given in the value of the
 150       <parameter>subset.profile</parameter> parameter. The current
 151       implementation of that capability here relies on the
 152       <function>evaluate</function> extension XSLT function.</para>
 153
 154   </refsect1><refsect1><title>Parameters</title>
 155
 156 <variablelist>
 157       <varlistentry><term>use.subset</term>
 158         <listitem>
 159
 160 <para>Specifies whether to use a subset of the character
 161             map instead of the whole map; boolean
 162             <literal>0</literal> or <literal>1</literal></para>
 163
 164         </listitem>
 165       </varlistentry>
 166       <varlistentry><term>subset.profile</term>
 167         <listitem>
 168
 169 <para>XPath expression that specifies what subset of the
 170             character map to use</para>
 171
 172         </listitem>
 173       </varlistentry>
 174       <varlistentry><term>uri</term>
 175         <listitem>
 176
 177 <para>URI for a character map</para>
 178
 179         </listitem>
 180       </varlistentry>
 181     </variablelist>
 182
 183   </refsect1></refentry>
 184 </reference>
 185