1 <?xml version="1.0" encoding="UTF-8"?>
2 <reference xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="base">
4 <title>Common » Base 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 “base”
13 set of common templates in the DocBook XSL Stylesheets.</para>
16 <para>This is not intended to be user documentation. It is
17 provided for developers writing customization layers for the
22 <refentry xml:id="template.is.component">
24 <refname>is.component</refname>
25 <refpurpose>Tests if a given node is a component-level element</refpurpose>
28 <synopsis><xsl:template name="is.component">
29 <xsl:param name="node" select="."/>
31 </xsl:template></synopsis>
33 <refsect1><title>Description</title>
35 <para>This template returns '1' if the specified node is a component
36 (Chapter, Appendix, etc.), and '0' otherwise.</para>
38 </refsect1><refsect1><title>Parameters</title>
41 <varlistentry><term>node</term>
44 <para>The node which is to be tested.</para>
50 </refsect1><refsect1><title>Returns</title>
52 <para>This template returns '1' if the specified node is a component
53 (Chapter, Appendix, etc.), and '0' otherwise.</para>
55 </refsect1></refentry>
57 <refentry xml:id="template.is.section">
59 <refname>is.section</refname>
60 <refpurpose>Tests if a given node is a section-level element</refpurpose>
63 <synopsis><xsl:template name="is.section">
64 <xsl:param name="node" select="."/>
66 </xsl:template></synopsis>
68 <refsect1><title>Description</title>
70 <para>This template returns '1' if the specified node is a section
71 (Section, Sect1, Sect2, etc.), and '0' otherwise.</para>
73 </refsect1><refsect1><title>Parameters</title>
76 <varlistentry><term>node</term>
79 <para>The node which is to be tested.</para>
85 </refsect1><refsect1><title>Returns</title>
87 <para>This template returns '1' if the specified node is a section
88 (Section, Sect1, Sect2, etc.), and '0' otherwise.</para>
90 </refsect1></refentry>
92 <refentry xml:id="template.section.level">
94 <refname>section.level</refname>
95 <refpurpose>Returns the hierarchical level of a section</refpurpose>
98 <synopsis><xsl:template name="section.level">
99 <xsl:param name="node" select="."/>
101 </xsl:template></synopsis>
103 <refsect1><title>Description</title>
105 <para>This template calculates the hierarchical level of a section.
106 The element <tag>sect1</tag> is at level 1, <tag>sect2</tag> is
107 at level 2, etc.</para>
111 <para>Recursive sections are calculated down to the fifth level.</para>
113 </refsect1><refsect1><title>Parameters</title>
116 <varlistentry><term>node</term>
119 <para>The section node for which the level should be calculated.
120 Defaults to the context node.</para>
126 </refsect1><refsect1><title>Returns</title>
128 <para>The section level, <quote>1</quote>, <quote>2</quote>, etc.
131 </refsect1></refentry>
133 <refentry xml:id="template.qanda.section.level">
135 <refname>qanda.section.level</refname>
136 <refpurpose>Returns the hierarchical level of a QandASet</refpurpose>
139 <synopsis><xsl:template name="qanda.section.level"/></synopsis>
141 <refsect1><title>Description</title>
143 <para>This template calculates the hierarchical level of a QandASet.
146 </refsect1><refsect1><title>Returns</title>
148 <para>The level, <quote>1</quote>, <quote>2</quote>, etc.
151 </refsect1></refentry>
153 <refentry xml:id="template.select.mediaobject">
155 <refname>select.mediaobject</refname>
156 <refpurpose>Selects and processes an appropriate media object from a list</refpurpose>
159 <synopsis><xsl:template name="select.mediaobject">
160 <xsl:param name="olist" select="d:imageobject|d:imageobjectco |d:videoobject|d:audioobject|d:textobject"/>
162 </xsl:template></synopsis>
164 <refsect1><title>Description</title>
166 <para>This template takes a list of media objects (usually the
167 children of a mediaobject or inlinemediaobject) and processes
168 the "right" object.</para>
172 <para>This template relies on a template named
173 "select.mediaobject.index" to determine which object
174 in the list is appropriate.</para>
178 <para>If no acceptable object is located, nothing happens.</para>
180 </refsect1><refsect1><title>Parameters</title>
183 <varlistentry><term>olist</term>
186 <para>The node list of potential objects to examine.</para>
192 </refsect1><refsect1><title>Returns</title>
194 <para>Calls <xsl:apply-templates> on the selected object.</para>
196 </refsect1></refentry>
198 <refentry xml:id="template.select.mediaobject.index">
200 <refname>select.mediaobject.index</refname>
201 <refpurpose>Selects the position of the appropriate media object from a list</refpurpose>
204 <synopsis><xsl:template name="select.mediaobject.index">
205 <xsl:param name="olist" select="d:imageobject|d:imageobjectco |d:videoobject|d:audioobject|d:textobject"/>
206 <xsl:param name="count">1</xsl:param>
208 </xsl:template></synopsis>
210 <refsect1><title>Description</title>
212 <para>This template takes a list of media objects (usually the
213 children of a mediaobject or inlinemediaobject) and determines
214 the "right" object. It returns the position of that object
215 to be used by the calling template.</para>
219 <para>If the parameter <parameter>use.role.for.mediaobject</parameter>
220 is nonzero, then it first checks for an object with
221 a role attribute of the appropriate value. It takes the first
222 of those. Otherwise, it takes the first acceptable object
223 through a recursive pass through the list.</para>
227 <para>This template relies on a template named "is.acceptable.mediaobject"
228 to determine if a given object is an acceptable graphic. The semantics
229 of media objects is that the first acceptable graphic should be used.
234 <para>If no acceptable object is located, no index is returned.</para>
236 </refsect1><refsect1><title>Parameters</title>
239 <varlistentry><term>olist</term>
242 <para>The node list of potential objects to examine.</para>
246 <varlistentry><term>count</term>
249 <para>The position in the list currently being considered by the
250 recursive process.</para>
256 </refsect1><refsect1><title>Returns</title>
258 <para>Returns the position in the original list of the selected object.</para>
260 </refsect1></refentry>
262 <refentry xml:id="template.is.acceptable.mediaobject">
264 <refname>is.acceptable.mediaobject</refname>
265 <refpurpose>Returns '1' if the specified media object is recognized</refpurpose>
268 <synopsis><xsl:template name="is.acceptable.mediaobject">
269 <xsl:param name="object"/>
271 </xsl:template></synopsis>
273 <refsect1><title>Description</title>
275 <para>This template examines a media object and returns '1' if the
276 object is recognized as a graphic.</para>
278 </refsect1><refsect1><title>Parameters</title>
281 <varlistentry><term>object</term>
284 <para>The media object to consider.</para>
290 </refsect1><refsect1><title>Returns</title>
294 </refsect1></refentry>
296 <refentry xml:id="template.check.id.unique">
298 <refname>check.id.unique</refname>
299 <refpurpose>Warn users about references to non-unique IDs</refpurpose>
302 <synopsis><xsl:template name="check.id.unique">
303 <xsl:param name="linkend"/>
305 </xsl:template></synopsis>
307 <refsect1><title>Description</title>
309 <para>If passed an ID in <varname>linkend</varname>,
310 <function>check.id.unique</function> prints
311 a warning message to the user if either the ID does not exist or
312 the ID is not unique.</para>
314 </refsect1></refentry>
316 <refentry xml:id="template.check.idref.targets">
318 <refname>check.idref.targets</refname>
319 <refpurpose>Warn users about incorrectly typed references</refpurpose>
322 <synopsis><xsl:template name="check.idref.targets">
323 <xsl:param name="linkend"/>
324 <xsl:param name="element-list"/>
326 </xsl:template></synopsis>
328 <refsect1><title>Description</title>
330 <para>If passed an ID in <varname>linkend</varname>,
331 <function>check.idref.targets</function> makes sure that the element
332 pointed to by the link is one of the elements listed in
333 <varname>element-list</varname> and warns the user otherwise.</para>
335 </refsect1></refentry>
337 <refentry xml:id="template.copyright.years">
339 <refname>copyright.years</refname>
340 <refpurpose>Print a set of years with collapsed ranges</refpurpose>
343 <synopsis><xsl:template name="copyright.years">
344 <xsl:param name="years"/>
345 <xsl:param name="print.ranges" select="1"/>
346 <xsl:param name="single.year.ranges" select="0"/>
347 <xsl:param name="firstyear" select="0"/>
348 <xsl:param name="nextyear" select="0"/>
350 </xsl:template></synopsis>
352 <refsect1><title>Description</title>
354 <para>This template prints a list of year elements with consecutive
355 years printed as a range. In other words:</para>
358 <screen><year>1992</year>
359 <year>1993</year>
360 <year>1994</year></screen>
363 <para>is printed <quote>1992-1994</quote>, whereas:</para>
366 <screen><year>1992</year>
367 <year>1994</year></screen>
370 <para>is printed <quote>1992, 1994</quote>.</para>
374 <para>This template assumes that all the year elements contain only
375 decimal year numbers, that the elements are sorted in increasing
376 numerical order, that there are no duplicates, and that all the years
377 are expressed in full <quote>century+year</quote>
378 (<quote>1999</quote> not <quote>99</quote>) notation.</para>
380 </refsect1><refsect1><title>Parameters</title>
383 <varlistentry><term>years</term>
386 <para>The initial set of year elements.</para>
390 <varlistentry><term>print.ranges</term>
393 <para>If non-zero, multi-year ranges are collapsed. If zero, all years
394 are printed discretely.</para>
398 <varlistentry><term>single.year.ranges</term>
401 <para>If non-zero, two consecutive years will be printed as a range,
402 otherwise, they will be printed discretely. In other words, a single
403 year range is <quote>1991-1992</quote> but discretely it's
404 <quote>1991, 1992</quote>.</para>
410 </refsect1><refsect1><title>Returns</title>
412 <para>This template returns the formatted list of years.</para>
414 </refsect1></refentry>
416 <refentry xml:id="template.find.path.params">
418 <refname>find.path.params</refname>
419 <refpurpose>Search in a table for the "best" match for the node</refpurpose>
422 <synopsis><xsl:template name="find.path.params">
423 <xsl:param name="node" select="."/>
424 <xsl:param name="table" select="''"/>
425 <xsl:param name="location">
426 <xsl:call-template name="xpath.location">
427 <xsl:with-param name="node" select="$node"/>
428 </xsl:call-template>
431 </xsl:template></synopsis>
433 <refsect1><title>Description</title>
435 <para>This template searches in a table for the value that most-closely
436 (in the typical best-match sense of XSLT) matches the current (element)
437 node location.</para>
439 </refsect1></refentry>
441 <refentry xml:id="template.string.upper">
443 <refname>string.upper</refname>
444 <refpurpose>Converts a string to all uppercase letters</refpurpose>
447 <synopsis><xsl:template name="string.upper">
448 <xsl:param name="string" select="''"/>
450 </xsl:template></synopsis>
452 <refsect1><title>Description</title>
454 <para>Given a string, this template does a language-aware conversion
455 of that string to all uppercase letters, based on the values of the
456 <literal>lowercase.alpha</literal> and
457 <literal>uppercase.alpha</literal> gentext keys for the current
458 locale. It affects only those characters found in the values of
459 <literal>lowercase.alpha</literal> and
460 <literal>uppercase.alpha</literal>. All other characters are left
463 </refsect1><refsect1><title>Parameters</title>
466 <varlistentry><term>string</term>
469 <para>The string to convert to uppercase.</para>
475 </refsect1></refentry>
477 <refentry xml:id="template.string.lower">
479 <refname>string.lower</refname>
480 <refpurpose>Converts a string to all lowercase letters</refpurpose>
483 <synopsis><xsl:template name="string.lower">
484 <xsl:param name="string" select="''"/>
486 </xsl:template></synopsis>
488 <refsect1><title>Description</title>
490 <para>Given a string, this template does a language-aware conversion
491 of that string to all lowercase letters, based on the values of the
492 <literal>uppercase.alpha</literal> and
493 <literal>lowercase.alpha</literal> gentext keys for the current
494 locale. It affects only those characters found in the values of
495 <literal>uppercase.alpha</literal> and
496 <literal>lowercase.alpha</literal>. All other characters are left
499 </refsect1><refsect1><title>Parameters</title>
502 <varlistentry><term>string</term>
505 <para>The string to convert to lowercase.</para>
511 </refsect1></refentry>
513 <refentry xml:id="template.select.choice.separator">
515 <refname>select.choice.separator</refname>
516 <refpurpose>Returns localized choice separator</refpurpose>
519 <synopsis><xsl:template name="select.choice.separator"/></synopsis>
521 <refsect1><title>Description</title>
523 <para>This template enables auto-generation of an appropriate
524 localized "choice" separator (for example, "and" or "or") before
525 the final item in an inline list (though it could also be useful
526 for generating choice separators for non-inline lists).</para>
529 <para>It currently works by evaluating a processing instruction
530 (PI) of the form <?dbchoice choice="foo"?> :
534 <simpara>if the value of the <tag>choice</tag>
535 pseudo-attribute is "and" or "or", returns a localized "and"
539 <simpara>otherwise returns the literal value of the
540 <tag>choice</tag> pseudo-attribute</simpara>
544 The latter is provided only as a temporary workaround because the
545 locale files do not currently have translations for the word
546 <wordasword>or</wordasword>. So if you want to generate a a
547 logical "or" separator in French (for example), you currently need
549 <literallayout><?dbchoice choice="ou"?></literallayout>
554 <para>The <tag>dbchoice</tag> processing instruction is
555 an unfortunate hack; support for it may disappear in the future
556 (particularly if and when a more appropriate means for marking
557 up "choice" lists becomes available in DocBook).</para>
560 </refsect1></refentry>
562 <refentry xml:id="template.evaluate.info.profile">
564 <refname>evaluate.info.profile</refname>
565 <refpurpose>Evaluates an info profile</refpurpose>
568 <synopsis><xsl:template name="evaluate.info.profile">
569 <xsl:param name="profile"/>
570 <xsl:param name="info"/>
572 </xsl:template></synopsis>
574 <refsect1><title>Description</title>
576 <para>This template evaluates an "info profile" matching the XPath
577 expression given by the <parameter>profile</parameter>
578 parameter. It relies on the XSLT <function>evaluate()</function>
579 extension function.</para>
583 <para>The value of the <parameter>profile</parameter> parameter
584 can include the literal string <literal>$info</literal>. If found
585 in the value of the <parameter>profile</parameter> parameter, the
586 literal string <literal>$info</literal> string is replaced with
587 the value of the <parameter>info</parameter> parameter, which
588 should be a set of <replaceable>*info</replaceable> nodes; the
589 expression is then evaluated using the XSLT
590 <function>evaluate()</function> extension function.</para>
592 </refsect1><refsect1><title>Parameters</title>
599 <para>A string representing an XPath expression </para>
607 <para>A set of *info nodes</para>
613 </refsect1><refsect1><title>Returns</title>
615 <para>Returns a node (the result of evaluating the
616 <parameter>profile</parameter> parameter)</para>
618 </refsect1></refentry>
620 <refentry xml:id="template.graphic.format.content-type">
622 <refname>graphic.format.content-type</refname>
623 <refpurpose>Returns mimetype for media format</refpurpose>
626 <synopsis><xsl:template name="graphic.format.content-type">
627 <xsl:param name="format"/>
629 </xsl:template></synopsis>
631 <refsect1><title>Description</title>
633 <para>This takes as input a 'format' param and returns
634 a mimetype string. It uses an xsl:choose after first
635 converting the input to all uppercase.</para>
637 </refsect1></refentry>