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