doc/xslt/common/refentry.xml

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