lib/docbook/common/common.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <reference xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="base">
   3   <info>
   4     <title>Common » Base Template Reference</title>
   5     <releaseinfo role="meta">
   6     </releaseinfo>
   7   </info>
   8
   9   <partintro xml:id="partintro">
  10     <title>Introduction</title>
  11
  12 <para>This is technical reference documentation for the “base”
  13       set of common templates in the DocBook XSL Stylesheets.</para>
  14
  15
  16 <para>This is not intended to be user documentation. It is
  17       provided for developers writing customization layers for the
  18       stylesheets.</para>
  19
  20   </partintro>
  21
  22 <refentry xml:id="template.is.component">
  23 <refnamediv>
  24 <refname>is.component</refname>
  25 <refpurpose>Tests if a given node is a component-level element</refpurpose>
  26 </refnamediv>
  27 <refsynopsisdiv>
  28 <synopsis>&lt;xsl:template name="is.component"&gt;
  29 &lt;xsl:param name="node" select="."/&gt;
  30   ...
  31 &lt;/xsl:template&gt;</synopsis>
  32 </refsynopsisdiv>
  33 <refsect1><title>Description</title>
  34
  35 <para>This template returns '1' if the specified node is a component
  36 (Chapter, Appendix, etc.), and '0' otherwise.</para>
  37
  38 </refsect1><refsect1><title>Parameters</title>
  39
  40 <variablelist>
  41 <varlistentry><term>node</term>
  42 <listitem>
  43
  44 <para>The node which is to be tested.</para>
  45
  46 </listitem>
  47 </varlistentry>
  48 </variablelist>
  49
  50 </refsect1><refsect1><title>Returns</title>
  51
  52 <para>This template returns '1' if the specified node is a component
  53 (Chapter, Appendix, etc.), and '0' otherwise.</para>
  54
  55 </refsect1></refentry>
  56
  57 <refentry xml:id="template.is.section">
  58 <refnamediv>
  59 <refname>is.section</refname>
  60 <refpurpose>Tests if a given node is a section-level element</refpurpose>
  61 </refnamediv>
  62 <refsynopsisdiv>
  63 <synopsis>&lt;xsl:template name="is.section"&gt;
  64 &lt;xsl:param name="node" select="."/&gt;
  65   ...
  66 &lt;/xsl:template&gt;</synopsis>
  67 </refsynopsisdiv>
  68 <refsect1><title>Description</title>
  69
  70 <para>This template returns '1' if the specified node is a section
  71 (Section, Sect1, Sect2, etc.), and '0' otherwise.</para>
  72
  73 </refsect1><refsect1><title>Parameters</title>
  74
  75 <variablelist>
  76 <varlistentry><term>node</term>
  77 <listitem>
  78
  79 <para>The node which is to be tested.</para>
  80
  81 </listitem>
  82 </varlistentry>
  83 </variablelist>
  84
  85 </refsect1><refsect1><title>Returns</title>
  86
  87 <para>This template returns '1' if the specified node is a section
  88 (Section, Sect1, Sect2, etc.), and '0' otherwise.</para>
  89
  90 </refsect1></refentry>
  91
  92 <refentry xml:id="template.section.level">
  93 <refnamediv>
  94 <refname>section.level</refname>
  95 <refpurpose>Returns the hierarchical level of a section</refpurpose>
  96 </refnamediv>
  97 <refsynopsisdiv>
  98 <synopsis>&lt;xsl:template name="section.level"&gt;
  99 &lt;xsl:param name="node" select="."/&gt;
 100   ...
 101 &lt;/xsl:template&gt;</synopsis>
 102 </refsynopsisdiv>
 103 <refsect1><title>Description</title>
 104
 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>
 108
 109
 110
 111 <para>Recursive sections are calculated down to the fifth level.</para>
 112
 113 </refsect1><refsect1><title>Parameters</title>
 114
 115 <variablelist>
 116 <varlistentry><term>node</term>
 117 <listitem>
 118
 119 <para>The section node for which the level should be calculated.
 120 Defaults to the context node.</para>
 121
 122 </listitem>
 123 </varlistentry>
 124 </variablelist>
 125
 126 </refsect1><refsect1><title>Returns</title>
 127
 128 <para>The section level, <quote>1</quote>, <quote>2</quote>, etc.
 129 </para>
 130
 131 </refsect1></refentry>
 132
 133 <refentry xml:id="template.qanda.section.level">
 134 <refnamediv>
 135 <refname>qanda.section.level</refname>
 136 <refpurpose>Returns the hierarchical level of a QandASet</refpurpose>
 137 </refnamediv>
 138 <refsynopsisdiv>
 139 <synopsis>&lt;xsl:template name="qanda.section.level"/&gt;</synopsis>
 140 </refsynopsisdiv>
 141 <refsect1><title>Description</title>
 142
 143 <para>This template calculates the hierarchical level of a QandASet.
 144 </para>
 145
 146 </refsect1><refsect1><title>Returns</title>
 147
 148 <para>The level, <quote>1</quote>, <quote>2</quote>, etc.
 149 </para>
 150
 151 </refsect1></refentry>
 152
 153 <refentry xml:id="template.select.mediaobject">
 154 <refnamediv>
 155 <refname>select.mediaobject</refname>
 156 <refpurpose>Selects and processes an appropriate media object from a list</refpurpose>
 157 </refnamediv>
 158 <refsynopsisdiv>
 159 <synopsis>&lt;xsl:template name="select.mediaobject"&gt;
 160 &lt;xsl:param name="olist" select="d:imageobject|d:imageobjectco                      |d:videoobject|d:audioobject|d:textobject"/&gt;
 161   ...
 162 &lt;/xsl:template&gt;</synopsis>
 163 </refsynopsisdiv>
 164 <refsect1><title>Description</title>
 165
 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>
 169
 170
 171
 172 <para>This template relies on a template named
 173 "select.mediaobject.index" to determine which object
 174 in the list is appropriate.</para>
 175
 176
 177
 178 <para>If no acceptable object is located, nothing happens.</para>
 179
 180 </refsect1><refsect1><title>Parameters</title>
 181
 182 <variablelist>
 183 <varlistentry><term>olist</term>
 184 <listitem>
 185
 186 <para>The node list of potential objects to examine.</para>
 187
 188 </listitem>
 189 </varlistentry>
 190 </variablelist>
 191
 192 </refsect1><refsect1><title>Returns</title>
 193
 194 <para>Calls &lt;xsl:apply-templates&gt; on the selected object.</para>
 195
 196 </refsect1></refentry>
 197
 198 <refentry xml:id="template.select.mediaobject.index">
 199 <refnamediv>
 200 <refname>select.mediaobject.index</refname>
 201 <refpurpose>Selects the position of the appropriate media object from a list</refpurpose>
 202 </refnamediv>
 203 <refsynopsisdiv>
 204 <synopsis>&lt;xsl:template name="select.mediaobject.index"&gt;
 205 &lt;xsl:param name="olist" select="d:imageobject|d:imageobjectco                      |d:videoobject|d:audioobject|d:textobject"/&gt;
 206 &lt;xsl:param name="count"&gt;1&lt;/xsl:param&gt;
 207   ...
 208 &lt;/xsl:template&gt;</synopsis>
 209 </refsynopsisdiv>
 210 <refsect1><title>Description</title>
 211
 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>
 216
 217
 218
 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>
 224
 225
 226
 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.
 230 </para>
 231
 232
 233
 234 <para>If no acceptable object is located, no index is returned.</para>
 235
 236 </refsect1><refsect1><title>Parameters</title>
 237
 238 <variablelist>
 239 <varlistentry><term>olist</term>
 240 <listitem>
 241
 242 <para>The node list of potential objects to examine.</para>
 243
 244 </listitem>
 245 </varlistentry>
 246 <varlistentry><term>count</term>
 247 <listitem>
 248
 249 <para>The position in the list currently being considered by the
 250 recursive process.</para>
 251
 252 </listitem>
 253 </varlistentry>
 254 </variablelist>
 255
 256 </refsect1><refsect1><title>Returns</title>
 257
 258 <para>Returns the position in the original list of the selected object.</para>
 259
 260 </refsect1></refentry>
 261
 262 <refentry xml:id="template.is.acceptable.mediaobject">
 263 <refnamediv>
 264 <refname>is.acceptable.mediaobject</refname>
 265 <refpurpose>Returns '1' if the specified media object is recognized</refpurpose>
 266 </refnamediv>
 267 <refsynopsisdiv>
 268 <synopsis>&lt;xsl:template name="is.acceptable.mediaobject"&gt;
 269 &lt;xsl:param name="object"/&gt;
 270   ...
 271 &lt;/xsl:template&gt;</synopsis>
 272 </refsynopsisdiv>
 273 <refsect1><title>Description</title>
 274
 275 <para>This template examines a media object and returns '1' if the
 276 object is recognized as a graphic.</para>
 277
 278 </refsect1><refsect1><title>Parameters</title>
 279
 280 <variablelist>
 281 <varlistentry><term>object</term>
 282 <listitem>
 283
 284 <para>The media object to consider.</para>
 285
 286 </listitem>
 287 </varlistentry>
 288 </variablelist>
 289
 290 </refsect1><refsect1><title>Returns</title>
 291
 292 <para>0 or 1</para>
 293
 294 </refsect1></refentry>
 295
 296 <refentry xml:id="template.check.id.unique">
 297 <refnamediv>
 298 <refname>check.id.unique</refname>
 299 <refpurpose>Warn users about references to non-unique IDs</refpurpose>
 300 </refnamediv>
 301 <refsynopsisdiv>
 302 <synopsis>&lt;xsl:template name="check.id.unique"&gt;
 303 &lt;xsl:param name="linkend"/&gt;
 304   ...
 305 &lt;/xsl:template&gt;</synopsis>
 306 </refsynopsisdiv>
 307 <refsect1><title>Description</title>
 308
 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>
 313
 314 </refsect1></refentry>
 315
 316 <refentry xml:id="template.check.idref.targets">
 317 <refnamediv>
 318 <refname>check.idref.targets</refname>
 319 <refpurpose>Warn users about incorrectly typed references</refpurpose>
 320 </refnamediv>
 321 <refsynopsisdiv>
 322 <synopsis>&lt;xsl:template name="check.idref.targets"&gt;
 323 &lt;xsl:param name="linkend"/&gt;
 324 &lt;xsl:param name="element-list"/&gt;
 325   ...
 326 &lt;/xsl:template&gt;</synopsis>
 327 </refsynopsisdiv>
 328 <refsect1><title>Description</title>
 329
 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>
 334
 335 </refsect1></refentry>
 336
 337 <refentry xml:id="template.copyright.years">
 338 <refnamediv>
 339 <refname>copyright.years</refname>
 340 <refpurpose>Print a set of years with collapsed ranges</refpurpose>
 341 </refnamediv>
 342 <refsynopsisdiv>
 343 <synopsis>&lt;xsl:template name="copyright.years"&gt;
 344 &lt;xsl:param name="years"/&gt;
 345 &lt;xsl:param name="print.ranges" select="1"/&gt;
 346 &lt;xsl:param name="single.year.ranges" select="0"/&gt;
 347 &lt;xsl:param name="firstyear" select="0"/&gt;
 348 &lt;xsl:param name="nextyear" select="0"/&gt;
 349   ...
 350 &lt;/xsl:template&gt;</synopsis>
 351 </refsynopsisdiv>
 352 <refsect1><title>Description</title>
 353
 354 <para>This template prints a list of year elements with consecutive
 355 years printed as a range. In other words:</para>
 356
 357
 358 <screen>&lt;year&gt;1992&lt;/year&gt;
 359 &lt;year&gt;1993&lt;/year&gt;
 360 &lt;year&gt;1994&lt;/year&gt;</screen>
 361
 362
 363 <para>is printed <quote>1992-1994</quote>, whereas:</para>
 364
 365
 366 <screen>&lt;year&gt;1992&lt;/year&gt;
 367 &lt;year&gt;1994&lt;/year&gt;</screen>
 368
 369
 370 <para>is printed <quote>1992, 1994</quote>.</para>
 371
 372
 373
 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>
 379
 380 </refsect1><refsect1><title>Parameters</title>
 381
 382 <variablelist>
 383 <varlistentry><term>years</term>
 384 <listitem>
 385
 386 <para>The initial set of year elements.</para>
 387
 388 </listitem>
 389 </varlistentry>
 390 <varlistentry><term>print.ranges</term>
 391 <listitem>
 392
 393 <para>If non-zero, multi-year ranges are collapsed. If zero, all years
 394 are printed discretely.</para>
 395
 396 </listitem>
 397 </varlistentry>
 398 <varlistentry><term>single.year.ranges</term>
 399 <listitem>
 400
 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>
 405
 406 </listitem>
 407 </varlistentry>
 408 </variablelist>
 409
 410 </refsect1><refsect1><title>Returns</title>
 411
 412 <para>This template returns the formatted list of years.</para>
 413
 414 </refsect1></refentry>
 415
 416 <refentry xml:id="template.find.path.params">
 417 <refnamediv>
 418 <refname>find.path.params</refname>
 419 <refpurpose>Search in a table for the "best" match for the node</refpurpose>
 420 </refnamediv>
 421 <refsynopsisdiv>
 422 <synopsis>&lt;xsl:template name="find.path.params"&gt;
 423 &lt;xsl:param name="node" select="."/&gt;
 424 &lt;xsl:param name="table" select="''"/&gt;
 425 &lt;xsl:param name="location"&gt;
 426     &lt;xsl:call-template name="xpath.location"&gt;
 427       &lt;xsl:with-param name="node" select="$node"/&gt;
 428     &lt;/xsl:call-template&gt;
 429   &lt;/xsl:param&gt;
 430   ...
 431 &lt;/xsl:template&gt;</synopsis>
 432 </refsynopsisdiv>
 433 <refsect1><title>Description</title>
 434
 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>
 438
 439 </refsect1></refentry>
 440
 441 <refentry xml:id="template.string.upper">
 442 <refnamediv>
 443 <refname>string.upper</refname>
 444 <refpurpose>Converts a string to all uppercase letters</refpurpose>
 445 </refnamediv>
 446 <refsynopsisdiv>
 447 <synopsis>&lt;xsl:template name="string.upper"&gt;
 448 &lt;xsl:param name="string" select="''"/&gt;
 449   ...
 450 &lt;/xsl:template&gt;</synopsis>
 451 </refsynopsisdiv>
 452 <refsect1><title>Description</title>
 453
 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
 461 unchanged.</para>
 462
 463 </refsect1><refsect1><title>Parameters</title>
 464
 465 <variablelist>
 466 <varlistentry><term>string</term>
 467 <listitem>
 468
 469 <para>The string to convert to uppercase.</para>
 470
 471 </listitem>
 472 </varlistentry>
 473 </variablelist>
 474
 475 </refsect1></refentry>
 476
 477 <refentry xml:id="template.string.lower">
 478 <refnamediv>
 479 <refname>string.lower</refname>
 480 <refpurpose>Converts a string to all lowercase letters</refpurpose>
 481 </refnamediv>
 482 <refsynopsisdiv>
 483 <synopsis>&lt;xsl:template name="string.lower"&gt;
 484 &lt;xsl:param name="string" select="''"/&gt;
 485   ...
 486 &lt;/xsl:template&gt;</synopsis>
 487 </refsynopsisdiv>
 488 <refsect1><title>Description</title>
 489
 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
 497 unchanged.</para>
 498
 499 </refsect1><refsect1><title>Parameters</title>
 500
 501 <variablelist>
 502 <varlistentry><term>string</term>
 503 <listitem>
 504
 505 <para>The string to convert to lowercase.</para>
 506
 507 </listitem>
 508 </varlistentry>
 509 </variablelist>
 510
 511 </refsect1></refentry>
 512
 513 <refentry xml:id="template.select.choice.separator">
 514 <refnamediv>
 515 <refname>select.choice.separator</refname>
 516 <refpurpose>Returns localized choice separator</refpurpose>
 517 </refnamediv>
 518 <refsynopsisdiv>
 519 <synopsis>&lt;xsl:template name="select.choice.separator"/&gt;</synopsis>
 520 </refsynopsisdiv>
 521 <refsect1><title>Description</title>
 522
 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>
 527
 528
 529 <para>It currently works by evaluating a processing instruction
 530     (PI) of the form &lt;?dbchoice choice="foo"?&gt; :
 531
 532 <itemizedlist>
 533       <listitem>
 534         <simpara>if the value of the <tag>choice</tag>
 535         pseudo-attribute is "and" or "or", returns a localized "and"
 536         or "or"</simpara>
 537       </listitem>
 538       <listitem>
 539         <simpara>otherwise returns the literal value of the
 540         <tag>choice</tag> pseudo-attribute</simpara>
 541       </listitem>
 542     </itemizedlist>
 543
 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
 548     to do this:
 549     <literallayout>&lt;?dbchoice choice="ou"?&gt;</literallayout>
 550     </para>
 551
 552     <warning>
 553
 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>
 558
 559     </warning>
 560   </refsect1></refentry>
 561
 562 <refentry xml:id="template.evaluate.info.profile">
 563 <refnamediv>
 564 <refname>evaluate.info.profile</refname>
 565 <refpurpose>Evaluates an info profile</refpurpose>
 566 </refnamediv>
 567 <refsynopsisdiv>
 568 <synopsis>&lt;xsl:template name="evaluate.info.profile"&gt;
 569 &lt;xsl:param name="profile"/&gt;
 570 &lt;xsl:param name="info"/&gt;
 571   ...
 572 &lt;/xsl:template&gt;</synopsis>
 573 </refsynopsisdiv>
 574 <refsect1><title>Description</title>
 575
 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>
 580
 581
 582
 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>
 591
 592   </refsect1><refsect1><title>Parameters</title>
 593
 594 <variablelist>
 595        <varlistentry>
 596         <term>profile</term>
 597         <listitem>
 598
 599 <para>A string representing an XPath expression </para>
 600
 601         </listitem>
 602       </varlistentry>
 603        <varlistentry>
 604         <term>info</term>
 605         <listitem>
 606
 607 <para>A set of *info nodes</para>
 608
 609         </listitem>
 610       </varlistentry>
 611     </variablelist>
 612
 613   </refsect1><refsect1><title>Returns</title>
 614
 615 <para>Returns a node (the result of evaluating the
 616     <parameter>profile</parameter> parameter)</para>
 617
 618   </refsect1></refentry>
 619
 620 <refentry xml:id="template.graphic.format.content-type">
 621 <refnamediv>
 622 <refname>graphic.format.content-type</refname>
 623 <refpurpose>Returns mimetype for media format</refpurpose>
 624 </refnamediv>
 625 <refsynopsisdiv>
 626 <synopsis>&lt;xsl:template name="graphic.format.content-type"&gt;
 627 &lt;xsl:param name="format"/&gt;
 628   ...
 629 &lt;/xsl:template&gt;</synopsis>
 630 </refsynopsisdiv>
 631 <refsect1><title>Description</title>
 632
 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>
 636
 637   </refsect1></refentry>
 638 </reference>