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