]> git.stg.codes - stg.git/blob - doc/xslt/common/charmap.xml
Added resetable service conf.
[stg.git] / 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