lib/docbook/common/charmap.xml

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