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><xsl:template name="get.refentry.metadata">
|
---|
36 | <xsl:param name="refname"/>
|
---|
37 | <xsl:param name="info"/>
|
---|
38 | <xsl:param name="prefs"/>
|
---|
39 | ...
|
---|
40 | </xsl:template></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><xsl:template name="get.refentry.title">
|
---|
177 | <xsl:param name="refname"/>
|
---|
178 | ...
|
---|
179 | </xsl:template></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><xsl:template name="get.refentry.section">
|
---|
215 | <xsl:param name="refname"/>
|
---|
216 | <xsl:param name="quiet" select="0"/>
|
---|
217 | ...
|
---|
218 | </xsl:template></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><xsl:template name="get.refentry.date">
|
---|
264 | <xsl:param name="refname"/>
|
---|
265 | <xsl:param name="info"/>
|
---|
266 | <xsl:param name="prefs"/>
|
---|
267 | ...
|
---|
268 | </xsl:template></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><xsl:template name="get.refentry.source">
|
---|
319 | <xsl:param name="refname"/>
|
---|
320 | <xsl:param name="info"/>
|
---|
321 | <xsl:param name="prefs"/>
|
---|
322 | ...
|
---|
323 | </xsl:template></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><xsl:template name="get.refentry.source.name">
|
---|
450 | <xsl:param name="refname"/>
|
---|
451 | <xsl:param name="info"/>
|
---|
452 | <xsl:param name="prefs"/>
|
---|
453 | ...
|
---|
454 | </xsl:template></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><xsl:template name="get.refentry.version">
|
---|
509 | <xsl:param name="refname"/>
|
---|
510 | <xsl:param name="info"/>
|
---|
511 | <xsl:param name="prefs"/>
|
---|
512 | ...
|
---|
513 | </xsl:template></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><xsl:template name="get.refentry.manual">
|
---|
568 | <xsl:param name="refname"/>
|
---|
569 | <xsl:param name="info"/>
|
---|
570 | <xsl:param name="prefs"/>
|
---|
571 | ...
|
---|
572 | </xsl:template></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><xsl:template name="get.refentry.metadata.prefs"/></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><xsl:template name="set.refentry.metadata">
|
---|
723 | <xsl:param name="refname"/>
|
---|
724 | <xsl:param name="info"/>
|
---|
725 | <xsl:param name="contents"/>
|
---|
726 | <xsl:param name="context"/>
|
---|
727 | <xsl:param name="preferred"/>
|
---|
728 | ...
|
---|
729 | </xsl:template></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 |
|
---|