]> git.stg.codes - stg.git/blob - doc/xslt/common/common.xml
Settings object is now allocated on stack, no need to delete it.
[stg.git] / doc / xslt / common / common.xml
1 <?xml version="1.0"?>
2
3 <reference xml:id="base">
4   <info>
5     <title>Common » Base Template Reference</title>
6     <releaseinfo role="meta">
7       $Id: common.xsl 8784 2010-07-28 12:32:54Z mzjn $
8     </releaseinfo>
9   </info>
10   
11   <partintro xml:id="partintro">
12     <title>Introduction</title>
13     
14 <para>This is technical reference documentation for the “base”
15       set of common templates in the DocBook XSL Stylesheets.</para>
16
17     
18 <para>This is not intended to be user documentation. It is
19       provided for developers writing customization layers for the
20       stylesheets.</para>
21
22   </partintro>
23
24 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.is.component">
25 <refnamediv>
26 <refname>is.component</refname>
27 <refpurpose>Tests if a given node is a component-level element</refpurpose>
28 </refnamediv>
29 <refsynopsisdiv>
30 <synopsis>&lt;xsl:template name="is.component"&gt;
31 &lt;xsl:param name="node" select="."/&gt;
32   ...
33 &lt;/xsl:template&gt;</synopsis>
34 </refsynopsisdiv>
35 <refsect1><title>Description</title>
36
37 <para>This template returns '1' if the specified node is a component
38 (Chapter, Appendix, etc.), and '0' otherwise.</para>
39
40 </refsect1><refsect1><title>Parameters</title>
41
42 <variablelist>
43 <varlistentry><term>node</term>
44 <listitem>
45
46 <para>The node which is to be tested.</para>
47
48 </listitem>
49 </varlistentry>
50 </variablelist>
51
52 </refsect1><refsect1><title>Returns</title>
53
54 <para>This template returns '1' if the specified node is a component
55 (Chapter, Appendix, etc.), and '0' otherwise.</para>
56
57 </refsect1></refentry>
58
59 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.is.section">
60 <refnamediv>
61 <refname>is.section</refname>
62 <refpurpose>Tests if a given node is a section-level element</refpurpose>
63 </refnamediv>
64 <refsynopsisdiv>
65 <synopsis>&lt;xsl:template name="is.section"&gt;
66 &lt;xsl:param name="node" select="."/&gt;
67   ...
68 &lt;/xsl:template&gt;</synopsis>
69 </refsynopsisdiv>
70 <refsect1><title>Description</title>
71
72 <para>This template returns '1' if the specified node is a section
73 (Section, Sect1, Sect2, etc.), and '0' otherwise.</para>
74
75 </refsect1><refsect1><title>Parameters</title>
76
77 <variablelist>
78 <varlistentry><term>node</term>
79 <listitem>
80
81 <para>The node which is to be tested.</para>
82
83 </listitem>
84 </varlistentry>
85 </variablelist>
86
87 </refsect1><refsect1><title>Returns</title>
88
89 <para>This template returns '1' if the specified node is a section
90 (Section, Sect1, Sect2, etc.), and '0' otherwise.</para>
91
92 </refsect1></refentry>
93
94 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.section.level">
95 <refnamediv>
96 <refname>section.level</refname>
97 <refpurpose>Returns the hierarchical level of a section</refpurpose>
98 </refnamediv>
99 <refsynopsisdiv>
100 <synopsis>&lt;xsl:template name="section.level"&gt;
101 &lt;xsl:param name="node" select="."/&gt;
102   ...
103 &lt;/xsl:template&gt;</synopsis>
104 </refsynopsisdiv>
105 <refsect1><title>Description</title>
106
107 <para>This template calculates the hierarchical level of a section.
108 The element <tag>sect1</tag> is at level 1, <tag>sect2</tag> is
109 at level 2, etc.</para>
110
111
112
113 <para>Recursive sections are calculated down to the fifth level.</para>
114
115 </refsect1><refsect1><title>Parameters</title>
116
117 <variablelist>
118 <varlistentry><term>node</term>
119 <listitem>
120
121 <para>The section node for which the level should be calculated.
122 Defaults to the context node.</para>
123
124 </listitem>
125 </varlistentry>
126 </variablelist>
127
128 </refsect1><refsect1><title>Returns</title>
129
130 <para>The section level, <quote>1</quote>, <quote>2</quote>, etc.
131 </para>
132
133 </refsect1></refentry>
134
135 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.qanda.section.level">
136 <refnamediv>
137 <refname>qanda.section.level</refname>
138 <refpurpose>Returns the hierarchical level of a QandASet</refpurpose>
139 </refnamediv>
140 <refsynopsisdiv>
141 <synopsis>&lt;xsl:template name="qanda.section.level"/&gt;</synopsis>
142 </refsynopsisdiv>
143 <refsect1><title>Description</title>
144
145 <para>This template calculates the hierarchical level of a QandASet.
146 </para>
147
148 </refsect1><refsect1><title>Returns</title>
149
150 <para>The level, <quote>1</quote>, <quote>2</quote>, etc.
151 </para>
152
153 </refsect1></refentry>
154
155 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.select.mediaobject">
156 <refnamediv>
157 <refname>select.mediaobject</refname>
158 <refpurpose>Selects and processes an appropriate media object from a list</refpurpose>
159 </refnamediv>
160 <refsynopsisdiv>
161 <synopsis>&lt;xsl:template name="select.mediaobject"&gt;
162 &lt;xsl:param name="olist" select="imageobject|imageobjectco                      |videoobject|audioobject|textobject"/&gt;
163   ...
164 &lt;/xsl:template&gt;</synopsis>
165 </refsynopsisdiv>
166 <refsect1><title>Description</title>
167
168 <para>This template takes a list of media objects (usually the
169 children of a mediaobject or inlinemediaobject) and processes
170 the "right" object.</para>
171
172
173
174 <para>This template relies on a template named 
175 "select.mediaobject.index" to determine which object
176 in the list is appropriate.</para>
177
178
179
180 <para>If no acceptable object is located, nothing happens.</para>
181
182 </refsect1><refsect1><title>Parameters</title>
183
184 <variablelist>
185 <varlistentry><term>olist</term>
186 <listitem>
187
188 <para>The node list of potential objects to examine.</para>
189
190 </listitem>
191 </varlistentry>
192 </variablelist>
193
194 </refsect1><refsect1><title>Returns</title>
195
196 <para>Calls &lt;xsl:apply-templates&gt; on the selected object.</para>
197
198 </refsect1></refentry>
199
200 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.select.mediaobject.index">
201 <refnamediv>
202 <refname>select.mediaobject.index</refname>
203 <refpurpose>Selects the position of the appropriate media object from a list</refpurpose>
204 </refnamediv>
205 <refsynopsisdiv>
206 <synopsis>&lt;xsl:template name="select.mediaobject.index"&gt;
207 &lt;xsl:param name="olist" select="imageobject|imageobjectco                      |videoobject|audioobject|textobject"/&gt;
208 &lt;xsl:param name="count"&gt;1&lt;/xsl:param&gt;
209   ...
210 &lt;/xsl:template&gt;</synopsis>
211 </refsynopsisdiv>
212 <refsect1><title>Description</title>
213
214 <para>This template takes a list of media objects (usually the
215 children of a mediaobject or inlinemediaobject) and determines
216 the "right" object. It returns the position of that object
217 to be used by the calling template.</para>
218
219
220
221 <para>If the parameter <parameter>use.role.for.mediaobject</parameter>
222 is nonzero, then it first checks for an object with
223 a role attribute of the appropriate value.  It takes the first
224 of those.  Otherwise, it takes the first acceptable object
225 through a recursive pass through the list.</para>
226
227
228
229 <para>This template relies on a template named "is.acceptable.mediaobject"
230 to determine if a given object is an acceptable graphic. The semantics
231 of media objects is that the first acceptable graphic should be used.
232 </para>
233
234
235
236 <para>If no acceptable object is located, no index is returned.</para>
237
238 </refsect1><refsect1><title>Parameters</title>
239
240 <variablelist>
241 <varlistentry><term>olist</term>
242 <listitem>
243
244 <para>The node list of potential objects to examine.</para>
245
246 </listitem>
247 </varlistentry>
248 <varlistentry><term>count</term>
249 <listitem>
250
251 <para>The position in the list currently being considered by the 
252 recursive process.</para>
253
254 </listitem>
255 </varlistentry>
256 </variablelist>
257
258 </refsect1><refsect1><title>Returns</title>
259
260 <para>Returns the position in the original list of the selected object.</para>
261
262 </refsect1></refentry>
263
264 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.is.acceptable.mediaobject">
265 <refnamediv>
266 <refname>is.acceptable.mediaobject</refname>
267 <refpurpose>Returns '1' if the specified media object is recognized</refpurpose>
268 </refnamediv>
269 <refsynopsisdiv>
270 <synopsis>&lt;xsl:template name="is.acceptable.mediaobject"&gt;
271 &lt;xsl:param name="object"/&gt;
272   ...
273 &lt;/xsl:template&gt;</synopsis>
274 </refsynopsisdiv>
275 <refsect1><title>Description</title>
276
277 <para>This template examines a media object and returns '1' if the
278 object is recognized as a graphic.</para>
279
280 </refsect1><refsect1><title>Parameters</title>
281
282 <variablelist>
283 <varlistentry><term>object</term>
284 <listitem>
285
286 <para>The media object to consider.</para>
287
288 </listitem>
289 </varlistentry>
290 </variablelist>
291
292 </refsect1><refsect1><title>Returns</title>
293
294 <para>0 or 1</para>
295
296 </refsect1></refentry>
297
298 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.check.id.unique">
299 <refnamediv>
300 <refname>check.id.unique</refname>
301 <refpurpose>Warn users about references to non-unique IDs</refpurpose>
302 </refnamediv>
303 <refsynopsisdiv>
304 <synopsis>&lt;xsl:template name="check.id.unique"&gt;
305 &lt;xsl:param name="linkend"/&gt;
306   ...
307 &lt;/xsl:template&gt;</synopsis>
308 </refsynopsisdiv>
309 <refsect1><title>Description</title>
310
311 <para>If passed an ID in <varname>linkend</varname>,
312 <function>check.id.unique</function> prints
313 a warning message to the user if either the ID does not exist or
314 the ID is not unique.</para>
315
316 </refsect1></refentry>
317
318 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.check.idref.targets">
319 <refnamediv>
320 <refname>check.idref.targets</refname>
321 <refpurpose>Warn users about incorrectly typed references</refpurpose>
322 </refnamediv>
323 <refsynopsisdiv>
324 <synopsis>&lt;xsl:template name="check.idref.targets"&gt;
325 &lt;xsl:param name="linkend"/&gt;
326 &lt;xsl:param name="element-list"/&gt;
327   ...
328 &lt;/xsl:template&gt;</synopsis>
329 </refsynopsisdiv>
330 <refsect1><title>Description</title>
331
332 <para>If passed an ID in <varname>linkend</varname>,
333 <function>check.idref.targets</function> makes sure that the element
334 pointed to by the link is one of the elements listed in
335 <varname>element-list</varname> and warns the user otherwise.</para>
336
337 </refsect1></refentry>
338
339 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.copyright.years">
340 <refnamediv>
341 <refname>copyright.years</refname>
342 <refpurpose>Print a set of years with collapsed ranges</refpurpose>
343 </refnamediv>
344 <refsynopsisdiv>
345 <synopsis>&lt;xsl:template name="copyright.years"&gt;
346 &lt;xsl:param name="years"/&gt;
347 &lt;xsl:param name="print.ranges" select="1"/&gt;
348 &lt;xsl:param name="single.year.ranges" select="0"/&gt;
349 &lt;xsl:param name="firstyear" select="0"/&gt;
350 &lt;xsl:param name="nextyear" select="0"/&gt;
351   ...
352 &lt;/xsl:template&gt;</synopsis>
353 </refsynopsisdiv>
354 <refsect1><title>Description</title>
355
356 <para>This template prints a list of year elements with consecutive
357 years printed as a range. In other words:</para>
358
359
360 <screen>&lt;year&gt;1992&lt;/year&gt;
361 &lt;year&gt;1993&lt;/year&gt;
362 &lt;year&gt;1994&lt;/year&gt;</screen>
363
364
365 <para>is printed <quote>1992-1994</quote>, whereas:</para>
366
367
368 <screen>&lt;year&gt;1992&lt;/year&gt;
369 &lt;year&gt;1994&lt;/year&gt;</screen>
370
371
372 <para>is printed <quote>1992, 1994</quote>.</para>
373
374
375
376 <para>This template assumes that all the year elements contain only
377 decimal year numbers, that the elements are sorted in increasing
378 numerical order, that there are no duplicates, and that all the years
379 are expressed in full <quote>century+year</quote>
380 (<quote>1999</quote> not <quote>99</quote>) notation.</para>
381
382 </refsect1><refsect1><title>Parameters</title>
383
384 <variablelist>
385 <varlistentry><term>years</term>
386 <listitem>
387
388 <para>The initial set of year elements.</para>
389
390 </listitem>
391 </varlistentry>
392 <varlistentry><term>print.ranges</term>
393 <listitem>
394
395 <para>If non-zero, multi-year ranges are collapsed. If zero, all years
396 are printed discretely.</para>
397
398 </listitem>
399 </varlistentry>
400 <varlistentry><term>single.year.ranges</term>
401 <listitem>
402
403 <para>If non-zero, two consecutive years will be printed as a range,
404 otherwise, they will be printed discretely. In other words, a single
405 year range is <quote>1991-1992</quote> but discretely it's
406 <quote>1991, 1992</quote>.</para>
407
408 </listitem>
409 </varlistentry>
410 </variablelist>
411
412 </refsect1><refsect1><title>Returns</title>
413
414 <para>This template returns the formatted list of years.</para>
415
416 </refsect1></refentry>
417
418 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.find.path.params">
419 <refnamediv>
420 <refname>find.path.params</refname>
421 <refpurpose>Search in a table for the "best" match for the node</refpurpose>
422 </refnamediv>
423 <refsynopsisdiv>
424 <synopsis>&lt;xsl:template name="find.path.params"&gt;
425 &lt;xsl:param name="node" select="."/&gt;
426 &lt;xsl:param name="table" select="''"/&gt;
427 &lt;xsl:param name="location"&gt;
428     &lt;xsl:call-template name="xpath.location"&gt;
429       &lt;xsl:with-param name="node" select="$node"/&gt;
430     &lt;/xsl:call-template&gt;
431   &lt;/xsl:param&gt;
432   ...
433 &lt;/xsl:template&gt;</synopsis>
434 </refsynopsisdiv>
435 <refsect1><title>Description</title>
436
437 <para>This template searches in a table for the value that most-closely
438 (in the typical best-match sense of XSLT) matches the current (element)
439 node location.</para>
440
441 </refsect1></refentry>
442
443 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.string.upper">
444 <refnamediv>
445 <refname>string.upper</refname>
446 <refpurpose>Converts a string to all uppercase letters</refpurpose>
447 </refnamediv>
448 <refsynopsisdiv>
449 <synopsis>&lt;xsl:template name="string.upper"&gt;
450 &lt;xsl:param name="string" select="''"/&gt;
451   ...
452 &lt;/xsl:template&gt;</synopsis>
453 </refsynopsisdiv>
454 <refsect1><title>Description</title>
455
456 <para>Given a string, this template does a language-aware conversion
457 of that string to all uppercase letters, based on the values of the
458 <literal>lowercase.alpha</literal> and
459 <literal>uppercase.alpha</literal> gentext keys for the current
460 locale. It affects only those characters found in the values of
461 <literal>lowercase.alpha</literal> and
462 <literal>uppercase.alpha</literal>. All other characters are left
463 unchanged.</para>
464
465 </refsect1><refsect1><title>Parameters</title>
466
467 <variablelist>
468 <varlistentry><term>string</term>
469 <listitem>
470
471 <para>The string to convert to uppercase.</para>
472
473 </listitem>
474 </varlistentry>
475 </variablelist>
476
477 </refsect1></refentry>
478
479 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.string.lower">
480 <refnamediv>
481 <refname>string.lower</refname>
482 <refpurpose>Converts a string to all lowercase letters</refpurpose>
483 </refnamediv>
484 <refsynopsisdiv>
485 <synopsis>&lt;xsl:template name="string.lower"&gt;
486 &lt;xsl:param name="string" select="''"/&gt;
487   ...
488 &lt;/xsl:template&gt;</synopsis>
489 </refsynopsisdiv>
490 <refsect1><title>Description</title>
491
492 <para>Given a string, this template does a language-aware conversion
493 of that string to all lowercase letters, based on the values of the
494 <literal>uppercase.alpha</literal> and
495 <literal>lowercase.alpha</literal> gentext keys for the current
496 locale. It affects only those characters found in the values of
497 <literal>uppercase.alpha</literal> and
498 <literal>lowercase.alpha</literal>. All other characters are left
499 unchanged.</para>
500
501 </refsect1><refsect1><title>Parameters</title>
502
503 <variablelist>
504 <varlistentry><term>string</term>
505 <listitem>
506
507 <para>The string to convert to lowercase.</para>
508
509 </listitem>
510 </varlistentry>
511 </variablelist>
512
513 </refsect1></refentry>
514
515 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.select.choice.separator">
516 <refnamediv>
517 <refname>select.choice.separator</refname>
518 <refpurpose>Returns localized choice separator</refpurpose>
519 </refnamediv>
520 <refsynopsisdiv>
521 <synopsis>&lt;xsl:template name="select.choice.separator"/&gt;</synopsis>
522 </refsynopsisdiv>
523 <refsect1><title>Description</title>
524     
525 <para>This template enables auto-generation of an appropriate
526     localized "choice" separator (for example, "and" or "or") before
527     the final item in an inline list (though it could also be useful
528     for generating choice separators for non-inline lists).</para>
529
530     
531 <para>It currently works by evaluating a processing instruction
532     (PI) of the form &lt;?dbchoice choice="foo"?&gt; :
533     
534 <itemizedlist>
535       <listitem>
536         <simpara>if the value of the <tag>choice</tag>
537         pseudo-attribute is "and" or "or", returns a localized "and"
538         or "or"</simpara>
539       </listitem>
540       <listitem>
541         <simpara>otherwise returns the literal value of the
542         <tag>choice</tag> pseudo-attribute</simpara>
543       </listitem>
544     </itemizedlist>
545
546     The latter is provided only as a temporary workaround because the
547     locale files do not currently have translations for the word
548     <wordasword>or</wordasword>. So if you want to generate a a
549     logical "or" separator in French (for example), you currently need
550     to do this:
551     <literallayout>&lt;?dbchoice choice="ou"?&gt;</literallayout>
552     </para>
553
554     <warning>
555       
556 <para>The <tag>dbchoice</tag> processing instruction is
557       an unfortunate hack; support for it may disappear in the future
558       (particularly if and when a more appropriate means for marking
559       up "choice" lists becomes available in DocBook).</para>
560
561     </warning>
562   </refsect1></refentry>
563
564 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.evaluate.info.profile">
565 <refnamediv>
566 <refname>evaluate.info.profile</refname>
567 <refpurpose>Evaluates an info profile</refpurpose>
568 </refnamediv>
569 <refsynopsisdiv>
570 <synopsis>&lt;xsl:template name="evaluate.info.profile"&gt;
571 &lt;xsl:param name="profile"/&gt;
572 &lt;xsl:param name="info"/&gt;
573   ...
574 &lt;/xsl:template&gt;</synopsis>
575 </refsynopsisdiv>
576 <refsect1><title>Description</title>
577     
578 <para>This template evaluates an "info profile" matching the XPath
579     expression given by the <parameter>profile</parameter>
580     parameter. It relies on the XSLT <function>evaluate()</function>
581     extension function.</para>
582
583
584     
585 <para>The value of the <parameter>profile</parameter> parameter
586     can include the literal string <literal>$info</literal>. If found
587     in the value of the <parameter>profile</parameter> parameter, the
588     literal string <literal>$info</literal> string is replaced with
589     the value of the <parameter>info</parameter> parameter, which
590     should be a set of <replaceable>*info</replaceable> nodes; the
591     expression is then evaluated using the XSLT
592     <function>evaluate()</function> extension function.</para>
593
594   </refsect1><refsect1><title>Parameters</title>
595     
596 <variablelist>
597        <varlistentry>
598         <term>profile</term>
599         <listitem>
600           
601 <para>A string representing an XPath expression </para>
602
603         </listitem>
604       </varlistentry>
605        <varlistentry>
606         <term>info</term>
607         <listitem>
608           
609 <para>A set of *info nodes</para>
610
611         </listitem>
612       </varlistentry>
613     </variablelist>
614
615   </refsect1><refsect1><title>Returns</title>
616     
617 <para>Returns a node (the result of evaluating the
618     <parameter>profile</parameter> parameter)</para>
619
620   </refsect1></refentry>
621 </reference>
622