]> git.stg.codes - stg.git/blob - doc/xslt/manpages/param.xml
Merge branch 'naffanya-dev'
[stg.git] / doc / xslt / manpages / param.xml
1 <?xml version="1.0" encoding="ASCII"?>
2 <book version="5.0">
3   <info>
4     <title>Manpages Parameter Reference</title>
5     <releaseinfo role="meta">
6       $Id: param.xweb 8235 2009-02-09 16:22:14Z xmldoc $
7     </releaseinfo>
8     <author>
9       <orgname>The DocBook Project</orgname>
10     </author>
11     <copyright>
12       <year>2005-2007</year>
13       <holder>The DocBook Project</holder>
14     </copyright>
15     <abstract>
16       <para>This is reference documentation for all user-configurable
17       parameters in the DocBook XSL "manpages" stylesheet (for
18       generating groff/nroff output). Note that the manpages
19       stylesheet is a customization layer of the DocBook XSL HTML
20       stylesheet. Therefore, you can also use a number of <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../html/">HTML stylesheet parameters</link>
21       to control manpages output (in addition to the
22       manpages-specific parameters listed in this section).</para>
23     </abstract>
24   </info>
25   <reference xml:id="general">
26   <title>Hyphenation, justification, and breaking</title>
27 <refentry version="5.0" xml:id="man.hyphenate">
28 <refmeta>
29 <refentrytitle>man.hyphenate</refentrytitle>
30 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
31 </refmeta>
32 <refnamediv>
33 <refname>man.hyphenate</refname>
34 <refpurpose>Enable hyphenation?</refpurpose>
35 </refnamediv>
36
37 <refsynopsisdiv>
38 <programlisting xml:id="man.hyphenate.frag">
39 &lt;xsl:param name="man.hyphenate"&gt;0&lt;/xsl:param&gt;</programlisting>
40 </refsynopsisdiv>
41
42 <refsection><info><title>Description</title></info>
43
44 <para>If non-zero, hyphenation is enabled.</para>
45
46 <note>
47 <para>The default value for this parameter is zero because groff is
48 not particularly smart about how it does hyphenation; it can end up
49 hyphenating a lot of things that you don't want hyphenated. To
50 mitigate that, the default behavior of the stylesheets is to suppress
51 hyphenation of computer inlines, filenames, and URLs. (You can
52 override the default behavior by setting non-zero values for the
53 <parameter>man.hyphenate.urls</parameter>,
54 <parameter>man.hyphenate.filenames</parameter>, and
55 <parameter>man.hyphenate.computer.inlines</parameter> parameters.) But
56 the best way is still to just globally disable hyphenation, as the
57 stylesheets do by default.</para>
58
59 <para>The only good reason to enabled hyphenation is if you have also
60 enabled justification (which is disabled by default). The reason is
61 that justified text can look very bad unless you also hyphenate it; to
62 quote the <quote>Hypenation</quote> node from the groff info page:
63
64 <blockquote>
65   <para><emphasis>Since the odds are not great for finding a set of
66   words, for every output line, which fit nicely on a line without
67   inserting excessive amounts of space between words, 'gtroff'
68   hyphenates words so that it can justify lines without inserting too
69   much space between words.</emphasis></para>
70 </blockquote>
71
72 So, if you set a non-zero value for the
73 <parameter>man.justify</parameter> parameter (to enable
74 justification), then you should probably also set a non-zero value for
75 <parameter>man.hyphenate</parameter> (to enable hyphenation).</para>
76 </note>
77
78
79 </refsection>
80 </refentry>
81
82 <refentry version="5.0" xml:id="man.hyphenate.urls">
83 <refmeta>
84 <refentrytitle>man.hyphenate.urls</refentrytitle>
85 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
86 </refmeta>
87 <refnamediv>
88 <refname>man.hyphenate.urls</refname>
89 <refpurpose>Hyphenate URLs?</refpurpose>
90 </refnamediv>
91
92 <refsynopsisdiv>
93 <programlisting xml:id="man.hyphenate.urls.frag">
94 &lt;xsl:param name="man.hyphenate.urls"&gt;0&lt;/xsl:param&gt;</programlisting>
95 </refsynopsisdiv>
96
97 <refsection><info><title>Description</title></info>
98
99 <para>If zero (the default), hyphenation is suppressed for output of
100 the <tag>ulink</tag> <tag class="attribute">url</tag> attribute.</para>
101
102 <note>
103   <para>If hyphenation is already turned off globally (that is, if
104   <parameter>man.hyphenate</parameter> is zero, setting
105   <parameter>man.hyphenate.urls</parameter> is not necessary.</para>
106 </note>
107
108 <para>If <parameter>man.hyphenate.urls</parameter> is non-zero, URLs
109 will not be treated specially and are subject to hyphenation just like
110 other words.</para>
111
112 <note>
113   <para>If you are thinking about setting a non-zero value for
114   <parameter>man.hyphenate.urls</parameter> in order to make long
115   URLs break across lines, you'd probably be better off
116   experimenting with setting the
117   <parameter>man.break.after.slash</parameter> parameter first. That
118   will cause long URLs to be broken after slashes.</para>
119 </note>
120
121 </refsection>
122 </refentry>
123
124 <refentry version="5.0" xml:id="man.hyphenate.filenames">
125 <refmeta>
126 <refentrytitle>man.hyphenate.filenames</refentrytitle>
127 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
128 </refmeta>
129 <refnamediv>
130 <refname>man.hyphenate.filenames</refname>
131 <refpurpose>Hyphenate filenames?</refpurpose>
132 </refnamediv>
133
134 <refsynopsisdiv>
135 <programlisting xml:id="man.hyphenate.filenames.frag">
136 &lt;xsl:param name="man.hyphenate.filenames"&gt;0&lt;/xsl:param&gt;</programlisting>
137 </refsynopsisdiv>
138
139 <refsection><info><title>Description</title></info>
140
141 <para>If zero (the default), hyphenation is suppressed for
142 <tag>filename</tag> output.</para>
143
144 <note>
145   <para>If hyphenation is already turned off globally (that is, if
146   <parameter>man.hyphenate</parameter> is zero, setting
147   <parameter>man.hyphenate.filenames</parameter> is not
148   necessary.</para>
149 </note>
150
151 <para>If <parameter>man.hyphenate.filenames</parameter> is non-zero,
152 filenames will not be treated specially and are subject to hyphenation
153 just like other words.</para>
154
155 <note>
156   <para>If you are thinking about setting a non-zero value for
157   <parameter>man.hyphenate.filenames</parameter> in order to make long
158   filenames/pathnames break across lines, you'd probably be better off
159   experimenting with setting the
160   <parameter>man.break.after.slash</parameter> parameter first. That
161   will cause long pathnames to be broken after slashes.</para>
162 </note>
163
164 </refsection>
165 </refentry>
166
167 <refentry version="5.0" xml:id="man.hyphenate.computer.inlines">
168 <refmeta>
169 <refentrytitle>man.hyphenate.computer.inlines</refentrytitle>
170 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
171 </refmeta>
172 <refnamediv>
173 <refname>man.hyphenate.computer.inlines</refname>
174 <refpurpose>Hyphenate computer inlines?</refpurpose>
175 </refnamediv>
176
177 <refsynopsisdiv>
178 <programlisting xml:id="man.hyphenate.computer.inlines.frag">
179 &lt;xsl:param name="man.hyphenate.computer.inlines"&gt;0&lt;/xsl:param&gt;</programlisting>
180 </refsynopsisdiv>
181
182 <refsection><info><title>Description</title></info>
183
184 <para>If zero (the default), hyphenation is suppressed for
185 <quote>computer inlines</quote> such as environment variables,
186 constants, etc. This parameter current affects output of the following
187 elements:
188 <simplelist type="inline">
189   
190   <member><tag>classname</tag></member>
191   <member><tag>constant</tag></member>
192   <member><tag>envar</tag></member>
193   <member><tag>errorcode</tag></member>
194   <member><tag>option</tag></member>
195   <member><tag>replaceable</tag></member>
196   <member><tag>userinput</tag></member>
197   <member><tag>type</tag></member>
198   <member><tag>varname</tag></member>
199 </simplelist>
200 </para>
201
202 <note>
203   <para>If hyphenation is already turned off globally (that is, if
204   <parameter>man.hyphenate</parameter> is zero, setting the
205   <parameter>man.hyphenate.computer.inlines</parameter> is not
206   necessary.</para>
207 </note>
208
209 <para>If <parameter>man.hyphenate.computer.inlines</parameter> is
210 non-zero, computer inlines will not be treated specially and will be
211 hyphenated like other words when needed.</para>
212
213 </refsection>
214 </refentry>
215
216 <refentry version="5.0" xml:id="man.justify">
217 <refmeta>
218 <refentrytitle>man.justify</refentrytitle>
219 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
220 </refmeta>
221 <refnamediv>
222 <refname>man.justify</refname>
223 <refpurpose>Justify text to both right and left margins?</refpurpose>
224 </refnamediv>
225
226 <refsynopsisdiv>
227 <programlisting xml:id="man.justify.frag">
228 &lt;xsl:param name="man.justify"&gt;0&lt;/xsl:param&gt;</programlisting>
229 </refsynopsisdiv>
230
231 <refsection><info><title>Description</title></info>
232
233 <para>If non-zero, text is justified to both the right and left
234 margins (or, in roff terminology, "adjusted and filled" to both the
235 right and left margins). If zero (the default), text is adjusted to
236 the left margin only -- producing what is traditionally called
237 "ragged-right" text.</para>
238
239 <note>
240 <para>The default value for this parameter is zero because justified
241 text looks good only when it is also hyphenated. Without hyphenation,
242 excessive amounts of space often end up getting between words, in
243 order to "pad" lines out to align on the right margin.</para>
244
245 <para>The problem is that groff is not particularly smart about how it
246 does hyphenation; it can end up hyphenating a lot of things that you
247 don't want hyphenated. So, disabling both justification and
248 hyphenation ensures that hyphens won't get inserted where you don't
249 want to them, and you don't end up with lines containing excessive
250 amounts of space between words.</para>
251
252 <para>However, if do you decide to set a non-zero value for the
253 <parameter>man.justify</parameter> parameter (to enable
254 justification), then you should probably also set a non-zero value for
255 <parameter>man.hyphenate</parameter> (to enable hyphenation).</para>
256
257 <para>Yes, these default settings run counter to how most existing man
258 pages are formatted. But there are some notable exceptions, such as
259 the <literal>perl</literal> man pages.</para>
260 </note>
261 </refsection>
262 </refentry>
263
264 <refentry version="5.0" xml:id="man.break.after.slash">
265 <refmeta>
266 <refentrytitle>man.break.after.slash</refentrytitle>
267 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
268 </refmeta>
269 <refnamediv>
270 <refname>man.break.after.slash</refname>
271 <refpurpose>Enable line-breaking after slashes?</refpurpose>
272 </refnamediv>
273
274 <refsynopsisdiv>
275 <programlisting xml:id="man.break.after.slash.frag">
276 &lt;xsl:param name="man.break.after.slash"&gt;0&lt;/xsl:param&gt;</programlisting>
277 </refsynopsisdiv>
278
279 <refsection><info><title>Description</title></info>
280
281 <para>If non-zero, line-breaking after slashes is enabled. This is
282 mainly useful for causing long URLs or pathnames/filenames to be
283 broken up or "wrapped" across lines (though it also has the side
284 effect of sometimes causing relatively short URLs and pathnames to be
285 broken up across lines too).</para>
286
287 <para>If zero (the default), line-breaking after slashes is
288 disabled. In that case, strings containing slashes (for example, URLs
289 or filenames) are not broken across lines, even if they exceed the
290 maximum column widith.</para>
291
292 <warning>
293   <para>If you set a non-zero value for this parameter, check your
294   man-page output carefuly afterwards, in order to make sure that the
295   setting has not introduced an excessive amount of breaking-up of URLs
296   or pathnames. If your content contains mostly short URLs or
297   pathnames, setting a non-zero value for
298   <parameter>man.break.after.slash</parameter> will probably result in
299   in a significant number of relatively short URLs and pathnames being
300   broken across lines, which is probably not what you want.</para>
301 </warning>
302
303 </refsection>
304 </refentry>
305
306   </reference>
307   <reference xml:id="indent">
308   <title>Indentation</title>
309 <refentry version="5.0" xml:id="man.indent.width">
310 <refmeta>
311 <refentrytitle>man.indent.width</refentrytitle>
312 <refmiscinfo class="other" otherclass="datatype">length</refmiscinfo>
313 </refmeta>
314 <refnamediv>
315 <refname>man.indent.width</refname>
316 <refpurpose>Specifies width used for adjusted indents</refpurpose>
317 </refnamediv>
318
319 <refsynopsisdiv>
320 <programlisting xml:id="man.indent.width.frag">
321 &lt;xsl:param name="man.indent.width"&gt;4&lt;/xsl:param&gt;
322 </programlisting>
323 </refsynopsisdiv>
324
325 <refsection><info><title>Description</title></info>
326 <para>The <parameter>man.indent.width</parameter> parameter specifies
327 the width used for adjusted indents. The value of
328 <parameter>man.indent.width</parameter> is used for indenting of
329 lists, verbatims, headings, and elsewhere, depending on whether the
330 values of certain <literal>man.indent.*</literal> boolean parameters
331 are non-zero.</para>
332
333 <para>The value of <parameter>man.indent.width</parameter> should
334 include a valid roff measurement unit (for example,
335 <literal>n</literal> or <literal>u</literal>). The default value of
336 <literal>4n</literal> specifies a 4-en width; when viewed on a
337 console, that amounts to the width of four characters. For details
338 about roff measurment units, see the <literal>Measurements</literal>
339 node in the groff info page.</para>
340
341 </refsection>
342 </refentry>
343
344 <refentry version="5.0" xml:id="man.indent.refsect">
345 <refmeta>
346 <refentrytitle>man.indent.refsect</refentrytitle>
347 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
348 </refmeta>
349 <refnamediv>
350 <refname>man.indent.refsect</refname>
351 <refpurpose>Adjust indentation of refsect* and refsection?</refpurpose>
352 </refnamediv>
353
354 <refsynopsisdiv>
355 <programlisting xml:id="man.indent.refsect.frag">
356 &lt;xsl:param name="man.indent.refsect" select="0"&gt;&lt;/xsl:param&gt;</programlisting>
357 </refsynopsisdiv>
358
359 <refsection><info><title>Description</title></info>
360
361 <para>If the value of <parameter>man.indent.refsect</parameter> is
362 non-zero, the width of the left margin for
363 <tag>refsect1</tag>, <tag>refsect2</tag> and
364 <tag>refsect3</tag> contents and titles (and first-level,
365 second-level, and third-level nested
366 <tag>refsection</tag>instances) is adjusted by the value of
367 the <parameter>man.indent.width</parameter> parameter. With
368 <parameter>man.indent.width</parameter> set to its default value of
369 <literal>3n</literal>, the main results are that:
370
371 <itemizedlist>
372   <listitem>
373     <para>contents of <tag>refsect1</tag> are output with a
374     left margin of three characters instead the roff default of seven
375     or eight characters</para>
376   </listitem>
377   <listitem>
378     <para>contents of <tag>refsect2</tag> are displayed in
379     console output with a left margin of six characters instead the of
380     the roff default of seven characters</para>
381   </listitem>
382   <listitem>
383     <para> the contents of <tag>refsect3</tag> and nested
384     <tag>refsection</tag> instances are adjusted
385     accordingly.</para>
386   </listitem>
387 </itemizedlist>
388
389 If instead the value of <parameter>man.indent.refsect</parameter> is
390 zero, no margin adjustment is done for <literal>refsect*</literal>
391 output.</para>
392
393 <tip>
394   <para>If your content is primarly comprised of
395   <tag>refsect1</tag> and <tag>refsect2</tag> content
396   (or the <tag>refsection</tag> equivalent)&#160;&#8211; with few or
397   no <tag>refsect3</tag> or lower nested sections , you may be
398   able to &#8220;conserve&#8221; space in your output by setting
399   <parameter>man.indent.refsect</parameter> to a non-zero value. Doing
400   so will &#8220;squeeze&#8221; the left margin in such as way as to provide an
401   additional four characters of &#8220;room&#8221; per line in
402   <tag>refsect1</tag> output. That extra room may be useful
403   if, for example, you have many verbatim sections with long lines in
404   them.</para>
405 </tip>
406
407 </refsection>
408 </refentry>
409
410 <refentry version="5.0" xml:id="man.indent.blurbs">
411 <refmeta>
412 <refentrytitle>man.indent.blurbs</refentrytitle>
413 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
414 </refmeta>
415 <refnamediv>
416 <refname>man.indent.blurbs</refname>
417 <refpurpose>Adjust indentation of blurbs?</refpurpose>
418 </refnamediv>
419
420 <refsynopsisdiv>
421 <programlisting xml:id="man.indent.blurbs.frag">
422 &lt;xsl:param name="man.indent.blurbs" select="1"&gt;&lt;/xsl:param&gt;</programlisting>
423 </refsynopsisdiv>
424
425 <refsection><info><title>Description</title></info>
426
427 <para>If the value of <parameter>man.indent.blurbs</parameter> is
428 non-zero, the width of the left margin for
429 <tag>authorblurb</tag>, <tag>personblurb</tag>, and
430 <tag>contrib</tag> output is set to the value of the
431 <parameter>man.indent.width</parameter> parameter
432 (<literal>3n</literal> by default). If instead the value of
433 <parameter>man.indent.blurbs</parameter> is zero, the built-in roff
434 default width (<literal>7.2n</literal>) is used.</para>
435
436 </refsection>
437 </refentry>
438
439 <refentry version="5.0" xml:id="man.indent.lists">
440 <refmeta>
441 <refentrytitle>man.indent.lists</refentrytitle>
442 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
443 </refmeta>
444 <refnamediv>
445 <refname>man.indent.lists</refname>
446 <refpurpose>Adjust indentation of lists?</refpurpose>
447 </refnamediv>
448
449 <refsynopsisdiv>
450 <programlisting xml:id="man.indent.lists.frag">
451 &lt;xsl:param name="man.indent.lists" select="1"&gt;&lt;/xsl:param&gt;</programlisting>
452 </refsynopsisdiv>
453
454 <refsection><info><title>Description</title></info>
455
456 <para>If the value of <parameter>man.indent.lists</parameter> is
457 non-zero, the width of the left margin for list items in
458 <tag>itemizedlist</tag>,
459 <tag>orderedlist</tag>,
460 <tag>variablelist</tag> output (and output of some other
461 lists) is set to the value of the
462 <parameter>man.indent.width</parameter> parameter
463 (<literal>4n</literal> by default). If instead the value of
464 <parameter>man.indent.lists</parameter> is zero, the built-in roff
465 default width (<literal>7.2n</literal>) is used.</para>
466
467 </refsection>
468 </refentry>
469
470 <refentry version="5.0" xml:id="man.indent.verbatims">
471 <refmeta>
472 <refentrytitle>man.indent.verbatims</refentrytitle>
473 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
474 </refmeta>
475 <refnamediv>
476 <refname>man.indent.verbatims</refname>
477 <refpurpose>Adjust indentation of verbatims?</refpurpose>
478 </refnamediv>
479
480 <refsynopsisdiv>
481 <programlisting xml:id="man.indent.verbatims.frag">
482 &lt;xsl:param name="man.indent.verbatims" select="1"&gt;&lt;/xsl:param&gt;</programlisting>
483 </refsynopsisdiv>
484
485 <refsection><info><title>Description</title></info>
486
487 <para>If the value of <parameter>man.indent.verbatims</parameter> is
488 non-zero, the width of the left margin for output of verbatim
489 environments (<tag>programlisting</tag>,
490 <tag>screen</tag>, and so on) is set to the value of the
491 <parameter>man.indent.width</parameter> parameter
492 (<literal>3n</literal> by default). If instead the value of
493 <parameter>man.indent.verbatims</parameter> is zero, the built-in roff
494 default width (<literal>7.2n</literal>) is used.</para>
495
496 </refsection>
497 </refentry>
498
499   </reference>
500   <reference xml:id="fonts">
501   <title>Fonts</title>
502 <refentry version="5.0" xml:id="man.font.funcprototype">
503 <refmeta>
504 <refentrytitle>man.font.funcprototype</refentrytitle>
505 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
506 </refmeta>
507 <refnamediv>
508 <refname>man.font.funcprototype</refname>
509 <refpurpose>Specifies font for funcprototype output</refpurpose>
510 </refnamediv>
511
512 <refsynopsisdiv>
513 <programlisting xml:id="man.font.funcprototype.frag">
514   &lt;xsl:param name="man.font.funcprototype"&gt;BI&lt;/xsl:param&gt;
515 </programlisting>
516 </refsynopsisdiv>
517
518 <refsection><info><title>Description</title></info>
519
520 <para>The <parameter>man.font.funcprototype</parameter> parameter
521 specifies the font for <tag>funcprototype</tag> output. It
522 should be a valid roff font name, such as <literal>BI</literal> or
523 <literal>B</literal>.</para>
524
525 </refsection>
526 </refentry>
527
528 <refentry version="5.0" xml:id="man.font.funcsynopsisinfo">
529 <refmeta>
530 <refentrytitle>man.font.funcsynopsisinfo</refentrytitle>
531 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
532 </refmeta>
533 <refnamediv>
534 <refname>man.font.funcsynopsisinfo</refname>
535 <refpurpose>Specifies font for funcsynopsisinfo output</refpurpose>
536 </refnamediv>
537
538 <refsynopsisdiv>
539 <programlisting xml:id="man.font.funcsynopsisinfo.frag">
540   &lt;xsl:param name="man.font.funcsynopsisinfo"&gt;B&lt;/xsl:param&gt;
541 </programlisting>
542 </refsynopsisdiv>
543
544 <refsection><info><title>Description</title></info>
545
546 <para>The <parameter>man.font.funcsynopsisinfo</parameter> parameter
547 specifies the font for <tag>funcsynopsisinfo</tag> output. It
548 should be a valid roff font name, such as <literal>B</literal> or
549 <literal>I</literal>.</para>
550
551 </refsection>
552 </refentry>
553
554 <refentry version="5.0" xml:id="man.font.links">
555 <refmeta>
556 <refentrytitle>man.font.links</refentrytitle>
557 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
558 </refmeta>
559 <refnamediv>
560 <refname>man.font.links</refname>
561 <refpurpose>Specifies font for links</refpurpose>
562 </refnamediv>
563
564 <refsynopsisdiv>
565 <programlisting xml:id="man.font.links.frag">
566 &lt;xsl:param name="man.font.links"&gt;B&lt;/xsl:param&gt;
567 </programlisting>
568 </refsynopsisdiv>
569
570 <refsection><info><title>Description</title></info>
571
572 <para>The <parameter>man.font.links</parameter> parameter
573 specifies the font for output of links (<tag>ulink</tag> instances
574 and any instances of any element with an <tag class="attribute">xlink:href</tag> attribute).</para>
575
576 <para>The value of <parameter>man.font.links</parameter> must be
577   either <literal>B</literal> or <literal>I</literal>, or empty. If
578 the value is empty, no font formatting is applied to links.</para>
579
580 <para>If you set <parameter>man.endnotes.are.numbered</parameter> and/or
581 <parameter>man.endnotes.list.enabled</parameter> to zero (disabled), then
582 you should probably also set an empty value for
583 <parameter>man.font.links</parameter>. But if
584 <parameter>man.endnotes.are.numbered</parameter> is non-zero (enabled),
585 you should probably keep
586 <parameter>man.font.links</parameter> set to
587 <literal>B</literal> or <literal>I</literal><footnote><para>The
588     main purpose of applying a font format to links in most output
589 formats it to indicate that the formatted text is
590 &#8220;clickable&#8221;; given that links rendered in man pages are
591 not &#8220;real&#8221; hyperlinks that users can click on, it might
592 seem like there is never a good reason to have font formatting for
593 link contents in man output.</para>
594 <para>In fact, if you suppress the
595 display of inline link references (by setting
596 <parameter>man.endnotes.are.numbered</parameter> to zero), there is no
597 good reason to apply font formatting to links. However, if
598 <parameter>man.endnotes.are.numbered</parameter> is non-zero, having
599 font formatting for links (arguably) serves a purpose: It provides
600 &#8220;context&#8221; information about exactly what part of the text
601 is being &#8220;annotated&#8221; by the link. Depending on how you
602 mark up your content, that context information may or may not
603 have value.</para></footnote>.</para>
604 </refsection>
605
606 <refsection><info><title>Related Parameters</title></info>
607   <para><parameter>man.endnotes.list.enabled</parameter>,
608     <parameter>man.endnotes.are.numbered</parameter></para>
609 </refsection>
610
611 </refentry>
612
613 <refentry version="5.0" xml:id="man.font.table.headings">
614 <refmeta>
615 <refentrytitle>man.font.table.headings</refentrytitle>
616 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
617 </refmeta>
618 <refnamediv>
619 <refname>man.font.table.headings</refname>
620 <refpurpose>Specifies font for table headings</refpurpose>
621 </refnamediv>
622
623 <refsynopsisdiv>
624 <programlisting xml:id="man.font.table.headings.frag">
625   &lt;xsl:param name="man.font.table.headings"&gt;B&lt;/xsl:param&gt;
626 </programlisting>
627 </refsynopsisdiv>
628
629 <refsection><info><title>Description</title></info>
630
631 <para>The <parameter>man.font.table.headings</parameter> parameter
632 specifies the font for <tag>table</tag> headings. It should be
633 a valid roff font, such as <literal>B</literal> or
634 <literal>I</literal>.</para>
635
636 </refsection>
637 </refentry>
638
639 <refentry version="5.0" xml:id="man.font.table.title">
640 <refmeta>
641 <refentrytitle>man.font.table.title</refentrytitle>
642 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
643 </refmeta>
644 <refnamediv>
645 <refname>man.font.table.title</refname>
646 <refpurpose>Specifies font for table headings</refpurpose>
647 </refnamediv>
648
649 <refsynopsisdiv>
650 <programlisting xml:id="man.font.table.title.frag">
651   &lt;xsl:param name="man.font.table.title"&gt;B&lt;/xsl:param&gt;
652 </programlisting>
653 </refsynopsisdiv>
654
655 <refsection><info><title>Description</title></info>
656
657 <para>The <parameter>man.font.table.title</parameter> parameter
658 specifies the font for <tag>table</tag> titles. It should be
659 a valid roff font, such as <literal>B</literal> or
660 <literal>I</literal>.</para>
661
662 </refsection>
663 </refentry>
664
665   </reference>
666   <reference xml:id="synopsis">
667   <title>SYNOPSIS section</title>
668 <refentry version="5.0" xml:id="man.funcsynopsis.style">
669 <refmeta>
670 <refentrytitle>man.funcsynopsis.style</refentrytitle>
671 <refmiscinfo class="other" otherclass="datatype">list</refmiscinfo>
672 <refmiscinfo class="other" otherclass="value">ansi</refmiscinfo>
673 <refmiscinfo class="other" otherclass="value">kr</refmiscinfo>
674 </refmeta>
675 <refnamediv>
676 <refname>man.funcsynopsis.style</refname>
677 <refpurpose>What style of <tag>funcsynopsis</tag> should be generated?</refpurpose>
678 </refnamediv>
679 <refsynopsisdiv>
680 <programlisting xml:id="man.funcsynopsis.style.frag">&lt;xsl:param name="man.funcsynopsis.style"&gt;ansi&lt;/xsl:param&gt;</programlisting>
681 </refsynopsisdiv>
682 <refsection><info><title>Description</title></info>
683 <para>If <parameter>man.funcsynopsis.style</parameter> is
684 <literal>ansi</literal>, ANSI-style function synopses are
685 generated for a <tag>funcsynopsis</tag>, otherwise K&amp;R-style
686 function synopses are generated.</para>
687 </refsection>
688 </refentry>
689
690   </reference>
691   <reference xml:id="authors">
692   <title>AUTHORS and COPYRIGHT sections</title>
693   <refentry version="5.0" xml:id="man.authors.section.enabled">
694 <refmeta>
695 <refentrytitle>man.authors.section.enabled</refentrytitle>
696 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
697 </refmeta>
698 <refnamediv>
699 <refname>man.authors.section.enabled</refname>
700 <refpurpose>Display auto-generated AUTHORS section?</refpurpose>
701 </refnamediv>
702 <refsynopsisdiv>
703 <programlisting xml:id="man.authors.section.enabled.frag">
704 &lt;xsl:param name="man.authors.section.enabled"&gt;1&lt;/xsl:param&gt;
705 </programlisting>
706 </refsynopsisdiv>
707 <refsection><info><title>Description</title></info>
708
709 <para>If the value of
710 <parameter>man.authors.section.enabled</parameter> is non-zero
711 (the default), then an <literal>AUTHORS</literal> section is
712 generated near the end of each man page. The output of the
713 <literal>AUTHORS</literal> section is assembled from any
714 <tag>author</tag>, <tag>editor</tag>, and <tag>othercredit</tag>
715 metadata found in the contents of the child <tag>info</tag> or
716 <tag>refentryinfo</tag> (if any) of the <tag>refentry</tag>
717 itself, or from any <tag>author</tag>, <tag>editor</tag>, and
718 <tag>othercredit</tag> metadata that may appear in <tag>info</tag>
719 contents of any ancestors of the <tag>refentry</tag>.</para>
720
721 <para>If the value of
722 <parameter>man.authors.section.enabled</parameter> is zero, the
723 the auto-generated <literal>AUTHORS</literal> section is
724 suppressed.</para>
725
726 <para>Set the value of
727   <parameter>man.authors.section.enabled</parameter> to zero if
728   you want to have a manually created <literal>AUTHORS</literal>
729   section in your source, and you want it to appear in output
730   instead of the auto-generated <literal>AUTHORS</literal>
731   section.</para>
732 </refsection>
733 </refentry>
734
735   <refentry version="5.0" xml:id="man.copyright.section.enabled">
736 <refmeta>
737 <refentrytitle>man.copyright.section.enabled</refentrytitle>
738 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
739 </refmeta>
740 <refnamediv>
741 <refname>man.copyright.section.enabled</refname>
742 <refpurpose>Display auto-generated COPYRIGHT section?</refpurpose>
743 </refnamediv>
744 <refsynopsisdiv>
745 <programlisting xml:id="man.copyright.section.enabled.frag">
746 &lt;xsl:param name="man.copyright.section.enabled"&gt;1&lt;/xsl:param&gt;
747 </programlisting>
748 </refsynopsisdiv>
749 <refsection><info><title>Description</title></info>
750
751 <para>If the value of
752 <parameter>man.copyright.section.enabled</parameter> is non-zero
753 (the default), then a <literal>COPYRIGHT</literal> section is
754 generated near the end of each man page. The output of the
755 <literal>COPYRIGHT</literal> section is assembled from any
756 <tag>copyright</tag> and <tag>legalnotice</tag> metadata found in
757 the contents of the child <tag>info</tag> or
758 <tag>refentryinfo</tag> (if any) of the <tag>refentry</tag>
759 itself, or from any <tag>copyright</tag> and
760 <tag>legalnotice</tag> metadata that may appear in <tag>info</tag>
761 contents of any ancestors of the <tag>refentry</tag>.</para>
762
763 <para>If the value of
764 <parameter>man.copyright.section.enabled</parameter> is zero, the
765 the auto-generated <literal>COPYRIGHT</literal> section is
766 suppressed.</para>
767
768 <para>Set the value of
769   <parameter>man.copyright.section.enabled</parameter> to zero if
770   you want to have a manually created <literal>COPYRIGHT</literal>
771   section in your source, and you want it to appear in output
772   instead of the auto-generated <literal>COPYRIGHT</literal>
773   section.</para>
774 </refsection>
775 </refentry>
776
777   </reference>
778   <reference xml:id="endnotes">
779   <title>Endnotes and link handling</title>
780 <refentry version="5.0" xml:id="man.endnotes.list.enabled">
781 <refmeta>
782 <refentrytitle>man.endnotes.list.enabled</refentrytitle>
783 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
784 </refmeta>
785 <refnamediv>
786 <refname>man.endnotes.list.enabled</refname>
787 <refpurpose>Display endnotes list at end of man page?</refpurpose>
788 </refnamediv>
789
790 <refsynopsisdiv>
791 <programlisting xml:id="man.endnotes.list.enabled.frag">
792 &lt;xsl:param name="man.endnotes.list.enabled"&gt;1&lt;/xsl:param&gt;
793 </programlisting>
794 </refsynopsisdiv>
795
796 <refsection><info><title>Description</title></info>
797
798 <para>If the value of <parameter>man.endnotes.list.enabled</parameter> is
799 non-zero (the default), then an endnotes list is added to the end of
800 the output man page.</para>
801
802 <para>If the value of <parameter>man.endnotes.list.enabled</parameter> is
803 zero, the list is suppressed &#8212; unless link numbering is enabled (that
804 is, if <parameter>man.endnotes.are.numbered</parameter> is non-zero), in
805 which case, that setting overrides the
806 <parameter>man.endnotes.list.enabled</parameter> setting, and the
807 endnotes list is still displayed. The reason is that inline
808 numbering of notesources associated with endnotes only makes sense
809 if a (numbered) list of endnotes is also generated.</para>
810
811 <note>
812   <para>Leaving
813   <parameter>man.endnotes.list.enabled</parameter> at its default
814   (non-zero) value ensures that no &#8220;out of line&#8221; information (such
815   as the URLs for hyperlinks and images) gets lost in your
816   man-page output. It just gets &#8220;rearranged&#8221;.</para>
817   <para>So if you&#8217;re thinking about disabling endnotes listing by
818     setting the value of
819     <parameter>man.endnotes.list.enabled</parameter> to zero:
820     Before you do so, first take some time to carefully consider
821     the information needs and experiences of your users. The &#8220;out
822     of line&#8221; information has value even if the presentation of it
823     in text output is not as interactive as it may be in other
824     output formats.</para>
825   <para>As far as the specific case of URLs: Even though the URLs
826     displayed in text output may not be &#8220;real&#8221; (clickable)
827     hyperlinks, many X terminals have convenience features for
828     recognizing URLs and can, for example, present users with
829     an options to open a URL in a browser with the user clicks on
830     the URL is a terminal window. And short of those, users with X
831     terminals can always manually cut and paste the URLs into a web
832     browser.</para>
833   <para>Also, note that various &#8220;man to html&#8221; tools, such as the
834     widely used <command><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://users.actrix.gen.nz/michael/vhman2html.html">man2html</link></command> (<literal>VH-Man2html</literal>)
835     application, automatically mark up URLs with <literal>a@href</literal> markup
836   during conversion &#8212; resulting in &#8220;real&#8221; hyperlinks in HTML
837   output from those tools.</para>
838 </note>
839
840 <para>To &#8220;turn off&#8221; numbering of endnotes in the
841 endnotes list, set <parameter>man.endnotes.are.numbered</parameter>
842 to zero. The endnotes list will
843 still be displayed; it will just be displayed without the
844 numbers<footnote><para>It can still make sense to have
845 the list of endnotes displayed even if you have endnotes numbering turned
846 off. In that case, your endnotes list basically becomes a &#8220;list
847 of references&#8221; without any association with specific text in
848 your document. This is probably the best option if you find the inline
849 endnotes numbering obtrusive. Your users will still have access to all the &#8220;out of line&#8221;
850 such as URLs for hyperlinks.</para></footnote>
851 </para>
852
853 <para>The default heading for the endnotes list is
854 <literal>NOTES</literal>. To change that, set a non-empty
855 value for the <parameter>man.endnotes.list.heading</parameter>
856 parameter.</para>
857
858 <para>In the case of notesources that are links: Along with the
859 URL for each link, the endnotes list includes the contents of the
860 link. The list thus includes only non-empty<footnote>
861
862 <para>A &#8220;non-empty&#8221; link is one that looks like
863 this:<literallayout class="monospaced">  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"&gt;manpages&lt;/ulink&gt;</literallayout>
864 an &#8220;empty link&#8221; is on that looks like this:<literallayout class="monospaced">  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/&gt;</literallayout>
865 </para></footnote> links.
866
867 Empty links are never included, and never numbered. They are simply
868 displayed inline, without any numbering.</para>
869
870 <para>In addition, if there are multiple instances of links in a
871 <tag>refentry</tag> that have the same URL, the URL is listed only
872 once. The contents listed for that link in the endnotes list are
873 the contents of the first link which has that URL.</para>
874
875 <para>If you disable endnotes listing, you should probably also set
876 <parameter>man.links.are.underlined</parameter> to zero (to disable
877 link underlining).</para>
878 </refsection>
879 </refentry>
880
881 <refentry version="5.0" xml:id="man.endnotes.list.heading">
882 <refmeta>
883 <refentrytitle>man.endnotes.list.heading</refentrytitle>
884 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
885 </refmeta>
886 <refnamediv>
887 <refname>man.endnotes.list.heading</refname>
888 <refpurpose>Specifies an alternate name for endnotes list</refpurpose>
889 </refnamediv>
890
891 <refsynopsisdiv>
892 <programlisting xml:id="man.endnotes.list.heading.frag">
893 &lt;xsl:param name="man.endnotes.list.heading"&gt;&lt;/xsl:param&gt;
894 </programlisting>
895 </refsynopsisdiv>
896
897 <refsection><info><title>Description</title></info>
898
899 <para>If the value of the
900 <parameter>man.endnotes.are.numbered</parameter> parameter
901 and/or the <parameter>man.endnotes.list.enabled</parameter>
902 parameter is non-zero (the defaults for both are non-zero), a
903 numbered list of endnotes is generated near the end of each man
904 page. The default heading for the list of endnotes is the
905 equivalent of the English word <literal>NOTES</literal> in
906 the current locale. To cause an alternate heading to be displayed,
907 set a non-empty value for the
908 <parameter>man.endnotes.list.heading</parameter> parameter &#8212;
909 for example, <literal>REFERENCES</literal>.</para>
910 </refsection>
911 </refentry>
912
913 <refentry version="5.0" xml:id="man.endnotes.are.numbered">
914 <refmeta>
915 <refentrytitle>man.endnotes.are.numbered</refentrytitle>
916 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
917 </refmeta>
918 <refnamediv>
919 <refname>man.endnotes.are.numbered</refname>
920 <refpurpose>Number endnotes?</refpurpose>
921 </refnamediv>
922
923 <refsynopsisdiv>
924 <programlisting xml:id="man.endnotes.are.numbered.frag">
925 &lt;xsl:param name="man.endnotes.are.numbered"&gt;1&lt;/xsl:param&gt;
926 </programlisting>
927 </refsynopsisdiv>
928
929 <refsection><info><title>Description</title></info>
930
931 <para>If the value of <parameter>man.endnotes.are.numbered</parameter> is
932 non-zero (the default), then for each non-empty<footnote>
933 <para>A &#8220;non-empty&#8221; notesource is one that looks like
934 this:<literallayout class="monospaced">  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"&gt;manpages&lt;/ulink&gt;</literallayout>
935 an &#8220;empty&#8221; notesource is on that looks like this:<literallayout class="monospaced">  &lt;ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/&gt;</literallayout>
936 </para></footnote> &#8220;notesource&#8221;:
937
938 <itemizedlist>
939   <listitem>
940     <para>a number (in square brackets) is displayed inline after the
941     rendered inline contents (if any) of the notesource</para>
942   </listitem>
943   <listitem>
944     <para>the contents of the notesource are included in a
945       numbered list of endnotes that is generated at the end of
946       each man page; the number for each endnote corresponds to
947       the inline number for the notesource with which it is
948       associated</para>
949   </listitem>
950 </itemizedlist>
951 The default heading for the list of endnotes is
952 <literal>NOTES</literal>. To output a different heading, set a value
953 for the <parameter>man.endnotes.section.heading</parameter>
954 parameter.</para>
955
956 <note>
957   <para>The endnotes list is also displayed (but without
958     numbers) if the value of
959     <parameter>man.endnotes.list.enabled</parameter> is
960     non-zero.</para>
961 </note>
962
963
964 <para>If the value of <parameter>man.endnotes.are.numbered</parameter> is
965 zero, numbering of endnotess is suppressed; only inline
966 contents (if any) of the notesource are displayed inline.
967 <important>
968   <para>If you are thinking about disabling endnote numbering by setting
969   the value of <parameter>man.endnotes.are.numbered</parameter> to zero,
970   before you do so, first take some time to carefully
971   consider the information needs and experiences of your users. The
972   square-bracketed numbers displayed inline after notesources may seem
973   obstrusive and aesthetically unpleasing<footnote><para>As far as notesources that are links, ytou might
974   think it would be better to just display URLs for non-empty
975   links inline, after their content, rather than displaying
976   square-bracketed numbers all over the place. But it's not better. In
977   fact, it's not even practical, because many (most) URLs for links
978   are too long to be displayed inline. They end up overflowing the
979   right margin. You can set a non-zero value for
980   <parameter>man.break.after.slash</parameter> parameter to deal with
981   that, but it could be argued that what you end up with is at least
982   as ugly, and definitely more obstrusive, then having short
983   square-bracketed numbers displayed inline.</para></footnote>,
984
985   but in a text-only output format, the
986   numbered-notesources/endnotes-listing mechanism is the only
987   practical way to handle this kind of content.</para>
988
989   <para>Also, users of &#8220;text based&#8221; browsers such as
990   <command>lynx</command> will already be accustomed to seeing inline
991   numbers for links. And various "man to html" applications, such as
992   the widely used <command><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://users.actrix.gen.nz/michael/vhman2html.html">man2html</link></command> (<literal>VH-Man2html</literal>)
993   application, can automatically turn URLs into "real" HTML hyperlinks
994   in output. So leaving <parameter>man.endnotes.are.numbered</parameter>
995   at its default (non-zero) value ensures that no information is
996   lost in your man-page output. It just gets
997   &#8220;rearranged&#8221;.</para>
998 </important>
999 </para>
1000 <para>The handling of empty links is not affected by this
1001 parameter. Empty links are handled simply by displaying their URLs
1002 inline. Empty links are never auto-numbered.</para>
1003
1004 <para>If you disable endnotes numbering, you should probably also set
1005 <parameter>man.font.links</parameter> to an empty value (to
1006 disable font formatting for links.</para>
1007 </refsection>
1008
1009 <refsection><info><title>Related Parameters</title></info>
1010   <para><parameter>man.endnotes.list.enabled</parameter>,
1011     <parameter>man.font.links</parameter></para>
1012 </refsection>
1013 </refentry>
1014
1015 <refentry version="5.0" xml:id="man.base.url.for.relative.links">
1016   <refmeta>
1017     <refentrytitle>man.base.url.for.relative.links</refentrytitle>
1018     <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
1019   </refmeta>
1020   <refnamediv>
1021     <refname>man.base.url.for.relative.links</refname>
1022     <refpurpose>Specifies a base URL for relative links</refpurpose>
1023   </refnamediv>
1024
1025   <refsynopsisdiv>
1026     <programlisting xml:id="man.base.url.for.relative.links.frag">&lt;xsl:param name="man.base.url.for.relative.links"&gt;[set $man.base.url.for.relative.links]/&lt;/xsl:param&gt;</programlisting>
1027   </refsynopsisdiv>
1028
1029   <refsection><info><title>Description</title></info>
1030
1031     <para>For any &#8220;notesource&#8221; listed in the auto-generated
1032       &#8220;NOTES&#8221; section of output man pages (which is generated when
1033       the value of the
1034       <parameter>man.endnotes.list.enabled</parameter> parameter
1035       is non-zero), if the notesource is a link source with a
1036       relative URI, the URI is displayed in output with the value
1037       of the
1038       <parameter>man.base.url.for.relative.links</parameter>
1039       parameter prepended to the value of the link URI.</para>
1040
1041     <note>
1042       <para>A link source is an notesource that references an
1043         external resource:
1044         <itemizedlist>
1045           <listitem>
1046             <para>a <tag>ulink</tag> element with a <tag class="attribute">url</tag> attribute</para>
1047           </listitem>
1048           <listitem>
1049             <para>any element with an <tag class="attribute">xlink:href</tag> attribute</para>
1050           </listitem>
1051           <listitem>
1052             <para>an <tag>imagedata</tag>, <tag>audiodata</tag>, or
1053               <tag>videodata</tag> element</para>
1054           </listitem>
1055         </itemizedlist>
1056       </para>
1057     </note>
1058
1059     <para>If you use relative URIs in link sources in your DocBook
1060       <tag>refentry</tag> source, and you leave
1061       <parameter>man.base.url.for.relative.links</parameter>
1062       unset, the relative links will appear &#8220;as is&#8221; in the &#8220;Notes&#8221;
1063       section of any man-page output generated from your source.
1064       That&#8217;s probably not what you want, because such relative
1065       links are only usable in the context of HTML output. So, to
1066       make the links meaningful and usable in the context of
1067       man-page output, set a value for
1068       <parameter>man.base.url.for.relative.links</parameter> that
1069       points to the online version of HTML output generated from
1070       your DocBook <tag>refentry</tag> source. For
1071       example:
1072       <programlisting>&lt;xsl:param name="man.base.url.for.relative.links"
1073         &gt;http://www.kernel.org/pub/software/scm/git/docs/&lt;/xsl:param&gt;</programlisting>
1074     </para>
1075
1076   </refsection>
1077
1078   <refsection><info><title>Related Parameters</title></info>
1079     <para><parameter>man.endnotes.list.enabled</parameter></para>
1080   </refsection>
1081
1082 </refentry>
1083
1084   </reference>
1085   <reference xml:id="lists">
1086   <title>Lists</title>
1087 <refentry version="5.0" xml:id="man.segtitle.suppress">
1088 <refmeta>
1089 <refentrytitle>man.segtitle.suppress</refentrytitle>
1090 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
1091 </refmeta>
1092 <refnamediv>
1093 <refname>man.segtitle.suppress</refname>
1094 <refpurpose>Suppress display of segtitle contents?</refpurpose>
1095 </refnamediv>
1096
1097 <refsynopsisdiv>
1098 <programlisting xml:id="man.segtitle.suppress.frag">
1099 &lt;xsl:param name="man.segtitle.suppress" select="0"&gt;&lt;/xsl:param&gt;</programlisting>
1100 </refsynopsisdiv>
1101
1102 <refsection><info><title>Description</title></info>
1103
1104 <para>If the value of <parameter>man.segtitle.suppress</parameter> is
1105 non-zero, then display of <tag>segtitle</tag> contents is
1106 suppressed in output.</para>
1107
1108 </refsection>
1109 </refentry>
1110
1111   </reference>
1112   <reference xml:id="charmap">
1113   <title>Character/string substitution</title>
1114 <refentry version="5.0" xml:id="man.charmap.enabled">
1115 <refmeta>
1116 <refentrytitle>man.charmap.enabled</refentrytitle>
1117 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
1118 </refmeta>
1119 <refnamediv>
1120 <refname>man.charmap.enabled</refname>
1121 <refpurpose>Apply character map before final output?</refpurpose>
1122 </refnamediv>
1123
1124 <refsynopsisdiv>
1125 <programlisting xml:id="man.charmap.enabled.frag">
1126 &lt;xsl:param name="man.charmap.enabled" select="1"&gt;&lt;/xsl:param&gt;
1127 </programlisting>
1128 </refsynopsisdiv>
1129
1130 <refsection><info><title>Description</title></info>
1131
1132 <para>If the value of the <parameter>man.charmap.enabled</parameter>
1133 parameter is non-zero, a "character map" is used to substitute certain
1134 Unicode symbols and special characters with appropriate roff/groff
1135 equivalents, just before writing each man-page file to the
1136 filesystem. If instead the value of
1137 <parameter>man.charmap.enabled</parameter> is zero, Unicode characters
1138 are passed through "as is".</para>
1139
1140 <refsection><info><title>Details</title></info>
1141
1142 <para>For converting certain Unicode symbols and special characters in
1143 UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
1144 equivalents in man-page output, the DocBook XSL Stylesheets
1145 distribution includes a <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl">roff character map</link> that is compliant with the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.w3.org/TR/xslt20/#character-maps">XSLT character
1146 map</link> format as detailed in the XSLT 2.0 specification. The map
1147 contains more than 800 character mappings and can be considered the
1148 standard roff character map for the distribution.</para>
1149
1150 <para>You can use the <parameter>man.charmap.uri</parameter>
1151 parameter to specify a URI for the location for an alternate roff
1152 character map to use in place of the standard roff character map
1153 provided in the distribution.</para>
1154
1155 <para>You can also use a subset of a character map. For details,
1156 see the <parameter>man.charmap.use.subset</parameter>,
1157 <parameter>man.charmap.subset.profile</parameter>, and
1158 <parameter>man.charmap.subset.profile.english</parameter>
1159 parameters.</para>
1160
1161 </refsection>
1162 </refsection>
1163 </refentry>
1164
1165 <refentry version="5.0" xml:id="man.charmap.uri">
1166 <refmeta>
1167 <refentrytitle>man.charmap.uri</refentrytitle>
1168 <refmiscinfo class="other" otherclass="datatype">uri</refmiscinfo>
1169 </refmeta>
1170 <refnamediv>
1171 <refname>man.charmap.uri</refname>
1172 <refpurpose>URI for custom roff character map</refpurpose>
1173 </refnamediv>
1174
1175 <refsynopsisdiv>
1176 <programlisting xml:id="man.charmap.uri.frag">
1177 &lt;xsl:param name="man.charmap.uri"&gt;&lt;/xsl:param&gt;
1178 </programlisting>
1179 </refsynopsisdiv>
1180
1181 <refsection><info><title>Description</title></info>
1182
1183 <para>For converting certain Unicode symbols and special characters in
1184 UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
1185 equivalents in man-page output, the DocBook XSL Stylesheets
1186 distribution includes an <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.w3.org/TR/xslt20/#character-maps">XSLT character
1187 map</link>. That character map can be considered the standard roff
1188 character map for the distribution.</para>
1189
1190 <para>If the value of the <parameter>man.charmap.uri</parameter>
1191 parameter is non-empty, that value is used as the URI for the location
1192 for an alternate roff character map to use in place of the standard
1193 roff character map provided in the distribution.</para>
1194
1195 <warning>
1196 <para>Do not set a value for <parameter>man.charmap.uri</parameter>
1197 unless you have a custom roff character map that differs from the
1198 standard one provided in the distribution.</para>
1199 </warning>
1200 </refsection>
1201 </refentry>
1202
1203 <refentry version="5.0" xml:id="man.charmap.use.subset">
1204 <refmeta>
1205 <refentrytitle>man.charmap.use.subset</refentrytitle>
1206 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
1207 </refmeta>
1208 <refnamediv>
1209 <refname>man.charmap.use.subset</refname>
1210 <refpurpose>Use subset of character map instead of full map?</refpurpose>
1211 </refnamediv>
1212
1213 <refsynopsisdiv>
1214 <programlisting xml:id="man.charmap.use.subset.frag">
1215 &lt;xsl:param name="man.charmap.use.subset" select="1"&gt;&lt;/xsl:param&gt;
1216 </programlisting>
1217 </refsynopsisdiv>
1218
1219 <refsection><info><title>Description</title></info>
1220
1221 <para>If the value of the
1222 <parameter>man.charmap.use.subset</parameter> parameter is non-zero,
1223 a subset of the roff character map is used instead of the full roff
1224 character map. The profile of the subset used is determined either
1225 by the value of the
1226 <parameter>man.charmap.subset.profile</parameter>
1227 parameter (if the source is not in English) or the
1228 <parameter>man.charmap.subset.profile.english</parameter>
1229 parameter (if the source is in English).</para>
1230
1231 <note>
1232   <para>You may want to experiment with setting a non-zero value of
1233   <parameter>man.charmap.use.subset</parameter>, so that the full
1234   character map is used. Depending on which XSLT engine you run,
1235   setting a non-zero value for
1236   <parameter>man.charmap.use.subset</parameter> may significantly
1237   increase the time needed to process your documents. Or it may
1238   not. For example, if you set it and run it with xsltproc, it seems
1239   to dramatically increase processing time; on the other hand, if you
1240   set it and run it with Saxon, it does not seem to increase
1241   processing time nearly as much.</para>
1242
1243   <para>If processing time is not a important concern and/or you can
1244   tolerate the increase in processing time imposed by using the full
1245   character map, set <parameter>man.charmap.use.subset</parameter> to
1246   zero.</para>
1247 </note>
1248
1249 <refsection><info><title>Details</title></info>
1250
1251 <para>For converting certain Unicode symbols and special characters in
1252 UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
1253 equivalents in man-page output, the DocBook XSL Stylesheets
1254 distribution includes a <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl">roff character map</link> that is compliant with the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.w3.org/TR/xslt20/#character-maps">XSLT character
1255 map</link> format as detailed in the XSLT 2.0 specification. The map
1256 contains more than 800 character mappings and can be considered the
1257 standard roff character map for the distribution.</para>
1258
1259 <note>
1260 <para>You can use the <parameter>man.charmap.uri</parameter>
1261 parameter to specify a URI for the location for an alternate roff
1262 character map to use in place of the standard roff character map
1263 provided in the distribution.</para>
1264 </note>
1265
1266 <para>Because it is not terrifically efficient to use the standard
1267 800-character character map in full -- and for most (or all) users,
1268 never necessary to use it in full -- the DocBook XSL Stylesheets
1269 support a mechanism for using, within any given character map, a
1270 subset of character mappings instead of the full set. You can use the
1271 <parameter>man.charmap.subset.profile</parameter> or
1272 <parameter>man.charmap.subset.profile.english</parameter>
1273 parameter to tune the profile of that subset to use.</para>
1274
1275 </refsection>
1276 </refsection>
1277 </refentry>
1278
1279 <refentry version="5.0" xml:id="man.charmap.subset.profile">
1280 <refmeta>
1281 <refentrytitle>man.charmap.subset.profile</refentrytitle>
1282 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
1283 </refmeta>
1284 <refnamediv>
1285 <refname>man.charmap.subset.profile</refname>
1286 <refpurpose>Profile of character map subset</refpurpose>
1287 </refnamediv>
1288
1289 <refsynopsisdiv>
1290 <programlisting xml:id="man.charmap.subset.profile.frag">
1291 &lt;xsl:param name="man.charmap.subset.profile"&gt;
1292 @*[local-name() = 'block'] = 'Miscellaneous Technical' or
1293 (@*[local-name() = 'block'] = 'C1 Controls And Latin-1 Supplement (Latin-1 Supplement)' and
1294  (@*[local-name() = 'class'] = 'symbols' or
1295   @*[local-name() = 'class'] = 'letters')
1296 ) or
1297 @*[local-name() = 'block'] = 'Latin Extended-A'
1298 or
1299 (@*[local-name() = 'block'] = 'General Punctuation' and
1300  (@*[local-name() = 'class'] = 'spaces' or
1301   @*[local-name() = 'class'] = 'dashes' or
1302   @*[local-name() = 'class'] = 'quotes' or
1303   @*[local-name() = 'class'] = 'bullets'
1304  )
1305 ) or
1306 @*[local-name() = 'name'] = 'HORIZONTAL ELLIPSIS' or
1307 @*[local-name() = 'name'] = 'WORD JOINER' or
1308 @*[local-name() = 'name'] = 'SERVICE MARK' or
1309 @*[local-name() = 'name'] = 'TRADE MARK SIGN' or
1310 @*[local-name() = 'name'] = 'ZERO WIDTH NO-BREAK SPACE'
1311 &lt;/xsl:param&gt;
1312 </programlisting>
1313 </refsynopsisdiv>
1314
1315 <refsection><info><title>Description</title></info>
1316
1317 <para>If the value of the
1318 <parameter>man.charmap.use.subset</parameter> parameter is non-zero,
1319 and your DocBook source is not written in English (that
1320   is, if the <tag class="attribute">lang</tag> or <tag class="attribute">xml:lang</tag> attribute on the root element
1321   in your DocBook source or on the first <tag>refentry</tag>
1322   element in your source has a value other than
1323   <literal>en</literal>), then the character-map subset specified
1324   by the <parameter>man.charmap.subset.profile</parameter>
1325   parameter is used instead of the full roff character map.</para>
1326
1327 <para>Otherwise, if the <tag class="attribute">lang</tag> or <tag class="attribute">xml:lang</tag> attribute on the root
1328   element in your DocBook
1329   source or on the first <tag>refentry</tag> element in your source
1330   has the value <literal>en</literal> or if it has no <tag class="attribute">lang</tag> or <tag class="attribute">xml:lang</tag> attribute, then the character-map
1331   subset specified by the
1332   <parameter>man.charmap.subset.profile.english</parameter>
1333   parameter is used instead of
1334   <parameter>man.charmap.subset.profile</parameter>.</para>
1335
1336 <para>The difference between the two subsets is that
1337   <parameter>man.charmap.subset.profile</parameter> provides
1338   mappings for characters in Western European languages that are
1339   not part of the Roman (English) alphabet (ASCII character set).</para>
1340
1341 <para>The value of <parameter>man.charmap.subset.profile</parameter>
1342 is a string representing an XPath expression that matches attribute
1343 names and values for <tag namespace="http://docbook.sf.net/xmlns/unichar/1.0">output-character</tag>
1344 elements in the character map.</para>
1345
1346 <para>The attributes supported in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl">standard roff character map included in the distribution</link> are:
1347 <variablelist>
1348   <varlistentry>
1349     <term>character</term>
1350     <listitem>
1351       <simpara>a raw Unicode character or numeric Unicode
1352       character-entity value (either in decimal or hex); all
1353       characters have this attribute</simpara>
1354     </listitem>
1355   </varlistentry>
1356   <varlistentry>
1357     <term>name</term>
1358     <listitem>
1359       <simpara>a standard full/long ISO/Unicode character name (e.g.,
1360       "OHM SIGN"); all characters have this attribute</simpara>
1361     </listitem>
1362   </varlistentry>
1363   <varlistentry>
1364     <term>block</term>
1365     <listitem>
1366       <simpara>a standard Unicode "block" name (e.g., "General
1367       Punctuation"); all characters have this attribute. For the full
1368       list of Unicode block names supported in the standard roff
1369       character map, see <xref linkend="BlocksAndClasses"/>.</simpara>
1370     </listitem>
1371   </varlistentry>
1372   <varlistentry>
1373     <term>class</term>
1374     <listitem>
1375       <simpara>a class of characters (e.g., "spaces"). Not all
1376       characters have this attribute; currently, it is used only with
1377       certain characters within the "C1 Controls And Latin-1
1378       Supplement" and "General Punctuation" blocks. For details, see
1379       <xref linkend="BlocksAndClasses"/>.</simpara>
1380     </listitem>
1381   </varlistentry>
1382   <varlistentry>
1383     <term>entity</term>
1384     <listitem>
1385       <simpara>an ISO entity name (e.g., "ohm"); not all characters
1386       have this attribute, because not all characters have ISO entity
1387       names; for example, of the 800 or so characters in the standard
1388       roff character map included in the distribution, only around 300
1389       have ISO entity names.
1390       </simpara>
1391     </listitem>
1392   </varlistentry>
1393   <varlistentry>
1394     <term>string</term>
1395     <listitem>
1396       <simpara>a string representing an roff/groff escape-code (with
1397       "@esc@" used in place of the backslash), or a simple ASCII
1398       string; all characters in the roff character map have this
1399       attribute</simpara>
1400     </listitem>
1401   </varlistentry>
1402 </variablelist>
1403 </para>
1404 <para>The value of <parameter>man.charmap.subset.profile</parameter>
1405 is evaluated as an XPath expression at run-time to select a portion of
1406 the roff character map to use. You can tune the subset used by adding
1407 or removing parts. For example, if you need to use a wide range of
1408 mathematical operators in a document, and you want to have them
1409 converted into roff markup properly, you might add the following:
1410
1411 <literallayout class="monospaced">  @*[local-name() = 'block'] ='MathematicalOperators' </literallayout>
1412
1413 That will cause a additional set of around 67 additional "math"
1414 characters to be converted into roff markup. </para>
1415
1416 <note>
1417 <para>Depending on which XSLT engine you use, either the EXSLT
1418 <function>dyn:evaluate</function> extension function (for xsltproc or
1419 Xalan) or <function>saxon:evaluate</function> extension function (for
1420 Saxon) are used to dynamically evaluate the value of
1421 <parameter>man.charmap.subset.profile</parameter> at run-time. If you
1422 don't use xsltproc, Saxon, Xalan -- or some other XSLT engine that
1423 supports <function>dyn:evaluate</function> -- you must either set the
1424 value of the <parameter>man.charmap.use.subset</parameter> parameter
1425 to zero and process your documents using the full character map
1426 instead, or set the value of the
1427 <parameter>man.charmap.enabled</parameter> parameter to zero instead
1428 (so that character-map processing is disabled completely.</para>
1429 </note>
1430
1431 <para>An alternative to using
1432 <parameter>man.charmap.subset.profile</parameter> is to create your
1433 own custom character map, and set the value of
1434 <parameter>man.charmap.uri</parameter> to the URI/filename for
1435 that. If you use a custom character map, you will probably want to
1436 include in it just the characters you want to use, and so you will
1437 most likely also want to set the value of
1438 <parameter>man.charmap.use.subset</parameter> to zero.</para>
1439 <para>You can create a
1440 custom character map by making a copy of the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docbook.sourceforge.net/snapshot/xsl/manpages/charmap.groff.xsl">standard roff character map</link> provided in the distribution, and
1441 then adding to, changing, and/or deleting from that.</para>
1442
1443 <caution>
1444 <para>If you author your DocBook XML source in UTF-8 or UTF-16
1445 encoding and aren't sure what OSes or environments your man-page
1446 output might end up being viewed on, and not sure what version of
1447 nroff/groff those environments might have, you should be careful about
1448 what Unicode symbols and special characters you use in your source and
1449 what parts you add to the value of
1450 <parameter>man.charmap.subset.profile</parameter>.</para>
1451 <para>Many of the escape codes used are specific to groff and using
1452 them may not provide the expected output on an OS or environment that
1453 uses nroff instead of groff.</para>
1454 <para>On the other hand, if you intend for your man-page output to be
1455 viewed only on modern systems (for example, GNU/Linux systems, FreeBSD
1456 systems, or Cygwin environments) that have a good, up-to-date groff,
1457 then you can safely include a wide range of Unicode symbols and
1458 special characters in your UTF-8 or UTF-16 encoded DocBook XML source
1459 and add any of the supported Unicode block names to the value of
1460 <parameter>man.charmap.subset.profile</parameter>.</para>
1461 </caution>
1462
1463
1464 <para>For other details, see the documentation for the
1465 <parameter>man.charmap.use.subset</parameter> parameter.</para>
1466
1467 <refsection xml:id="BlocksAndClasses"><info><title>Supported Unicode block names and "class" values</title></info>
1468   
1469
1470   <para>Below is the full list of Unicode block names and "class"
1471   values supported in the standard roff stylesheet provided in the
1472   distribution, along with a description of which codepoints from the
1473   Unicode range corresponding to that block name or block/class
1474   combination are supported.</para>
1475
1476   <itemizedlist>
1477     <listitem>
1478       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=C1%20Controls%20and%20Latin-1%20Supplement%20(Latin-1%20Supplement)">C1 Controls And Latin-1 Supplement (Latin-1 Supplement)</link> (x00a0 to x00ff)
1479       <itemizedlist><info><title>class values</title></info>
1480         
1481         <listitem>
1482           <para>symbols</para>
1483         </listitem>
1484         <listitem>
1485           <para>letters</para>
1486         </listitem>
1487       </itemizedlist></para>
1488     </listitem>
1489     <listitem>
1490       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Latin%20Extended-A">Latin Extended-A</link> (x0100 to x017f, partial)</para>
1491     </listitem>
1492     <listitem>
1493       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Spacing%20Modifier%20Letters">Spacing Modifier Letters</link> (x02b0 to x02ee, partial)</para>
1494     </listitem>
1495     <listitem>
1496       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Greek%20and%20Coptic">Greek and Coptic</link> (x0370 to x03ff, partial)</para>
1497     </listitem>
1498     <listitem>
1499       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=General%20Punctuation">General Punctuation</link> (x2000 to x206f, partial)
1500       <itemizedlist><info><title>class values</title></info>
1501         
1502         <listitem>
1503           <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;start=8192&amp;end=8203">spaces</link></para>
1504         </listitem>
1505         <listitem>
1506           <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;start=8208&amp;end=8213">dashes</link></para>
1507         </listitem>
1508         <listitem>
1509           <para>quotes</para>
1510         </listitem>
1511         <listitem>
1512           <para>daggers</para>
1513         </listitem>
1514         <listitem>
1515           <para>bullets</para>
1516         </listitem>
1517         <listitem>
1518           <para>leaders</para>
1519         </listitem>
1520         <listitem>
1521           <para>primes</para>
1522         </listitem>
1523       </itemizedlist>
1524       </para>
1525     </listitem>
1526     <listitem>
1527       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Superscripts%20and%20Subscripts">Superscripts and Subscripts</link> (x2070 to x209f)</para>
1528     </listitem>
1529     <listitem>
1530       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Currency%20Symbols">Currency Symbols</link> (x20a0 to x20b1)</para>
1531     </listitem>
1532     <listitem>
1533       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Letterlike%20Symbols">Letterlike Symbols</link> (x2100 to x214b)</para>
1534     </listitem>
1535     <listitem>
1536       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Number%20Forms">Number Forms</link> (x2150 to x218f)</para>
1537     </listitem>
1538     <listitem>
1539       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Arrows">Arrows</link> (x2190 to x21ff, partial)</para>
1540     </listitem>
1541     <listitem>
1542       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Mathematical%20Operators">Mathematical Operators</link> (x2200 to x22ff, partial)</para>
1543     </listitem>
1544     <listitem>
1545       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Control%20Pictures">Control Pictures</link> (x2400 to x243f)</para>
1546     </listitem>
1547     <listitem>
1548       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Enclosed%20Alphanumerics">Enclosed Alphanumerics</link> (x2460 to x24ff)</para>
1549     </listitem>
1550     <listitem>
1551       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Geometric%20Shapes">Geometric Shapes</link> (x25a0 to x25f7, partial)</para>
1552     </listitem>
1553     <listitem>
1554       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Miscellaneous%20Symbols">Miscellaneous Symbols</link> (x2600 to x26ff, partial)</para>
1555     </listitem>
1556     <listitem>
1557       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Dingbats">Dingbats</link> (x2700 to x27be, partial)</para>
1558     </listitem>
1559     <listitem>
1560       <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://zvon.org/other/charSearch/PHP/search.php?searchType=103&amp;id=Alphabetic%20Presentation%20Forms">Alphabetic Presentation Forms</link> (xfb00 to xfb04 only)</para>
1561     </listitem>
1562   </itemizedlist>
1563 </refsection>
1564 </refsection>
1565 </refentry>
1566
1567 <refentry version="5.0" xml:id="man.charmap.subset.profile.english">
1568 <refmeta>
1569 <refentrytitle>man.charmap.subset.profile.english</refentrytitle>
1570 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
1571 </refmeta>
1572 <refnamediv>
1573 <refname>man.charmap.subset.profile.english</refname>
1574 <refpurpose>Profile of character map subset</refpurpose>
1575 </refnamediv>
1576
1577 <refsynopsisdiv>
1578 <programlisting xml:id="man.charmap.subset.profile.english.frag">
1579 &lt;xsl:param name="man.charmap.subset.profile.english"&gt;
1580 @*[local-name() = 'block'] = 'Miscellaneous Technical' or
1581 (@*[local-name() = 'block'] = 'C1 Controls And Latin-1 Supplement (Latin-1 Supplement)' and
1582  @*[local-name() = 'class'] = 'symbols')
1583 or
1584 (@*[local-name() = 'block'] = 'General Punctuation' and
1585  (@*[local-name() = 'class'] = 'spaces' or
1586   @*[local-name() = 'class'] = 'dashes' or
1587   @*[local-name() = 'class'] = 'quotes' or
1588   @*[local-name() = 'class'] = 'bullets'
1589  )
1590 ) or
1591 @*[local-name() = 'name'] = 'HORIZONTAL ELLIPSIS' or
1592 @*[local-name() = 'name'] = 'WORD JOINER' or
1593 @*[local-name() = 'name'] = 'SERVICE MARK' or
1594 @*[local-name() = 'name'] = 'TRADE MARK SIGN' or
1595 @*[local-name() = 'name'] = 'ZERO WIDTH NO-BREAK SPACE'
1596 &lt;/xsl:param&gt;
1597 </programlisting>
1598 </refsynopsisdiv>
1599
1600 <refsection><info><title>Description</title></info>
1601
1602 <para>If the value of the
1603   <parameter>man.charmap.use.subset</parameter> parameter is
1604   non-zero, and your DocBook source is written in English (that
1605   is, if its <tag class="attribute">lang</tag> or <tag class="attribute">xml:lang</tag> attribute on the root element
1606   in your DocBook source or on the first <tag>refentry</tag>
1607   element in your source has the value <literal>en</literal> or if
1608   it has no <tag class="attribute">lang</tag> or <tag class="attribute">xml:lang</tag> attribute), then the
1609   character-map subset specified by the
1610   <parameter>man.charmap.subset.profile.english</parameter>
1611   parameter is used instead of the full roff character map.</para>
1612
1613 <para>Otherwise, if the <tag class="attribute">lang</tag> or <tag class="attribute">xml:lang</tag> attribute
1614   on the root element in your DocBook source or on the first
1615   <tag>refentry</tag> element in your source has a value other
1616   than <literal>en</literal>, then the character-map subset
1617   specified by the
1618   <parameter>man.charmap.subset.profile</parameter> parameter is
1619   used instead of
1620   <parameter>man.charmap.subset.profile.english</parameter>.</para>
1621
1622 <para>The difference between the two subsets is that
1623   <parameter>man.charmap.subset.profile</parameter> provides
1624   mappings for characters in Western European languages that are
1625   not part of the Roman (English) alphabet (ASCII character set).</para>
1626
1627 <para>The value of <parameter>man.charmap.subset.profile.english</parameter>
1628 is a string representing an XPath expression that matches attribute
1629 names and values for <tag namespace="http://docbook.sf.net/xmlns/unichar/1.0">output-character</tag> elements in the character map.</para>
1630
1631 <para>For other details, see the documentation for the
1632 <parameter>man.charmap.subset.profile.english</parameter> and
1633 <parameter>man.charmap.use.subset</parameter> parameters.</para>
1634
1635 </refsection>
1636 </refentry>
1637
1638 <refentry version="5.0" xml:id="man.string.subst.map.local.pre">
1639 <refmeta>
1640 <refentrytitle>man.string.subst.map.local.pre</refentrytitle>
1641 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
1642 </refmeta>
1643 <refnamediv>
1644 <refname>man.string.subst.map.local.pre</refname>
1645 <refpurpose>Specifies &#8220;local&#8221; string substitutions</refpurpose>
1646 </refnamediv>
1647
1648 <refsynopsisdiv>
1649 <programlisting xml:id="man.string.subst.map.local.pre.frag">
1650   &lt;xsl:param name="man.string.subst.map.local.pre"&gt;&lt;/xsl:param&gt;
1651 </programlisting>
1652 </refsynopsisdiv>
1653
1654 <refsection><info><title>Description</title></info>
1655
1656 <para>Use the <parameter>man.string.subst.map.local.pre</parameter>
1657 parameter to specify any &#8220;local&#8221; string substitutions to perform over
1658 the entire roff source for each man page <emphasis>before</emphasis>
1659 performing the string substitutions specified by the <parameter>man.string.subst.map</parameter> parameter.</para>
1660
1661 <para>For details about the format of this parameter, see the
1662 documentation for the <parameter>man.string.subst.map</parameter>
1663 parameter.</para>
1664
1665 </refsection>
1666 </refentry>
1667
1668 <refentry version="5.0" xml:id="man.string.subst.map">
1669 <refmeta>
1670 <refentrytitle>man.string.subst.map</refentrytitle>
1671 <refmiscinfo class="other" otherclass="datatype">rtf</refmiscinfo>
1672 </refmeta>
1673 <refnamediv>
1674 <refname>man.string.subst.map</refname>
1675 <refpurpose>Specifies a set of string substitutions</refpurpose>
1676 </refnamediv>
1677
1678 <refsynopsisdiv>
1679 <programlisting xml:id="man.string.subst.map.frag">
1680 &lt;xsl:param name="man.string.subst.map"&gt;
1681
1682   &lt;!-- * remove no-break marker at beginning of line (stylesheet artifact) --&gt; 
1683   &lt;ss:substitution oldstring="&#9618;&#9600;" newstring="&#9618;"&gt;&lt;/ss:substitution&gt;
1684   &lt;!-- * replace U+2580 no-break marker (stylesheet-added) w/ no-break space --&gt;
1685   &lt;ss:substitution oldstring="&#9600;" newstring="\ "&gt;&lt;/ss:substitution&gt;
1686
1687   &lt;!-- ==================================================================== --&gt;
1688
1689   &lt;!-- * squeeze multiple newlines before a roff request  --&gt;
1690   &lt;ss:substitution oldstring="
1691
1692 ." newstring="
1693 ."&gt;&lt;/ss:substitution&gt;
1694   &lt;!-- * remove any .sp instances that directly precede a .PP  --&gt;
1695   &lt;ss:substitution oldstring=".sp
1696 .PP" newstring=".PP"&gt;&lt;/ss:substitution&gt;
1697   &lt;!-- * remove any .sp instances that directly follow a .PP  --&gt;
1698   &lt;ss:substitution oldstring=".sp
1699 .sp" newstring=".sp"&gt;&lt;/ss:substitution&gt;
1700   &lt;!-- * squeeze multiple .sp instances into a single .sp--&gt;
1701   &lt;ss:substitution oldstring=".PP
1702 .sp" newstring=".PP"&gt;&lt;/ss:substitution&gt;
1703   &lt;!-- * squeeze multiple newlines after start of no-fill (verbatim) env. --&gt;
1704   &lt;ss:substitution oldstring=".nf
1705
1706 " newstring=".nf
1707 "&gt;&lt;/ss:substitution&gt;
1708   &lt;!-- * squeeze multiple newlines after REstoring margin --&gt;
1709   &lt;ss:substitution oldstring=".RE
1710
1711 " newstring=".RE
1712 "&gt;&lt;/ss:substitution&gt;
1713   &lt;!-- * U+2591 is a marker we add before and after every Parameter in --&gt;
1714   &lt;!-- * Funcprototype output --&gt;
1715   &lt;ss:substitution oldstring="&#9617;" newstring=" "&gt;&lt;/ss:substitution&gt;
1716   &lt;!-- * U+2592 is a marker we add for the newline before output of &lt;sbr&gt;; --&gt;
1717   &lt;ss:substitution oldstring="&#9618;" newstring="
1718 "&gt;&lt;/ss:substitution&gt;
1719   &lt;!-- * --&gt;
1720   &lt;!-- * Now deal with some other characters that are added by the --&gt;
1721   &lt;!-- * stylesheets during processing. --&gt;
1722   &lt;!-- * --&gt;
1723   &lt;!-- * bullet --&gt;
1724   &lt;ss:substitution oldstring="&#8226;" newstring="\(bu"&gt;&lt;/ss:substitution&gt;
1725   &lt;!-- * left double quote --&gt;
1726   &lt;ss:substitution oldstring="&#8220;" newstring="\(lq"&gt;&lt;/ss:substitution&gt;
1727   &lt;!-- * right double quote --&gt;
1728   &lt;ss:substitution oldstring="&#8221;" newstring="\(rq"&gt;&lt;/ss:substitution&gt;
1729   &lt;!-- * left single quote --&gt;
1730   &lt;ss:substitution oldstring="&#8216;" newstring="\(oq"&gt;&lt;/ss:substitution&gt;
1731   &lt;!-- * right single quote --&gt;
1732   &lt;ss:substitution oldstring="&#8217;" newstring="\(cq"&gt;&lt;/ss:substitution&gt;
1733   &lt;!-- * copyright sign --&gt;
1734   &lt;ss:substitution oldstring="&#169;" newstring="\(co"&gt;&lt;/ss:substitution&gt;
1735   &lt;!-- * registered sign --&gt;
1736   &lt;ss:substitution oldstring="&#174;" newstring="\(rg"&gt;&lt;/ss:substitution&gt;
1737   &lt;!-- * ...servicemark... --&gt;
1738   &lt;!-- * There is no groff equivalent for it. --&gt;
1739   &lt;ss:substitution oldstring="&#8480;" newstring="(SM)"&gt;&lt;/ss:substitution&gt;
1740   &lt;!-- * ...trademark... --&gt;
1741   &lt;!-- * We don't do "\(tm" because for console output, --&gt;
1742   &lt;!-- * groff just renders that as "tm"; that is: --&gt;
1743   &lt;!-- * --&gt;
1744   &lt;!-- *   Product&amp;#x2122; -&gt; Producttm --&gt;
1745   &lt;!-- * --&gt;
1746   &lt;!-- * So we just make it to "(TM)" instead; thus: --&gt;
1747   &lt;!-- * --&gt;
1748   &lt;!-- *   Product&amp;#x2122; -&gt; Product(TM) --&gt;
1749   &lt;ss:substitution oldstring="&#8482;" newstring="(TM)"&gt;&lt;/ss:substitution&gt;
1750
1751 &lt;/xsl:param&gt;
1752 </programlisting>
1753 </refsynopsisdiv>
1754
1755 <refsection><info><title>Description</title></info>
1756
1757 <para>The <parameter>man.string.subst.map</parameter> parameter
1758 contains <link linkend="map">a map</link> that specifies a set of
1759 string substitutions to perform over the entire roff source for each
1760 man page, either just before generating final man-page output (that
1761 is, before writing man-page files to disk) or, if the value of the
1762 <parameter>man.charmap.enabled</parameter> parameter is non-zero,
1763 before applying the roff character map.</para>
1764
1765 <para>You can use <parameter>man.string.subst.map</parameter> as a
1766 &#8220;lightweight&#8221; character map to perform &#8220;essential&#8221; substitutions --
1767 that is, substitutions that are <emphasis>always</emphasis> performed,
1768 even if the value of the <parameter>man.charmap.enabled</parameter>
1769 parameter is zero. For example, you can use it to replace quotation
1770 marks or other special characters that are generated by the DocBook
1771 XSL stylesheets for a particular locale setting (as opposed to those
1772 characters that are actually in source XML documents), or to replace
1773 any special characters that may be automatically generated by a
1774 particular customization of the DocBook XSL stylesheets.</para>
1775
1776 <warning>
1777   <para>Do you not change value of the
1778   <parameter>man.string.subst.map</parameter> parameter unless you are
1779   sure what you are doing. First consider adding your
1780   string-substitution mappings to either or both of the following
1781   parameters:
1782   <variablelist>
1783     <varlistentry>
1784       <term><parameter>man.string.subst.map.local.pre</parameter></term>
1785       <listitem><para>applied before
1786       <parameter>man.string.subst.map</parameter></para></listitem>
1787     </varlistentry>
1788     <varlistentry>
1789       <term><parameter>man.string.subst.map.local.post</parameter></term>
1790       <listitem><para>applied after
1791       <parameter>man.string.subst.map</parameter></para></listitem>
1792     </varlistentry>
1793   </variablelist>
1794   By default, both of those parameters contain no
1795   string substitutions. They are intended as a means for you to
1796   specify your own local string-substitution mappings.</para>
1797
1798   <para>If you remove any of default mappings from the value of the
1799   <parameter>man.string.subst.map</parameter> parameter, you are
1800   likely to end up with broken output. And be very careful about adding
1801   anything to it; it&#8217;s used for doing string substitution over the
1802   entire roff source of each man page &#8211; it causes target strings to be
1803   replaced in roff requests and escapes, not just in the visible
1804   contents of the page.</para>
1805
1806 </warning>
1807
1808 <refsection xml:id="map">
1809   <info>
1810     <title>Contents of the substitution map</title>
1811   </info>
1812   <para>The string-substitution map contains one or more
1813   <tag>ss:substitution</tag> elements, each of which has two
1814   attributes:
1815   <variablelist>
1816     <varlistentry>
1817       <term>oldstring</term>
1818       <listitem>
1819         <simpara>string to replace</simpara>
1820       </listitem>
1821     </varlistentry>
1822     <varlistentry>
1823       <term>newstring</term>
1824       <listitem>
1825         <simpara>string with which to replace <tag class="attribute">oldstring</tag></simpara>
1826       </listitem>
1827     </varlistentry>
1828   </variablelist>
1829   It may also include XML comments (that is, delimited with
1830   "<literal>&lt;!--</literal>" and "<literal>--&gt;</literal>").
1831   </para>
1832 </refsection>
1833
1834 </refsection>
1835 </refentry>
1836
1837 <refentry version="5.0" xml:id="man.string.subst.map.local.post">
1838 <refmeta>
1839 <refentrytitle>man.string.subst.map.local.post</refentrytitle>
1840 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
1841 </refmeta>
1842 <refnamediv>
1843 <refname>man.string.subst.map.local.post</refname>
1844 <refpurpose>Specifies &#8220;local&#8221; string substitutions</refpurpose>
1845 </refnamediv>
1846
1847 <refsynopsisdiv>
1848 <programlisting xml:id="man.string.subst.map.local.post.frag">
1849 &lt;xsl:param name="man.string.subst.map.local.post"&gt;&lt;/xsl:param&gt;
1850 </programlisting>
1851 </refsynopsisdiv>
1852
1853 <refsection><info><title>Description</title></info>
1854
1855 <para>Use the <parameter>man.string.subst.map.local.post</parameter>
1856 parameter to specify any &#8220;local&#8221; string substitutions to perform over
1857 the entire roff source for each man page <emphasis>after</emphasis>
1858 performing the string substitutions specified by the <parameter>man.string.subst.map</parameter> parameter.</para>
1859
1860 <para>For details about the format of this parameter, see the
1861 documentation for the <parameter>man.string.subst.map</parameter>
1862 parameter.</para>
1863
1864 </refsection>
1865 </refentry>
1866
1867   </reference>
1868   <reference xml:id="refmeta">
1869   <title>Refentry metadata gathering</title>
1870 <refentry version="5.0" xml:id="refentry.meta.get.quietly">
1871 <refmeta>
1872 <refentrytitle>refentry.meta.get.quietly</refentrytitle>
1873 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
1874 </refmeta>
1875 <refnamediv>
1876 <refname>refentry.meta.get.quietly</refname>
1877 <refpurpose>Suppress notes and warnings when gathering refentry metadata?</refpurpose>
1878 </refnamediv>
1879
1880 <refsynopsisdiv>
1881 <programlisting xml:id="refentry.meta.get.quietly.frag">
1882 &lt;xsl:param name="refentry.meta.get.quietly" select="0"&gt;&lt;/xsl:param&gt;
1883 </programlisting>
1884 </refsynopsisdiv>
1885
1886 <refsection><info><title>Description</title></info>
1887
1888 <para>If zero (the default), notes and warnings about &#8220;missing&#8221; markup
1889 are generated during gathering of refentry metadata. If non-zero, the
1890 metadata is gathered &#8220;quietly&#8221; -- that is, the notes and warnings are
1891 suppressed.</para>
1892
1893 <tip>
1894   <para>If you are processing a large amount of <tag>refentry</tag>
1895   content, you may be able to speed up processing significantly by
1896   setting a non-zero value for
1897   <parameter>refentry.meta.get.quietly</parameter>.</para>
1898 </tip>
1899
1900 </refsection>
1901 </refentry>
1902
1903 <refentry version="5.0" xml:id="refentry.date.profile">
1904 <refmeta>
1905 <refentrytitle>refentry.date.profile</refentrytitle>
1906 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
1907 </refmeta>
1908 <refnamediv>
1909 <refname>refentry.date.profile</refname>
1910 <refpurpose>Specifies profile for refentry "date" data</refpurpose>
1911 </refnamediv>
1912
1913 <refsynopsisdiv>
1914 <programlisting xml:id="refentry.date.profile.frag">
1915 &lt;xsl:param name="refentry.date.profile"&gt;
1916   (($info[//date])[last()]/date)[1]|
1917   (($info[//pubdate])[last()]/pubdate)[1]
1918 &lt;/xsl:param&gt;
1919 </programlisting>
1920 </refsynopsisdiv>
1921
1922 <refsection><info><title>Description</title></info>
1923
1924 <para>The value of <parameter>refentry.date.profile</parameter> is a
1925 string representing an XPath expression. It is evaluated at run-time
1926 and used only if <parameter>refentry.date.profile.enabled</parameter>
1927 is non-zero. Otherwise, the <tag>refentry</tag> metadata-gathering
1928 logic "hard coded" into the stylesheets is used.</para>
1929
1930 <para> The <literal>man(7)</literal> man page describes this content
1931 as "the date of the last revision". In man pages, it is the content
1932 that is usually displayed in the center footer.</para>
1933
1934 </refsection>
1935 </refentry>
1936
1937 <refentry version="5.0" xml:id="refentry.date.profile.enabled">
1938 <refmeta>
1939 <refentrytitle>refentry.date.profile.enabled</refentrytitle>
1940 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
1941 </refmeta>
1942 <refnamediv>
1943 <refname>refentry.date.profile.enabled</refname>
1944 <refpurpose>Enable refentry "date" profiling?</refpurpose>
1945 </refnamediv>
1946
1947 <refsynopsisdiv>
1948 <programlisting xml:id="refentry.date.profile.enabled.frag">
1949 &lt;xsl:param name="refentry.date.profile.enabled"&gt;0&lt;/xsl:param&gt;</programlisting>
1950 </refsynopsisdiv>
1951
1952 <refsection><info><title>Description</title></info>
1953
1954 <para>If the value of
1955 <parameter>refentry.date.profile.enabled</parameter> is non-zero, then
1956 during <tag>refentry</tag> metadata gathering, the info profile
1957 specified by the customizable
1958 <parameter>refentry.date.profile</parameter> parameter is used.</para>
1959
1960 <para>If instead the value of
1961 <parameter>refentry.date.profile.enabled</parameter> is zero (the
1962 default), then "hard coded" logic within the DocBook XSL stylesheets
1963 is used for gathering <tag>refentry</tag> "date" data.</para>
1964
1965 <para>If you find that the default <tag>refentry</tag>
1966 metadata-gathering behavior is causing incorrect "date" data to show
1967 up in your output, then consider setting a non-zero value for
1968 <parameter>refentry.date.profile.enabled</parameter> and adjusting the
1969 value of <parameter>refentry.date.profile</parameter> to cause correct
1970 data to be gathered. </para>
1971
1972 <para>Note that the terms "source" and "date" have special meanings in
1973 this context. For details, see the documentation for the
1974 <parameter>refentry.date.profile</parameter> parameter.</para>
1975
1976 </refsection>
1977 </refentry>
1978
1979 <refentry version="5.0" xml:id="refentry.manual.profile">
1980 <refmeta>
1981 <refentrytitle>refentry.manual.profile</refentrytitle>
1982 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
1983 </refmeta>
1984 <refnamediv>
1985 <refname>refentry.manual.profile</refname>
1986 <refpurpose>Specifies profile for refentry "manual" data</refpurpose>
1987 </refnamediv>
1988
1989 <refsynopsisdiv>
1990 <programlisting xml:id="refentry.manual.profile.frag">
1991 &lt;xsl:param name="refentry.manual.profile"&gt;
1992   (($info[//title])[last()]/title)[1]|
1993   ../title/node()
1994 &lt;/xsl:param&gt;
1995 </programlisting>
1996 </refsynopsisdiv>
1997
1998 <refsection><info><title>Description</title></info>
1999
2000 <para>The value of <parameter>refentry.manual.profile</parameter> is
2001 a string representing an XPath expression. It is evaluated at
2002 run-time and used only if
2003 <parameter>refentry.manual.profile.enabled</parameter> is
2004 non-zero. Otherwise, the <tag>refentry</tag> metadata-gathering logic
2005 "hard coded" into the stylesheets is used.</para>
2006
2007 <para>In man pages, this content is usually displayed in the middle of
2008 the header of the page. The <literal>man(7)</literal> man page
2009 describes this as "the title of the manual (e.g., <citetitle>Linux
2010 Programmer's Manual</citetitle>)". Here are some examples from
2011 existing man pages:
2012 <itemizedlist>
2013   <listitem>
2014     <para><citetitle>dpkg utilities</citetitle>
2015     (<command>dpkg-name</command>)</para>
2016   </listitem>
2017   <listitem>
2018     <para><citetitle>User Contributed Perl Documentation</citetitle>
2019     (<command>GET</command>)</para>
2020   </listitem>
2021   <listitem>
2022     <para><citetitle>GNU Development Tools</citetitle>
2023     (<command>ld</command>)</para>
2024   </listitem>
2025   <listitem>
2026     <para><citetitle>Emperor Norton Utilities</citetitle>
2027     (<command>ddate</command>)</para>
2028   </listitem>
2029   <listitem>
2030     <para><citetitle>Debian GNU/Linux manual</citetitle>
2031     (<command>faked</command>)</para>
2032   </listitem>
2033   <listitem>
2034     <para><citetitle>GIMP Manual Pages</citetitle>
2035     (<command>gimp</command>)</para>
2036   </listitem>
2037   <listitem>
2038     <para><citetitle>KDOC Documentation System</citetitle>
2039     (<command>qt2kdoc</command>)</para>
2040   </listitem>
2041 </itemizedlist>
2042 </para>
2043
2044 </refsection>
2045 </refentry>
2046
2047 <refentry version="5.0" xml:id="refentry.manual.profile.enabled">
2048 <refmeta>
2049 <refentrytitle>refentry.manual.profile.enabled</refentrytitle>
2050 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2051 </refmeta>
2052 <refnamediv>
2053 <refname>refentry.manual.profile.enabled</refname>
2054 <refpurpose>Enable refentry "manual" profiling?</refpurpose>
2055 </refnamediv>
2056
2057 <refsynopsisdiv>
2058 <programlisting xml:id="refentry.manual.profile.enabled.frag">
2059 &lt;xsl:param name="refentry.manual.profile.enabled"&gt;0&lt;/xsl:param&gt;</programlisting>
2060 </refsynopsisdiv>
2061
2062 <refsection><info><title>Description</title></info>
2063
2064 <para>If the value of
2065 <parameter>refentry.manual.profile.enabled</parameter> is
2066 non-zero, then during <tag>refentry</tag> metadata gathering, the info
2067 profile specified by the customizable
2068 <parameter>refentry.manual.profile</parameter> parameter is
2069 used.</para>
2070
2071 <para>If instead the value of
2072 <parameter>refentry.manual.profile.enabled</parameter> is zero (the
2073 default), then "hard coded" logic within the DocBook XSL stylesheets
2074 is used for gathering <tag>refentry</tag> "manual" data.</para>
2075
2076 <para>If you find that the default <tag>refentry</tag>
2077 metadata-gathering behavior is causing incorrect "manual" data to show
2078 up in your output, then consider setting a non-zero value for
2079 <parameter>refentry.manual.profile.enabled</parameter> and adjusting
2080 the value of <parameter>refentry.manual.profile</parameter> to cause
2081 correct data to be gathered. </para>
2082
2083 <para>Note that the term "manual" has a special meanings in this
2084 context. For details, see the documentation for the
2085 <parameter>refentry.manual.profile</parameter> parameter.</para>
2086
2087 </refsection>
2088 </refentry>
2089
2090 <refentry version="5.0" xml:id="refentry.source.name.suppress">
2091 <refmeta>
2092 <refentrytitle>refentry.source.name.suppress</refentrytitle>
2093 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2094 </refmeta>
2095 <refnamediv>
2096 <refname>refentry.source.name.suppress</refname>
2097 <refpurpose>Suppress "name" part of refentry "source" contents?</refpurpose>
2098 </refnamediv>
2099
2100 <refsynopsisdiv>
2101 <programlisting xml:id="refentry.source.name.suppress.frag">
2102 &lt;xsl:param name="refentry.source.name.suppress"&gt;0&lt;/xsl:param&gt;</programlisting>
2103 </refsynopsisdiv>
2104
2105 <refsection><info><title>Description</title></info>
2106
2107 <para>If the value of
2108 <parameter>refentry.source.name.suppress</parameter> is non-zero, then
2109 during <tag>refentry</tag> metadata gathering, no "source name" data
2110 is added to the <tag>refentry</tag> "source" contents. Instead (unless
2111 <parameter>refentry.version.suppress</parameter> is also non-zero),
2112 only "version" data is added to the "source" contents.</para>
2113
2114 <para>If you find that the <tag>refentry</tag> metadata gathering
2115 mechanism is causing unwanted "source name" data to show up in your
2116 output -- for example, in the footer (or possibly header) of a man
2117 page -- then you might consider setting a non-zero value for
2118 <parameter>refentry.source.name.suppress</parameter>.</para>
2119
2120 <para>Note that the terms "source", "source name", and "version" have
2121 special meanings in this context. For details, see the documentation
2122 for the <parameter>refentry.source.name.profile</parameter>
2123 parameter.</para>
2124
2125 </refsection>
2126 </refentry>
2127
2128 <refentry version="5.0" xml:id="refentry.source.name.profile">
2129 <refmeta>
2130 <refentrytitle>refentry.source.name.profile</refentrytitle>
2131 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
2132 </refmeta>
2133 <refnamediv>
2134 <refname>refentry.source.name.profile</refname>
2135 <refpurpose>Specifies profile for refentry "source name" data</refpurpose>
2136 </refnamediv>
2137
2138 <refsynopsisdiv>
2139 <programlisting xml:id="refentry.source.name.profile.frag">
2140 &lt;xsl:param name="refentry.source.name.profile"&gt;
2141   (($info[//productname])[last()]/productname)[1]|
2142   (($info[//corpname])[last()]/corpname)[1]|
2143   (($info[//corpcredit])[last()]/corpcredit)[1]|
2144   (($info[//corpauthor])[last()]/corpauthor)[1]|
2145   (($info[//orgname])[last()]/orgname)[1]|
2146   (($info[//publishername])[last()]/publishername)[1]
2147 &lt;/xsl:param&gt;
2148 </programlisting>
2149 </refsynopsisdiv>
2150
2151 <refsection><info><title>Description</title></info>
2152
2153 <para>The value of <parameter>refentry.source.name.profile</parameter>
2154 is a string representing an XPath expression. It is evaluated at
2155 run-time and used only if
2156 <parameter>refentry.source.name.profile.enabled</parameter> is
2157 non-zero. Otherwise, the <tag>refentry</tag> metadata-gathering logic
2158 "hard coded" into the stylesheets is used.</para>
2159
2160 <para>A "source name" is one part of a (potentially) two-part
2161 <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>
2162 "source" field. In man pages, it is usually displayed in the left
2163 footer of the page. It typically indicates the software system or
2164 product that the item documented in the man page belongs to. The
2165 <literal>man(7)</literal> man page describes it as "the source of
2166 the command", and provides the following examples:
2167 <itemizedlist>
2168   <listitem>
2169     <para>For binaries, use something like: GNU, NET-2, SLS
2170     Distribution, MCC Distribution.</para>
2171   </listitem>
2172   <listitem>
2173     <para>For system calls, use the version of the kernel that you
2174     are currently looking at: Linux 0.99.11.</para>
2175   </listitem>
2176   <listitem>
2177     <para>For library calls, use the source of the function: GNU, BSD
2178     4.3, Linux DLL 4.4.1.</para>
2179   </listitem>
2180 </itemizedlist>
2181 </para>
2182
2183 <para>In practice, there are many pages that simply have a Version
2184 number in the "source" field. So, it looks like what we have is a
2185 two-part field,
2186 <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>,
2187 where:
2188 <variablelist>
2189   <varlistentry>
2190     <term>Name</term>
2191     <listitem>
2192       <para>product name (e.g., BSD) or org. name (e.g., GNU)</para>
2193     </listitem>
2194   </varlistentry>
2195   <varlistentry>
2196     <term>Version</term>
2197     <listitem>
2198       <para>version number</para>
2199     </listitem>
2200   </varlistentry>
2201 </variablelist>
2202 Each part is optional. If the <replaceable>Name</replaceable> is a
2203 product name, then the <replaceable>Version</replaceable> is probably
2204 the version of the product. Or there may be no
2205 <replaceable>Name</replaceable>, in which case, if there is a
2206 <replaceable>Version</replaceable>, it is probably the version
2207 of the item itself, not the product it is part of. Or, if the
2208 <replaceable>Name</replaceable> is an organization name, then there
2209 probably will be no <replaceable>Version</replaceable>.</para>
2210 </refsection>
2211 </refentry>
2212
2213 <refentry version="5.0" xml:id="refentry.source.name.profile.enabled">
2214 <refmeta>
2215 <refentrytitle>refentry.source.name.profile.enabled</refentrytitle>
2216 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2217 </refmeta>
2218 <refnamediv>
2219 <refname>refentry.source.name.profile.enabled</refname>
2220 <refpurpose>Enable refentry "source name" profiling?</refpurpose>
2221 </refnamediv>
2222
2223 <refsynopsisdiv>
2224 <programlisting xml:id="refentry.source.name.profile.enabled.frag">
2225 &lt;xsl:param name="refentry.source.name.profile.enabled"&gt;0&lt;/xsl:param&gt;</programlisting>
2226 </refsynopsisdiv>
2227
2228 <refsection><info><title>Description</title></info>
2229
2230 <para>If the value of
2231 <parameter>refentry.source.name.profile.enabled</parameter> is
2232 non-zero, then during <tag>refentry</tag> metadata gathering, the info
2233 profile specified by the customizable
2234 <parameter>refentry.source.name.profile</parameter> parameter is
2235 used.</para>
2236
2237 <para>If instead the value of
2238 <parameter>refentry.source.name.profile.enabled</parameter> is zero (the
2239 default), then "hard coded" logic within the DocBook XSL stylesheets
2240 is used for gathering <tag>refentry</tag> "source name" data.</para>
2241
2242 <para>If you find that the default <tag>refentry</tag>
2243 metadata-gathering behavior is causing incorrect "source name" data to
2244 show up in your output, then consider setting a non-zero value for
2245 <parameter>refentry.source.name.profile.enabled</parameter> and
2246 adjusting the value of
2247 <parameter>refentry.source.name.profile</parameter> to cause correct
2248 data to be gathered. </para>
2249
2250 <para>Note that the terms "source" and "source name" have special
2251 meanings in this context. For details, see the documentation for the
2252 <parameter>refentry.source.name.profile</parameter> parameter.</para>
2253
2254 </refsection>
2255 </refentry>
2256
2257 <refentry version="5.0" xml:id="refentry.version.suppress">
2258 <refmeta>
2259 <refentrytitle>refentry.version.suppress</refentrytitle>
2260 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2261 </refmeta>
2262 <refnamediv>
2263 <refname>refentry.version.suppress</refname>
2264 <refpurpose>Suppress "version" part of refentry "source" contents?</refpurpose>
2265 </refnamediv>
2266
2267 <refsynopsisdiv>
2268 <programlisting xml:id="refentry.version.suppress.frag">
2269 &lt;xsl:param name="refentry.version.suppress"&gt;0&lt;/xsl:param&gt;</programlisting>
2270 </refsynopsisdiv>
2271
2272 <refsection><info><title>Description</title></info>
2273
2274 <para>If the value of <parameter>refentry.version.suppress</parameter>
2275 is non-zero, then during <tag>refentry</tag> metadata gathering, no
2276 "version" data is added to the <tag>refentry</tag> "source"
2277 contents. Instead (unless
2278 <parameter>refentry.source.name.suppress</parameter> is also
2279 non-zero), only "source name" data is added to the "source"
2280 contents.</para>
2281
2282 <para>If you find that the <tag>refentry</tag> metadata gathering
2283 mechanism is causing unwanted "version" data to show up in your output
2284 -- for example, in the footer (or possibly header) of a man page --
2285 then you might consider setting a non-zero value for
2286 <parameter>refentry.version.suppress</parameter>.</para>
2287
2288 <para>Note that the terms "source", "source name", and "version" have
2289 special meanings in this context. For details, see the documentation
2290 for the <parameter>refentry.source.name.profile</parameter>
2291 parameter.</para>
2292
2293 </refsection>
2294 </refentry>
2295
2296 <refentry version="5.0" xml:id="refentry.version.profile">
2297 <refmeta>
2298 <refentrytitle>refentry.version.profile</refentrytitle>
2299 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
2300 </refmeta>
2301 <refnamediv>
2302 <refname>refentry.version.profile</refname>
2303 <refpurpose>Specifies profile for refentry "version" data</refpurpose>
2304 </refnamediv>
2305
2306 <refsynopsisdiv>
2307 <programlisting xml:id="refentry.version.profile.frag">
2308 &lt;xsl:param name="refentry.version.profile"&gt;
2309   (($info[//productnumber])[last()]/productnumber)[1]|
2310   (($info[//edition])[last()]/edition)[1]|
2311   (($info[//releaseinfo])[last()]/releaseinfo)[1]
2312 &lt;/xsl:param&gt;
2313 </programlisting>
2314 </refsynopsisdiv>
2315
2316 <refsection><info><title>Description</title></info>
2317
2318 <para>The value of <parameter>refentry.version.profile</parameter> is
2319 a string representing an XPath expression. It is evaluated at
2320 run-time and used only if
2321 <parameter>refentry.version.profile.enabled</parameter> is
2322 non-zero. Otherwise, the <tag>refentry</tag> metadata-gathering logic
2323 "hard coded" into the stylesheets is used.</para>
2324
2325 <para>A "source.name" is one part of a (potentially) two-part
2326 <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>
2327 "source" field. For more details, see the documentation for the
2328 <parameter>refentry.source.name.profile</parameter> parameter.</para>
2329
2330 </refsection>
2331 </refentry>
2332
2333 <refentry version="5.0" xml:id="refentry.version.profile.enabled">
2334 <refmeta>
2335 <refentrytitle>refentry.version.profile.enabled</refentrytitle>
2336 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2337 </refmeta>
2338 <refnamediv>
2339 <refname>refentry.version.profile.enabled</refname>
2340 <refpurpose>Enable refentry "version" profiling?</refpurpose>
2341 </refnamediv>
2342
2343 <refsynopsisdiv>
2344 <programlisting xml:id="refentry.version.profile.enabled.frag">
2345 &lt;xsl:param name="refentry.version.profile.enabled"&gt;0&lt;/xsl:param&gt;</programlisting>
2346 </refsynopsisdiv>
2347
2348 <refsection><info><title>Description</title></info>
2349
2350 <para>If the value of
2351 <parameter>refentry.version.profile.enabled</parameter> is
2352 non-zero, then during <tag>refentry</tag> metadata gathering, the info
2353 profile specified by the customizable
2354 <parameter>refentry.version.profile</parameter> parameter is
2355 used.</para>
2356
2357 <para>If instead the value of
2358 <parameter>refentry.version.profile.enabled</parameter> is zero (the
2359 default), then "hard coded" logic within the DocBook XSL stylesheets
2360 is used for gathering <tag>refentry</tag> "version" data.</para>
2361
2362 <para>If you find that the default <tag>refentry</tag>
2363 metadata-gathering behavior is causing incorrect "version" data to show
2364 up in your output, then consider setting a non-zero value for
2365 <parameter>refentry.version.profile.enabled</parameter> and adjusting
2366 the value of <parameter>refentry.version.profile</parameter> to cause
2367 correct data to be gathered. </para>
2368
2369 <para>Note that the terms "source" and "version" have special
2370 meanings in this context. For details, see the documentation for the
2371 <parameter>refentry.version.profile</parameter> parameter.</para>
2372
2373 </refsection>
2374 </refentry>
2375
2376 <refentry version="5.0" xml:id="refentry.manual.fallback.profile">
2377 <refmeta>
2378 <refentrytitle>refentry.manual.fallback.profile</refentrytitle>
2379 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
2380 </refmeta>
2381 <refnamediv>
2382 <refname>refentry.manual.fallback.profile</refname>
2383 <refpurpose>Specifies profile of "fallback" for refentry "manual" data</refpurpose>
2384 </refnamediv>
2385
2386 <refsynopsisdiv>
2387 <programlisting xml:id="refentry.manual.fallback.profile.frag">
2388 &lt;xsl:param name="refentry.manual.fallback.profile"&gt;
2389 refmeta/refmiscinfo[not(@class = 'date')][1]/node()&lt;/xsl:param&gt;
2390 </programlisting>
2391 </refsynopsisdiv>
2392
2393 <refsection><info><title>Description</title></info>
2394
2395 <para>The value of
2396 <parameter>refentry.manual.fallback.profile</parameter> is a string
2397 representing an XPath expression. It is evaluated at run-time and
2398 used only if no "manual" data can be found by other means (that is,
2399 either using the <tag>refentry</tag> metadata-gathering logic "hard
2400 coded" in the stylesheets, or the value of
2401 <parameter>refentry.manual.profile</parameter>, if it is
2402 enabled).</para>
2403
2404 <important>
2405 <para>Depending on which XSLT engine you run, either the EXSLT
2406 <function>dyn:evaluate</function> extension function (for xsltproc or
2407 Xalan) or <function>saxon:evaluate</function> extension function (for
2408 Saxon) are used to dynamically evaluate the value of
2409 <parameter>refentry.manual.fallback.profile</parameter> at
2410 run-time. If you don't use xsltproc, Saxon, Xalan -- or some other
2411 XSLT engine that supports <function>dyn:evaluate</function> -- you
2412 must manually disable fallback processing by setting an empty value
2413 for the <parameter>refentry.manual.fallback.profile</parameter>
2414 parameter.</para>
2415 </important>
2416
2417 </refsection>
2418 </refentry>
2419
2420 <refentry version="5.0" xml:id="refentry.source.fallback.profile">
2421 <refmeta>
2422 <refentrytitle>refentry.source.fallback.profile</refentrytitle>
2423 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
2424 </refmeta>
2425 <refnamediv>
2426 <refname>refentry.source.fallback.profile</refname>
2427 <refpurpose>Specifies profile of "fallback" for refentry "source" data</refpurpose>
2428 </refnamediv>
2429
2430 <refsynopsisdiv>
2431 <programlisting xml:id="refentry.source.fallback.profile.frag">
2432 &lt;xsl:param name="refentry.source.fallback.profile"&gt;
2433 refmeta/refmiscinfo[not(@class = 'date')][1]/node()&lt;/xsl:param&gt;
2434 </programlisting>
2435 </refsynopsisdiv>
2436
2437 <refsection><info><title>Description</title></info>
2438
2439 <para>The value of
2440 <parameter>refentry.source.fallback.profile</parameter> is a string
2441 representing an XPath expression. It is evaluated at run-time and used
2442 only if no "source" data can be found by other means (that is, either
2443 using the <tag>refentry</tag> metadata-gathering logic "hard coded" in
2444 the stylesheets, or the value of the
2445 <parameter>refentry.source.name.profile</parameter> and
2446 <parameter>refentry.version.profile</parameter> parameters, if those
2447 are enabled).</para>
2448
2449 <important>
2450 <para>Depending on which XSLT engine you run, either the EXSLT
2451 <function>dyn:evaluate</function> extension function (for xsltproc or
2452 Xalan) or <function>saxon:evaluate</function> extension function (for
2453 Saxon) are used to dynamically evaluate the value of
2454 <parameter>refentry.source.fallback.profile</parameter> at
2455 run-time. If you don't use xsltproc, Saxon, Xalan -- or some other
2456 XSLT engine that supports <function>dyn:evaluate</function> -- you
2457 must manually disable fallback processing by setting an empty value
2458 for the <parameter>refentry.source.fallback.profile</parameter>
2459 parameter.</para>
2460 </important>
2461
2462 </refsection>
2463 </refentry>
2464
2465   </reference>
2466   <reference xml:id="th">
2467   <title>Page header/footer</title>
2468 <refentry version="5.0" xml:id="man.th.extra1.suppress">
2469 <refmeta>
2470 <refentrytitle>man.th.extra1.suppress</refentrytitle>
2471 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2472 </refmeta>
2473 <refnamediv>
2474 <refname>man.th.extra1.suppress</refname>
2475 <refpurpose>Suppress extra1 part of header/footer?</refpurpose>
2476 </refnamediv>
2477
2478 <refsynopsisdiv>
2479 <programlisting xml:id="man.th.extra1.suppress.frag">
2480 &lt;xsl:param name="man.th.extra1.suppress"&gt;0&lt;/xsl:param&gt;</programlisting>
2481 </refsynopsisdiv>
2482
2483 <refsection><info><title>Description</title></info>
2484
2485 <para>If the value of <parameter>man.th.extra1.suppress</parameter> is
2486 non-zero, then the <literal>extra1</literal> part of the
2487 <literal>.TH</literal> title line header/footer is suppressed.</para>
2488
2489 <para>The content of the <literal>extra1</literal> field is almost
2490 always displayed in the center footer of the page and is, universally,
2491 a date.</para>
2492
2493 </refsection>
2494 </refentry>
2495
2496 <refentry version="5.0" xml:id="man.th.extra2.suppress">
2497 <refmeta>
2498 <refentrytitle>man.th.extra2.suppress</refentrytitle>
2499 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2500 </refmeta>
2501 <refnamediv>
2502 <refname>man.th.extra2.suppress</refname>
2503 <refpurpose>Suppress extra2 part of header/footer?</refpurpose>
2504 </refnamediv>
2505
2506 <refsynopsisdiv>
2507 <programlisting xml:id="man.th.extra2.suppress.frag">
2508 &lt;xsl:param name="man.th.extra2.suppress"&gt;0&lt;/xsl:param&gt;</programlisting>
2509 </refsynopsisdiv>
2510
2511 <refsection><info><title>Description</title></info>
2512
2513 <para>If the value of <parameter>man.th.extra2.suppress</parameter> is
2514 non-zero, then the <literal>extra2</literal> part of the
2515 <literal>.TH</literal> title line header/footer is suppressed.</para>
2516
2517 <para>The content of the <literal>extra2</literal> field is usually
2518 displayed in the left footer of the page and is typically "source"
2519 data, often in the form
2520 <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>;
2521 for example, "GTK+ 1.2" (from the <literal>gtk-options(7)</literal>
2522 man page).</para>
2523
2524 <note>
2525   <para>You can use the
2526   <parameter>refentry.source.name.suppress</parameter> and
2527   <parameter>refentry.version.suppress</parameter> parameters to
2528   independently suppress the <replaceable>Name</replaceable> and
2529   <replaceable>Version</replaceable> parts of the
2530   <literal>extra2</literal> field.</para>
2531 </note>
2532
2533 </refsection>
2534 </refentry>
2535
2536 <refentry version="5.0" xml:id="man.th.extra3.suppress">
2537 <refmeta>
2538 <refentrytitle>man.th.extra3.suppress</refentrytitle>
2539 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2540 </refmeta>
2541 <refnamediv>
2542 <refname>man.th.extra3.suppress</refname>
2543 <refpurpose>Suppress extra3 part of header/footer?</refpurpose>
2544 </refnamediv>
2545
2546 <refsynopsisdiv>
2547 <programlisting xml:id="man.th.extra3.suppress.frag">
2548 &lt;xsl:param name="man.th.extra3.suppress"&gt;0&lt;/xsl:param&gt;</programlisting>
2549 </refsynopsisdiv>
2550
2551 <refsection><info><title>Description</title></info>
2552
2553 <para>If the value of <parameter>man.th.extra3.suppress</parameter> is
2554 non-zero, then the <literal>extra3</literal> part of the
2555 <literal>.TH</literal> title line header/footer is
2556 suppressed.</para>
2557
2558 <para>The content of the <literal>extra3</literal> field is usually
2559 displayed in the middle header of the page and is typically a "manual
2560 name"; for example, "GTK+ User's Manual" (from the
2561 <literal>gtk-options(7)</literal> man page).</para>
2562
2563 </refsection>
2564 </refentry>
2565
2566 <refentry version="5.0" xml:id="man.th.title.max.length">
2567 <refmeta>
2568 <refentrytitle>man.th.title.max.length</refentrytitle>
2569 <refmiscinfo class="other" otherclass="datatype">integer</refmiscinfo>
2570 </refmeta>
2571 <refnamediv>
2572 <refname>man.th.title.max.length</refname>
2573 <refpurpose>Maximum length of title in header/footer</refpurpose>
2574 </refnamediv>
2575
2576 <refsynopsisdiv>
2577 <programlisting xml:id="man.th.title.max.length.frag">
2578 &lt;xsl:param name="man.th.title.max.length"&gt;20&lt;/xsl:param&gt;
2579 </programlisting>
2580 </refsynopsisdiv>
2581
2582 <refsection><info><title>Description</title></info>
2583
2584 <para>Specifies the maximum permitted length of the title part of the
2585 man-page <literal>.TH</literal> title line header/footer. If the title
2586 exceeds the maxiumum specified, it is truncated down to the maximum
2587 permitted length.</para>
2588
2589 <refsection><info><title>Details</title></info>
2590   
2591
2592 <para>Every man page generated using the DocBook stylesheets has a
2593 title line, specified using the <literal>TH</literal> roff
2594 macro. Within that title line, there is always, at a minimum, a title,
2595 followed by a section value (representing a man "section" -- usually
2596 just a number).</para>
2597
2598 <para>The title and section are displayed, together, in the visible
2599 header of each page. Where in the header they are displayed depends on
2600 OS the man page is viewed on, and on what version of nroff/groff/man
2601 is used for viewing the page. But, at a minimum and across all
2602 systems, the title and section are displayed on the right-hand column
2603 of the header. On many systems -- those with a modern groff, including
2604 Linux systems -- they are displayed twice: both in the left and right
2605 columns of the header.</para>
2606
2607 <para>So if the length of the title exceeds a certain percentage of
2608 the column width in which the page is viewed, the left and right
2609 titles can end up overlapping, making them unreadable, or breaking to
2610 another line, which doesn't look particularly good.</para>
2611
2612 <para>So the stylesheets provide the
2613 <parameter>man.th.title.max.length</parameter> parameter as a means
2614 for truncating titles that exceed the maximum length that can be
2615 viewing properly in a page header.</para>
2616
2617 <para>The default value is reasonable but somewhat arbitrary. If you
2618 have pages with long titles, you may want to experiment with changing
2619 the value in order to achieve the correct aesthetic results.</para>
2620 </refsection>
2621
2622 </refsection>
2623 </refentry>
2624
2625 <refentry version="5.0" xml:id="man.th.extra2.max.length">
2626 <refmeta>
2627 <refentrytitle>man.th.extra2.max.length</refentrytitle>
2628 <refmiscinfo class="other" otherclass="datatype">integer</refmiscinfo>
2629 </refmeta>
2630 <refnamediv>
2631 <refname>man.th.extra2.max.length</refname>
2632 <refpurpose>Maximum length of extra2 in header/footer</refpurpose>
2633 </refnamediv>
2634
2635 <refsynopsisdiv>
2636 <programlisting xml:id="man.th.extra2.max.length.frag">
2637 &lt;xsl:param name="man.th.extra2.max.length"&gt;30&lt;/xsl:param&gt;
2638 </programlisting>
2639 </refsynopsisdiv>
2640
2641 <refsection><info><title>Description</title></info>
2642
2643 <para>Specifies the maximum permitted length of the
2644 <literal>extra2</literal> part of the man-page part of the
2645 <literal>.TH</literal> title line header/footer. If the
2646 <literal>extra2</literal> content exceeds the maxiumum specified, it
2647 is truncated down to the maximum permitted length.</para>
2648
2649 <para>The content of the <literal>extra2</literal> field is usually
2650 displayed in the left footer of the page and is typically "source"
2651 data indicating the software system or product that the item
2652 documented in the man page belongs to, often in the form
2653 <replaceable>Name</replaceable>&#160;<replaceable>Version</replaceable>;
2654 for example, "GTK+ 1.2" (from the <literal>gtk-options(7)</literal>
2655 man page).</para>
2656
2657 <para>The default value for this parameter is reasonable but somewhat
2658 arbitrary. If you are processing pages with long "source" information,
2659 you may want to experiment with changing the value in order to achieve
2660 the correct aesthetic results.</para>
2661 </refsection>
2662 </refentry>
2663
2664 <refentry version="5.0" xml:id="man.th.extra3.max.length">
2665 <refmeta>
2666 <refentrytitle>man.th.extra3.max.length</refentrytitle>
2667 <refmiscinfo class="other" otherclass="datatype">integer</refmiscinfo>
2668 </refmeta>
2669 <refnamediv>
2670 <refname>man.th.extra3.max.length</refname>
2671 <refpurpose>Maximum length of extra3 in header/footer</refpurpose>
2672 </refnamediv>
2673
2674 <refsynopsisdiv>
2675 <programlisting xml:id="man.th.extra3.max.length.frag">
2676 &lt;xsl:param name="man.th.extra3.max.length"&gt;30&lt;/xsl:param&gt;
2677 </programlisting>
2678 </refsynopsisdiv>
2679
2680 <refsection><info><title>Description</title></info>
2681
2682 <para>Specifies the maximum permitted length of the
2683 <literal>extra3</literal> part of the man-page <literal>.TH</literal>
2684 title line header/footer. If the <literal>extra3</literal> content
2685 exceeds the maxiumum specified, it is truncated down to the maximum
2686 permitted length.</para>
2687
2688 <para>The content of the <literal>extra3</literal> field is usually
2689 displayed in the middle header of the page and is typically a "manual
2690 name"; for example, "GTK+ User's Manual" (from the
2691 <literal>gtk-options(7)</literal> man page).</para>
2692
2693 <para>The default value for this parameter is reasonable but somewhat
2694 arbitrary. If you are processing pages with long "manual names" -- or
2695 especially if you are processing pages that have both long "title"
2696 parts (command/function, etc. names) <emphasis>and</emphasis> long
2697 manual names -- you may want to experiment with changing the value in
2698 order to achieve the correct aesthetic results.</para>
2699 </refsection>
2700 </refentry>
2701
2702   </reference>
2703   <reference xml:id="output">
2704   <title>Output</title>
2705 <refentry version="5.0" xml:id="man.output.manifest.enabled">
2706   <refmeta>
2707     <refentrytitle>man.output.manifest.enabled</refentrytitle>
2708     <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2709   </refmeta>
2710   <refnamediv>
2711     <refname>man.output.manifest.enabled</refname>
2712     <refpurpose>Generate a manifest file?</refpurpose>
2713   </refnamediv>
2714
2715   <refsynopsisdiv>
2716     <programlisting xml:id="man.output.manifest.enabled.frag">&lt;xsl:param name="man.output.manifest.enabled" select="0"&gt;&lt;/xsl:param&gt;</programlisting>
2717   </refsynopsisdiv>
2718
2719   <refsection><info><title>Description</title></info>
2720
2721     <para>If non-zero, a list of filenames for man pages generated by
2722     the stylesheet transformation is written to the file named by the
2723     <parameter>man.output.manifest.filename</parameter> parameter.</para>
2724
2725   </refsection>
2726 </refentry>
2727
2728 <refentry version="5.0" xml:id="man.output.manifest.filename">
2729   <refmeta>
2730     <refentrytitle>man.output.manifest.filename</refentrytitle>
2731     <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
2732   </refmeta>
2733   <refnamediv>
2734     <refname>man.output.manifest.filename</refname>
2735     <refpurpose>Name of manifest file</refpurpose>
2736   </refnamediv>
2737
2738   <refsynopsisdiv>
2739     <programlisting xml:id="man.output.manifest.filename.frag">&lt;xsl:param name="man.output.manifest.filename"&gt;MAN.MANIFEST&lt;/xsl:param&gt;</programlisting>
2740   </refsynopsisdiv>
2741
2742   <refsection><info><title>Description</title></info>
2743
2744     <para>The <parameter>man.output.manifest.filename</parameter> parameter
2745     specifies the name of the file to which the manpages manifest file
2746     is written (if the value of the
2747     <parameter>man.output.manifest.enabled</parameter> parameter is
2748     non-zero).</para>
2749
2750   </refsection>
2751 </refentry>
2752
2753 <refentry version="5.0" xml:id="man.output.in.separate.dir">
2754 <refmeta>
2755 <refentrytitle>man.output.in.separate.dir</refentrytitle>
2756 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2757 </refmeta>
2758 <refnamediv>
2759 <refname>man.output.in.separate.dir</refname>
2760 <refpurpose>Output man-page files in separate output directory?</refpurpose>
2761 </refnamediv>
2762
2763 <refsynopsisdiv>
2764 <programlisting xml:id="man.output.in.separate.dir.frag">
2765 &lt;xsl:param name="man.output.in.separate.dir" select="0"&gt;&lt;/xsl:param&gt;
2766 </programlisting>
2767 </refsynopsisdiv>
2768
2769 <refsection><info><title>Description</title></info>
2770
2771 <para>If the value of <literal>man.output.in.separate.dir</literal>
2772 parameter is non-zero, man-page files are output in a separate
2773 directory, specified by the <parameter>man.output.base.dir</parameter>
2774 parameter; otherwise, if the value of
2775 <literal>man.output.in.separate.dir</literal> is zero, man-page files
2776 are not output in a separate directory.</para>
2777
2778 </refsection>
2779 </refentry>
2780
2781 <refentry version="5.0" xml:id="man.output.lang.in.name.enabled">
2782 <refmeta>
2783 <refentrytitle>man.output.lang.in.name.enabled</refentrytitle>
2784 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2785 </refmeta>
2786 <refnamediv>
2787 <refname>man.output.lang.in.name.enabled</refname>
2788 <refpurpose>Include $LANG value in man-page filename/pathname?</refpurpose>
2789 </refnamediv>
2790
2791 <refsynopsisdiv>
2792 <programlisting xml:id="man.output.lang.in.name.enabled.frag">
2793 &lt;xsl:param name="man.output.lang.in.name.enabled" select="0"&gt;&lt;/xsl:param&gt;
2794 </programlisting>
2795 </refsynopsisdiv>
2796
2797 <refsection><info><title>Description</title></info>
2798
2799   <para>The <parameter>man.output.lang.in.name.enabled</parameter>
2800   parameter specifies whether a <literal>$lang</literal> value is
2801   included in man-page filenames and pathnames.</para>
2802
2803   <para>If the value of
2804   <parameter>man.output.lang.in.name.enabled</parameter> is non-zero,
2805   man-page files are output with the <literal>$lang</literal> value
2806   included in their filenames or pathnames as follows;
2807
2808   <itemizedlist>
2809     <listitem>
2810       <para>if <parameter>man.output.subdirs.enabled</parameter> is
2811       non-zero, each file is output to, e.g., a
2812       <filename>man/<replaceable>$lang</replaceable>/man8/foo.8</filename>
2813       pathname</para>
2814     </listitem>
2815     <listitem>
2816       <para>if <parameter>man.output.subdirs.enabled</parameter> is
2817       zero, each file is output with a
2818       <literal>foo.<replaceable>$lang</replaceable>.8</literal>
2819       filename</para>
2820     </listitem>
2821   </itemizedlist>
2822   </para>
2823
2824 </refsection>
2825 </refentry>
2826
2827 <refentry version="5.0" xml:id="man.output.base.dir">
2828 <refmeta>
2829 <refentrytitle>man.output.base.dir</refentrytitle>
2830 <refmiscinfo class="other" otherclass="datatype">uri</refmiscinfo>
2831 </refmeta>
2832 <refnamediv>
2833 <refname>man.output.base.dir</refname>
2834 <refpurpose>Specifies separate output directory</refpurpose>
2835 </refnamediv>
2836
2837 <refsynopsisdiv>
2838 <programlisting xml:id="man.output.base.dir.frag">&lt;xsl:param name="man.output.base.dir"&gt;man/&lt;/xsl:param&gt;</programlisting>
2839 </refsynopsisdiv>
2840
2841 <refsection><info><title>Description</title></info>
2842
2843 <para>The <parameter>man.output.base.dir</parameter> parameter
2844 specifies the base directory into which man-page files are output. The
2845 <parameter>man.output.subdirs.enabled</parameter> parameter controls
2846 whether the files are output in subdirectories within the base
2847 directory.</para>
2848
2849 <note>
2850   <para>The values of the <parameter>man.output.base.dir</parameter>
2851   and <parameter>man.output.subdirs.enabled</parameter> parameters are
2852   used only if the value of
2853   <parameter>man.output.in.separate.dir</parameter> parameter is
2854   non-zero. If the value of the
2855   <parameter>man.output.in.separate.dir</parameter> is zero, man-page
2856   files are not output in a separate directory.</para>
2857 </note>
2858
2859 </refsection>
2860 </refentry>
2861
2862 <refentry version="5.0" xml:id="man.output.subdirs.enabled">
2863 <refmeta>
2864 <refentrytitle>man.output.subdirs.enabled</refentrytitle>
2865 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2866 </refmeta>
2867 <refnamediv>
2868 <refname>man.output.subdirs.enabled</refname>
2869 <refpurpose>Output man-page files in subdirectories within base output directory?</refpurpose>
2870 </refnamediv>
2871
2872 <refsynopsisdiv>
2873 <programlisting xml:id="man.output.subdirs.enabled.frag">
2874 &lt;xsl:param name="man.output.subdirs.enabled" select="1"&gt;&lt;/xsl:param&gt;
2875 </programlisting>
2876 </refsynopsisdiv>
2877
2878 <refsection><info><title>Description</title></info>
2879
2880 <para>The <parameter>man.output.subdirs.enabled</parameter> parameter
2881 controls whether man-pages files are output in subdirectories within
2882 the base directory specified by the directory specified by the
2883 <parameter>man.output.base.dir</parameter> parameter.</para>
2884
2885 <note>
2886   <para>The values of the <parameter>man.output.base.dir</parameter>
2887   and <parameter>man.output.subdirs.enabled</parameter> parameters are
2888   used only if the value of
2889   <parameter>man.output.in.separate.dir</parameter> parameter is
2890   non-zero. If the value of the
2891   <parameter>man.output.in.separate.dir</parameter> is zero, man-page
2892   files are not output in a separate directory.</para>
2893 </note>
2894
2895 </refsection>
2896 </refentry>
2897
2898 <refentry version="5.0" xml:id="man.output.quietly">
2899 <refmeta>
2900 <refentrytitle>man.output.quietly</refentrytitle>
2901 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2902 </refmeta>
2903 <refnamediv>
2904 <refname>man.output.quietly</refname>
2905 <refpurpose>Suppress filename messages emitted when generating output?</refpurpose>
2906 </refnamediv>
2907
2908 <refsynopsisdiv>
2909 <programlisting xml:id="man.output.quietly.frag">
2910 &lt;xsl:param name="man.output.quietly" select="0"&gt;&lt;/xsl:param&gt;
2911 </programlisting>
2912 </refsynopsisdiv>
2913
2914 <refsection><info><title>Description</title></info>
2915
2916 <para>If zero (the default), for each man-page file created, a message
2917 with the name of the file is emitted. If non-zero, the files are
2918 output "quietly" -- that is, the filename messages are
2919 suppressed.</para>
2920
2921 <tip>
2922   <para>If you are processing a large amount of <tag>refentry</tag>
2923   content, you may be able to speed up processing significantly by
2924   setting a non-zero value for
2925   <parameter>man.output.quietly</parameter>.</para>
2926 </tip>
2927
2928 </refsection>
2929 </refentry>
2930
2931 <refentry version="5.0" xml:id="man.output.encoding">
2932 <refmeta>
2933 <refentrytitle>man.output.encoding</refentrytitle>
2934 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
2935 </refmeta>
2936 <refnamediv>
2937 <refname>man.output.encoding</refname>
2938 <refpurpose>Encoding used for man-page output</refpurpose>
2939 </refnamediv>
2940
2941 <refsynopsisdiv>
2942 <programlisting xml:id="man.output.encoding.frag">
2943 &lt;xsl:param name="man.output.encoding"&gt;UTF-8&lt;/xsl:param&gt;
2944 </programlisting>
2945 </refsynopsisdiv>
2946
2947 <refsection><info><title>Description</title></info>
2948
2949 <para>This parameter specifies the encoding to use for files generated
2950 by the manpages stylesheet. Not all processors support specification
2951 of this parameter.</para>
2952
2953 <important>
2954   <para>If the value of the <parameter>man.charmap.enabled</parameter>
2955   parameter is non-zero (the default), keeping the
2956   <parameter>man.output.encoding</parameter> parameter at its default
2957   value (<literal>UTF-8</literal>) or setting it to
2958   <literal>UTF-16</literal> <emphasis role="bold">does not cause your
2959   man pages to be output in raw UTF-8 or UTF-16</emphasis> -- because
2960   any Unicode characters for which matches are found in the enabled
2961   character map will be replaced with roff escape sequences before the
2962   final man-page files are generated.</para>
2963
2964   <para>So if you want to generate "real" UTF-8 man pages, without any
2965   character substitution being performed on your content, you need to
2966   set <parameter>man.charmap.enabled</parameter> to zero (which will
2967   completely disable character-map processing). </para>
2968
2969   <para>You may also need to set
2970   <parameter>man.charmap.enabled</parameter> to zero if you want to
2971   output man pages in an encoding other than <literal>UTF-8</literal>
2972   or <literal>UTF-16</literal>. Character-map processing is based on
2973   Unicode character values and may not work with other output
2974   encodings.</para>
2975 </important>
2976
2977 </refsection>
2978 </refentry>
2979
2980 <refentry version="5.0" xml:id="man.output.better.ps.enabled">
2981 <refmeta>
2982 <refentrytitle>man.output.better.ps.enabled</refentrytitle>
2983 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
2984 </refmeta>
2985 <refnamediv>
2986 <refname>man.output.better.ps.enabled</refname>
2987 <refpurpose>Enable enhanced print/PostScript output?</refpurpose>
2988 </refnamediv>
2989 <refsynopsisdiv>
2990 <programlisting xml:id="man.output.better.ps.enabled.frag">
2991 &lt;xsl:param name="man.output.better.ps.enabled"&gt;0&lt;/xsl:param&gt;
2992 </programlisting>
2993 </refsynopsisdiv>
2994 <refsection><info><title>Description</title></info>
2995
2996 <para>If the value of the
2997 <parameter>man.output.better.ps.enabled</parameter> parameter is
2998 non-zero, certain markup is embedded in each generated man page
2999 such that PostScript output from the <command>man -Tps</command>
3000 command for that page will include a number of enhancements
3001 designed to improve the quality of that output.</para>
3002
3003 <para>If <parameter>man.output.better.ps.enabled</parameter> is
3004 zero (the default), no such markup is embedded in generated man
3005 pages, and no enhancements are included in the PostScript
3006 output generated from those man pages by the <command>man
3007  -Tps</command> command.</para>
3008
3009 <warning>
3010   <para>The enhancements provided by this parameter rely on
3011     features that are specific to groff (GNU troff) and that are
3012     not part of &#8220;classic&#8221; AT&amp;T troff or any of its
3013     derivatives. Therefore, any man pages you generate with this
3014     parameter enabled will be readable only on systems on which
3015     the groff (GNU troff) program is installed, such as GNU/Linux
3016     systems. The pages <emphasis role="bold">will not not be
3017       readable on systems on with the classic troff (AT&amp;T
3018       troff) command is installed</emphasis>.</para>
3019 </warning>
3020
3021 <para>The value of this parameter only affects PostScript output
3022   generated from the <command>man</command> command. It has no
3023   effect on output generated using the FO backend.</para>
3024
3025 <tip>
3026   <para>You can generate PostScript output for any man page by
3027     running the following command:</para>
3028   <programlisting>  man <replaceable>FOO</replaceable> -Tps &gt; <replaceable>FOO</replaceable>.ps</programlisting>
3029   <para>You can then generate PDF output by running the following
3030     command:</para>
3031   <programlisting>  ps2pdf <replaceable>FOO</replaceable>.ps</programlisting>
3032 </tip>
3033
3034 </refsection>
3035 </refentry>
3036
3037   </reference>
3038   <reference xml:id="other">
3039   <title>Other</title>
3040 <refentry version="5.0" xml:id="man.table.footnotes.divider">
3041 <refmeta>
3042 <refentrytitle>man.table.footnotes.divider</refentrytitle>
3043 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
3044 </refmeta>
3045 <refnamediv>
3046 <refname>man.table.footnotes.divider</refname>
3047 <refpurpose>Specifies divider string that appears before table footnotes</refpurpose>
3048 </refnamediv>
3049
3050 <refsynopsisdiv>
3051 <programlisting xml:id="man.table.footnotes.divider.frag">
3052 &lt;xsl:param name="man.table.footnotes.divider"&gt;----&lt;/xsl:param&gt;
3053 </programlisting>
3054 </refsynopsisdiv>
3055
3056 <refsection><info><title>Description</title></info>
3057
3058 <para>In each table that contains footenotes, the string specified by
3059 the <parameter>man.table.footnotes.divider</parameter> parameter is
3060 output before the list of footnotes for the table.</para>
3061
3062 </refsection>
3063 </refentry>
3064
3065 <refentry version="5.0" xml:id="man.subheading.divider.enabled">
3066 <refmeta>
3067 <refentrytitle>man.subheading.divider.enabled</refentrytitle>
3068 <refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
3069 </refmeta>
3070 <refnamediv>
3071 <refname>man.subheading.divider.enabled</refname>
3072 <refpurpose>Add divider comment to roff source before/after subheadings?</refpurpose>
3073 </refnamediv>
3074
3075 <refsynopsisdiv>
3076 <programlisting xml:id="man.subheading.divider.enabled.frag">
3077 &lt;xsl:param name="man.subheading.divider.enabled"&gt;0&lt;/xsl:param&gt;
3078 </programlisting>
3079 </refsynopsisdiv>
3080
3081 <refsection><info><title>Description</title></info>
3082
3083 <para>If the value of the
3084 <parameter>man.subheading.divider.enabled</parameter> parameter is
3085 non-zero, the contents of the
3086 <parameter>man.subheading.divider</parameter> parameter are used to
3087 add a "divider" before and after subheadings in the roff
3088 output. <emphasis role="bold">The divider is not visisble in the
3089 rendered man page</emphasis>; it is added as a comment, in the source,
3090 simply for the purpose of increasing reability of the source.</para>
3091
3092 <para>If <parameter>man.subheading.divider.enabled</parameter> is zero
3093 (the default), the subheading divider is suppressed.</para>
3094
3095 </refsection>
3096 </refentry>
3097
3098 <refentry version="5.0" xml:id="man.subheading.divider">
3099 <refmeta>
3100 <refentrytitle>man.subheading.divider</refentrytitle>
3101 <refmiscinfo class="other" otherclass="datatype">string</refmiscinfo>
3102 </refmeta>
3103 <refnamediv>
3104 <refname>man.subheading.divider</refname>
3105 <refpurpose>Specifies string to use as divider comment before/after subheadings</refpurpose>
3106 </refnamediv>
3107
3108 <refsynopsisdiv>
3109 <programlisting xml:id="man.subheading.divider.frag">
3110 &lt;xsl:param name="man.subheading.divider"&gt;========================================================================&lt;/xsl:param&gt;
3111 </programlisting>
3112 </refsynopsisdiv>
3113
3114 <refsection><info><title>Description</title></info>
3115
3116 <para>If the value of the
3117 <parameter>man.subheading.divider.enabled</parameter> parameter is
3118 non-zero, the contents of the
3119 <parameter>man.subheading.divider</parameter> parameter are used to
3120 add a "divider" before and after subheadings in the roff
3121 output. <emphasis role="bold">The divider is not visisble in the
3122 rendered man page</emphasis>; it is added as a comment, in the source,
3123 simply for the purpose of increasing reability of the source.</para>
3124
3125 <para>If <parameter>man.subheading.divider.enabled</parameter> is zero
3126 (the default), the subheading divider is suppressed.</para>
3127
3128 </refsection>
3129 </refentry>
3130
3131   </reference>
3132   <appendix xml:id="stylesheet">
3133     <title>The Stylesheet</title>
3134
3135     <para>The <filename>param.xsl</filename> stylesheet is just a
3136     wrapper around all of these parameters.</para>
3137
3138     <programlisting xml:id="top">
3139 &lt;xsl:stylesheet exclude-result-prefixes="src" version="1.0"&gt;
3140
3141 &lt;!-- This file is generated from param.xweb --&gt;
3142
3143 &lt;!-- ********************************************************************
3144      $Id: param.xweb 8235 2009-02-09 16:22:14Z xmldoc $
3145      ********************************************************************
3146
3147      This file is part of the XSL DocBook Stylesheet distribution.
3148      See ../README or http://docbook.sf.net/release/xsl/current/ for
3149      copyright and other information.
3150
3151      ******************************************************************** --&gt;
3152
3153 &lt;src:fragref linkend="man.authors.section.enabled.frag"&gt;&lt;/src:fragref&gt;
3154 &lt;src:fragref linkend="man.break.after.slash.frag"&gt;&lt;/src:fragref&gt;
3155 &lt;src:fragref linkend="man.base.url.for.relative.links.frag"&gt;&lt;/src:fragref&gt;
3156 &lt;src:fragref linkend="man.charmap.enabled.frag"&gt;&lt;/src:fragref&gt;
3157 &lt;src:fragref linkend="man.charmap.subset.profile.frag"&gt;&lt;/src:fragref&gt;
3158 &lt;src:fragref linkend="man.charmap.subset.profile.english.frag"&gt;&lt;/src:fragref&gt;
3159 &lt;src:fragref linkend="man.charmap.uri.frag"&gt;&lt;/src:fragref&gt;
3160 &lt;src:fragref linkend="man.charmap.use.subset.frag"&gt;&lt;/src:fragref&gt;
3161 &lt;src:fragref linkend="man.copyright.section.enabled.frag"&gt;&lt;/src:fragref&gt;
3162 &lt;src:fragref linkend="man.endnotes.are.numbered.frag"&gt;&lt;/src:fragref&gt;
3163 &lt;src:fragref linkend="man.endnotes.list.enabled.frag"&gt;&lt;/src:fragref&gt;
3164 &lt;src:fragref linkend="man.endnotes.list.heading.frag"&gt;&lt;/src:fragref&gt;
3165 &lt;src:fragref linkend="man.font.funcprototype.frag"&gt;&lt;/src:fragref&gt;
3166 &lt;src:fragref linkend="man.font.funcsynopsisinfo.frag"&gt;&lt;/src:fragref&gt;
3167 &lt;src:fragref linkend="man.font.links.frag"&gt;&lt;/src:fragref&gt;
3168 &lt;src:fragref linkend="man.font.table.headings.frag"&gt;&lt;/src:fragref&gt;
3169 &lt;src:fragref linkend="man.font.table.title.frag"&gt;&lt;/src:fragref&gt;
3170 &lt;src:fragref linkend="man.funcsynopsis.style.frag"&gt;&lt;/src:fragref&gt;
3171 &lt;src:fragref linkend="man.hyphenate.computer.inlines.frag"&gt;&lt;/src:fragref&gt;
3172 &lt;src:fragref linkend="man.hyphenate.filenames.frag"&gt;&lt;/src:fragref&gt;
3173 &lt;src:fragref linkend="man.hyphenate.frag"&gt;&lt;/src:fragref&gt;
3174 &lt;src:fragref linkend="man.hyphenate.urls.frag"&gt;&lt;/src:fragref&gt;
3175 &lt;src:fragref linkend="man.indent.blurbs.frag"&gt;&lt;/src:fragref&gt;
3176 &lt;src:fragref linkend="man.indent.lists.frag"&gt;&lt;/src:fragref&gt;
3177 &lt;src:fragref linkend="man.indent.refsect.frag"&gt;&lt;/src:fragref&gt;
3178 &lt;src:fragref linkend="man.indent.verbatims.frag"&gt;&lt;/src:fragref&gt;
3179 &lt;src:fragref linkend="man.indent.width.frag"&gt;&lt;/src:fragref&gt;
3180 &lt;src:fragref linkend="man.justify.frag"&gt;&lt;/src:fragref&gt;
3181 &lt;src:fragref linkend="man.output.base.dir.frag"&gt;&lt;/src:fragref&gt;
3182 &lt;src:fragref linkend="man.output.encoding.frag"&gt;&lt;/src:fragref&gt;
3183 &lt;src:fragref linkend="man.output.in.separate.dir.frag"&gt;&lt;/src:fragref&gt;
3184 &lt;src:fragref linkend="man.output.lang.in.name.enabled.frag"&gt;&lt;/src:fragref&gt;
3185 &lt;src:fragref linkend="man.output.manifest.enabled.frag"&gt;&lt;/src:fragref&gt;
3186 &lt;src:fragref linkend="man.output.manifest.filename.frag"&gt;&lt;/src:fragref&gt;
3187 &lt;src:fragref linkend="man.output.better.ps.enabled.frag"&gt;&lt;/src:fragref&gt;
3188 &lt;src:fragref linkend="man.output.quietly.frag"&gt;&lt;/src:fragref&gt;
3189 &lt;src:fragref linkend="man.output.subdirs.enabled.frag"&gt;&lt;/src:fragref&gt;
3190 &lt;src:fragref linkend="man.segtitle.suppress.frag"&gt;&lt;/src:fragref&gt;
3191 &lt;src:fragref linkend="man.string.subst.map.frag"&gt;&lt;/src:fragref&gt;
3192 &lt;src:fragref linkend="man.string.subst.map.local.post.frag"&gt;&lt;/src:fragref&gt;
3193 &lt;src:fragref linkend="man.string.subst.map.local.pre.frag"&gt;&lt;/src:fragref&gt;
3194 &lt;src:fragref linkend="man.subheading.divider.enabled.frag"&gt;&lt;/src:fragref&gt;
3195 &lt;src:fragref linkend="man.subheading.divider.frag"&gt;&lt;/src:fragref&gt;
3196 &lt;src:fragref linkend="man.table.footnotes.divider.frag"&gt;&lt;/src:fragref&gt;
3197 &lt;src:fragref linkend="man.th.extra1.suppress.frag"&gt;&lt;/src:fragref&gt;
3198 &lt;src:fragref linkend="man.th.extra2.max.length.frag"&gt;&lt;/src:fragref&gt;
3199 &lt;src:fragref linkend="man.th.extra2.suppress.frag"&gt;&lt;/src:fragref&gt;
3200 &lt;src:fragref linkend="man.th.extra3.max.length.frag"&gt;&lt;/src:fragref&gt;
3201 &lt;src:fragref linkend="man.th.extra3.suppress.frag"&gt;&lt;/src:fragref&gt;
3202 &lt;src:fragref linkend="man.th.title.max.length.frag"&gt;&lt;/src:fragref&gt;
3203 &lt;src:fragref linkend="refentry.date.profile.enabled.frag"&gt;&lt;/src:fragref&gt;
3204 &lt;src:fragref linkend="refentry.date.profile.frag"&gt;&lt;/src:fragref&gt;
3205 &lt;src:fragref linkend="refentry.manual.fallback.profile.frag"&gt;&lt;/src:fragref&gt;
3206 &lt;src:fragref linkend="refentry.manual.profile.enabled.frag"&gt;&lt;/src:fragref&gt;
3207 &lt;src:fragref linkend="refentry.manual.profile.frag"&gt;&lt;/src:fragref&gt;
3208 &lt;src:fragref linkend="refentry.meta.get.quietly.frag"&gt;&lt;/src:fragref&gt;
3209 &lt;src:fragref linkend="refentry.source.fallback.profile.frag"&gt;&lt;/src:fragref&gt;
3210 &lt;src:fragref linkend="refentry.source.name.profile.enabled.frag"&gt;&lt;/src:fragref&gt;
3211 &lt;src:fragref linkend="refentry.source.name.profile.frag"&gt;&lt;/src:fragref&gt;
3212 &lt;src:fragref linkend="refentry.source.name.suppress.frag"&gt;&lt;/src:fragref&gt;
3213 &lt;src:fragref linkend="refentry.version.profile.enabled.frag"&gt;&lt;/src:fragref&gt;
3214 &lt;src:fragref linkend="refentry.version.profile.frag"&gt;&lt;/src:fragref&gt;
3215 &lt;src:fragref linkend="refentry.version.suppress.frag"&gt;&lt;/src:fragref&gt;
3216 &lt;/xsl:stylesheet&gt;
3217     </programlisting>
3218
3219   </appendix>
3220 </book>