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