1 <?xml version="1.0" encoding="UTF-8"?>
2 <reference xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="charmap">
4 <title>Common » Character-Map Template Reference</title>
5 <releaseinfo role="meta">
9 <partintro xml:id="partintro">
10 <title>Introduction</title>
12 <para>This is technical reference documentation for the
13 character-map templates in the DocBook XSL Stylesheets.</para>
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>
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>
31 <para>This is not intended to be user documentation. It is
32 provided for developers writing customization layers for the
37 <refentry xml:id="template.apply-character-map">
39 <refname>apply-character-map</refname>
40 <refpurpose>Applies an XSLT character map</refpurpose>
43 <synopsis><xsl:template name="apply-character-map">
44 <xsl:param name="content"/>
45 <xsl:param name="map.contents"/>
47 </xsl:template></synopsis>
49 <refsect1><title>Description</title>
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>
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>
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>
76 </refsect1><refsect1><title>Parameters</title>
79 <varlistentry><term>content</term>
82 <para>The content on which to perform the character-map
87 <varlistentry><term>map.contents</term>
90 <para>A node set of elements, with each element having
91 the following attributes:
95 <simpara><tag class="attribute">character</tag>, a
96 character to be replaced</simpara>
99 <simpara><tag class="attribute">string</tag>, a
100 string with which to replace <tag class="attribute">character</tag></simpara>
110 </refsect1></refentry>
112 <refentry xml:id="template.read-character-map">
114 <refname>read-character-map</refname>
115 <refpurpose>Reads in all or part of an XSLT character map</refpurpose>
118 <synopsis><xsl:template name="read-character-map">
119 <xsl:param name="use.subset"/>
120 <xsl:param name="subset.profile"/>
121 <xsl:param name="uri"/>
123 </xsl:template></synopsis>
125 <refsect1><title>Description</title>
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>
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>
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>
152 </refsect1><refsect1><title>Parameters</title>
155 <varlistentry><term>use.subset</term>
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>
164 <varlistentry><term>subset.profile</term>
167 <para>XPath expression that specifies what subset of the
168 character map to use</para>
172 <varlistentry><term>uri</term>
175 <para>URI for a character map</para>
181 </refsect1></refentry>