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"
11 <!-- ********************************************************************
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.
17 ******************************************************************** -->
18 <doc:reference xmlns="" xml:id="charmap">
20 <title>Common » Character-Map Template Reference</title>
21 <releaseinfo role="meta">
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>
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>
40 <para>This is not intended to be user documentation. It is
41 provided for developers writing customization layers for the
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>
61 <para>This template is a very slightly modified version of
62 Jeni Tennison’s <function>replace_strings</function>
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>
79 <refparameter id="apply-character-map-params">
81 <varlistentry><term>content</term>
83 <para>The content on which to perform the character-map
87 <varlistentry><term>map.contents</term>
89 <para>A node set of elements, with each element having
90 the following attributes:
93 <simpara><tag class="attribute">character</tag>, a
94 character to be replaced</simpara>
97 <simpara><tag class="attribute">string</tag>, a
98 string with which to replace <tag
99 class="attribute">character</tag></simpara>
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" />
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]" />
129 <xsl:value-of select="$replaced_text" />
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>
161 <refparameter id="read-character-map-params">
163 <varlistentry><term>use.subset</term>
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>
170 <varlistentry><term>subset.profile</term>
172 <para>XPath expression that specifies what subset of the
173 character map to use</para>
176 <varlistentry><term>uri</term>
178 <para>URI for a character map</para>
184 <xsl:template name="read-character-map">
185 <xsl:param name="use.subset"/>
186 <xsl:param name="subset.profile"/>
187 <xsl:param name="uri"/>
189 <xsl:when test="$use.subset != 0">
190 <!-- *use a subset of the character map instead of the full map -->
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)]"/>
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)]"/>
203 <xsl:message terminate="yes"
205 Error: To process character-map subsets, you must use an XSLT engine
206 that supports the evaluate() XSLT extension function. Your XSLT engine
213 <!-- *value of $use.subset is non-zero, so use the full map -->
214 <xsl:copy-of select="document($uri)//*[local-name()='output-character']"/>