lib/docbook/common/refentry.xsl

   1 <?xml version='1.0'?>
   2 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   3                 xmlns:d="http://docbook.org/ns/docbook"
   4                 xmlns:doc="http://nwalsh.com/xsl/documentation/1.0"
   5                 xmlns:date="http://exslt.org/dates-and-times"
   6                 exclude-result-prefixes="doc date d"
   7                 version='1.0'>
   8
   9 <!-- ********************************************************************
  10
  11      This file is part of the XSL DocBook Stylesheet distribution.
  12      See ../README or http://cdn.docbook.org/release/xsl/current/ for
  13      copyright and other information.
  14
  15      ******************************************************************** -->
  16
  17 <!-- ==================================================================== -->
  18 <doc:reference xmlns="" xml:id="refentry">
  19   <info>
  20     <title>Common » Refentry Metadata Template Reference</title>
  21     <releaseinfo role="meta">
  22     </releaseinfo>
  23   </info>
  24   <!-- * yes, partintro is a valid child of a reference... -->
  25   <partintro xml:id="partintro">
  26     <title>Introduction</title>
  27     <para>This is technical reference documentation for the “refentry
  28     metadata” templates in the DocBook XSL Stylesheets.</para>
  29     <para>This is not intended to be user documentation. It is provided
  30     for developers writing customization layers for the stylesheets.</para>
  31     <note>
  32       <para>Currently, only the manpages stylesheets make use of these
  33       templates. They are, however, potentially useful elsewhere.</para>
  34     </note>
  35   </partintro>
  36 </doc:reference>
  37
  38 <!-- ==================================================================== -->
  39 <doc:template name="get.refentry.metadata" xmlns="">
  40   <refpurpose>Gathers metadata from a refentry and its ancestors</refpurpose>
  41   <refdescription id="get.refentry.metadata-desc">
  42     <para>Reference documentation for particular commands, functions,
  43     etc., is sometimes viewed in isolation from its greater "context". For
  44     example, users view Unix man pages as, well, individual pages, not as
  45     part of a "book" of some kind. Therefore, it is sometimes necessary to
  46     embed "context" information in output for each <tag>refentry</tag>.</para>
  47
  48     <para>However, one problem is that different users mark up that
  49     context information in different ways. Often (usually), the
  50     context information is not actually part of the content of the
  51     <tag>refentry</tag> itself, but instead part of the content of a
  52     parent or ancestor element to the <tag>refentry</tag>. And
  53     even then, DocBook provides a variety of elements that users might
  54     potentially use to mark up the same kind of information. One user
  55     might use the <tag>productnumber</tag> element to mark up version
  56     information about a particular product, while another might use
  57     the <tag>releaseinfo</tag> element.</para>
  58
  59     <para>Taking all that in mind, the
  60     <function>get.refentry.metadata</function> template tries to gather
  61     metadata from a <tag>refentry</tag> element and its ancestor
  62     elements in an intelligent and user-configurable way. The basic
  63     mechanism used in the XPath expressions throughout this stylesheet
  64     is to select the relevant metadata from the *info element that is
  65     closest to the actual <tag>refentry</tag>&#160;– either on the
  66     <tag>refentry</tag> itself, or on its nearest ancestor.</para>
  67
  68     <note>
  69       <para>The <function>get.refentry.metadata</function>
  70         template is actually just sort of a "driver" template; it
  71         calls other templates that do the actual data collection,
  72         then returns the data as a set.</para>
  73     </note>
  74
  75   </refdescription>
  76   <refparameter id="get.refentry.metadata-params">
  77     <variablelist>
  78       <varlistentry>
  79         <term>refname</term>
  80         <listitem>
  81           <para>The first <tag>refname</tag> in the refentry</para>
  82         </listitem>
  83       </varlistentry>
  84       <varlistentry>
  85         <term>info</term>
  86         <listitem>
  87           <para>A set of info nodes (from a <tag>refentry</tag>
  88           element and its ancestors)</para>
  89         </listitem>
  90       </varlistentry>
  91       <varlistentry>
  92         <term>prefs</term>
  93         <listitem>
  94           <para>A node containing user preferences (from global
  95           stylesheet parameters)</para>
  96         </listitem>
  97       </varlistentry>
  98     </variablelist>
  99   </refparameter>
 100   <refreturn id="get.refentry.metadata-returns">
 101     <para>Returns a node set with the following elements. The
 102     descriptions are verbatim from the <literal>man(7)</literal> man
 103     page.
 104     <variablelist>
 105       <varlistentry>
 106         <term>title</term>
 107         <listitem>
 108           <para>the title of the man page (e.g., <literal>MAN</literal>)</para>
 109         </listitem>
 110       </varlistentry>
 111       <varlistentry>
 112         <term>section</term>
 113         <listitem>
 114           <para>the section number the man page should be placed in (e.g.,
 115           <literal>7</literal>)</para>
 116         </listitem>
 117       </varlistentry>
 118       <varlistentry>
 119         <term>date</term>
 120         <listitem>
 121           <para>the date of the last revision</para>
 122         </listitem>
 123       </varlistentry>
 124       <varlistentry>
 125         <term>source</term>
 126         <listitem>
 127           <para>the source of the command</para>
 128         </listitem>
 129       </varlistentry>
 130       <varlistentry>
 131         <term>manual</term>
 132         <listitem>
 133           <para>the title of the manual (e.g., <citetitle>Linux
 134           Programmer's Manual</citetitle>)</para>
 135         </listitem>
 136       </varlistentry>
 137     </variablelist>
 138     </para>
 139   </refreturn>
 140 </doc:template>
 141 <xsl:template name="get.refentry.metadata">
 142   <xsl:param name="refname"/>
 143   <xsl:param name="info"/>
 144   <xsl:param name="prefs"/>
 145   <title>
 146     <xsl:call-template name="get.refentry.title">
 147       <xsl:with-param name="refname" select="$refname"/>
 148     </xsl:call-template>
 149   </title>
 150   <section>
 151     <xsl:call-template name="get.refentry.section">
 152       <xsl:with-param name="refname" select="$refname"/>
 153     </xsl:call-template>
 154   </section>
 155   <date>
 156     <xsl:call-template name="get.refentry.date">
 157       <xsl:with-param name="info" select="$info"/>
 158       <xsl:with-param name="refname" select="$refname"/>
 159       <xsl:with-param name="prefs" select="$prefs/DatePrefs"/>
 160     </xsl:call-template>
 161   </date>
 162   <source>
 163     <xsl:call-template name="get.refentry.source">
 164       <xsl:with-param name="info" select="$info"/>
 165       <xsl:with-param name="refname" select="$refname"/>
 166       <xsl:with-param name="prefs" select="$prefs/SourcePrefs"/>
 167     </xsl:call-template>
 168   </source>
 169   <manual>
 170     <xsl:call-template name="get.refentry.manual">
 171       <xsl:with-param name="info" select="$info"/>
 172       <xsl:with-param name="refname" select="$refname"/>
 173       <xsl:with-param name="prefs" select="$prefs/ManualPrefs"/>
 174     </xsl:call-template>
 175   </manual>
 176 </xsl:template>
 177
 178 <!-- ====================================================================== -->
 179 <doc:template name="get.refentry.title" xmlns="">
 180   <refpurpose>Gets title metadata for a refentry</refpurpose>
 181   <refdescription id="get.refentry.title-desc">
 182     <para>The <literal>man(7)</literal> man page describes this as "the
 183     title of the man page (e.g., <literal>MAN</literal>). This differs
 184     from <tag>refname</tag> in that, if the <tag>refentry</tag> has a
 185     <tag>refentrytitle</tag>, we use that as the <tag>title</tag>;
 186     otherwise, we just use first <tag>refname</tag> in the first
 187     <tag>refnamediv</tag> in the source.</para>
 188   </refdescription>
 189   <refparameter id="get.refentry.title-params">
 190     <variablelist>
 191       <varlistentry>
 192         <term>refname</term>
 193         <listitem>
 194           <para>The first <tag>refname</tag> in the refentry</para>
 195         </listitem>
 196       </varlistentry>
 197     </variablelist>
 198   </refparameter>
 199   <refreturn id="get.refentry.title-returns">
 200   <para>Returns a <tag>title</tag> node.</para></refreturn>
 201 </doc:template>
 202 <xsl:template name="get.refentry.title">
 203   <xsl:param name="refname"/>
 204   <xsl:choose>
 205     <xsl:when test="d:refmeta/d:refentrytitle">
 206       <xsl:copy>
 207         <xsl:apply-templates select="d:refmeta/d:refentrytitle/node()"/>
 208       </xsl:copy>
 209     </xsl:when>
 210     <xsl:otherwise>
 211       <xsl:copy-of select="$refname"/>
 212     </xsl:otherwise>
 213   </xsl:choose>
 214 </xsl:template>
 215
 216 <!-- ==================================================================== -->
 217 <doc:template name="get.refentry.section" xmlns="">
 218   <refpurpose>Gets section metadata for a refentry</refpurpose>
 219   <refdescription id="get.refentry.section-desc">
 220     <para>The <literal>man(7)</literal> man page describes this as "the
 221     section number the man page should be placed in (e.g.,
 222     <literal>7</literal>)". If we do not find a <tag>manvolnum</tag>
 223     specified in the source, and we find that the <tag>refentry</tag> is
 224     for a function, we use the section number <literal>3</literal>
 225     ["Library calls (functions within program libraries)"]; otherwise, we
 226     default to using <literal>1</literal> ["Executable programs or shell
 227     commands"].</para>
 228   </refdescription>
 229   <refparameter id="get.refentry.section-params">
 230     <variablelist>
 231       <varlistentry>
 232         <term>refname</term>
 233         <listitem>
 234           <para>The first <tag>refname</tag> in the refentry</para>
 235         </listitem>
 236       </varlistentry>
 237       <varlistentry>
 238         <term>quiet</term>
 239         <listitem>
 240           <para>If non-zero, no "missing" message is emitted</para>
 241         </listitem>
 242       </varlistentry>
 243     </variablelist>
 244   </refparameter>
 245   <refreturn id="get.refentry.section-returns">
 246   <para>Returns a string representing a section number.</para></refreturn>
 247 </doc:template>
 248 <xsl:template name="get.refentry.section">
 249   <xsl:param name="refname"/>
 250   <xsl:param name="quiet" select="0"/>
 251   <xsl:choose>
 252     <xsl:when test="d:refmeta/d:manvolnum">
 253       <xsl:value-of select="d:refmeta/d:manvolnum"/>
 254     </xsl:when>
 255     <xsl:otherwise>
 256       <xsl:if test="$quiet = 0">
 257         <xsl:if test="$refentry.meta.get.quietly = 0">
 258           <xsl:call-template name="log.message">
 259             <xsl:with-param name="level">Note</xsl:with-param>
 260             <xsl:with-param name="source" select="$refname"/>
 261             <xsl:with-param name="context-desc">meta manvol</xsl:with-param>
 262             <xsl:with-param name="message">
 263               <xsl:text>no refentry/refmeta/manvolnum</xsl:text>
 264             </xsl:with-param>
 265           </xsl:call-template>
 266           <xsl:call-template name="log.message">
 267             <xsl:with-param name="level">Note</xsl:with-param>
 268             <xsl:with-param name="source" select="$refname"/>
 269             <xsl:with-param name="context-desc">meta manvol</xsl:with-param>
 270             <xsl:with-param name="message">
 271               <xsl:text>see http://www.docbook.org/tdg5/en/html/manvolnum</xsl:text>
 272             </xsl:with-param>
 273           </xsl:call-template>
 274         </xsl:if>
 275       </xsl:if>
 276       <xsl:choose>
 277         <xsl:when test=".//d:funcsynopsis">
 278           <xsl:if test="$quiet = 0">
 279             <xsl:if test="$refentry.meta.get.quietly = 0">
 280               <xsl:call-template name="log.message">
 281                 <xsl:with-param name="level">Note</xsl:with-param>
 282                 <xsl:with-param name="source" select="$refname"/>
 283                 <xsl:with-param name="context-desc">meta manvol</xsl:with-param>
 284                 <xsl:with-param name="message">
 285                   <xsl:text>Setting man section to 3</xsl:text>
 286                 </xsl:with-param>
 287               </xsl:call-template>
 288             </xsl:if>
 289           </xsl:if>
 290           <xsl:text>3</xsl:text>
 291         </xsl:when>
 292         <xsl:otherwise>
 293           <xsl:text>1</xsl:text>
 294         </xsl:otherwise>
 295       </xsl:choose>
 296     </xsl:otherwise>
 297   </xsl:choose>
 298 </xsl:template>
 299
 300 <!-- ==================================================================== -->
 301 <doc:template name="get.refentry.date" xmlns="">
 302   <refpurpose>Gets date metadata for a refentry</refpurpose>
 303   <refdescription id="get.refentry.date-desc">
 304     <para>The <literal>man(7)</literal> man page describes this as "the
 305     date of the last revision". If we cannot find a date in the source, we
 306     generate one.</para>
 307   </refdescription>
 308   <refparameter id="get.refentry.date-params">
 309     <variablelist>
 310       <varlistentry>
 311         <term>refname</term>
 312         <listitem>
 313           <para>The first <tag>refname</tag> in the refentry</para>
 314         </listitem>
 315       </varlistentry>
 316       <varlistentry>
 317         <term>info</term>
 318         <listitem>
 319           <para>A set of info nodes (from a <tag>refentry</tag>
 320           element and its ancestors)</para>
 321         </listitem>
 322       </varlistentry>
 323       <varlistentry>
 324         <term>prefs</term>
 325         <listitem>
 326           <para>A node containing users preferences (from global stylesheet parameters)</para>
 327         </listitem>
 328       </varlistentry>
 329     </variablelist>
 330   </refparameter>
 331   <refreturn id="get.refentry.date-returns">
 332     <para>Returns a <tag>date</tag> node.</para>
 333   </refreturn>
 334 </doc:template>
 335 <xsl:template name="get.refentry.date">
 336   <xsl:param name="refname"/>
 337   <xsl:param name="info"/>
 338   <xsl:param name="prefs"/>
 339   <xsl:variable name="Date">
 340     <xsl:choose>
 341       <!-- * if profiling is enabled for date, and the date -->
 342       <!-- * profile is non-empty, use it -->
 343       <xsl:when test="not($prefs/@profileEnabled = 0) and
 344                       not($prefs/@profile = '')">
 345         <xsl:call-template name="evaluate.info.profile">
 346           <xsl:with-param name="profile" select="$prefs/@profile"/>
 347           <xsl:with-param name="info" select="$info"/>
 348         </xsl:call-template>
 349       </xsl:when>
 350       <xsl:otherwise>
 351         <!-- * either profiling is not enabled for date, or the-->
 352         <!-- * date profile is empty, so we need to look for date -->
 353         <!-- * in *info -->
 354         <xsl:choose>
 355           <!-- * look for date or pubdate in *info -->
 356           <xsl:when test="$info/d:date/node()
 357                           |$info/d:pubdate/node()">
 358             <xsl:apply-templates
 359                 select="(($info[d:date])[last()]/d:date)[1]|
 360                         (($info[d:pubdate])[last()]/d:pubdate)[1]"/>
 361           </xsl:when>
 362           <xsl:otherwise>
 363             <!-- * found no Date or Pubdate -->
 364           </xsl:otherwise>
 365         </xsl:choose>
 366       </xsl:otherwise>
 367     </xsl:choose>
 368   </xsl:variable>
 369   <xsl:choose>
 370     <xsl:when test="not($Date = '')">
 371       <xsl:value-of select="$Date"/>
 372     </xsl:when>
 373     <!-- * We couldn't find a date, so we generate a date. -->
 374     <!-- * And we make it an appropriately localized date. -->
 375     <xsl:otherwise>
 376       <!-- * The following block is commented out because: -->
 377       <!-- *  -->
 378       <!-- * - having a missing date in the source doesn’t result in -->
 379       <!-- *   any information being missing from the generated man -->
 380       <!-- *   page (since we generate the needed date) -->
 381       <!-- *  -->
 382       <!-- * - experience has shown the many users omit the date -->
 383       <!-- *   intentionally, because they want to be it generated -->
 384       <!-- *  -->
 385       <!-- * - in practice it’s not really a condition that most users -->
 386       <!-- *   want reported to them -->
 387       <!-- *  -->
 388       <!-- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
 389       <!-- * <xsl:if test="$refentry.meta.get.quietly = 0"> -->
 390         <!-- * <xsl:call-template name="log.message"> -->
 391           <!-- * <xsl:with-param name="level">Note</xsl:with-param> -->
 392           <!-- * <xsl:with-param name="source" select="$refname"/> -->
 393           <!-- * <xsl:with-param name="context-desc">meta date</xsl:with-param> -->
 394           <!-- * <xsl:with-param name="message"> -->
 395             <!-- * <xsl:text>no date; using generated date</xsl:text> -->
 396           <!-- * </xsl:with-param> -->
 397         <!-- * </xsl:call-template> -->
 398         <!-- * <xsl:call-template name="log.message"> -->
 399           <!-- * <xsl:with-param name="level">Note</xsl:with-param> -->
 400           <!-- * <xsl:with-param name="source" select="$refname"/> -->
 401           <!-- * <xsl:with-param name="context-desc">meta date</xsl:with-param> -->
 402           <!-- * <xsl:with-param name="message"> -->
 403             <!-- * <xsl:text>see http://www.docbook.org/tdg5/en/html/date</xsl:text> -->
 404           <!-- * </xsl:with-param> -->
 405         <!-- * </xsl:call-template> -->
 406       <!-- * </xsl:if> -->
 407       <!-- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
 408       <xsl:call-template name="datetime.format">
 409         <xsl:with-param name="date">
 410           <xsl:choose>
 411             <xsl:when test="function-available('date:date-time')">
 412               <xsl:value-of select="date:date-time()"/>
 413             </xsl:when>
 414             <xsl:when test="function-available('date:dateTime')">
 415               <!-- Xalan quirk -->
 416               <xsl:value-of select="date:dateTime()"/>
 417             </xsl:when>
 418           </xsl:choose>
 419         </xsl:with-param>
 420         <xsl:with-param name="format">
 421           <xsl:call-template name="gentext.template">
 422             <xsl:with-param name="context" select="'datetime'"/>
 423             <xsl:with-param name="name" select="'format'"/>
 424           </xsl:call-template>
 425         </xsl:with-param>
 426       </xsl:call-template>
 427     </xsl:otherwise>
 428   </xsl:choose>
 429 </xsl:template>
 430
 431 <!-- ==================================================================== -->
 432 <doc:template name="get.refentry.source" xmlns="">
 433   <refpurpose>Gets source metadata for a refentry</refpurpose>
 434   <refdescription id="get.refentry.source-desc">
 435     <para>The <literal>man(7)</literal> man page describes this as "the
 436     source of the command", and provides the following examples:
 437     <itemizedlist>
 438       <listitem>
 439         <para>For binaries, use something like: GNU, NET-2, SLS
 440         Distribution, MCC Distribution.</para>
 441       </listitem>
 442       <listitem>
 443         <para>For system calls, use the version of the kernel that you are
 444         currently looking at: Linux 0.99.11.</para>
 445       </listitem>
 446       <listitem>
 447         <para>For library calls, use the source of the function: GNU, BSD
 448         4.3, Linux DLL 4.4.1.</para>
 449       </listitem>
 450     </itemizedlist>
 451     </para>
 452
 453     <para>The <literal>solbook(5)</literal> man page describes
 454     something very much like what <literal>man(7)</literal> calls
 455     "source", except that <literal>solbook(5)</literal> names it
 456     "software" and describes it like this:
 457     <blockquote>
 458       <para>This is the name of the software product that the topic
 459       discussed on the reference page belongs to. For example UNIX
 460       commands are part of the <literal>SunOS x.x</literal>
 461       release.</para>
 462     </blockquote>
 463     </para>
 464
 465     <para>In practice, there are many pages that simply have a version
 466     number in the "source" field. So, it looks like what we have is a
 467     two-part field,
 468     <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>,
 469     where:
 470     <variablelist>
 471       <varlistentry>
 472         <term>Name</term>
 473         <listitem>
 474           <para>product name (e.g., BSD) or org. name (e.g., GNU)</para>
 475         </listitem>
 476       </varlistentry>
 477       <varlistentry>
 478         <term>Version</term>
 479         <listitem>
 480           <para>version name</para>
 481         </listitem>
 482       </varlistentry>
 483     </variablelist>
 484     Each part is optional. If the <replaceable>Name</replaceable> is a
 485     product name, then the <replaceable>Version</replaceable> is probably
 486     the version of the product. Or there may be no
 487     <replaceable>Name</replaceable>, in which case, if there is a
 488     <replaceable>Version</replaceable>, it is probably the version of the
 489     item itself, not the product it is part of. Or, if the
 490     <replaceable>Name</replaceable> is an organization name, then there
 491     probably will be no <replaceable>Version</replaceable>.
 492     </para>
 493   </refdescription>
 494   <refparameter id="get.refentry.source-params">
 495     <variablelist>
 496       <varlistentry>
 497         <term>refname</term>
 498         <listitem>
 499           <para>The first <tag>refname</tag> in the refentry</para>
 500         </listitem>
 501       </varlistentry>
 502       <varlistentry>
 503         <term>info</term>
 504         <listitem>
 505           <para>A set of info nodes (from a <tag>refentry</tag>
 506           element and its ancestors)</para>
 507         </listitem>
 508       </varlistentry>
 509       <varlistentry>
 510         <term>prefs</term>
 511         <listitem>
 512           <para>A node containing users preferences (from global
 513           stylesheet parameters)</para>
 514         </listitem>
 515       </varlistentry>
 516     </variablelist>
 517   </refparameter>
 518   <refreturn id="get.refentry.source-returns">
 519     <para>Returns a <tag>source</tag> node.</para>
 520   </refreturn>
 521 </doc:template>
 522 <xsl:template name="get.refentry.source">
 523   <xsl:param name="refname"/>
 524   <xsl:param name="info"/>
 525   <xsl:param name="prefs"/>
 526   <xsl:variable name="Name">
 527     <xsl:if test="$prefs/Name/@suppress = 0">
 528       <xsl:call-template name="get.refentry.source.name">
 529         <xsl:with-param name="info" select="$info"/>
 530         <xsl:with-param name="refname" select="$refname"/>
 531         <xsl:with-param name="prefs" select="$prefs/Name"/>
 532       </xsl:call-template>
 533     </xsl:if>
 534   </xsl:variable>
 535   <xsl:variable name="Version">
 536     <xsl:if test="$prefs/Version/@suppress = 0">
 537       <xsl:call-template name="get.refentry.version">
 538         <xsl:with-param name="info" select="$info"/>
 539         <xsl:with-param name="refname" select="$refname"/>
 540         <xsl:with-param name="prefs" select="$prefs/Version"/>
 541       </xsl:call-template>
 542     </xsl:if>
 543   </xsl:variable>
 544   <xsl:choose>
 545     <!-- * if we have a Name and/or Version, use either or both -->
 546     <!-- * of those, in the form "Name Version" or just "Name" -->
 547     <!-- * or just "Version" -->
 548     <xsl:when test="not($Name = '') or not($Version = '')">
 549       <xsl:choose>
 550         <xsl:when test="not($Name = '') and not($Version = '')">
 551           <xsl:copy-of select="$Name"/>
 552           <xsl:text> </xsl:text>
 553         </xsl:when>
 554         <xsl:otherwise>
 555           <xsl:copy-of select="$Name"/>
 556         </xsl:otherwise>
 557       </xsl:choose>
 558       <xsl:copy-of select="$Version"/>
 559     </xsl:when>
 560     <!-- * if no Name and no Version, use fallback (if any) -->
 561     <xsl:when test="not($prefs/@fallback = '')">
 562       <xsl:variable name="source.fallback">
 563         <xsl:call-template name="evaluate.info.profile">
 564           <xsl:with-param name="profile" select="$prefs/@fallback"/>
 565           <xsl:with-param name="info" select="$info"/>
 566         </xsl:call-template>
 567       </xsl:variable>
 568       <!-- * At this point, we know that we don't have properly marked-up -->
 569       <!-- * source metadata, so even if we do have source fallback -->
 570       <!-- * content, we still report to the user that it should be -->
 571       <!-- * marked up properly instead. -->
 572       <xsl:if test="$refentry.meta.get.quietly = 0">
 573         <xsl:call-template name="report.missing.source.name">
 574           <xsl:with-param name="refname" select="$refname"/>
 575         </xsl:call-template>
 576         <xsl:call-template name="report.missing.version">
 577           <xsl:with-param name="refname" select="$refname"/>
 578         </xsl:call-template>
 579       </xsl:if>
 580       <xsl:choose>
 581         <xsl:when test="not($source.fallback = '')">
 582           <xsl:value-of select="$source.fallback"/>
 583           <xsl:if test="$refentry.meta.get.quietly = 0">
 584             <xsl:call-template name="log.message">
 585               <xsl:with-param name="level">Warn</xsl:with-param>
 586               <xsl:with-param name="source" select="$refname"/>
 587               <xsl:with-param name="context-desc">meta source</xsl:with-param>
 588               <xsl:with-param name="message">
 589                 <xsl:text>using</xsl:text>
 590                 <xsl:text> "</xsl:text>
 591                 <xsl:value-of select="$source.fallback"/>
 592                 <xsl:text>" </xsl:text>
 593                 <xsl:text>for "source"</xsl:text>
 594               </xsl:with-param>
 595             </xsl:call-template>
 596           </xsl:if>
 597         </xsl:when>
 598         <xsl:otherwise>
 599           <!-- * we have no Name, no Version, and no fallback content, so -->
 600           <!-- * insert a fixme -->
 601           <xsl:text>[FIXME: source]</xsl:text>
 602           <xsl:if test="$refentry.meta.get.quietly = 0">
 603             <xsl:call-template name="log.message">
 604               <xsl:with-param name="level">Warn</xsl:with-param>
 605               <xsl:with-param name="source" select="$refname"/>
 606               <xsl:with-param name="context-desc">meta source</xsl:with-param>
 607               <xsl:with-param name="message">
 608                 <xsl:text>no fallback for source, so inserted a fixme</xsl:text>
 609               </xsl:with-param>
 610             </xsl:call-template>
 611           </xsl:if>
 612         </xsl:otherwise>
 613       </xsl:choose>
 614     </xsl:when>
 615     <xsl:otherwise>
 616       <!-- * we have no Name, no Version, and no fallback given, so -->
 617       <!-- * insert a fixme -->
 618       <xsl:text>[FIXME: source]</xsl:text>
 619       <xsl:if test="$refentry.meta.get.quietly = 0">
 620         <xsl:call-template name="log.message">
 621           <xsl:with-param name="level">Warn</xsl:with-param>
 622           <xsl:with-param name="source" select="$refname"/>
 623           <xsl:with-param name="context-desc">meta source</xsl:with-param>
 624           <xsl:with-param name="message">
 625             <xsl:text>no source fallback given, so inserted a fixme</xsl:text>
 626           </xsl:with-param>
 627         </xsl:call-template>
 628       </xsl:if>
 629     </xsl:otherwise>
 630   </xsl:choose>
 631 </xsl:template>
 632
 633 <!-- ==================================================================== -->
 634 <doc:template name="get.refentry.source.name" xmlns="">
 635   <refpurpose>Gets source-name metadata for a refentry</refpurpose>
 636   <refdescription id="get.refentry.source.name-desc">
 637     <para>A "source name" is one part of a (potentially) two-part
 638     <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>
 639     source field. For more details, see the documentation for the
 640     <function>get.refentry.source</function> template.</para>
 641   </refdescription>
 642   <refparameter id="get.refentry.source.name-params">
 643     <variablelist>
 644       <varlistentry>
 645         <term>refname</term>
 646         <listitem>
 647           <para>The first <tag>refname</tag> in the refentry</para>
 648         </listitem>
 649       </varlistentry>
 650       <varlistentry>
 651         <term>info</term>
 652         <listitem>
 653           <para>A set of info nodes (from a <tag>refentry</tag>
 654           element and its ancestors)</para>
 655         </listitem>
 656       </varlistentry>
 657       <varlistentry>
 658         <term>prefs</term>
 659         <listitem>
 660           <para>A node containing users preferences (from global
 661           stylesheet parameters)</para>
 662         </listitem>
 663       </varlistentry>
 664     </variablelist>
 665   </refparameter>
 666   <refreturn id="get.refentry.source.name-returns">
 667     <para>Depending on what output method is used for the
 668   current stylesheet, either returns a text node or possibly an element
 669   node, containing "source name" data.</para>
 670   </refreturn>
 671 </doc:template>
 672 <xsl:template name="get.refentry.source.name">
 673   <xsl:param name="refname"/>
 674   <xsl:param name="info"/>
 675   <xsl:param name="prefs"/>
 676   <xsl:choose>
 677     <!-- * if profiling is enabled for source.name, and the -->
 678     <!-- * source.name profile is non-empty, use it -->
 679     <xsl:when test="not($prefs/@profileEnabled = 0) and
 680                     not($prefs/@profile = '')">
 681       <xsl:call-template name="evaluate.info.profile">
 682         <xsl:with-param name="profile" select="$prefs/@profile"/>
 683         <xsl:with-param name="info" select="$info"/>
 684       </xsl:call-template>
 685     </xsl:when>
 686     <xsl:otherwise>
 687       <!-- * either profiling for source.name is not enabled, or-->
 688       <!-- * the source.name profile is empty; so we need to look -->
 689       <!-- * for a name to use -->
 690       <xsl:choose>
 691         <xsl:when test="d:refmeta/d:refmiscinfo[@class = 'source' or @class = 'software']">
 692           <xsl:apply-templates
 693               select="d:refmeta/d:refmiscinfo[@class = 'source' or @class='software'][1]/node()"/>
 694         </xsl:when>
 695         <xsl:otherwise>
 696           <xsl:choose>
 697             <xsl:when test="$info/d:productname">
 698               <xsl:call-template name="set.refentry.metadata">
 699                 <xsl:with-param name="refname" select="$refname"/>
 700                 <xsl:with-param
 701                     name="info"
 702                     select="($info[d:productname])[last()]"/>
 703                 <xsl:with-param
 704                     name="contents"
 705                     select="(($info[d:productname])[last()]/d:productname)[1]"/>
 706                 <xsl:with-param name="context">source</xsl:with-param>
 707               </xsl:call-template>
 708             </xsl:when>
 709             <xsl:when test="$info/d:corpname">
 710               <xsl:call-template name="set.refentry.metadata">
 711                 <xsl:with-param name="refname" select="$refname"/>
 712                 <xsl:with-param
 713                     name="info"
 714                     select="($info[d:corpname])[last()]"/>
 715                 <xsl:with-param
 716                     name="contents"
 717                     select="(($info[d:corpname])[last()]/d:corpname)[1]"/>
 718                 <xsl:with-param name="context">source</xsl:with-param>
 719                 <xsl:with-param name="preferred">productname</xsl:with-param>
 720               </xsl:call-template>
 721             </xsl:when>
 722             <xsl:when test="$info/d:corpcredit">
 723               <xsl:call-template name="set.refentry.metadata">
 724                 <xsl:with-param name="refname" select="$refname"/>
 725                 <xsl:with-param
 726                     name="info"
 727                     select="($info[d:corpcredit])[last()]"/>
 728                 <xsl:with-param
 729                     name="contents"
 730                     select="(($info[d:corpcredit])[last()]/d:corpcredit)[1]"/>
 731                 <xsl:with-param name="context">source</xsl:with-param>
 732                 <xsl:with-param name="preferred">productname</xsl:with-param>
 733               </xsl:call-template>
 734             </xsl:when>
 735             <xsl:when test="$info/d:corpauthor">
 736               <xsl:call-template name="set.refentry.metadata">
 737                 <xsl:with-param name="refname" select="$refname"/>
 738                 <xsl:with-param
 739                     name="info"
 740                     select="($info[d:corpauthor])[last()]"/>
 741                 <xsl:with-param
 742                     name="contents"
 743                     select="(($info[d:corpauthor])[last()]/d:corpauthor)[1]"/>
 744                 <xsl:with-param name="context">source</xsl:with-param>
 745                 <xsl:with-param name="preferred">productname</xsl:with-param>
 746               </xsl:call-template>
 747             </xsl:when>
 748             <xsl:when test="$info//d:orgname">
 749               <xsl:call-template name="set.refentry.metadata">
 750                 <xsl:with-param name="refname" select="$refname"/>
 751                 <xsl:with-param
 752                     name="info"
 753                     select="($info[//d:orgname])[last()]"/>
 754                 <xsl:with-param
 755                     name="contents"
 756                     select="(($info[//d:orgname])[last()]//d:orgname)[1]"/>
 757                 <xsl:with-param name="context">source</xsl:with-param>
 758                 <xsl:with-param name="preferred">productname</xsl:with-param>
 759               </xsl:call-template>
 760             </xsl:when>
 761             <xsl:when test="$info//d:publishername">
 762               <xsl:call-template name="set.refentry.metadata">
 763                 <xsl:with-param name="refname" select="$refname"/>
 764                 <xsl:with-param
 765                     name="info"
 766                     select="($info[//d:publishername])[last()]"/>
 767                 <xsl:with-param
 768                     name="contents"
 769                     select="(($info[//d:publishername])[last()]//d:publishername)[1]"/>
 770                 <xsl:with-param name="context">source</xsl:with-param>
 771                 <xsl:with-param name="preferred">productname</xsl:with-param>
 772               </xsl:call-template>
 773             </xsl:when>
 774           </xsl:choose>
 775         </xsl:otherwise>
 776       </xsl:choose>
 777     </xsl:otherwise>
 778   </xsl:choose>
 779 </xsl:template>
 780
 781 <xsl:template name="report.missing.source.name">
 782   <xsl:param name="refname"/>
 783   <xsl:call-template name="log.message">
 784     <xsl:with-param name="level">Note</xsl:with-param>
 785     <xsl:with-param name="source" select="$refname"/>
 786     <xsl:with-param name="context-desc">meta source</xsl:with-param>
 787     <xsl:with-param name="message">
 788       <xsl:text>no *info/productname or alternative</xsl:text>
 789     </xsl:with-param>
 790   </xsl:call-template>
 791   <xsl:call-template name="log.message">
 792     <xsl:with-param name="level">Note</xsl:with-param>
 793     <xsl:with-param name="source" select="$refname"/>
 794     <xsl:with-param name="context-desc">meta source</xsl:with-param>
 795     <xsl:with-param name="message">
 796       <xsl:text>see http://www.docbook.org/tdg5/en/html/productname</xsl:text>
 797     </xsl:with-param>
 798   </xsl:call-template>
 799   <xsl:call-template name="log.message">
 800     <xsl:with-param name="level">Note</xsl:with-param>
 801     <xsl:with-param name="source" select="$refname"/>
 802     <xsl:with-param name="context-desc">meta source</xsl:with-param>
 803     <xsl:with-param name="message">
 804       <xsl:text>no refentry/refmeta/refmiscinfo@class=source</xsl:text>
 805     </xsl:with-param>
 806   </xsl:call-template>
 807   <xsl:call-template name="log.message">
 808     <xsl:with-param name="level">Note</xsl:with-param>
 809     <xsl:with-param name="source" select="$refname"/>
 810     <xsl:with-param name="context-desc">meta source</xsl:with-param>
 811     <xsl:with-param name="message">
 812       <xsl:text>see http://www.docbook.org/tdg5/en/html/refmiscinfo</xsl:text>
 813     </xsl:with-param>
 814   </xsl:call-template>
 815 </xsl:template>
 816
 817 <!-- ==================================================================== -->
 818 <doc:template name="get.refentry.version" xmlns="">
 819   <refpurpose>Gets version metadata for a refentry</refpurpose>
 820   <refdescription id="get.refentry.version-desc">
 821     <para>A "version" is one part of a (potentially) two-part
 822     <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>
 823     source field. For more details, see the documentation for the
 824     <function>get.refentry.source</function> template.</para>
 825   </refdescription>
 826   <refparameter id="get.refentry.version-params">
 827     <variablelist>
 828       <varlistentry>
 829         <term>refname</term>
 830         <listitem>
 831           <para>The first <tag>refname</tag> in the refentry</para>
 832         </listitem>
 833       </varlistentry>
 834       <varlistentry>
 835         <term>info</term>
 836         <listitem>
 837           <para>A set of info nodes (from a <tag>refentry</tag>
 838           element and its ancestors)</para>
 839         </listitem>
 840       </varlistentry>
 841       <varlistentry>
 842         <term>prefs</term>
 843         <listitem>
 844           <para>A node containing users preferences (from global
 845           stylesheet parameters)</para>
 846         </listitem>
 847       </varlistentry>
 848     </variablelist>
 849   </refparameter>
 850   <refreturn id="get.refentry.version-returns">
 851     <para>Depending on what output method is used for the
 852   current stylesheet, either returns a text node or possibly an element
 853   node, containing "version" data.</para>
 854   </refreturn>
 855 </doc:template>
 856 <xsl:template name="get.refentry.version">
 857   <xsl:param name="refname"/>
 858   <xsl:param name="info"/>
 859   <xsl:param name="prefs"/>
 860   <xsl:choose>
 861     <!-- * if profiling is enabled for version, and the -->
 862     <!-- * version profile is non-empty, use it -->
 863     <xsl:when test="not($prefs/@profileEnabled = 0) and
 864                     not($prefs/@profile = '')">
 865       <xsl:call-template name="evaluate.info.profile">
 866         <xsl:with-param name="profile" select="$prefs/@profile"/>
 867         <xsl:with-param name="info" select="$info"/>
 868       </xsl:call-template>
 869     </xsl:when>
 870     <xsl:otherwise>
 871       <!-- * either profiling for source.name is not enabled, or-->
 872       <!-- * the source.name profile is empty; so we need to look -->
 873       <!-- * for a name to use -->
 874       <xsl:choose>
 875         <xsl:when test="d:refmeta/d:refmiscinfo[@class = 'version']">
 876           <xsl:apply-templates
 877               select="d:refmeta/d:refmiscinfo[@class = 'version'][1]/node()"/>
 878         </xsl:when>
 879         <xsl:otherwise>
 880           <xsl:choose>
 881             <xsl:when test="$info/d:productnumber">
 882               <xsl:call-template name="set.refentry.metadata">
 883                 <xsl:with-param name="refname" select="$refname"/>
 884                 <xsl:with-param
 885                     name="info"
 886                     select="($info[d:productnumber])[last()]"/>
 887                 <xsl:with-param
 888                     name="contents"
 889                     select="(($info[d:productnumber])[last()]/d:productnumber)[1]"/>
 890                 <xsl:with-param name="context">version</xsl:with-param>
 891               </xsl:call-template>
 892             </xsl:when>
 893             <xsl:when test="$info/d:edition">
 894               <xsl:call-template name="set.refentry.metadata">
 895                 <xsl:with-param name="refname" select="$refname"/>
 896                 <xsl:with-param
 897                     name="info"
 898                     select="($info[d:edition])[last()]"/>
 899                 <xsl:with-param
 900                     name="contents"
 901                     select="(($info[d:edition])[last()]/d:edition)[1]"/>
 902                 <xsl:with-param name="context">version</xsl:with-param>
 903                 <xsl:with-param name="preferred">productnumber</xsl:with-param>
 904               </xsl:call-template>
 905             </xsl:when>
 906             <xsl:when test="$info/d:releaseinfo">
 907               <xsl:call-template name="set.refentry.metadata">
 908                 <xsl:with-param name="refname" select="$refname"/>
 909                 <xsl:with-param
 910                     name="info"
 911                     select="($info[d:releaseinfo])[last()]"/>
 912                 <xsl:with-param
 913                     name="contents"
 914                     select="(($info[d:releaseinfo])[last()]/d:releaseinfo)[1]"/>
 915                 <xsl:with-param name="context">version</xsl:with-param>
 916                 <xsl:with-param name="preferred">productnumber</xsl:with-param>
 917               </xsl:call-template>
 918             </xsl:when>
 919           </xsl:choose>
 920         </xsl:otherwise>
 921       </xsl:choose>
 922     </xsl:otherwise>
 923   </xsl:choose>
 924 </xsl:template>
 925
 926 <xsl:template name="report.missing.version">
 927   <xsl:param name="refname"/>
 928   <xsl:call-template name="log.message">
 929     <xsl:with-param name="level">Note</xsl:with-param>
 930     <xsl:with-param name="source" select="$refname"/>
 931     <xsl:with-param name="context-desc">meta version</xsl:with-param>
 932     <xsl:with-param name="message">
 933       <xsl:text>no *info/productnumber or alternative</xsl:text>
 934     </xsl:with-param>
 935   </xsl:call-template>
 936   <xsl:call-template name="log.message">
 937     <xsl:with-param name="level">Note</xsl:with-param>
 938     <xsl:with-param name="source" select="$refname"/>
 939     <xsl:with-param name="context-desc">meta version</xsl:with-param>
 940     <xsl:with-param name="message">
 941       <xsl:text>see http://www.docbook.org/tdg5/en/html/productnumber</xsl:text>
 942     </xsl:with-param>
 943   </xsl:call-template>
 944   <xsl:call-template name="log.message">
 945     <xsl:with-param name="level">Note</xsl:with-param>
 946     <xsl:with-param name="source" select="$refname"/>
 947     <xsl:with-param name="context-desc">meta version</xsl:with-param>
 948     <xsl:with-param name="message">
 949       <xsl:text>no refentry/refmeta/refmiscinfo@class=version</xsl:text>
 950     </xsl:with-param>
 951   </xsl:call-template>
 952   <xsl:call-template name="log.message">
 953     <xsl:with-param name="level">Note</xsl:with-param>
 954     <xsl:with-param name="source" select="$refname"/>
 955     <xsl:with-param name="context-desc">meta version</xsl:with-param>
 956     <xsl:with-param name="message">
 957       <xsl:text>see http://www.docbook.org/tdg5/en/html/refmiscinfo</xsl:text>
 958     </xsl:with-param>
 959   </xsl:call-template>
 960 </xsl:template>
 961
 962 <!-- ==================================================================== -->
 963 <doc:template name="get.refentry.manual" xmlns="">
 964   <refpurpose>Gets source metadata for a refentry</refpurpose>
 965   <refdescription id="get.refentry.manual-desc">
 966     <para>The <literal>man(7)</literal> man page describes this as "the
 967     title of the manual (e.g., <citetitle>Linux Programmer's
 968     Manual</citetitle>)". Here are some examples from existing man pages:
 969     <itemizedlist>
 970       <listitem>
 971         <para><citetitle>dpkg utilities</citetitle>
 972         (<command>dpkg-name</command>)</para>
 973       </listitem>
 974       <listitem>
 975         <para><citetitle>User Contributed Perl Documentation</citetitle>
 976         (<command>GET</command>)</para>
 977       </listitem>
 978       <listitem>
 979         <para><citetitle>GNU Development Tools</citetitle>
 980         (<command>ld</command>)</para>
 981       </listitem>
 982       <listitem>
 983         <para><citetitle>Emperor Norton Utilities</citetitle>
 984         (<command>ddate</command>)</para>
 985       </listitem>
 986       <listitem>
 987         <para><citetitle>Debian GNU/Linux manual</citetitle>
 988         (<command>faked</command>)</para>
 989       </listitem>
 990       <listitem>
 991         <para><citetitle>GIMP Manual Pages</citetitle>
 992         (<command>gimp</command>)</para>
 993       </listitem>
 994       <listitem>
 995         <para><citetitle>KDOC Documentation System</citetitle>
 996         (<command>qt2kdoc</command>)</para>
 997       </listitem>
 998     </itemizedlist>
 999     </para>
1000
1001     <para>The <literal>solbook(5)</literal> man page describes
1002     something very much like what <literal>man(7)</literal> calls
1003     "manual", except that <literal>solbook(5)</literal> names it
1004     "sectdesc" and describes it like this:
1005     <blockquote>
1006       <para>This is the section title of the reference page; for
1007       example <literal>User Commands</literal>.</para>
1008     </blockquote>
1009     </para>
1010
1011   </refdescription>
1012   <refparameter id="get.refentry.manual-params">
1013     <variablelist>
1014       <varlistentry>
1015         <term>refname</term>
1016         <listitem>
1017           <para>The first <tag>refname</tag> in the refentry</para>
1018         </listitem>
1019       </varlistentry>
1020       <varlistentry>
1021         <term>info</term>
1022         <listitem>
1023           <para>A set of info nodes (from a <tag>refentry</tag>
1024           element and its ancestors)</para>
1025         </listitem>
1026       </varlistentry>
1027       <varlistentry>
1028         <term>prefs</term>
1029         <listitem>
1030           <para>A node containing users preferences (from global
1031           stylesheet parameters)</para>
1032         </listitem>
1033       </varlistentry>
1034     </variablelist>
1035   </refparameter>
1036   <refreturn id="get.refentry.manual-returns">
1037     <para>Returns a <tag>manual</tag> node.</para>
1038   </refreturn>
1039 </doc:template>
1040 <xsl:template name="get.refentry.manual">
1041   <xsl:param name="refname"/>
1042   <xsl:param name="info"/>
1043   <xsl:param name="prefs"/>
1044   <xsl:variable name="Manual">
1045     <xsl:choose>
1046       <!-- * if profiling is enabled for manual, and the manual -->
1047       <!-- * profile is non-empty, use it -->
1048       <xsl:when test="not($prefs/@profileEnabled = 0) and
1049                       not($prefs/@profile = '')">
1050         <xsl:call-template name="evaluate.info.profile">
1051           <xsl:with-param name="profile" select="$prefs/@profile"/>
1052           <xsl:with-param name="info" select="$info"/>
1053         </xsl:call-template>
1054       </xsl:when>
1055       <xsl:otherwise>
1056         <xsl:choose>
1057           <xsl:when test="d:refmeta/d:refmiscinfo[@class = 'manual' or @class = 'sectdesc']">
1058             <xsl:apply-templates
1059                 select="d:refmeta/d:refmiscinfo[@class = 'manual' or @class = 'sectdesc'][1]/node()"/>
1060           </xsl:when>
1061           <xsl:otherwise>
1062             <!-- * only in the case of choosing appropriate -->
1063             <!-- * "manual" content do we select the furthest -->
1064             <!-- * (first) matching element instead of the -->
1065             <!-- * closest (last) matching one -->
1066             <xsl:choose>
1067               <xsl:when test="ancestor::*/d:title">
1068                 <xsl:call-template name="set.refentry.metadata">
1069                   <xsl:with-param name="refname" select="$refname"/>
1070                   <xsl:with-param
1071                       name="info"
1072                       select="(ancestor::*[d:title])[1]"/>
1073                   <xsl:with-param
1074                       name="contents"
1075                       select="(ancestor::*[d:title])[1]/d:title"/>
1076                   <xsl:with-param name="context">manual</xsl:with-param>
1077                 </xsl:call-template>
1078               </xsl:when>
1079               <xsl:when test="$info/d:title">
1080                 <xsl:call-template name="set.refentry.metadata">
1081                   <xsl:with-param name="refname" select="$refname"/>
1082                   <xsl:with-param
1083                       name="info"
1084                       select="($info[d:title])[1]"/>
1085                   <xsl:with-param
1086                       name="contents"
1087                       select="(($info[d:title])[1]/d:title)[1]"/>
1088                   <xsl:with-param name="context">manual</xsl:with-param>
1089                 </xsl:call-template>
1090               </xsl:when>
1091               <xsl:otherwise>
1092               </xsl:otherwise>
1093             </xsl:choose>
1094           </xsl:otherwise>
1095         </xsl:choose>
1096       </xsl:otherwise>
1097     </xsl:choose>
1098   </xsl:variable>
1099   <xsl:choose>
1100     <xsl:when test="not($Manual = '')">
1101       <xsl:copy-of select="$Manual"/>
1102     </xsl:when>
1103     <!-- * if no Manual, use contents of specified fallback (if any) -->
1104     <xsl:when test="not($prefs/@fallback = '')">
1105       <xsl:variable name="manual.fallback">
1106         <xsl:call-template name="evaluate.info.profile">
1107           <xsl:with-param name="profile" select="$prefs/@fallback"/>
1108           <xsl:with-param name="info" select="$info"/>
1109         </xsl:call-template>
1110       </xsl:variable>
1111       <!-- * At this point, we know that we don't have properly marked-up -->
1112       <!-- * manual metadata, so even if we do have manual fallback -->
1113       <!-- * content, we still report to the user that it should be -->
1114       <!-- * marked up properly instead. -->
1115       <xsl:if test="$refentry.meta.get.quietly = 0">
1116         <xsl:call-template name="report.missing.manual">
1117           <xsl:with-param name="refname" select="$refname"/>
1118         </xsl:call-template>
1119       </xsl:if>
1120       <xsl:choose>
1121         <xsl:when test="not($manual.fallback = '')">
1122           <xsl:value-of select="$manual.fallback"/>
1123           <xsl:if test="$refentry.meta.get.quietly = 0">
1124             <xsl:call-template name="log.message">
1125               <xsl:with-param name="level">Warn</xsl:with-param>
1126               <xsl:with-param name="source" select="$refname"/>
1127               <xsl:with-param name="context-desc">meta manual</xsl:with-param>
1128               <xsl:with-param name="message">
1129                 <xsl:text>using</xsl:text>
1130                 <xsl:text> "</xsl:text>
1131                 <xsl:value-of select="$manual.fallback"/>
1132                 <xsl:text>" </xsl:text>
1133                 <xsl:text>for "manual"</xsl:text>
1134               </xsl:with-param>
1135             </xsl:call-template>
1136           </xsl:if>
1137         </xsl:when>
1138         <xsl:otherwise>
1139           <!-- * we have nothing appropriate to use for manual, and no fallback -->
1140           <!-- * content, so report insert a fixme -->
1141           <xsl:text>[FIXME: manual]</xsl:text>
1142           <xsl:if test="$refentry.meta.get.quietly = 0">
1143             <xsl:call-template name="log.message">
1144               <xsl:with-param name="level">Warn</xsl:with-param>
1145               <xsl:with-param name="source" select="$refname"/>
1146               <xsl:with-param name="context-desc">meta manual</xsl:with-param>
1147               <xsl:with-param name="message">
1148                 <xsl:text>no fallback for manual, so inserted a fixme</xsl:text>
1149               </xsl:with-param>
1150             </xsl:call-template>
1151           </xsl:if>
1152         </xsl:otherwise>
1153       </xsl:choose>
1154     </xsl:when>
1155     <xsl:otherwise>
1156       <!-- * we have nothing appropriate to use for manual, and no fallback -->
1157       <!-- * given, so insert a fixme -->
1158       <xsl:text>[FIXME: manual]</xsl:text>
1159       <xsl:if test="$refentry.meta.get.quietly = 0">
1160         <xsl:call-template name="log.message">
1161           <xsl:with-param name="level">Warn</xsl:with-param>
1162           <xsl:with-param name="source" select="$refname"/>
1163           <xsl:with-param name="context-desc">meta manual</xsl:with-param>
1164           <xsl:with-param name="message">
1165             <xsl:text>no manual fallback given, so inserted a fixme</xsl:text>
1166           </xsl:with-param>
1167         </xsl:call-template>
1168       </xsl:if>
1169     </xsl:otherwise>
1170   </xsl:choose>
1171 </xsl:template>
1172
1173 <xsl:template name="report.missing.manual">
1174   <xsl:param name="refname"/>
1175   <xsl:call-template name="log.message">
1176     <xsl:with-param name="level">Note</xsl:with-param>
1177     <xsl:with-param name="source" select="$refname"/>
1178     <xsl:with-param name="context-desc">meta manual</xsl:with-param>
1179     <xsl:with-param name="message">
1180       <xsl:text>no titled ancestor of refentry</xsl:text>
1181     </xsl:with-param>
1182   </xsl:call-template>
1183   <xsl:call-template name="log.message">
1184     <xsl:with-param name="level">Note</xsl:with-param>
1185     <xsl:with-param name="source" select="$refname"/>
1186     <xsl:with-param name="context-desc">meta manual</xsl:with-param>
1187     <xsl:with-param name="message">
1188       <xsl:text>no refentry/refmeta/refmiscinfo@class=manual</xsl:text>
1189     </xsl:with-param>
1190   </xsl:call-template>
1191   <xsl:call-template name="log.message">
1192     <xsl:with-param name="level">Note</xsl:with-param>
1193     <xsl:with-param name="source" select="$refname"/>
1194     <xsl:with-param name="context-desc">meta manual</xsl:with-param>
1195     <xsl:with-param name="message">
1196       <xsl:text>see http://www.docbook.org/tdg5/en/html/refmiscinfo</xsl:text>
1197     </xsl:with-param>
1198   </xsl:call-template>
1199 </xsl:template>
1200 <!-- ====================================================================== -->
1201 <doc:template name="get.refentry.metadata.prefs" xmlns="">
1202   <refpurpose>Gets user preferences for refentry metadata gathering</refpurpose>
1203   <refdescription id="get.refentry.metadata.prefs-desc">
1204     <para>The DocBook XSL stylesheets include several user-configurable
1205     global stylesheet parameters for controlling <tag>refentry</tag>
1206     metadata gathering. Those parameters are not read directly by the
1207     other <tag>refentry</tag> metadata-gathering
1208     templates. Instead, they are read only by the
1209     <function>get.refentry.metadata.prefs</function> template,
1210     which assembles them into a structure that is then passed to
1211     the other <tag>refentry</tag> metadata-gathering
1212     templates.</para>
1213
1214     <para>So the, <function>get.refentry.metadata.prefs</function>
1215     template is the only interface to collecting stylesheet parameters for
1216     controlling <tag>refentry</tag> metadata gathering.</para>
1217   </refdescription>
1218   <refparameter id="get.refentry.metadata.prefs-params">
1219     <para>There are no local parameters for this template; however, it
1220     does rely on a number of global parameters.</para>
1221   </refparameter>
1222   <refreturn id="get.refentry.metadata.prefs-returns">
1223     <para>Returns a <tag>manual</tag> node.</para>
1224   </refreturn>
1225 </doc:template>
1226 <xsl:template name="get.refentry.metadata.prefs">
1227   <DatePrefs>
1228     <xsl:attribute name="profile">
1229       <xsl:value-of select="$refentry.date.profile"/>
1230     </xsl:attribute>
1231     <xsl:attribute name="profileEnabled">
1232       <xsl:value-of select="$refentry.date.profile.enabled"/>
1233     </xsl:attribute>
1234   </DatePrefs>
1235   <SourcePrefs>
1236     <xsl:attribute name="fallback">
1237       <xsl:value-of select="$refentry.source.fallback.profile"/>
1238     </xsl:attribute>
1239     <Name>
1240       <xsl:attribute name="profile">
1241         <xsl:value-of select="$refentry.source.name.profile"/>
1242       </xsl:attribute>
1243       <xsl:attribute name="profileEnabled">
1244         <xsl:value-of select="$refentry.source.name.profile.enabled"/>
1245       </xsl:attribute>
1246       <xsl:attribute name="suppress">
1247         <xsl:value-of select="$refentry.source.name.suppress"/>
1248       </xsl:attribute>
1249     </Name>
1250     <Version>
1251       <xsl:attribute name="profile">
1252         <xsl:value-of select="$refentry.version.profile"/>
1253       </xsl:attribute>
1254       <xsl:attribute name="profileEnabled">
1255         <xsl:value-of select="$refentry.version.profile.enabled"/>
1256       </xsl:attribute>
1257       <xsl:attribute name="suppress">
1258         <xsl:value-of select="$refentry.version.suppress"/>
1259       </xsl:attribute>
1260     </Version>
1261   </SourcePrefs>
1262   <ManualPrefs>
1263     <xsl:attribute name="fallback">
1264       <xsl:value-of select="$refentry.manual.fallback.profile"/>
1265     </xsl:attribute>
1266     <xsl:attribute name="profile">
1267       <xsl:value-of select="$refentry.manual.profile"/>
1268     </xsl:attribute>
1269     <xsl:attribute name="profileEnabled">
1270       <xsl:value-of select="$refentry.manual.profile.enabled"/>
1271     </xsl:attribute>
1272   </ManualPrefs>
1273 </xsl:template>
1274
1275 <!-- ====================================================================== -->
1276 <doc:template name="set.refentry.metadata" xmlns="">
1277   <refpurpose>Sets content of a refentry metadata item</refpurpose>
1278   <refdescription id="set.refentry.metadata-desc">
1279     <para>The <function>set.refentry.metadata</function> template is
1280     called each time a suitable source element is found for a certain
1281     metadata field.</para>
1282   </refdescription>
1283   <refparameter id="set.refentry.metadata-params">
1284     <variablelist>
1285       <varlistentry>
1286         <term>refname</term>
1287         <listitem>
1288           <para>The first <tag>refname</tag> in the refentry</para>
1289         </listitem>
1290       </varlistentry>
1291       <varlistentry>
1292         <term>info</term>
1293         <listitem>
1294           <para>A single *info node that contains the selected source element.</para>
1295         </listitem>
1296       </varlistentry>
1297       <varlistentry>
1298         <term>contents</term>
1299         <listitem>
1300           <para>A node containing the selected source element.</para>
1301         </listitem>
1302       </varlistentry>
1303       <varlistentry>
1304         <term>context</term>
1305         <listitem>
1306           <para>A string describing the metadata context in which the
1307           <function>set.refentry.metadata</function> template was
1308           called: either "date", "source", "version", or "manual".</para>
1309         </listitem>
1310       </varlistentry>
1311     </variablelist>
1312   </refparameter>
1313   <refreturn id="set.refentry.metadata-returns">
1314   <para>Returns formatted contents of a selected source element.</para></refreturn>
1315 </doc:template>
1316 <xsl:template name="set.refentry.metadata">
1317   <xsl:param name="refname"/>
1318   <xsl:param name="info"/>
1319   <xsl:param name="contents"/>
1320   <xsl:param name="context"/>
1321   <xsl:param name="preferred"/>
1322   <!-- * <xsl:if test="not($preferred = '')"> -->
1323     <!-- * <xsl:if test="$refentry.meta.get.quietly = 0"> -->
1324       <!-- * <xsl:call-template name="log.message"> -->
1325         <!-- * <xsl:with-param name="level">Note</xsl:with-param> -->
1326         <!-- * <xsl:with-param name="source" select="$refname"/> -->
1327         <!-- * <xsl:with-param name="context-desc" select="concat('meta ', $context)"/> -->
1328         <!-- * <xsl:with-param name="message" select="concat('No ', $preferred)"/> -->
1329       <!-- * </xsl:call-template> -->
1330       <!-- * <xsl:call-template name="log.message"> -->
1331         <!-- * <xsl:with-param name="level">Note</xsl:with-param> -->
1332         <!-- * <xsl:with-param name="source" select="$refname"/> -->
1333         <!-- * <xsl:with-param name="context-desc" select="concat('meta ', $context)"/> -->
1334         <!-- * <xsl:with-param name="message"> -->
1335           <!-- * <xsl:text>no refentry/refmeta/refmiscinfo@class=</xsl:text> -->
1336           <!-- * <xsl:value-of select="$context"/> -->
1337         <!-- * </xsl:with-param> -->
1338       <!-- * </xsl:call-template> -->
1339       <!-- * <xsl:call-template name="log.message"> -->
1340         <!-- * <xsl:with-param name="level">Note</xsl:with-param> -->
1341         <!-- * <xsl:with-param name="source" select="$refname"/> -->
1342         <!-- * <xsl:with-param name="context-desc" select="concat('meta ', $context)"/> -->
1343         <!-- * <xsl:with-param name="message" select="concat('Using ', local-name($contents))"/> -->
1344       <!-- * </xsl:call-template> -->
1345     <!-- * </xsl:if> -->
1346   <!-- * </xsl:if> -->
1347   <xsl:value-of select="$contents"/>
1348 </xsl:template>
1349
1350 </xsl:stylesheet>