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 9130 2011-10-11 08:05:37Z dpawson $
|
---|
7 | </releaseinfo>
|
---|
8 | <author>
|
---|
9 | <orgname>The DocBook Project</orgname>
|
---|
10 | </author>
|
---|
11 | <copyright>
|
---|
12 | <year>2005-2011</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 | <xsl:param name="man.hyphenate">0</xsl:param></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 | <xsl:param name="man.hyphenate.urls">0</xsl:param></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 | <xsl:param name="man.hyphenate.filenames">0</xsl:param></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 | <xsl:param name="man.hyphenate.computer.inlines">0</xsl:param></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 | <xsl:param name="man.justify">0</xsl:param></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 | <xsl:param name="man.break.after.slash">0</xsl:param></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 | <xsl:param name="man.indent.width">4</xsl:param>
|
---|
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 | <xsl:param name="man.indent.refsect" select="0"></xsl:param></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) – with few or
|
---|
397 | no <tag>refsect3</tag> or lower nested sections , you may be
|
---|
398 | able to “conserve” space in your output by setting
|
---|
399 | <parameter>man.indent.refsect</parameter> to a non-zero value. Doing
|
---|
400 | so will “squeeze” the left margin in such as way as to provide an
|
---|
401 | additional four characters of “room” 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 | <xsl:param name="man.indent.blurbs" select="1"></xsl:param></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 | <xsl:param name="man.indent.lists" select="1"></xsl:param></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 | <xsl:param name="man.indent.verbatims" select="1"></xsl:param></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 | <xsl:param name="man.font.funcprototype">BI</xsl:param>
|
---|
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 | <xsl:param name="man.font.funcsynopsisinfo">B</xsl:param>
|
---|
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 | <xsl:param name="man.font.links">B</xsl:param>
|
---|
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 | “clickable”; given that links rendered in man pages are
|
---|
591 | not “real” 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 | “context” information about exactly what part of the text
|
---|
601 | is being “annotated” 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 | <xsl:param name="man.font.table.headings">B</xsl:param>
|
---|
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 | <xsl:param name="man.font.table.title">B</xsl:param>
|
---|
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"><xsl:param name="man.funcsynopsis.style">ansi</xsl:param></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&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 | <xsl:param name="man.authors.section.enabled">1</xsl:param>
|
---|
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 | <xsl:param name="man.copyright.section.enabled">1</xsl:param>
|
---|
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 | <xsl:param name="man.endnotes.list.enabled">1</xsl:param>
|
---|
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 — 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 “out of line” information (such
|
---|
815 | as the URLs for hyperlinks and images) gets lost in your
|
---|
816 | man-page output. It just gets “rearranged”.</para>
|
---|
817 | <para>So if you’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 “out
|
---|
822 | of line” 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 “real” (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 “man to html” 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 — resulting in “real” hyperlinks in HTML
|
---|
837 | output from those tools.</para>
|
---|
838 | </note>
|
---|
839 |
|
---|
840 | <para>To “turn off” 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 “list
|
---|
847 | of references” 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 “out of line”
|
---|
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 “non-empty” link is one that looks like
|
---|
863 | this:<literallayout class="monospaced"> <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/">manpages</ulink></literallayout>
|
---|
864 | an “empty link” is on that looks like this:<literallayout class="monospaced"> <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/></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 | <xsl:param name="man.endnotes.list.heading"></xsl:param>
|
---|
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 —
|
---|
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 | <xsl:param name="man.endnotes.are.numbered">1</xsl:param>
|
---|
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 “non-empty” notesource is one that looks like
|
---|
934 | this:<literallayout class="monospaced"> <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/">manpages</ulink></literallayout>
|
---|
935 | an “empty” notesource is on that looks like this:<literallayout class="monospaced"> <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/></literallayout>
|
---|
936 | </para></footnote> “notesource”:
|
---|
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 “text based” 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 | “rearranged”.</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"><xsl:param name="man.base.url.for.relative.links">[set $man.base.url.for.relative.links]/</xsl:param></programlisting>
|
---|
1027 | </refsynopsisdiv>
|
---|
1028 |
|
---|
1029 | <refsection><info><title>Description</title></info>
|
---|
1030 |
|
---|
1031 | <para>For any “notesource” listed in the auto-generated
|
---|
1032 | “NOTES” 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 “as is” in the “Notes”
|
---|
1063 | section of any man-page output generated from your source.
|
---|
1064 | That’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><xsl:param name="man.base.url.for.relative.links"
|
---|
1073 | >http://www.kernel.org/pub/software/scm/git/docs/</xsl:param></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 | <xsl:param name="man.segtitle.suppress" select="0"></xsl:param></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 | <xsl:param name="man.charmap.enabled" select="1"></xsl:param>
|
---|
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 | <xsl:param name="man.charmap.uri"></xsl:param>
|
---|
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 | <xsl:param name="man.charmap.use.subset" select="1"></xsl:param>
|
---|
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 | <xsl:param name="man.charmap.subset.profile">
|
---|
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 | </xsl:param>
|
---|
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&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&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&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&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&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&start=8192&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&start=8208&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&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&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&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&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&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&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&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&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&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&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&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&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 | <xsl:param name="man.charmap.subset.profile.english">
|
---|
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 | </xsl:param>
|
---|
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 “local” string substitutions</refpurpose>
|
---|
1646 | </refnamediv>
|
---|
1647 |
|
---|
1648 | <refsynopsisdiv>
|
---|
1649 | <programlisting xml:id="man.string.subst.map.local.pre.frag">
|
---|
1650 | <xsl:param name="man.string.subst.map.local.pre"></xsl:param>
|
---|
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 “local” 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 | <xsl:param name="man.string.subst.map">
|
---|
1681 |
|
---|
1682 | <!-- * remove no-break marker at beginning of line (stylesheet artifact) -->
|
---|
1683 | <ss:substitution oldstring="▒▀" newstring="▒"></ss:substitution>
|
---|
1684 | <!-- * replace U+2580 no-break marker (stylesheet-added) w/ no-break space -->
|
---|
1685 | <ss:substitution oldstring="▀" newstring="\ "></ss:substitution>
|
---|
1686 |
|
---|
1687 | <!-- ==================================================================== -->
|
---|
1688 |
|
---|
1689 | <!-- * squeeze multiple newlines before a roff request -->
|
---|
1690 | <ss:substitution oldstring="
|
---|
1691 |
|
---|
1692 | ." newstring="
|
---|
1693 | ."></ss:substitution>
|
---|
1694 | <!-- * remove any .sp instances that directly precede a .PP -->
|
---|
1695 | <ss:substitution oldstring=".sp
|
---|
1696 | .PP" newstring=".PP"></ss:substitution>
|
---|
1697 | <!-- * remove any .sp instances that directly follow a .PP -->
|
---|
1698 | <ss:substitution oldstring=".sp
|
---|
1699 | .sp" newstring=".sp"></ss:substitution>
|
---|
1700 | <!-- * squeeze multiple .sp instances into a single .sp-->
|
---|
1701 | <ss:substitution oldstring=".PP
|
---|
1702 | .sp" newstring=".PP"></ss:substitution>
|
---|
1703 | <!-- * squeeze multiple newlines after start of no-fill (verbatim) env. -->
|
---|
1704 | <ss:substitution oldstring=".nf
|
---|
1705 |
|
---|
1706 | " newstring=".nf
|
---|
1707 | "></ss:substitution>
|
---|
1708 | <!-- * squeeze multiple newlines after REstoring margin -->
|
---|
1709 | <ss:substitution oldstring=".RE
|
---|
1710 |
|
---|
1711 | " newstring=".RE
|
---|
1712 | "></ss:substitution>
|
---|
1713 | <!-- * U+2591 is a marker we add before and after every Parameter in -->
|
---|
1714 | <!-- * Funcprototype output -->
|
---|
1715 | <ss:substitution oldstring="░" newstring=" "></ss:substitution>
|
---|
1716 | <!-- * U+2592 is a marker we add for the newline before output of <sbr>; -->
|
---|
1717 | <ss:substitution oldstring="▒" newstring="
|
---|
1718 | "></ss:substitution>
|
---|
1719 | <!-- * -->
|
---|
1720 | <!-- * Now deal with some other characters that are added by the -->
|
---|
1721 | <!-- * stylesheets during processing. -->
|
---|
1722 | <!-- * -->
|
---|
1723 | <!-- * bullet -->
|
---|
1724 | <ss:substitution oldstring="•" newstring="\(bu"></ss:substitution>
|
---|
1725 | <!-- * left double quote -->
|
---|
1726 | <ss:substitution oldstring="“" newstring="\(lq"></ss:substitution>
|
---|
1727 | <!-- * right double quote -->
|
---|
1728 | <ss:substitution oldstring="”" newstring="\(rq"></ss:substitution>
|
---|
1729 | <!-- * left single quote -->
|
---|
1730 | <ss:substitution oldstring="‘" newstring="\(oq"></ss:substitution>
|
---|
1731 | <!-- * right single quote -->
|
---|
1732 | <ss:substitution oldstring="’" newstring="\(cq"></ss:substitution>
|
---|
1733 | <!-- * copyright sign -->
|
---|
1734 | <ss:substitution oldstring="©" newstring="\(co"></ss:substitution>
|
---|
1735 | <!-- * registered sign -->
|
---|
1736 | <ss:substitution oldstring="®" newstring="\(rg"></ss:substitution>
|
---|
1737 | <!-- * ...servicemark... -->
|
---|
1738 | <!-- * There is no groff equivalent for it. -->
|
---|
1739 | <ss:substitution oldstring="℠" newstring="(SM)"></ss:substitution>
|
---|
1740 | <!-- * ...trademark... -->
|
---|
1741 | <!-- * We don't do "\(tm" because for console output, -->
|
---|
1742 | <!-- * groff just renders that as "tm"; that is: -->
|
---|
1743 | <!-- * -->
|
---|
1744 | <!-- * Product&#x2122; -> Producttm -->
|
---|
1745 | <!-- * -->
|
---|
1746 | <!-- * So we just make it to "(TM)" instead; thus: -->
|
---|
1747 | <!-- * -->
|
---|
1748 | <!-- * Product&#x2122; -> Product(TM) -->
|
---|
1749 | <ss:substitution oldstring="™" newstring="(TM)"></ss:substitution>
|
---|
1750 |
|
---|
1751 | </xsl:param>
|
---|
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 | “lightweight” character map to perform “essential” 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’s used for doing string substitution over the
|
---|
1802 | entire roff source of each man page – 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><!--</literal>" and "<literal>--></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 “local” string substitutions</refpurpose>
|
---|
1845 | </refnamediv>
|
---|
1846 |
|
---|
1847 | <refsynopsisdiv>
|
---|
1848 | <programlisting xml:id="man.string.subst.map.local.post.frag">
|
---|
1849 | <xsl:param name="man.string.subst.map.local.post"></xsl:param>
|
---|
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 “local” 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 | <xsl:param name="refentry.meta.get.quietly" select="0"></xsl:param>
|
---|
1883 | </programlisting>
|
---|
1884 | </refsynopsisdiv>
|
---|
1885 |
|
---|
1886 | <refsection><info><title>Description</title></info>
|
---|
1887 |
|
---|
1888 | <para>If zero (the default), notes and warnings about “missing” markup
|
---|
1889 | are generated during gathering of refentry metadata. If non-zero, the
|
---|
1890 | metadata is gathered “quietly” -- 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 | <xsl:param name="refentry.date.profile">
|
---|
1916 | (($info[//date])[last()]/date)[1]|
|
---|
1917 | (($info[//pubdate])[last()]/pubdate)[1]
|
---|
1918 | </xsl:param>
|
---|
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 | <xsl:param name="refentry.date.profile.enabled">0</xsl:param></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 | <xsl:param name="refentry.manual.profile">
|
---|
1992 | (($info[//title])[last()]/title)[1]|
|
---|
1993 | ../title/node()
|
---|
1994 | </xsl:param>
|
---|
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 | <xsl:param name="refentry.manual.profile.enabled">0</xsl:param></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 | <xsl:param name="refentry.source.name.suppress">0</xsl:param></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 | <xsl:param name="refentry.source.name.profile">
|
---|
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 | </xsl:param>
|
---|
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> <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> <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 | <xsl:param name="refentry.source.name.profile.enabled">0</xsl:param></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 | <xsl:param name="refentry.version.suppress">0</xsl:param></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 | <xsl:param name="refentry.version.profile">
|
---|
2309 | (($info[//productnumber])[last()]/productnumber)[1]|
|
---|
2310 | (($info[//edition])[last()]/edition)[1]|
|
---|
2311 | (($info[//releaseinfo])[last()]/releaseinfo)[1]
|
---|
2312 | </xsl:param>
|
---|
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> <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 | <xsl:param name="refentry.version.profile.enabled">0</xsl:param></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 | <xsl:param name="refentry.manual.fallback.profile">
|
---|
2389 | refmeta/refmiscinfo[not(@class = 'date')][1]/node()</xsl:param>
|
---|
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 | <xsl:param name="refentry.source.fallback.profile">
|
---|
2433 | refmeta/refmiscinfo[not(@class = 'date')][1]/node()</xsl:param>
|
---|
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 | <xsl:param name="man.th.extra1.suppress">0</xsl:param></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 | <xsl:param name="man.th.extra2.suppress">0</xsl:param></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> <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 | <xsl:param name="man.th.extra3.suppress">0</xsl:param></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 | <xsl:param name="man.th.title.max.length">20</xsl:param>
|
---|
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 | <xsl:param name="man.th.extra2.max.length">30</xsl:param>
|
---|
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> <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 | <xsl:param name="man.th.extra3.max.length">30</xsl:param>
|
---|
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"><xsl:param name="man.output.manifest.enabled" select="0"></xsl:param></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"><xsl:param name="man.output.manifest.filename">MAN.MANIFEST</xsl:param></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 | <xsl:param name="man.output.in.separate.dir" select="0"></xsl:param>
|
---|
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 | <xsl:param name="man.output.lang.in.name.enabled" select="0"></xsl:param>
|
---|
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"><xsl:param name="man.output.base.dir">man/</xsl:param></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 | <xsl:param name="man.output.subdirs.enabled" select="1"></xsl:param>
|
---|
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 | <xsl:param name="man.output.quietly" select="0"></xsl:param>
|
---|
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 | <xsl:param name="man.output.encoding">UTF-8</xsl:param>
|
---|
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 | <xsl:param name="man.output.better.ps.enabled">0</xsl:param>
|
---|
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 “classic” AT&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&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 > <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 | <xsl:param name="man.table.footnotes.divider">----</xsl:param>
|
---|
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 | <xsl:param name="man.subheading.divider.enabled">0</xsl:param>
|
---|
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 | <xsl:param name="man.subheading.divider">========================================================================</xsl:param>
|
---|
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 | <xsl:stylesheet exclude-result-prefixes="src" version="1.0">
|
---|
3140 |
|
---|
3141 | <!-- This file is generated from param.xweb -->
|
---|
3142 |
|
---|
3143 | <!-- ********************************************************************
|
---|
3144 | $Id: param.xweb 9130 2011-10-11 08:05:37Z dpawson $
|
---|
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 | ******************************************************************** -->
|
---|
3152 |
|
---|
3153 | <src:fragref linkend="man.authors.section.enabled.frag"></src:fragref>
|
---|
3154 | <src:fragref linkend="man.break.after.slash.frag"></src:fragref>
|
---|
3155 | <src:fragref linkend="man.base.url.for.relative.links.frag"></src:fragref>
|
---|
3156 | <src:fragref linkend="man.charmap.enabled.frag"></src:fragref>
|
---|
3157 | <src:fragref linkend="man.charmap.subset.profile.frag"></src:fragref>
|
---|
3158 | <src:fragref linkend="man.charmap.subset.profile.english.frag"></src:fragref>
|
---|
3159 | <src:fragref linkend="man.charmap.uri.frag"></src:fragref>
|
---|
3160 | <src:fragref linkend="man.charmap.use.subset.frag"></src:fragref>
|
---|
3161 | <src:fragref linkend="man.copyright.section.enabled.frag"></src:fragref>
|
---|
3162 | <src:fragref linkend="man.endnotes.are.numbered.frag"></src:fragref>
|
---|
3163 | <src:fragref linkend="man.endnotes.list.enabled.frag"></src:fragref>
|
---|
3164 | <src:fragref linkend="man.endnotes.list.heading.frag"></src:fragref>
|
---|
3165 | <src:fragref linkend="man.font.funcprototype.frag"></src:fragref>
|
---|
3166 | <src:fragref linkend="man.font.funcsynopsisinfo.frag"></src:fragref>
|
---|
3167 | <src:fragref linkend="man.font.links.frag"></src:fragref>
|
---|
3168 | <src:fragref linkend="man.font.table.headings.frag"></src:fragref>
|
---|
3169 | <src:fragref linkend="man.font.table.title.frag"></src:fragref>
|
---|
3170 | <src:fragref linkend="man.funcsynopsis.style.frag"></src:fragref>
|
---|
3171 | <src:fragref linkend="man.hyphenate.computer.inlines.frag"></src:fragref>
|
---|
3172 | <src:fragref linkend="man.hyphenate.filenames.frag"></src:fragref>
|
---|
3173 | <src:fragref linkend="man.hyphenate.frag"></src:fragref>
|
---|
3174 | <src:fragref linkend="man.hyphenate.urls.frag"></src:fragref>
|
---|
3175 | <src:fragref linkend="man.indent.blurbs.frag"></src:fragref>
|
---|
3176 | <src:fragref linkend="man.indent.lists.frag"></src:fragref>
|
---|
3177 | <src:fragref linkend="man.indent.refsect.frag"></src:fragref>
|
---|
3178 | <src:fragref linkend="man.indent.verbatims.frag"></src:fragref>
|
---|
3179 | <src:fragref linkend="man.indent.width.frag"></src:fragref>
|
---|
3180 | <src:fragref linkend="man.justify.frag"></src:fragref>
|
---|
3181 | <src:fragref linkend="man.output.base.dir.frag"></src:fragref>
|
---|
3182 | <src:fragref linkend="man.output.encoding.frag"></src:fragref>
|
---|
3183 | <src:fragref linkend="man.output.in.separate.dir.frag"></src:fragref>
|
---|
3184 | <src:fragref linkend="man.output.lang.in.name.enabled.frag"></src:fragref>
|
---|
3185 | <src:fragref linkend="man.output.manifest.enabled.frag"></src:fragref>
|
---|
3186 | <src:fragref linkend="man.output.manifest.filename.frag"></src:fragref>
|
---|
3187 | <src:fragref linkend="man.output.better.ps.enabled.frag"></src:fragref>
|
---|
3188 | <src:fragref linkend="man.output.quietly.frag"></src:fragref>
|
---|
3189 | <src:fragref linkend="man.output.subdirs.enabled.frag"></src:fragref>
|
---|
3190 | <src:fragref linkend="man.segtitle.suppress.frag"></src:fragref>
|
---|
3191 | <src:fragref linkend="man.string.subst.map.frag"></src:fragref>
|
---|
3192 | <src:fragref linkend="man.string.subst.map.local.post.frag"></src:fragref>
|
---|
3193 | <src:fragref linkend="man.string.subst.map.local.pre.frag"></src:fragref>
|
---|
3194 | <src:fragref linkend="man.subheading.divider.enabled.frag"></src:fragref>
|
---|
3195 | <src:fragref linkend="man.subheading.divider.frag"></src:fragref>
|
---|
3196 | <src:fragref linkend="man.table.footnotes.divider.frag"></src:fragref>
|
---|
3197 | <src:fragref linkend="man.th.extra1.suppress.frag"></src:fragref>
|
---|
3198 | <src:fragref linkend="man.th.extra2.max.length.frag"></src:fragref>
|
---|
3199 | <src:fragref linkend="man.th.extra2.suppress.frag"></src:fragref>
|
---|
3200 | <src:fragref linkend="man.th.extra3.max.length.frag"></src:fragref>
|
---|
3201 | <src:fragref linkend="man.th.extra3.suppress.frag"></src:fragref>
|
---|
3202 | <src:fragref linkend="man.th.title.max.length.frag"></src:fragref>
|
---|
3203 | <src:fragref linkend="refentry.date.profile.enabled.frag"></src:fragref>
|
---|
3204 | <src:fragref linkend="refentry.date.profile.frag"></src:fragref>
|
---|
3205 | <src:fragref linkend="refentry.manual.fallback.profile.frag"></src:fragref>
|
---|
3206 | <src:fragref linkend="refentry.manual.profile.enabled.frag"></src:fragref>
|
---|
3207 | <src:fragref linkend="refentry.manual.profile.frag"></src:fragref>
|
---|
3208 | <src:fragref linkend="refentry.meta.get.quietly.frag"></src:fragref>
|
---|
3209 | <src:fragref linkend="refentry.source.fallback.profile.frag"></src:fragref>
|
---|
3210 | <src:fragref linkend="refentry.source.name.profile.enabled.frag"></src:fragref>
|
---|
3211 | <src:fragref linkend="refentry.source.name.profile.frag"></src:fragref>
|
---|
3212 | <src:fragref linkend="refentry.source.name.suppress.frag"></src:fragref>
|
---|
3213 | <src:fragref linkend="refentry.version.profile.enabled.frag"></src:fragref>
|
---|
3214 | <src:fragref linkend="refentry.version.profile.frag"></src:fragref>
|
---|
3215 | <src:fragref linkend="refentry.version.suppress.frag"></src:fragref>
|
---|
3216 | </xsl:stylesheet>
|
---|
3217 | </programlisting>
|
---|
3218 |
|
---|
3219 | </appendix>
|
---|
3220 | </book>
|
---|