← Back to branch summary

~todd-deshane/openstack-manuals/working

« back to all changes in this revision

Viewing changes to doc/build/docbook-xsl-1.76.1/common/refentry.xsl

  • Committer: Anne Gentle
  • Date: 2011-04-04 17:54:52 UTC
  • Revision ID: anne@openstack.org-20110404175452-gtth3hfrniqhpp5o
Switching from Ant builds to Maven, still working out kinks but should be functional

Show diffs side-by-side

added added

removed removed

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