stylesheets/evergreen_docbook_files/docbook-xsl-1.75.2/common/refentry.xml

   1 <?xml version="1.0"?>\r
   2 \r
   3 <reference xml:id="refentry">\r
   4   <info>\r
   5     <title>Common » Refentry Metadata Template Reference</title>\r
   6     <releaseinfo role="meta">\r
   7       $Id: refentry.xsl 7867 2008-03-07 09:54:25Z xmldoc $\r
   8     </releaseinfo>\r
   9   </info>\r
  10   \r
  11   <partintro xml:id="partintro">\r
  12     <title>Introduction</title>\r
  13     \r
  14 <para>This is technical reference documentation for the “refentry\r
  15     metadata” templates in the DocBook XSL Stylesheets.</para>\r
  16 \r
  17     \r
  18 <para>This is not intended to be user documentation. It is provided\r
  19     for developers writing customization layers for the stylesheets.</para>\r
  20 \r
  21     <note>\r
  22       \r
  23 <para>Currently, only the manpages stylesheets make use of these\r
  24       templates. They are, however, potentially useful elsewhere.</para>\r
  25 \r
  26     </note>\r
  27   </partintro>\r
  28 \r
  29 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.metadata">\r
  30 <refnamediv>\r
  31 <refname>get.refentry.metadata</refname>\r
  32 <refpurpose>Gathers metadata from a refentry and its ancestors</refpurpose>\r
  33 </refnamediv>\r
  34 <refsynopsisdiv>\r
  35 <synopsis>&lt;xsl:template name="get.refentry.metadata"&gt;\r
  36 &lt;xsl:param name="refname"/&gt;\r
  37 &lt;xsl:param name="info"/&gt;\r
  38 &lt;xsl:param name="prefs"/&gt;\r
  39   ...\r
  40 &lt;/xsl:template&gt;</synopsis>\r
  41 </refsynopsisdiv>\r
  42 <refsect1><title>Description</title>\r
  43     \r
  44 <para>Reference documentation for particular commands, functions,\r
  45     etc., is sometimes viewed in isolation from its greater "context". For\r
  46     example, users view Unix man pages as, well, individual pages, not as\r
  47     part of a "book" of some kind. Therefore, it is sometimes necessary to\r
  48     embed "context" information in output for each <tag>refentry</tag>.</para>\r
  49 \r
  50 \r
  51     \r
  52 <para>However, one problem is that different users mark up that\r
  53     context information in different ways. Often (usually), the\r
  54     context information is not actually part of the content of the\r
  55     <tag>refentry</tag> itself, but instead part of the content of a\r
  56     parent or ancestor element to the <tag>refentry</tag>. And\r
  57     even then, DocBook provides a variety of elements that users might\r
  58     potentially use to mark up the same kind of information. One user\r
  59     might use the <tag>productnumber</tag> element to mark up version\r
  60     information about a particular product, while another might use\r
  61     the <tag>releaseinfo</tag> element.</para>\r
  62 \r
  63 \r
  64     \r
  65 <para>Taking all that in mind, the\r
  66     <function>get.refentry.metadata</function> template tries to gather\r
  67     metadata from a <tag>refentry</tag> element and its ancestor\r
  68     elements in an intelligent and user-configurable way. The basic\r
  69     mechanism used in the XPath expressions throughout this stylesheet\r
  70     is to select the relevant metadata from the *info element that is\r
  71     closest to the actual <tag>refentry</tag> – either on the\r
  72     <tag>refentry</tag> itself, or on its nearest ancestor.</para>\r
  73 \r
  74 \r
  75     <note>\r
  76       \r
  77 <para>The <function>get.refentry.metadata</function>\r
  78         template is actually just sort of a "driver" template; it\r
  79         calls other templates that do the actual data collection,\r
  80         then returns the data as a set.</para>\r
  81 \r
  82     </note>\r
  83 \r
  84   </refsect1><refsect1><title>Parameters</title>\r
  85     \r
  86 <variablelist>\r
  87       <varlistentry>\r
  88         <term>refname</term>\r
  89         <listitem>\r
  90           \r
  91 <para>The first <tag>refname</tag> in the refentry</para>\r
  92 \r
  93         </listitem>\r
  94       </varlistentry>\r
  95       <varlistentry>\r
  96         <term>info</term>\r
  97         <listitem>\r
  98           \r
  99 <para>A set of info nodes (from a <tag>refentry</tag>\r
 100           element and its ancestors)</para>\r
 101 \r
 102         </listitem>\r
 103       </varlistentry>\r
 104       <varlistentry>\r
 105         <term>prefs</term>\r
 106         <listitem>\r
 107           \r
 108 <para>A node containing user preferences (from global\r
 109           stylesheet parameters)</para>\r
 110 \r
 111         </listitem>\r
 112       </varlistentry>\r
 113     </variablelist>\r
 114 \r
 115   </refsect1><refsect1><title>Returns</title>\r
 116     \r
 117 <para>Returns a node set with the following elements. The\r
 118     descriptions are verbatim from the <literal>man(7)</literal> man\r
 119     page.\r
 120     \r
 121 <variablelist>\r
 122       <varlistentry>\r
 123         <term>title</term>\r
 124         <listitem>\r
 125           \r
 126 <para>the title of the man page (e.g., <literal>MAN</literal>)</para>\r
 127 \r
 128         </listitem>\r
 129       </varlistentry>\r
 130       <varlistentry>\r
 131         <term>section</term>\r
 132         <listitem>\r
 133           \r
 134 <para>the section number the man page should be placed in (e.g.,\r
 135           <literal>7</literal>)</para>\r
 136 \r
 137         </listitem>\r
 138       </varlistentry>\r
 139       <varlistentry>\r
 140         <term>date</term>\r
 141         <listitem>\r
 142           \r
 143 <para>the date of the last revision</para>\r
 144 \r
 145         </listitem>\r
 146       </varlistentry>\r
 147       <varlistentry>\r
 148         <term>source</term>\r
 149         <listitem>\r
 150           \r
 151 <para>the source of the command</para>\r
 152 \r
 153         </listitem>\r
 154       </varlistentry>\r
 155       <varlistentry>\r
 156         <term>manual</term>\r
 157         <listitem>\r
 158           \r
 159 <para>the title of the manual (e.g., <citetitle>Linux\r
 160           Programmer's Manual</citetitle>)</para>\r
 161 \r
 162         </listitem>\r
 163       </varlistentry>\r
 164     </variablelist>\r
 165 \r
 166     </para>\r
 167 \r
 168   </refsect1></refentry>\r
 169 \r
 170 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.title">\r
 171 <refnamediv>\r
 172 <refname>get.refentry.title</refname>\r
 173 <refpurpose>Gets title metadata for a refentry</refpurpose>\r
 174 </refnamediv>\r
 175 <refsynopsisdiv>\r
 176 <synopsis>&lt;xsl:template name="get.refentry.title"&gt;\r
 177 &lt;xsl:param name="refname"/&gt;\r
 178   ...\r
 179 &lt;/xsl:template&gt;</synopsis>\r
 180 </refsynopsisdiv>\r
 181 <refsect1><title>Description</title>\r
 182     \r
 183 <para>The <literal>man(7)</literal> man page describes this as "the\r
 184     title of the man page (e.g., <literal>MAN</literal>). This differs\r
 185     from <tag>refname</tag> in that, if the <tag>refentry</tag> has a\r
 186     <tag>refentrytitle</tag>, we use that as the <tag>title</tag>;\r
 187     otherwise, we just use first <tag>refname</tag> in the first\r
 188     <tag>refnamediv</tag> in the source.</para>\r
 189 \r
 190   </refsect1><refsect1><title>Parameters</title>\r
 191     \r
 192 <variablelist>\r
 193       <varlistentry>\r
 194         <term>refname</term>\r
 195         <listitem>\r
 196           \r
 197 <para>The first <tag>refname</tag> in the refentry</para>\r
 198 \r
 199         </listitem>\r
 200       </varlistentry>\r
 201     </variablelist>\r
 202 \r
 203   </refsect1><refsect1><title>Returns</title>\r
 204   \r
 205 <para>Returns a <tag>title</tag> node.</para>\r
 206 </refsect1></refentry>\r
 207 \r
 208 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.section">\r
 209 <refnamediv>\r
 210 <refname>get.refentry.section</refname>\r
 211 <refpurpose>Gets section metadata for a refentry</refpurpose>\r
 212 </refnamediv>\r
 213 <refsynopsisdiv>\r
 214 <synopsis>&lt;xsl:template name="get.refentry.section"&gt;\r
 215 &lt;xsl:param name="refname"/&gt;\r
 216 &lt;xsl:param name="quiet" select="0"/&gt;\r
 217   ...\r
 218 &lt;/xsl:template&gt;</synopsis>\r
 219 </refsynopsisdiv>\r
 220 <refsect1><title>Description</title>\r
 221     \r
 222 <para>The <literal>man(7)</literal> man page describes this as "the\r
 223     section number the man page should be placed in (e.g.,\r
 224     <literal>7</literal>)". If we do not find a <tag>manvolnum</tag>\r
 225     specified in the source, and we find that the <tag>refentry</tag> is\r
 226     for a function, we use the section number <literal>3</literal>\r
 227     ["Library calls (functions within program libraries)"]; otherwise, we\r
 228     default to using <literal>1</literal> ["Executable programs or shell\r
 229     commands"].</para>\r
 230 \r
 231   </refsect1><refsect1><title>Parameters</title>\r
 232     \r
 233 <variablelist>\r
 234       <varlistentry>\r
 235         <term>refname</term>\r
 236         <listitem>\r
 237           \r
 238 <para>The first <tag>refname</tag> in the refentry</para>\r
 239 \r
 240         </listitem>\r
 241       </varlistentry>\r
 242       <varlistentry>\r
 243         <term>quiet</term>\r
 244         <listitem>\r
 245           \r
 246 <para>If non-zero, no "missing" message is emitted</para>\r
 247 \r
 248         </listitem>\r
 249       </varlistentry>\r
 250     </variablelist>\r
 251 \r
 252   </refsect1><refsect1><title>Returns</title>\r
 253   \r
 254 <para>Returns a string representing a section number.</para>\r
 255 </refsect1></refentry>\r
 256 \r
 257 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.date">\r
 258 <refnamediv>\r
 259 <refname>get.refentry.date</refname>\r
 260 <refpurpose>Gets date metadata for a refentry</refpurpose>\r
 261 </refnamediv>\r
 262 <refsynopsisdiv>\r
 263 <synopsis>&lt;xsl:template name="get.refentry.date"&gt;\r
 264 &lt;xsl:param name="refname"/&gt;\r
 265 &lt;xsl:param name="info"/&gt;\r
 266 &lt;xsl:param name="prefs"/&gt;\r
 267   ...\r
 268 &lt;/xsl:template&gt;</synopsis>\r
 269 </refsynopsisdiv>\r
 270 <refsect1><title>Description</title>\r
 271     \r
 272 <para>The <literal>man(7)</literal> man page describes this as "the\r
 273     date of the last revision". If we cannot find a date in the source, we\r
 274     generate one.</para>\r
 275 \r
 276   </refsect1><refsect1><title>Parameters</title>\r
 277     \r
 278 <variablelist>\r
 279       <varlistentry>\r
 280         <term>refname</term>\r
 281         <listitem>\r
 282           \r
 283 <para>The first <tag>refname</tag> in the refentry</para>\r
 284 \r
 285         </listitem>\r
 286       </varlistentry>\r
 287       <varlistentry>\r
 288         <term>info</term>\r
 289         <listitem>\r
 290           \r
 291 <para>A set of info nodes (from a <tag>refentry</tag>\r
 292           element and its ancestors)</para>\r
 293 \r
 294         </listitem>\r
 295       </varlistentry>\r
 296       <varlistentry>\r
 297         <term>prefs</term>\r
 298         <listitem>\r
 299           \r
 300 <para>A node containing users preferences (from global stylesheet parameters)</para>\r
 301 \r
 302         </listitem>\r
 303       </varlistentry>\r
 304     </variablelist>\r
 305 \r
 306   </refsect1><refsect1><title>Returns</title>\r
 307     \r
 308 <para>Returns a <tag>date</tag> node.</para>\r
 309 \r
 310   </refsect1></refentry>\r
 311 \r
 312 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.source">\r
 313 <refnamediv>\r
 314 <refname>get.refentry.source</refname>\r
 315 <refpurpose>Gets source metadata for a refentry</refpurpose>\r
 316 </refnamediv>\r
 317 <refsynopsisdiv>\r
 318 <synopsis>&lt;xsl:template name="get.refentry.source"&gt;\r
 319 &lt;xsl:param name="refname"/&gt;\r
 320 &lt;xsl:param name="info"/&gt;\r
 321 &lt;xsl:param name="prefs"/&gt;\r
 322   ...\r
 323 &lt;/xsl:template&gt;</synopsis>\r
 324 </refsynopsisdiv>\r
 325 <refsect1><title>Description</title>\r
 326     \r
 327 <para>The <literal>man(7)</literal> man page describes this as "the\r
 328     source of the command", and provides the following examples:\r
 329     \r
 330 <itemizedlist>\r
 331       <listitem>\r
 332         \r
 333 <para>For binaries, use something like: GNU, NET-2, SLS\r
 334         Distribution, MCC Distribution.</para>\r
 335 \r
 336       </listitem>\r
 337       <listitem>\r
 338         \r
 339 <para>For system calls, use the version of the kernel that you are\r
 340         currently looking at: Linux 0.99.11.</para>\r
 341 \r
 342       </listitem>\r
 343       <listitem>\r
 344         \r
 345 <para>For library calls, use the source of the function: GNU, BSD\r
 346         4.3, Linux DLL 4.4.1.</para>\r
 347 \r
 348       </listitem>\r
 349     </itemizedlist>\r
 350 \r
 351     </para>\r
 352 \r
 353 \r
 354     \r
 355 <para>The <literal>solbook(5)</literal> man page describes\r
 356     something very much like what <literal>man(7)</literal> calls\r
 357     "source", except that <literal>solbook(5)</literal> names it\r
 358     "software" and describes it like this:\r
 359     <blockquote>\r
 360       \r
 361 <para>This is the name of the software product that the topic\r
 362       discussed on the reference page belongs to. For example UNIX\r
 363       commands are part of the <literal>SunOS x.x</literal>\r
 364       release.</para>\r
 365 \r
 366     </blockquote>\r
 367     </para>\r
 368 \r
 369 \r
 370     \r
 371 <para>In practice, there are many pages that simply have a version\r
 372     number in the "source" field. So, it looks like what we have is a\r
 373     two-part field,\r
 374     <replaceable>Name</replaceable> <replaceable>Version</replaceable>,\r
 375     where:\r
 376     \r
 377 <variablelist>\r
 378       <varlistentry>\r
 379         <term>Name</term>\r
 380         <listitem>\r
 381           \r
 382 <para>product name (e.g., BSD) or org. name (e.g., GNU)</para>\r
 383 \r
 384         </listitem>\r
 385       </varlistentry>\r
 386       <varlistentry>\r
 387         <term>Version</term>\r
 388         <listitem>\r
 389           \r
 390 <para>version name</para>\r
 391 \r
 392         </listitem>\r
 393       </varlistentry>\r
 394     </variablelist>\r
 395 \r
 396     Each part is optional. If the <replaceable>Name</replaceable> is a\r
 397     product name, then the <replaceable>Version</replaceable> is probably\r
 398     the version of the product. Or there may be no\r
 399     <replaceable>Name</replaceable>, in which case, if there is a\r
 400     <replaceable>Version</replaceable>, it is probably the version of the\r
 401     item itself, not the product it is part of. Or, if the\r
 402     <replaceable>Name</replaceable> is an organization name, then there\r
 403     probably will be no <replaceable>Version</replaceable>.\r
 404     </para>\r
 405 \r
 406   </refsect1><refsect1><title>Parameters</title>\r
 407     \r
 408 <variablelist>\r
 409       <varlistentry>\r
 410         <term>refname</term>\r
 411         <listitem>\r
 412           \r
 413 <para>The first <tag>refname</tag> in the refentry</para>\r
 414 \r
 415         </listitem>\r
 416       </varlistentry>\r
 417       <varlistentry>\r
 418         <term>info</term>\r
 419         <listitem>\r
 420           \r
 421 <para>A set of info nodes (from a <tag>refentry</tag>\r
 422           element and its ancestors)</para>\r
 423 \r
 424         </listitem>\r
 425       </varlistentry>\r
 426       <varlistentry>\r
 427         <term>prefs</term>\r
 428         <listitem>\r
 429           \r
 430 <para>A node containing users preferences (from global\r
 431           stylesheet parameters)</para>\r
 432 \r
 433         </listitem>\r
 434       </varlistentry>\r
 435     </variablelist>\r
 436 \r
 437   </refsect1><refsect1><title>Returns</title>\r
 438     \r
 439 <para>Returns a <tag>source</tag> node.</para>\r
 440 \r
 441   </refsect1></refentry>\r
 442 \r
 443 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.source.name">\r
 444 <refnamediv>\r
 445 <refname>get.refentry.source.name</refname>\r
 446 <refpurpose>Gets source-name metadata for a refentry</refpurpose>\r
 447 </refnamediv>\r
 448 <refsynopsisdiv>\r
 449 <synopsis>&lt;xsl:template name="get.refentry.source.name"&gt;\r
 450 &lt;xsl:param name="refname"/&gt;\r
 451 &lt;xsl:param name="info"/&gt;\r
 452 &lt;xsl:param name="prefs"/&gt;\r
 453   ...\r
 454 &lt;/xsl:template&gt;</synopsis>\r
 455 </refsynopsisdiv>\r
 456 <refsect1><title>Description</title>\r
 457     \r
 458 <para>A "source name" is one part of a (potentially) two-part\r
 459     <replaceable>Name</replaceable> <replaceable>Version</replaceable>\r
 460     source field. For more details, see the documentation for the\r
 461     <function>get.refentry.source</function> template.</para>\r
 462 \r
 463   </refsect1><refsect1><title>Parameters</title>\r
 464     \r
 465 <variablelist>\r
 466       <varlistentry>\r
 467         <term>refname</term>\r
 468         <listitem>\r
 469           \r
 470 <para>The first <tag>refname</tag> in the refentry</para>\r
 471 \r
 472         </listitem>\r
 473       </varlistentry>\r
 474       <varlistentry>\r
 475         <term>info</term>\r
 476         <listitem>\r
 477           \r
 478 <para>A set of info nodes (from a <tag>refentry</tag>\r
 479           element and its ancestors)</para>\r
 480 \r
 481         </listitem>\r
 482       </varlistentry>\r
 483       <varlistentry>\r
 484         <term>prefs</term>\r
 485         <listitem>\r
 486           \r
 487 <para>A node containing users preferences (from global\r
 488           stylesheet parameters)</para>\r
 489 \r
 490         </listitem>\r
 491       </varlistentry>\r
 492     </variablelist>\r
 493 \r
 494   </refsect1><refsect1><title>Returns</title>\r
 495     \r
 496 <para>Depending on what output method is used for the\r
 497   current stylesheet, either returns a text node or possibly an element\r
 498   node, containing "source name" data.</para>\r
 499 \r
 500   </refsect1></refentry>\r
 501 \r
 502 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.version">\r
 503 <refnamediv>\r
 504 <refname>get.refentry.version</refname>\r
 505 <refpurpose>Gets version metadata for a refentry</refpurpose>\r
 506 </refnamediv>\r
 507 <refsynopsisdiv>\r
 508 <synopsis>&lt;xsl:template name="get.refentry.version"&gt;\r
 509 &lt;xsl:param name="refname"/&gt;\r
 510 &lt;xsl:param name="info"/&gt;\r
 511 &lt;xsl:param name="prefs"/&gt;\r
 512   ...\r
 513 &lt;/xsl:template&gt;</synopsis>\r
 514 </refsynopsisdiv>\r
 515 <refsect1><title>Description</title>\r
 516     \r
 517 <para>A "version" is one part of a (potentially) two-part\r
 518     <replaceable>Name</replaceable> <replaceable>Version</replaceable>\r
 519     source field. For more details, see the documentation for the\r
 520     <function>get.refentry.source</function> template.</para>\r
 521 \r
 522   </refsect1><refsect1><title>Parameters</title>\r
 523     \r
 524 <variablelist>\r
 525       <varlistentry>\r
 526         <term>refname</term>\r
 527         <listitem>\r
 528           \r
 529 <para>The first <tag>refname</tag> in the refentry</para>\r
 530 \r
 531         </listitem>\r
 532       </varlistentry>\r
 533       <varlistentry>\r
 534         <term>info</term>\r
 535         <listitem>\r
 536           \r
 537 <para>A set of info nodes (from a <tag>refentry</tag>\r
 538           element and its ancestors)</para>\r
 539 \r
 540         </listitem>\r
 541       </varlistentry>\r
 542       <varlistentry>\r
 543         <term>prefs</term>\r
 544         <listitem>\r
 545           \r
 546 <para>A node containing users preferences (from global\r
 547           stylesheet parameters)</para>\r
 548 \r
 549         </listitem>\r
 550       </varlistentry>\r
 551     </variablelist>\r
 552 \r
 553   </refsect1><refsect1><title>Returns</title>\r
 554     \r
 555 <para>Depending on what output method is used for the\r
 556   current stylesheet, either returns a text node or possibly an element\r
 557   node, containing "version" data.</para>\r
 558 \r
 559   </refsect1></refentry>\r
 560 \r
 561 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.manual">\r
 562 <refnamediv>\r
 563 <refname>get.refentry.manual</refname>\r
 564 <refpurpose>Gets source metadata for a refentry</refpurpose>\r
 565 </refnamediv>\r
 566 <refsynopsisdiv>\r
 567 <synopsis>&lt;xsl:template name="get.refentry.manual"&gt;\r
 568 &lt;xsl:param name="refname"/&gt;\r
 569 &lt;xsl:param name="info"/&gt;\r
 570 &lt;xsl:param name="prefs"/&gt;\r
 571   ...\r
 572 &lt;/xsl:template&gt;</synopsis>\r
 573 </refsynopsisdiv>\r
 574 <refsect1><title>Description</title>\r
 575     \r
 576 <para>The <literal>man(7)</literal> man page describes this as "the\r
 577     title of the manual (e.g., <citetitle>Linux Programmer's\r
 578     Manual</citetitle>)". Here are some examples from existing man pages:\r
 579     \r
 580 <itemizedlist>\r
 581       <listitem>\r
 582         \r
 583 <para><citetitle>dpkg utilities</citetitle>\r
 584         (<command>dpkg-name</command>)</para>\r
 585 \r
 586       </listitem>\r
 587       <listitem>\r
 588         \r
 589 <para><citetitle>User Contributed Perl Documentation</citetitle>\r
 590         (<command>GET</command>)</para>\r
 591 \r
 592       </listitem>\r
 593       <listitem>\r
 594         \r
 595 <para><citetitle>GNU Development Tools</citetitle>\r
 596         (<command>ld</command>)</para>\r
 597 \r
 598       </listitem>\r
 599       <listitem>\r
 600         \r
 601 <para><citetitle>Emperor Norton Utilities</citetitle>\r
 602         (<command>ddate</command>)</para>\r
 603 \r
 604       </listitem>\r
 605       <listitem>\r
 606         \r
 607 <para><citetitle>Debian GNU/Linux manual</citetitle>\r
 608         (<command>faked</command>)</para>\r
 609 \r
 610       </listitem>\r
 611       <listitem>\r
 612         \r
 613 <para><citetitle>GIMP Manual Pages</citetitle>\r
 614         (<command>gimp</command>)</para>\r
 615 \r
 616       </listitem>\r
 617       <listitem>\r
 618         \r
 619 <para><citetitle>KDOC Documentation System</citetitle>\r
 620         (<command>qt2kdoc</command>)</para>\r
 621 \r
 622       </listitem>\r
 623     </itemizedlist>\r
 624 \r
 625     </para>\r
 626 \r
 627 \r
 628     \r
 629 <para>The <literal>solbook(5)</literal> man page describes\r
 630     something very much like what <literal>man(7)</literal> calls\r
 631     "manual", except that <literal>solbook(5)</literal> names it\r
 632     "sectdesc" and describes it like this:\r
 633     <blockquote>\r
 634       \r
 635 <para>This is the section title of the reference page; for\r
 636       example <literal>User Commands</literal>.</para>\r
 637 \r
 638     </blockquote>\r
 639     </para>\r
 640 \r
 641 \r
 642   </refsect1><refsect1><title>Parameters</title>\r
 643     \r
 644 <variablelist>\r
 645       <varlistentry>\r
 646         <term>refname</term>\r
 647         <listitem>\r
 648           \r
 649 <para>The first <tag>refname</tag> in the refentry</para>\r
 650 \r
 651         </listitem>\r
 652       </varlistentry>\r
 653       <varlistentry>\r
 654         <term>info</term>\r
 655         <listitem>\r
 656           \r
 657 <para>A set of info nodes (from a <tag>refentry</tag>\r
 658           element and its ancestors)</para>\r
 659 \r
 660         </listitem>\r
 661       </varlistentry>\r
 662       <varlistentry>\r
 663         <term>prefs</term>\r
 664         <listitem>\r
 665           \r
 666 <para>A node containing users preferences (from global\r
 667           stylesheet parameters)</para>\r
 668 \r
 669         </listitem>\r
 670       </varlistentry>\r
 671     </variablelist>\r
 672 \r
 673   </refsect1><refsect1><title>Returns</title>\r
 674     \r
 675 <para>Returns a <tag>manual</tag> node.</para>\r
 676 \r
 677   </refsect1></refentry>\r
 678 \r
 679 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.refentry.metadata.prefs">\r
 680 <refnamediv>\r
 681 <refname>get.refentry.metadata.prefs</refname>\r
 682 <refpurpose>Gets user preferences for refentry metadata gathering</refpurpose>\r
 683 </refnamediv>\r
 684 <refsynopsisdiv>\r
 685 <synopsis>&lt;xsl:template name="get.refentry.metadata.prefs"/&gt;</synopsis>\r
 686 </refsynopsisdiv>\r
 687 <refsect1><title>Description</title>\r
 688     \r
 689 <para>The DocBook XSL stylesheets include several user-configurable\r
 690     global stylesheet parameters for controlling <tag>refentry</tag>\r
 691     metadata gathering. Those parameters are not read directly by the\r
 692     other <tag>refentry</tag> metadata-gathering\r
 693     templates. Instead, they are read only by the\r
 694     <function>get.refentry.metadata.prefs</function> template,\r
 695     which assembles them into a structure that is then passed to\r
 696     the other <tag>refentry</tag> metadata-gathering\r
 697     templates.</para>\r
 698 \r
 699 \r
 700     \r
 701 <para>So the, <function>get.refentry.metadata.prefs</function>\r
 702     template is the only interface to collecting stylesheet parameters for\r
 703     controlling <tag>refentry</tag> metadata gathering.</para>\r
 704 \r
 705   </refsect1><refsect1><title>Parameters</title>\r
 706     \r
 707 <para>There are no local parameters for this template; however, it\r
 708     does rely on a number of global parameters.</para>\r
 709 \r
 710   </refsect1><refsect1><title>Returns</title>\r
 711     \r
 712 <para>Returns a <tag>manual</tag> node.</para>\r
 713 \r
 714   </refsect1></refentry>\r
 715 \r
 716 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.set.refentry.metadata">\r
 717 <refnamediv>\r
 718 <refname>set.refentry.metadata</refname>\r
 719 <refpurpose>Sets content of a refentry metadata item</refpurpose>\r
 720 </refnamediv>\r
 721 <refsynopsisdiv>\r
 722 <synopsis>&lt;xsl:template name="set.refentry.metadata"&gt;\r
 723 &lt;xsl:param name="refname"/&gt;\r
 724 &lt;xsl:param name="info"/&gt;\r
 725 &lt;xsl:param name="contents"/&gt;\r
 726 &lt;xsl:param name="context"/&gt;\r
 727 &lt;xsl:param name="preferred"/&gt;\r
 728   ...\r
 729 &lt;/xsl:template&gt;</synopsis>\r
 730 </refsynopsisdiv>\r
 731 <refsect1><title>Description</title>\r
 732     \r
 733 <para>The <function>set.refentry.metadata</function> template is\r
 734     called each time a suitable source element is found for a certain\r
 735     metadata field.</para>\r
 736 \r
 737   </refsect1><refsect1><title>Parameters</title>\r
 738     \r
 739 <variablelist>\r
 740       <varlistentry>\r
 741         <term>refname</term>\r
 742         <listitem>\r
 743           \r
 744 <para>The first <tag>refname</tag> in the refentry</para>\r
 745 \r
 746         </listitem>\r
 747       </varlistentry>\r
 748       <varlistentry>\r
 749         <term>info</term>\r
 750         <listitem>\r
 751           \r
 752 <para>A single *info node that contains the selected source element.</para>\r
 753 \r
 754         </listitem>\r
 755       </varlistentry>\r
 756       <varlistentry>\r
 757         <term>contents</term>\r
 758         <listitem>\r
 759           \r
 760 <para>A node containing the selected source element.</para>\r
 761 \r
 762         </listitem>\r
 763       </varlistentry>\r
 764       <varlistentry>\r
 765         <term>context</term>\r
 766         <listitem>\r
 767           \r
 768 <para>A string describing the metadata context in which the\r
 769           <function>set.refentry.metadata</function> template was\r
 770           called: either "date", "source", "version", or "manual".</para>\r
 771 \r
 772         </listitem>\r
 773       </varlistentry>\r
 774     </variablelist>\r
 775 \r
 776   </refsect1><refsect1><title>Returns</title>\r
 777   \r
 778 <para>Returns formatted contents of a selected source element.</para>\r
 779 </refsect1></refentry>\r
 780 </reference>\r
 781 \r