Manpages Parameter Reference
$Id: param.xweb 9130 2011-10-11 08:05:37Z dpawson $
The DocBook Project
2005-2011
The DocBook Project
This is reference documentation for all user-configurable
parameters in the DocBook XSL "manpages" stylesheet (for
generating groff/nroff output). Note that the manpages
stylesheet is a customization layer of the DocBook XSL HTML
stylesheet. Therefore, you can also use a number of
Hyphenation, justification, and breaking
man.hyphenate
boolean
man.hyphenate
Enable hyphenation?
<xsl:param name="man.hyphenate">0</xsl:param>
Description If non-zero, hyphenation is enabled.
The default value for this parameter is zero because groff is
not particularly smart about how it does hyphenation; it can end up
hyphenating a lot of things that you don't want hyphenated. To
mitigate that, the default behavior of the stylesheets is to suppress
hyphenation of computer inlines, filenames, and URLs. (You can
override the default behavior by setting non-zero values for the
man.hyphenate.urls ,
man.hyphenate.filenames , and
man.hyphenate.computer.inlines parameters.) But
the best way is still to just globally disable hyphenation, as the
stylesheets do by default.
The only good reason to enabled hyphenation is if you have also
enabled justification (which is disabled by default). The reason is
that justified text can look very bad unless you also hyphenate it; to
quote the Hypenation
node from the groff info page:
Since the odds are not great for finding a set of
words, for every output line, which fit nicely on a line without
inserting excessive amounts of space between words, 'gtroff'
hyphenates words so that it can justify lines without inserting too
much space between words.
So, if you set a non-zero value for the
man.justify parameter (to enable
justification), then you should probably also set a non-zero value for
man.hyphenate (to enable hyphenation).
man.hyphenate.urls
boolean
man.hyphenate.urls
Hyphenate URLs?
<xsl:param name="man.hyphenate.urls">0</xsl:param>
Description If zero (the default), hyphenation is suppressed for output of
the ulink url attribute.
If hyphenation is already turned off globally (that is, if
man.hyphenate is zero, setting
man.hyphenate.urls is not necessary.
If man.hyphenate.urls is non-zero, URLs
will not be treated specially and are subject to hyphenation just like
other words.
If you are thinking about setting a non-zero value for
man.hyphenate.urls in order to make long
URLs break across lines, you'd probably be better off
experimenting with setting the
man.break.after.slash parameter first. That
will cause long URLs to be broken after slashes.
man.hyphenate.filenames
boolean
man.hyphenate.filenames
Hyphenate filenames?
<xsl:param name="man.hyphenate.filenames">0</xsl:param>
Description If zero (the default), hyphenation is suppressed for
filename output.
If hyphenation is already turned off globally (that is, if
man.hyphenate is zero, setting
man.hyphenate.filenames is not
necessary.
If man.hyphenate.filenames is non-zero,
filenames will not be treated specially and are subject to hyphenation
just like other words.
If you are thinking about setting a non-zero value for
man.hyphenate.filenames in order to make long
filenames/pathnames break across lines, you'd probably be better off
experimenting with setting the
man.break.after.slash parameter first. That
will cause long pathnames to be broken after slashes.
man.hyphenate.computer.inlines
boolean
man.hyphenate.computer.inlines
Hyphenate computer inlines?
<xsl:param name="man.hyphenate.computer.inlines">0</xsl:param>
Description If zero (the default), hyphenation is suppressed for
computer inlines
such as environment variables,
constants, etc. This parameter current affects output of the following
elements:
classname constant envar errorcode option replaceable userinput type varname
If hyphenation is already turned off globally (that is, if
man.hyphenate is zero, setting the
man.hyphenate.computer.inlines is not
necessary.
If man.hyphenate.computer.inlines is
non-zero, computer inlines will not be treated specially and will be
hyphenated like other words when needed.
man.justify
boolean
man.justify
Justify text to both right and left margins?
<xsl:param name="man.justify">0</xsl:param>
Description If non-zero, text is justified to both the right and left
margins (or, in roff terminology, "adjusted and filled" to both the
right and left margins). If zero (the default), text is adjusted to
the left margin only -- producing what is traditionally called
"ragged-right" text.
The default value for this parameter is zero because justified
text looks good only when it is also hyphenated. Without hyphenation,
excessive amounts of space often end up getting between words, in
order to "pad" lines out to align on the right margin.
The problem is that groff is not particularly smart about how it
does hyphenation; it can end up hyphenating a lot of things that you
don't want hyphenated. So, disabling both justification and
hyphenation ensures that hyphens won't get inserted where you don't
want to them, and you don't end up with lines containing excessive
amounts of space between words.
However, if do you decide to set a non-zero value for the
man.justify parameter (to enable
justification), then you should probably also set a non-zero value for
man.hyphenate (to enable hyphenation).
Yes, these default settings run counter to how most existing man
pages are formatted. But there are some notable exceptions, such as
the perl man pages.
man.break.after.slash
boolean
man.break.after.slash
Enable line-breaking after slashes?
<xsl:param name="man.break.after.slash">0</xsl:param>
Description If non-zero, line-breaking after slashes is enabled. This is
mainly useful for causing long URLs or pathnames/filenames to be
broken up or "wrapped" across lines (though it also has the side
effect of sometimes causing relatively short URLs and pathnames to be
broken up across lines too).
If zero (the default), line-breaking after slashes is
disabled. In that case, strings containing slashes (for example, URLs
or filenames) are not broken across lines, even if they exceed the
maximum column widith.
If you set a non-zero value for this parameter, check your
man-page output carefuly afterwards, in order to make sure that the
setting has not introduced an excessive amount of breaking-up of URLs
or pathnames. If your content contains mostly short URLs or
pathnames, setting a non-zero value for
man.break.after.slash will probably result in
in a significant number of relatively short URLs and pathnames being
broken across lines, which is probably not what you want.
Indentation
man.indent.width
length
man.indent.width
Specifies width used for adjusted indents
<xsl:param name="man.indent.width">4</xsl:param>
Description The man.indent.width parameter specifies
the width used for adjusted indents. The value of
man.indent.width is used for indenting of
lists, verbatims, headings, and elsewhere, depending on whether the
values of certain man.indent.* boolean parameters
are non-zero.
The value of man.indent.width should
include a valid roff measurement unit (for example,
n or u ). The default value of
4n specifies a 4-en width; when viewed on a
console, that amounts to the width of four characters. For details
about roff measurment units, see the Measurements
node in the groff info page.
man.indent.refsect
boolean
man.indent.refsect
Adjust indentation of refsect* and refsection?
<xsl:param name="man.indent.refsect" select="0"></xsl:param>
Description If the value of man.indent.refsect is
non-zero, the width of the left margin for
refsect1 , refsect2 and
refsect3 contents and titles (and first-level,
second-level, and third-level nested
refsection instances) is adjusted by the value of
the man.indent.width parameter. With
man.indent.width set to its default value of
3n , the main results are that:
contents of refsect1 are output with a
left margin of three characters instead the roff default of seven
or eight characters
contents of refsect2 are displayed in
console output with a left margin of six characters instead the of
the roff default of seven characters
the contents of refsect3 and nested
refsection instances are adjusted
accordingly.
If instead the value of man.indent.refsect is
zero, no margin adjustment is done for refsect*
output.
If your content is primarly comprised of
refsect1 and refsect2 content
(or the refsection equivalent) – with few or
no refsect3 or lower nested sections , you may be
able to “conserve” space in your output by setting
man.indent.refsect to a non-zero value. Doing
so will “squeeze” the left margin in such as way as to provide an
additional four characters of “room” per line in
refsect1 output. That extra room may be useful
if, for example, you have many verbatim sections with long lines in
them.
man.indent.blurbs
boolean
man.indent.blurbs
Adjust indentation of blurbs?
<xsl:param name="man.indent.blurbs" select="1"></xsl:param>
Description If the value of man.indent.blurbs is
non-zero, the width of the left margin for
authorblurb , personblurb , and
contrib output is set to the value of the
man.indent.width parameter
(3n by default). If instead the value of
man.indent.blurbs is zero, the built-in roff
default width (7.2n ) is used.
man.indent.lists
boolean
man.indent.lists
Adjust indentation of lists?
<xsl:param name="man.indent.lists" select="1"></xsl:param>
Description If the value of man.indent.lists is
non-zero, the width of the left margin for list items in
itemizedlist ,
orderedlist ,
variablelist output (and output of some other
lists) is set to the value of the
man.indent.width parameter
(4n by default). If instead the value of
man.indent.lists is zero, the built-in roff
default width (7.2n ) is used.
man.indent.verbatims
boolean
man.indent.verbatims
Adjust indentation of verbatims?
<xsl:param name="man.indent.verbatims" select="1"></xsl:param>
Description If the value of man.indent.verbatims is
non-zero, the width of the left margin for output of verbatim
environments (programlisting ,
screen , and so on) is set to the value of the
man.indent.width parameter
(3n by default). If instead the value of
man.indent.verbatims is zero, the built-in roff
default width (7.2n ) is used.
Fonts
man.font.funcprototype
string
man.font.funcprototype
Specifies font for funcprototype output
<xsl:param name="man.font.funcprototype">BI</xsl:param>
Description The man.font.funcprototype parameter
specifies the font for funcprototype output. It
should be a valid roff font name, such as BI or
B .
man.font.funcsynopsisinfo
string
man.font.funcsynopsisinfo
Specifies font for funcsynopsisinfo output
<xsl:param name="man.font.funcsynopsisinfo">B</xsl:param>
Description The man.font.funcsynopsisinfo parameter
specifies the font for funcsynopsisinfo output. It
should be a valid roff font name, such as B or
I .
man.font.links
string
man.font.links
Specifies font for links
<xsl:param name="man.font.links">B</xsl:param>
Description The man.font.links parameter
specifies the font for output of links (ulink instances
and any instances of any element with an xlink:href attribute).
The value of man.font.links must be
either B or I , or empty. If
the value is empty, no font formatting is applied to links.
If you set man.endnotes.are.numbered and/or
man.endnotes.list.enabled to zero (disabled), then
you should probably also set an empty value for
man.font.links . But if
man.endnotes.are.numbered is non-zero (enabled),
you should probably keep
man.font.links set to
B or I The
main purpose of applying a font format to links in most output
formats it to indicate that the formatted text is
“clickable”; given that links rendered in man pages are
not “real” hyperlinks that users can click on, it might
seem like there is never a good reason to have font formatting for
link contents in man output.
In fact, if you suppress the
display of inline link references (by setting
man.endnotes.are.numbered to zero), there is no
good reason to apply font formatting to links. However, if
man.endnotes.are.numbered is non-zero, having
font formatting for links (arguably) serves a purpose: It provides
“context” information about exactly what part of the text
is being “annotated” by the link. Depending on how you
mark up your content, that context information may or may not
have value.
Related Parameters man.endnotes.list.enabled ,
man.endnotes.are.numbered
man.font.table.headings
string
man.font.table.headings
Specifies font for table headings
<xsl:param name="man.font.table.headings">B</xsl:param>
Description The man.font.table.headings parameter
specifies the font for table headings. It should be
a valid roff font, such as B or
I .
man.font.table.title
string
man.font.table.title
Specifies font for table headings
<xsl:param name="man.font.table.title">B</xsl:param>
Description The man.font.table.title parameter
specifies the font for table titles. It should be
a valid roff font, such as B or
I .
SYNOPSIS section
man.funcsynopsis.style
list
ansi
kr
man.funcsynopsis.style
What style of funcsynopsis should be generated?
<xsl:param name="man.funcsynopsis.style">ansi</xsl:param>
Description If man.funcsynopsis.style is
ansi , ANSI-style function synopses are
generated for a funcsynopsis , otherwise K&R-style
function synopses are generated.
AUTHORS and COPYRIGHT sections
man.authors.section.enabled
boolean
man.authors.section.enabled
Display auto-generated AUTHORS section?
<xsl:param name="man.authors.section.enabled">1</xsl:param>
Description If the value of
man.authors.section.enabled is non-zero
(the default), then an AUTHORS section is
generated near the end of each man page. The output of the
AUTHORS section is assembled from any
author , editor , and othercredit
metadata found in the contents of the child info or
refentryinfo (if any) of the refentry
itself, or from any author , editor , and
othercredit metadata that may appear in info
contents of any ancestors of the refentry .
If the value of
man.authors.section.enabled is zero, the
the auto-generated AUTHORS section is
suppressed.
Set the value of
man.authors.section.enabled to zero if
you want to have a manually created AUTHORS
section in your source, and you want it to appear in output
instead of the auto-generated AUTHORS
section.
man.copyright.section.enabled
boolean
man.copyright.section.enabled
Display auto-generated COPYRIGHT section?
<xsl:param name="man.copyright.section.enabled">1</xsl:param>
Description If the value of
man.copyright.section.enabled is non-zero
(the default), then a COPYRIGHT section is
generated near the end of each man page. The output of the
COPYRIGHT section is assembled from any
copyright and legalnotice metadata found in
the contents of the child info or
refentryinfo (if any) of the refentry
itself, or from any copyright and
legalnotice metadata that may appear in info
contents of any ancestors of the refentry .
If the value of
man.copyright.section.enabled is zero, the
the auto-generated COPYRIGHT section is
suppressed.
Set the value of
man.copyright.section.enabled to zero if
you want to have a manually created COPYRIGHT
section in your source, and you want it to appear in output
instead of the auto-generated COPYRIGHT
section.
Endnotes and link handling
man.endnotes.list.enabled
boolean
man.endnotes.list.enabled
Display endnotes list at end of man page?
<xsl:param name="man.endnotes.list.enabled">1</xsl:param>
Description If the value of man.endnotes.list.enabled is
non-zero (the default), then an endnotes list is added to the end of
the output man page.
If the value of man.endnotes.list.enabled is
zero, the list is suppressed — unless link numbering is enabled (that
is, if man.endnotes.are.numbered is non-zero), in
which case, that setting overrides the
man.endnotes.list.enabled setting, and the
endnotes list is still displayed. The reason is that inline
numbering of notesources associated with endnotes only makes sense
if a (numbered) list of endnotes is also generated.
Leaving
man.endnotes.list.enabled at its default
(non-zero) value ensures that no “out of line” information (such
as the URLs for hyperlinks and images) gets lost in your
man-page output. It just gets “rearranged”.
So if you’re thinking about disabling endnotes listing by
setting the value of
man.endnotes.list.enabled to zero:
Before you do so, first take some time to carefully consider
the information needs and experiences of your users. The “out
of line” information has value even if the presentation of it
in text output is not as interactive as it may be in other
output formats.
As far as the specific case of URLs: Even though the URLs
displayed in text output may not be “real” (clickable)
hyperlinks, many X terminals have convenience features for
recognizing URLs and can, for example, present users with
an options to open a URL in a browser with the user clicks on
the URL is a terminal window. And short of those, users with X
terminals can always manually cut and paste the URLs into a web
browser.
Also, note that various “man to html” tools, such as the
widely used VH-Man2html )
application, automatically mark up URLs with a@href markup
during conversion — resulting in “real” hyperlinks in HTML
output from those tools.
To “turn off” numbering of endnotes in the
endnotes list, set man.endnotes.are.numbered
to zero. The endnotes list will
still be displayed; it will just be displayed without the
numbersIt can still make sense to have
the list of endnotes displayed even if you have endnotes numbering turned
off. In that case, your endnotes list basically becomes a “list
of references” without any association with specific text in
your document. This is probably the best option if you find the inline
endnotes numbering obtrusive. Your users will still have access to all the “out of line”
such as URLs for hyperlinks.
The default heading for the endnotes list is
NOTES . To change that, set a non-empty
value for the man.endnotes.list.heading
parameter.
In the case of notesources that are links: Along with the
URL for each link, the endnotes list includes the contents of the
link. The list thus includes only non-empty
A “non-empty” link is one that looks like
this: <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/">manpages</ulink>
an “empty link” is on that looks like this: <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/>
links.
Empty links are never included, and never numbered. They are simply
displayed inline, without any numbering.
In addition, if there are multiple instances of links in a
refentry that have the same URL, the URL is listed only
once. The contents listed for that link in the endnotes list are
the contents of the first link which has that URL.
If you disable endnotes listing, you should probably also set
man.links.are.underlined to zero (to disable
link underlining).
man.endnotes.list.heading
string
man.endnotes.list.heading
Specifies an alternate name for endnotes list
<xsl:param name="man.endnotes.list.heading"></xsl:param>
Description If the value of the
man.endnotes.are.numbered parameter
and/or the man.endnotes.list.enabled
parameter is non-zero (the defaults for both are non-zero), a
numbered list of endnotes is generated near the end of each man
page. The default heading for the list of endnotes is the
equivalent of the English word NOTES in
the current locale. To cause an alternate heading to be displayed,
set a non-empty value for the
man.endnotes.list.heading parameter —
for example, REFERENCES .
man.endnotes.are.numbered
boolean
man.endnotes.are.numbered
Number endnotes?
<xsl:param name="man.endnotes.are.numbered">1</xsl:param>
Description If the value of man.endnotes.are.numbered is
non-zero (the default), then for each non-empty
A “non-empty” notesource is one that looks like
this: <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/">manpages</ulink>
an “empty” notesource is on that looks like this: <ulink url="http://docbook.sf.net/snapshot/xsl/doc/manpages/"/>
“notesource”:
a number (in square brackets) is displayed inline after the
rendered inline contents (if any) of the notesource
the contents of the notesource are included in a
numbered list of endnotes that is generated at the end of
each man page; the number for each endnote corresponds to
the inline number for the notesource with which it is
associated
The default heading for the list of endnotes is
NOTES . To output a different heading, set a value
for the man.endnotes.section.heading
parameter.
The endnotes list is also displayed (but without
numbers) if the value of
man.endnotes.list.enabled is
non-zero.
If the value of man.endnotes.are.numbered is
zero, numbering of endnotess is suppressed; only inline
contents (if any) of the notesource are displayed inline.
If you are thinking about disabling endnote numbering by setting
the value of man.endnotes.are.numbered to zero,
before you do so, first take some time to carefully
consider the information needs and experiences of your users. The
square-bracketed numbers displayed inline after notesources may seem
obstrusive and aesthetically unpleasingAs far as notesources that are links, ytou might
think it would be better to just display URLs for non-empty
links inline, after their content, rather than displaying
square-bracketed numbers all over the place. But it's not better. In
fact, it's not even practical, because many (most) URLs for links
are too long to be displayed inline. They end up overflowing the
right margin. You can set a non-zero value for
man.break.after.slash parameter to deal with
that, but it could be argued that what you end up with is at least
as ugly, and definitely more obstrusive, then having short
square-bracketed numbers displayed inline.
Also, users of “text based” browsers such as
lynx will already be accustomed to seeing inline
numbers for links. And various "man to html" applications, such as
the widely used VH-Man2html )
application, can automatically turn URLs into "real" HTML hyperlinks
in output. So leaving man.endnotes.are.numbered
at its default (non-zero) value ensures that no information is
lost in your man-page output. It just gets
“rearranged”.
The handling of empty links is not affected by this
parameter. Empty links are handled simply by displaying their URLs
inline. Empty links are never auto-numbered.
If you disable endnotes numbering, you should probably also set
man.font.links to an empty value (to
disable font formatting for links.
Related Parameters man.endnotes.list.enabled ,
man.font.links
man.base.url.for.relative.links
string
man.base.url.for.relative.links
Specifies a base URL for relative links
<xsl:param name="man.base.url.for.relative.links">[set $man.base.url.for.relative.links]/</xsl:param>
Description For any “notesource” listed in the auto-generated
“NOTES” section of output man pages (which is generated when
the value of the
man.endnotes.list.enabled parameter
is non-zero), if the notesource is a link source with a
relative URI, the URI is displayed in output with the value
of the
man.base.url.for.relative.links
parameter prepended to the value of the link URI.
A link source is an notesource that references an
external resource:
a ulink element with a url attribute
any element with an xlink:href attribute
an imagedata , audiodata , or
videodata element
If you use relative URIs in link sources in your DocBook
refentry source, and you leave
man.base.url.for.relative.links
unset, the relative links will appear “as is” in the “Notes”
section of any man-page output generated from your source.
That’s probably not what you want, because such relative
links are only usable in the context of HTML output. So, to
make the links meaningful and usable in the context of
man-page output, set a value for
man.base.url.for.relative.links that
points to the online version of HTML output generated from
your DocBook refentry source. For
example:
<xsl:param name="man.base.url.for.relative.links"
>http://www.kernel.org/pub/software/scm/git/docs/</xsl:param>
Related Parameters man.endnotes.list.enabled
Lists
man.segtitle.suppress
boolean
man.segtitle.suppress
Suppress display of segtitle contents?
<xsl:param name="man.segtitle.suppress" select="0"></xsl:param>
Description If the value of man.segtitle.suppress is
non-zero, then display of segtitle contents is
suppressed in output.
Character/string substitution
man.charmap.enabled
boolean
man.charmap.enabled
Apply character map before final output?
<xsl:param name="man.charmap.enabled" select="1"></xsl:param>
Description If the value of the man.charmap.enabled
parameter is non-zero, a "character map" is used to substitute certain
Unicode symbols and special characters with appropriate roff/groff
equivalents, just before writing each man-page file to the
filesystem. If instead the value of
man.charmap.enabled is zero, Unicode characters
are passed through "as is".
Details For converting certain Unicode symbols and special characters in
UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
equivalents in man-page output, the DocBook XSL Stylesheets
distribution includes a
You can use the man.charmap.uri
parameter to specify a URI for the location for an alternate roff
character map to use in place of the standard roff character map
provided in the distribution.
You can also use a subset of a character map. For details,
see the man.charmap.use.subset ,
man.charmap.subset.profile , and
man.charmap.subset.profile.english
parameters.
man.charmap.uri
uri
man.charmap.uri
URI for custom roff character map
<xsl:param name="man.charmap.uri"></xsl:param>
Description For converting certain Unicode symbols and special characters in
UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
equivalents in man-page output, the DocBook XSL Stylesheets
distribution includes an
If the value of the man.charmap.uri
parameter is non-empty, that value is used as the URI for the location
for an alternate roff character map to use in place of the standard
roff character map provided in the distribution.
Do not set a value for man.charmap.uri
unless you have a custom roff character map that differs from the
standard one provided in the distribution.
man.charmap.use.subset
boolean
man.charmap.use.subset
Use subset of character map instead of full map?
<xsl:param name="man.charmap.use.subset" select="1"></xsl:param>
Description If the value of the
man.charmap.use.subset parameter is non-zero,
a subset of the roff character map is used instead of the full roff
character map. The profile of the subset used is determined either
by the value of the
man.charmap.subset.profile
parameter (if the source is not in English) or the
man.charmap.subset.profile.english
parameter (if the source is in English).
You may want to experiment with setting a non-zero value of
man.charmap.use.subset , so that the full
character map is used. Depending on which XSLT engine you run,
setting a non-zero value for
man.charmap.use.subset may significantly
increase the time needed to process your documents. Or it may
not. For example, if you set it and run it with xsltproc, it seems
to dramatically increase processing time; on the other hand, if you
set it and run it with Saxon, it does not seem to increase
processing time nearly as much.
If processing time is not a important concern and/or you can
tolerate the increase in processing time imposed by using the full
character map, set man.charmap.use.subset to
zero.
Details For converting certain Unicode symbols and special characters in
UTF-8 or UTF-16 encoded XML source to appropriate groff/roff
equivalents in man-page output, the DocBook XSL Stylesheets
distribution includes a
You can use the man.charmap.uri
parameter to specify a URI for the location for an alternate roff
character map to use in place of the standard roff character map
provided in the distribution.
Because it is not terrifically efficient to use the standard
800-character character map in full -- and for most (or all) users,
never necessary to use it in full -- the DocBook XSL Stylesheets
support a mechanism for using, within any given character map, a
subset of character mappings instead of the full set. You can use the
man.charmap.subset.profile or
man.charmap.subset.profile.english
parameter to tune the profile of that subset to use.
man.charmap.subset.profile
string
man.charmap.subset.profile
Profile of character map subset
<xsl:param name="man.charmap.subset.profile">
@*[local-name() = 'block'] = 'Miscellaneous Technical' or
(@*[local-name() = 'block'] = 'C1 Controls And Latin-1 Supplement (Latin-1 Supplement)' and
(@*[local-name() = 'class'] = 'symbols' or
@*[local-name() = 'class'] = 'letters')
) or
@*[local-name() = 'block'] = 'Latin Extended-A'
or
(@*[local-name() = 'block'] = 'General Punctuation' and
(@*[local-name() = 'class'] = 'spaces' or
@*[local-name() = 'class'] = 'dashes' or
@*[local-name() = 'class'] = 'quotes' or
@*[local-name() = 'class'] = 'bullets'
)
) or
@*[local-name() = 'name'] = 'HORIZONTAL ELLIPSIS' or
@*[local-name() = 'name'] = 'WORD JOINER' or
@*[local-name() = 'name'] = 'SERVICE MARK' or
@*[local-name() = 'name'] = 'TRADE MARK SIGN' or
@*[local-name() = 'name'] = 'ZERO WIDTH NO-BREAK SPACE'
</xsl:param>
Description If the value of the
man.charmap.use.subset parameter is non-zero,
and your DocBook source is not written in English (that
is, if the lang or xml:lang attribute on the root element
in your DocBook source or on the first refentry
element in your source has a value other than
en ), then the character-map subset specified
by the man.charmap.subset.profile
parameter is used instead of the full roff character map.
Otherwise, if the lang or xml:lang attribute on the root
element in your DocBook
source or on the first refentry element in your source
has the value en or if it has no lang or xml:lang attribute, then the character-map
subset specified by the
man.charmap.subset.profile.english
parameter is used instead of
man.charmap.subset.profile .
The difference between the two subsets is that
man.charmap.subset.profile provides
mappings for characters in Western European languages that are
not part of the Roman (English) alphabet (ASCII character set).
The value of man.charmap.subset.profile
is a string representing an XPath expression that matches attribute
names and values for output-character
elements in the character map.
The attributes supported in the
character
a raw Unicode character or numeric Unicode
character-entity value (either in decimal or hex); all
characters have this attribute
name
a standard full/long ISO/Unicode character name (e.g.,
"OHM SIGN"); all characters have this attribute
block
a standard Unicode "block" name (e.g., "General
Punctuation"); all characters have this attribute. For the full
list of Unicode block names supported in the standard roff
character map, see
class
a class of characters (e.g., "spaces"). Not all
characters have this attribute; currently, it is used only with
certain characters within the "C1 Controls And Latin-1
Supplement" and "General Punctuation" blocks. For details, see
entity
an ISO entity name (e.g., "ohm"); not all characters
have this attribute, because not all characters have ISO entity
names; for example, of the 800 or so characters in the standard
roff character map included in the distribution, only around 300
have ISO entity names.
string
a string representing an roff/groff escape-code (with
"@esc@" used in place of the backslash), or a simple ASCII
string; all characters in the roff character map have this
attribute
The value of man.charmap.subset.profile
is evaluated as an XPath expression at run-time to select a portion of
the roff character map to use. You can tune the subset used by adding
or removing parts. For example, if you need to use a wide range of
mathematical operators in a document, and you want to have them
converted into roff markup properly, you might add the following:
@*[local-name() = 'block'] ='MathematicalOperators'
That will cause a additional set of around 67 additional "math"
characters to be converted into roff markup.
Depending on which XSLT engine you use, either the EXSLT
dyn:evaluate extension function (for xsltproc or
Xalan) or saxon:evaluate extension function (for
Saxon) are used to dynamically evaluate the value of
man.charmap.subset.profile at run-time. If you
don't use xsltproc, Saxon, Xalan -- or some other XSLT engine that
supports dyn:evaluate -- you must either set the
value of the man.charmap.use.subset parameter
to zero and process your documents using the full character map
instead, or set the value of the
man.charmap.enabled parameter to zero instead
(so that character-map processing is disabled completely.
An alternative to using
man.charmap.subset.profile is to create your
own custom character map, and set the value of
man.charmap.uri to the URI/filename for
that. If you use a custom character map, you will probably want to
include in it just the characters you want to use, and so you will
most likely also want to set the value of
man.charmap.use.subset to zero.
You can create a
custom character map by making a copy of the
If you author your DocBook XML source in UTF-8 or UTF-16
encoding and aren't sure what OSes or environments your man-page
output might end up being viewed on, and not sure what version of
nroff/groff those environments might have, you should be careful about
what Unicode symbols and special characters you use in your source and
what parts you add to the value of
man.charmap.subset.profile .
Many of the escape codes used are specific to groff and using
them may not provide the expected output on an OS or environment that
uses nroff instead of groff.
On the other hand, if you intend for your man-page output to be
viewed only on modern systems (for example, GNU/Linux systems, FreeBSD
systems, or Cygwin environments) that have a good, up-to-date groff,
then you can safely include a wide range of Unicode symbols and
special characters in your UTF-8 or UTF-16 encoded DocBook XML source
and add any of the supported Unicode block names to the value of
man.charmap.subset.profile .
For other details, see the documentation for the
man.charmap.use.subset parameter.
Supported Unicode block names and "class" values Below is the full list of Unicode block names and "class"
values supported in the standard roff stylesheet provided in the
distribution, along with a description of which codepoints from the
Unicode range corresponding to that block name or block/class
combination are supported.
class values
symbols
letters
class values
quotes
daggers
bullets
leaders
primes
man.charmap.subset.profile.english
string
man.charmap.subset.profile.english
Profile of character map subset
<xsl:param name="man.charmap.subset.profile.english">
@*[local-name() = 'block'] = 'Miscellaneous Technical' or
(@*[local-name() = 'block'] = 'C1 Controls And Latin-1 Supplement (Latin-1 Supplement)' and
@*[local-name() = 'class'] = 'symbols')
or
(@*[local-name() = 'block'] = 'General Punctuation' and
(@*[local-name() = 'class'] = 'spaces' or
@*[local-name() = 'class'] = 'dashes' or
@*[local-name() = 'class'] = 'quotes' or
@*[local-name() = 'class'] = 'bullets'
)
) or
@*[local-name() = 'name'] = 'HORIZONTAL ELLIPSIS' or
@*[local-name() = 'name'] = 'WORD JOINER' or
@*[local-name() = 'name'] = 'SERVICE MARK' or
@*[local-name() = 'name'] = 'TRADE MARK SIGN' or
@*[local-name() = 'name'] = 'ZERO WIDTH NO-BREAK SPACE'
</xsl:param>
Description If the value of the
man.charmap.use.subset parameter is
non-zero, and your DocBook source is written in English (that
is, if its lang or xml:lang attribute on the root element
in your DocBook source or on the first refentry
element in your source has the value en or if
it has no lang or xml:lang attribute), then the
character-map subset specified by the
man.charmap.subset.profile.english
parameter is used instead of the full roff character map.
Otherwise, if the lang or xml:lang attribute
on the root element in your DocBook source or on the first
refentry element in your source has a value other
than en , then the character-map subset
specified by the
man.charmap.subset.profile parameter is
used instead of
man.charmap.subset.profile.english .
The difference between the two subsets is that
man.charmap.subset.profile provides
mappings for characters in Western European languages that are
not part of the Roman (English) alphabet (ASCII character set).
The value of man.charmap.subset.profile.english
is a string representing an XPath expression that matches attribute
names and values for output-character elements in the character map.
For other details, see the documentation for the
man.charmap.subset.profile.english and
man.charmap.use.subset parameters.
man.string.subst.map.local.pre
string
man.string.subst.map.local.pre
Specifies “local” string substitutions
<xsl:param name="man.string.subst.map.local.pre"></xsl:param>
Description Use the man.string.subst.map.local.pre
parameter to specify any “local” string substitutions to perform over
the entire roff source for each man page before
performing the string substitutions specified by the man.string.subst.map parameter.
For details about the format of this parameter, see the
documentation for the man.string.subst.map
parameter.
man.string.subst.map
rtf
man.string.subst.map
Specifies a set of string substitutions
<xsl:param name="man.string.subst.map">
<!-- * remove no-break marker at beginning of line (stylesheet artifact) -->
<ss:substitution oldstring="▒▀" newstring="▒"></ss:substitution>
<!-- * replace U+2580 no-break marker (stylesheet-added) w/ no-break space -->
<ss:substitution oldstring="▀" newstring="\ "></ss:substitution>
<!-- ==================================================================== -->
<!-- * squeeze multiple newlines before a roff request -->
<ss:substitution oldstring="
." newstring="
."></ss:substitution>
<!-- * remove any .sp instances that directly precede a .PP -->
<ss:substitution oldstring=".sp
.PP" newstring=".PP"></ss:substitution>
<!-- * remove any .sp instances that directly follow a .PP -->
<ss:substitution oldstring=".sp
.sp" newstring=".sp"></ss:substitution>
<!-- * squeeze multiple .sp instances into a single .sp-->
<ss:substitution oldstring=".PP
.sp" newstring=".PP"></ss:substitution>
<!-- * squeeze multiple newlines after start of no-fill (verbatim) env. -->
<ss:substitution oldstring=".nf
" newstring=".nf
"></ss:substitution>
<!-- * squeeze multiple newlines after REstoring margin -->
<ss:substitution oldstring=".RE
" newstring=".RE
"></ss:substitution>
<!-- * U+2591 is a marker we add before and after every Parameter in -->
<!-- * Funcprototype output -->
<ss:substitution oldstring="░" newstring=" "></ss:substitution>
<!-- * U+2592 is a marker we add for the newline before output of <sbr>; -->
<ss:substitution oldstring="▒" newstring="
"></ss:substitution>
<!-- * -->
<!-- * Now deal with some other characters that are added by the -->
<!-- * stylesheets during processing. -->
<!-- * -->
<!-- * bullet -->
<ss:substitution oldstring="•" newstring="\(bu"></ss:substitution>
<!-- * left double quote -->
<ss:substitution oldstring="“" newstring="\(lq"></ss:substitution>
<!-- * right double quote -->
<ss:substitution oldstring="”" newstring="\(rq"></ss:substitution>
<!-- * left single quote -->
<ss:substitution oldstring="‘" newstring="\(oq"></ss:substitution>
<!-- * right single quote -->
<ss:substitution oldstring="’" newstring="\(cq"></ss:substitution>
<!-- * copyright sign -->
<ss:substitution oldstring="©" newstring="\(co"></ss:substitution>
<!-- * registered sign -->
<ss:substitution oldstring="®" newstring="\(rg"></ss:substitution>
<!-- * ...servicemark... -->
<!-- * There is no groff equivalent for it. -->
<ss:substitution oldstring="℠" newstring="(SM)"></ss:substitution>
<!-- * ...trademark... -->
<!-- * We don't do "\(tm" because for console output, -->
<!-- * groff just renders that as "tm"; that is: -->
<!-- * -->
<!-- * Product™ -> Producttm -->
<!-- * -->
<!-- * So we just make it to "(TM)" instead; thus: -->
<!-- * -->
<!-- * Product™ -> Product(TM) -->
<ss:substitution oldstring="™" newstring="(TM)"></ss:substitution>
</xsl:param>
Description The man.string.subst.map parameter
contains man.charmap.enabled parameter is non-zero,
before applying the roff character map.
You can use man.string.subst.map as a
“lightweight” character map to perform “essential” substitutions --
that is, substitutions that are always performed,
even if the value of the man.charmap.enabled
parameter is zero. For example, you can use it to replace quotation
marks or other special characters that are generated by the DocBook
XSL stylesheets for a particular locale setting (as opposed to those
characters that are actually in source XML documents), or to replace
any special characters that may be automatically generated by a
particular customization of the DocBook XSL stylesheets.
Do you not change value of the
man.string.subst.map parameter unless you are
sure what you are doing. First consider adding your
string-substitution mappings to either or both of the following
parameters:
man.string.subst.map.local.pre applied before
man.string.subst.map
man.string.subst.map.local.post applied after
man.string.subst.map
By default, both of those parameters contain no
string substitutions. They are intended as a means for you to
specify your own local string-substitution mappings.
If you remove any of default mappings from the value of the
man.string.subst.map parameter, you are
likely to end up with broken output. And be very careful about adding
anything to it; it’s used for doing string substitution over the
entire roff source of each man page – it causes target strings to be
replaced in roff requests and escapes, not just in the visible
contents of the page.
Contents of the substitution map
The string-substitution map contains one or more
ss:substitution elements, each of which has two
attributes:
oldstring
string to replace
newstring
string with which to replace oldstring
It may also include XML comments (that is, delimited with
"<!-- " and "--> ").
man.string.subst.map.local.post
string
man.string.subst.map.local.post
Specifies “local” string substitutions
<xsl:param name="man.string.subst.map.local.post"></xsl:param>
Description Use the man.string.subst.map.local.post
parameter to specify any “local” string substitutions to perform over
the entire roff source for each man page after
performing the string substitutions specified by the man.string.subst.map parameter.
For details about the format of this parameter, see the
documentation for the man.string.subst.map
parameter.
Refentry metadata gathering
refentry.meta.get.quietly
boolean
refentry.meta.get.quietly
Suppress notes and warnings when gathering refentry metadata?
<xsl:param name="refentry.meta.get.quietly" select="0"></xsl:param>
Description If zero (the default), notes and warnings about “missing” markup
are generated during gathering of refentry metadata. If non-zero, the
metadata is gathered “quietly” -- that is, the notes and warnings are
suppressed.
If you are processing a large amount of refentry
content, you may be able to speed up processing significantly by
setting a non-zero value for
refentry.meta.get.quietly .
refentry.date.profile
string
refentry.date.profile
Specifies profile for refentry "date" data
<xsl:param name="refentry.date.profile">
(($info[//date])[last()]/date)[1]|
(($info[//pubdate])[last()]/pubdate)[1]
</xsl:param>
Description The value of refentry.date.profile is a
string representing an XPath expression. It is evaluated at run-time
and used only if refentry.date.profile.enabled
is non-zero. Otherwise, the refentry metadata-gathering
logic "hard coded" into the stylesheets is used.
The man(7) man page describes this content
as "the date of the last revision". In man pages, it is the content
that is usually displayed in the center footer.
refentry.date.profile.enabled
boolean
refentry.date.profile.enabled
Enable refentry "date" profiling?
<xsl:param name="refentry.date.profile.enabled">0</xsl:param>
Description If the value of
refentry.date.profile.enabled is non-zero, then
during refentry metadata gathering, the info profile
specified by the customizable
refentry.date.profile parameter is used.
If instead the value of
refentry.date.profile.enabled is zero (the
default), then "hard coded" logic within the DocBook XSL stylesheets
is used for gathering refentry "date" data.
If you find that the default refentry
metadata-gathering behavior is causing incorrect "date" data to show
up in your output, then consider setting a non-zero value for
refentry.date.profile.enabled and adjusting the
value of refentry.date.profile to cause correct
data to be gathered.
Note that the terms "source" and "date" have special meanings in
this context. For details, see the documentation for the
refentry.date.profile parameter.
refentry.manual.profile
string
refentry.manual.profile
Specifies profile for refentry "manual" data
<xsl:param name="refentry.manual.profile">
(($info[//title])[last()]/title)[1]|
../title/node()
</xsl:param>
Description The value of refentry.manual.profile is
a string representing an XPath expression. It is evaluated at
run-time and used only if
refentry.manual.profile.enabled is
non-zero. Otherwise, the refentry metadata-gathering logic
"hard coded" into the stylesheets is used.
In man pages, this content is usually displayed in the middle of
the header of the page. The man(7) man page
describes this as "the title of the manual (e.g., Linux
Programmer's Manual )". Here are some examples from
existing man pages:
dpkg utilities
(dpkg-name )
User Contributed Perl Documentation
(GET )
GNU Development Tools
(ld )
Emperor Norton Utilities
(ddate )
Debian GNU/Linux manual
(faked )
GIMP Manual Pages
(gimp )
KDOC Documentation System
(qt2kdoc )
refentry.manual.profile.enabled
boolean
refentry.manual.profile.enabled
Enable refentry "manual" profiling?
<xsl:param name="refentry.manual.profile.enabled">0</xsl:param>
Description If the value of
refentry.manual.profile.enabled is
non-zero, then during refentry metadata gathering, the info
profile specified by the customizable
refentry.manual.profile parameter is
used.
If instead the value of
refentry.manual.profile.enabled is zero (the
default), then "hard coded" logic within the DocBook XSL stylesheets
is used for gathering refentry "manual" data.
If you find that the default refentry
metadata-gathering behavior is causing incorrect "manual" data to show
up in your output, then consider setting a non-zero value for
refentry.manual.profile.enabled and adjusting
the value of refentry.manual.profile to cause
correct data to be gathered.
Note that the term "manual" has a special meanings in this
context. For details, see the documentation for the
refentry.manual.profile parameter.
refentry.source.name.suppress
boolean
refentry.source.name.suppress
Suppress "name" part of refentry "source" contents?
<xsl:param name="refentry.source.name.suppress">0</xsl:param>
Description If the value of
refentry.source.name.suppress is non-zero, then
during refentry metadata gathering, no "source name" data
is added to the refentry "source" contents. Instead (unless
refentry.version.suppress is also non-zero),
only "version" data is added to the "source" contents.
If you find that the refentry metadata gathering
mechanism is causing unwanted "source name" data to show up in your
output -- for example, in the footer (or possibly header) of a man
page -- then you might consider setting a non-zero value for
refentry.source.name.suppress .
Note that the terms "source", "source name", and "version" have
special meanings in this context. For details, see the documentation
for the refentry.source.name.profile
parameter.
refentry.source.name.profile
string
refentry.source.name.profile
Specifies profile for refentry "source name" data
<xsl:param name="refentry.source.name.profile">
(($info[//productname])[last()]/productname)[1]|
(($info[//corpname])[last()]/corpname)[1]|
(($info[//corpcredit])[last()]/corpcredit)[1]|
(($info[//corpauthor])[last()]/corpauthor)[1]|
(($info[//orgname])[last()]/orgname)[1]|
(($info[//publishername])[last()]/publishername)[1]
</xsl:param>
Description The value of refentry.source.name.profile
is a string representing an XPath expression. It is evaluated at
run-time and used only if
refentry.source.name.profile.enabled is
non-zero. Otherwise, the refentry metadata-gathering logic
"hard coded" into the stylesheets is used.
A "source name" is one part of a (potentially) two-part
Name Version
"source" field. In man pages, it is usually displayed in the left
footer of the page. It typically indicates the software system or
product that the item documented in the man page belongs to. The
man(7) man page describes it as "the source of
the command", and provides the following examples:
For binaries, use something like: GNU, NET-2, SLS
Distribution, MCC Distribution.
For system calls, use the version of the kernel that you
are currently looking at: Linux 0.99.11.
For library calls, use the source of the function: GNU, BSD
4.3, Linux DLL 4.4.1.
In practice, there are many pages that simply have a Version
number in the "source" field. So, it looks like what we have is a
two-part field,
Name Version ,
where:
Name
product name (e.g., BSD) or org. name (e.g., GNU)
Version
version number
Each part is optional. If the Name is a
product name, then the Version is probably
the version of the product. Or there may be no
Name , in which case, if there is a
Version , it is probably the version
of the item itself, not the product it is part of. Or, if the
Name is an organization name, then there
probably will be no Version .
refentry.source.name.profile.enabled
boolean
refentry.source.name.profile.enabled
Enable refentry "source name" profiling?
<xsl:param name="refentry.source.name.profile.enabled">0</xsl:param>
Description If the value of
refentry.source.name.profile.enabled is
non-zero, then during refentry metadata gathering, the info
profile specified by the customizable
refentry.source.name.profile parameter is
used.
If instead the value of
refentry.source.name.profile.enabled is zero (the
default), then "hard coded" logic within the DocBook XSL stylesheets
is used for gathering refentry "source name" data.
If you find that the default refentry
metadata-gathering behavior is causing incorrect "source name" data to
show up in your output, then consider setting a non-zero value for
refentry.source.name.profile.enabled and
adjusting the value of
refentry.source.name.profile to cause correct
data to be gathered.
Note that the terms "source" and "source name" have special
meanings in this context. For details, see the documentation for the
refentry.source.name.profile parameter.
refentry.version.suppress
boolean
refentry.version.suppress
Suppress "version" part of refentry "source" contents?
<xsl:param name="refentry.version.suppress">0</xsl:param>
Description If the value of refentry.version.suppress
is non-zero, then during refentry metadata gathering, no
"version" data is added to the refentry "source"
contents. Instead (unless
refentry.source.name.suppress is also
non-zero), only "source name" data is added to the "source"
contents.
If you find that the refentry metadata gathering
mechanism is causing unwanted "version" data to show up in your output
-- for example, in the footer (or possibly header) of a man page --
then you might consider setting a non-zero value for
refentry.version.suppress .
Note that the terms "source", "source name", and "version" have
special meanings in this context. For details, see the documentation
for the refentry.source.name.profile
parameter.
refentry.version.profile
string
refentry.version.profile
Specifies profile for refentry "version" data
<xsl:param name="refentry.version.profile">
(($info[//productnumber])[last()]/productnumber)[1]|
(($info[//edition])[last()]/edition)[1]|
(($info[//releaseinfo])[last()]/releaseinfo)[1]
</xsl:param>
Description The value of refentry.version.profile is
a string representing an XPath expression. It is evaluated at
run-time and used only if
refentry.version.profile.enabled is
non-zero. Otherwise, the refentry metadata-gathering logic
"hard coded" into the stylesheets is used.
A "source.name" is one part of a (potentially) two-part
Name Version
"source" field. For more details, see the documentation for the
refentry.source.name.profile parameter.
refentry.version.profile.enabled
boolean
refentry.version.profile.enabled
Enable refentry "version" profiling?
<xsl:param name="refentry.version.profile.enabled">0</xsl:param>
Description If the value of
refentry.version.profile.enabled is
non-zero, then during refentry metadata gathering, the info
profile specified by the customizable
refentry.version.profile parameter is
used.
If instead the value of
refentry.version.profile.enabled is zero (the
default), then "hard coded" logic within the DocBook XSL stylesheets
is used for gathering refentry "version" data.
If you find that the default refentry
metadata-gathering behavior is causing incorrect "version" data to show
up in your output, then consider setting a non-zero value for
refentry.version.profile.enabled and adjusting
the value of refentry.version.profile to cause
correct data to be gathered.
Note that the terms "source" and "version" have special
meanings in this context. For details, see the documentation for the
refentry.version.profile parameter.
refentry.manual.fallback.profile
string
refentry.manual.fallback.profile
Specifies profile of "fallback" for refentry "manual" data
<xsl:param name="refentry.manual.fallback.profile">
refmeta/refmiscinfo[not(@class = 'date')][1]/node()</xsl:param>
Description The value of
refentry.manual.fallback.profile is a string
representing an XPath expression. It is evaluated at run-time and
used only if no "manual" data can be found by other means (that is,
either using the refentry metadata-gathering logic "hard
coded" in the stylesheets, or the value of
refentry.manual.profile , if it is
enabled).
Depending on which XSLT engine you run, either the EXSLT
dyn:evaluate extension function (for xsltproc or
Xalan) or saxon:evaluate extension function (for
Saxon) are used to dynamically evaluate the value of
refentry.manual.fallback.profile at
run-time. If you don't use xsltproc, Saxon, Xalan -- or some other
XSLT engine that supports dyn:evaluate -- you
must manually disable fallback processing by setting an empty value
for the refentry.manual.fallback.profile
parameter.
refentry.source.fallback.profile
string
refentry.source.fallback.profile
Specifies profile of "fallback" for refentry "source" data
<xsl:param name="refentry.source.fallback.profile">
refmeta/refmiscinfo[not(@class = 'date')][1]/node()</xsl:param>
Description The value of
refentry.source.fallback.profile is a string
representing an XPath expression. It is evaluated at run-time and used
only if no "source" data can be found by other means (that is, either
using the refentry metadata-gathering logic "hard coded" in
the stylesheets, or the value of the
refentry.source.name.profile and
refentry.version.profile parameters, if those
are enabled).
Depending on which XSLT engine you run, either the EXSLT
dyn:evaluate extension function (for xsltproc or
Xalan) or saxon:evaluate extension function (for
Saxon) are used to dynamically evaluate the value of
refentry.source.fallback.profile at
run-time. If you don't use xsltproc, Saxon, Xalan -- or some other
XSLT engine that supports dyn:evaluate -- you
must manually disable fallback processing by setting an empty value
for the refentry.source.fallback.profile
parameter.
Page header/footer
man.th.extra1.suppress
boolean
man.th.extra1.suppress
Suppress extra1 part of header/footer?
<xsl:param name="man.th.extra1.suppress">0</xsl:param>
Description If the value of man.th.extra1.suppress is
non-zero, then the extra1 part of the
.TH title line header/footer is suppressed.
The content of the extra1 field is almost
always displayed in the center footer of the page and is, universally,
a date.
man.th.extra2.suppress
boolean
man.th.extra2.suppress
Suppress extra2 part of header/footer?
<xsl:param name="man.th.extra2.suppress">0</xsl:param>
Description If the value of man.th.extra2.suppress is
non-zero, then the extra2 part of the
.TH title line header/footer is suppressed.
The content of the extra2 field is usually
displayed in the left footer of the page and is typically "source"
data, often in the form
Name Version ;
for example, "GTK+ 1.2" (from the gtk-options(7)
man page).
You can use the
refentry.source.name.suppress and
refentry.version.suppress parameters to
independently suppress the Name and
Version parts of the
extra2 field.
man.th.extra3.suppress
boolean
man.th.extra3.suppress
Suppress extra3 part of header/footer?
<xsl:param name="man.th.extra3.suppress">0</xsl:param>
Description If the value of man.th.extra3.suppress is
non-zero, then the extra3 part of the
.TH title line header/footer is
suppressed.
The content of the extra3 field is usually
displayed in the middle header of the page and is typically a "manual
name"; for example, "GTK+ User's Manual" (from the
gtk-options(7) man page).
man.th.title.max.length
integer
man.th.title.max.length
Maximum length of title in header/footer
<xsl:param name="man.th.title.max.length">20</xsl:param>
Description Specifies the maximum permitted length of the title part of the
man-page .TH title line header/footer. If the title
exceeds the maxiumum specified, it is truncated down to the maximum
permitted length.
Details Every man page generated using the DocBook stylesheets has a
title line, specified using the TH roff
macro. Within that title line, there is always, at a minimum, a title,
followed by a section value (representing a man "section" -- usually
just a number).
The title and section are displayed, together, in the visible
header of each page. Where in the header they are displayed depends on
OS the man page is viewed on, and on what version of nroff/groff/man
is used for viewing the page. But, at a minimum and across all
systems, the title and section are displayed on the right-hand column
of the header. On many systems -- those with a modern groff, including
Linux systems -- they are displayed twice: both in the left and right
columns of the header.
So if the length of the title exceeds a certain percentage of
the column width in which the page is viewed, the left and right
titles can end up overlapping, making them unreadable, or breaking to
another line, which doesn't look particularly good.
So the stylesheets provide the
man.th.title.max.length parameter as a means
for truncating titles that exceed the maximum length that can be
viewing properly in a page header.
The default value is reasonable but somewhat arbitrary. If you
have pages with long titles, you may want to experiment with changing
the value in order to achieve the correct aesthetic results.
man.th.extra2.max.length
integer
man.th.extra2.max.length
Maximum length of extra2 in header/footer
<xsl:param name="man.th.extra2.max.length">30</xsl:param>
Description Specifies the maximum permitted length of the
extra2 part of the man-page part of the
.TH title line header/footer. If the
extra2 content exceeds the maxiumum specified, it
is truncated down to the maximum permitted length.
The content of the extra2 field is usually
displayed in the left footer of the page and is typically "source"
data indicating the software system or product that the item
documented in the man page belongs to, often in the form
Name Version ;
for example, "GTK+ 1.2" (from the gtk-options(7)
man page).
The default value for this parameter is reasonable but somewhat
arbitrary. If you are processing pages with long "source" information,
you may want to experiment with changing the value in order to achieve
the correct aesthetic results.
man.th.extra3.max.length
integer
man.th.extra3.max.length
Maximum length of extra3 in header/footer
<xsl:param name="man.th.extra3.max.length">30</xsl:param>
Description Specifies the maximum permitted length of the
extra3 part of the man-page .TH
title line header/footer. If the extra3 content
exceeds the maxiumum specified, it is truncated down to the maximum
permitted length.
The content of the extra3 field is usually
displayed in the middle header of the page and is typically a "manual
name"; for example, "GTK+ User's Manual" (from the
gtk-options(7) man page).
The default value for this parameter is reasonable but somewhat
arbitrary. If you are processing pages with long "manual names" -- or
especially if you are processing pages that have both long "title"
parts (command/function, etc. names) and long
manual names -- you may want to experiment with changing the value in
order to achieve the correct aesthetic results.
Output
man.output.manifest.enabled
boolean
man.output.manifest.enabled
Generate a manifest file?
<xsl:param name="man.output.manifest.enabled" select="0"></xsl:param>
Description If non-zero, a list of filenames for man pages generated by
the stylesheet transformation is written to the file named by the
man.output.manifest.filename parameter.
man.output.manifest.filename
string
man.output.manifest.filename
Name of manifest file
<xsl:param name="man.output.manifest.filename">MAN.MANIFEST</xsl:param>
Description The man.output.manifest.filename parameter
specifies the name of the file to which the manpages manifest file
is written (if the value of the
man.output.manifest.enabled parameter is
non-zero).
man.output.in.separate.dir
boolean
man.output.in.separate.dir
Output man-page files in separate output directory?
<xsl:param name="man.output.in.separate.dir" select="0"></xsl:param>
Description If the value of man.output.in.separate.dir
parameter is non-zero, man-page files are output in a separate
directory, specified by the man.output.base.dir
parameter; otherwise, if the value of
man.output.in.separate.dir is zero, man-page files
are not output in a separate directory.
man.output.lang.in.name.enabled
boolean
man.output.lang.in.name.enabled
Include $LANG value in man-page filename/pathname?
<xsl:param name="man.output.lang.in.name.enabled" select="0"></xsl:param>
Description The man.output.lang.in.name.enabled
parameter specifies whether a $lang value is
included in man-page filenames and pathnames.
If the value of
man.output.lang.in.name.enabled is non-zero,
man-page files are output with the $lang value
included in their filenames or pathnames as follows;
if man.output.subdirs.enabled is
non-zero, each file is output to, e.g., a
man/$lang /man8/foo.8
pathname
if man.output.subdirs.enabled is
zero, each file is output with a
foo.$lang .8
filename
man.output.base.dir
uri
man.output.base.dir
Specifies separate output directory
<xsl:param name="man.output.base.dir">man/</xsl:param>
Description The man.output.base.dir parameter
specifies the base directory into which man-page files are output. The
man.output.subdirs.enabled parameter controls
whether the files are output in subdirectories within the base
directory.
The values of the man.output.base.dir
and man.output.subdirs.enabled parameters are
used only if the value of
man.output.in.separate.dir parameter is
non-zero. If the value of the
man.output.in.separate.dir is zero, man-page
files are not output in a separate directory.
man.output.subdirs.enabled
boolean
man.output.subdirs.enabled
Output man-page files in subdirectories within base output directory?
<xsl:param name="man.output.subdirs.enabled" select="1"></xsl:param>
Description The man.output.subdirs.enabled parameter
controls whether man-pages files are output in subdirectories within
the base directory specified by the directory specified by the
man.output.base.dir parameter.
The values of the man.output.base.dir
and man.output.subdirs.enabled parameters are
used only if the value of
man.output.in.separate.dir parameter is
non-zero. If the value of the
man.output.in.separate.dir is zero, man-page
files are not output in a separate directory.
man.output.quietly
boolean
man.output.quietly
Suppress filename messages emitted when generating output?
<xsl:param name="man.output.quietly" select="0"></xsl:param>
Description If zero (the default), for each man-page file created, a message
with the name of the file is emitted. If non-zero, the files are
output "quietly" -- that is, the filename messages are
suppressed.
If you are processing a large amount of refentry
content, you may be able to speed up processing significantly by
setting a non-zero value for
man.output.quietly .
man.output.encoding
string
man.output.encoding
Encoding used for man-page output
<xsl:param name="man.output.encoding">UTF-8</xsl:param>
Description This parameter specifies the encoding to use for files generated
by the manpages stylesheet. Not all processors support specification
of this parameter.
If the value of the man.charmap.enabled
parameter is non-zero (the default), keeping the
man.output.encoding parameter at its default
value (UTF-8 ) or setting it to
UTF-16 does not cause your
man pages to be output in raw UTF-8 or UTF-16 -- because
any Unicode characters for which matches are found in the enabled
character map will be replaced with roff escape sequences before the
final man-page files are generated.
So if you want to generate "real" UTF-8 man pages, without any
character substitution being performed on your content, you need to
set man.charmap.enabled to zero (which will
completely disable character-map processing).
You may also need to set
man.charmap.enabled to zero if you want to
output man pages in an encoding other than UTF-8
or UTF-16 . Character-map processing is based on
Unicode character values and may not work with other output
encodings.
man.output.better.ps.enabled
boolean
man.output.better.ps.enabled
Enable enhanced print/PostScript output?
<xsl:param name="man.output.better.ps.enabled">0</xsl:param>
Description If the value of the
man.output.better.ps.enabled parameter is
non-zero, certain markup is embedded in each generated man page
such that PostScript output from the man -Tps
command for that page will include a number of enhancements
designed to improve the quality of that output.
If man.output.better.ps.enabled is
zero (the default), no such markup is embedded in generated man
pages, and no enhancements are included in the PostScript
output generated from those man pages by the man
-Tps command.
The enhancements provided by this parameter rely on
features that are specific to groff (GNU troff) and that are
not part of “classic” AT&T troff or any of its
derivatives. Therefore, any man pages you generate with this
parameter enabled will be readable only on systems on which
the groff (GNU troff) program is installed, such as GNU/Linux
systems. The pages will not not be
readable on systems on with the classic troff (AT&T
troff) command is installed .
The value of this parameter only affects PostScript output
generated from the man command. It has no
effect on output generated using the FO backend.
You can generate PostScript output for any man page by
running the following command:
man FOO -Tps > FOO .ps
You can then generate PDF output by running the following
command:
ps2pdf FOO .ps
Other
man.table.footnotes.divider
string
man.table.footnotes.divider
Specifies divider string that appears before table footnotes
<xsl:param name="man.table.footnotes.divider">----</xsl:param>
Description In each table that contains footenotes, the string specified by
the man.table.footnotes.divider parameter is
output before the list of footnotes for the table.
man.subheading.divider.enabled
boolean
man.subheading.divider.enabled
Add divider comment to roff source before/after subheadings?
<xsl:param name="man.subheading.divider.enabled">0</xsl:param>
Description If the value of the
man.subheading.divider.enabled parameter is
non-zero, the contents of the
man.subheading.divider parameter are used to
add a "divider" before and after subheadings in the roff
output. The divider is not visisble in the
rendered man page ; it is added as a comment, in the source,
simply for the purpose of increasing reability of the source.
If man.subheading.divider.enabled is zero
(the default), the subheading divider is suppressed.
man.subheading.divider
string
man.subheading.divider
Specifies string to use as divider comment before/after subheadings
<xsl:param name="man.subheading.divider">========================================================================</xsl:param>
Description If the value of the
man.subheading.divider.enabled parameter is
non-zero, the contents of the
man.subheading.divider parameter are used to
add a "divider" before and after subheadings in the roff
output. The divider is not visisble in the
rendered man page ; it is added as a comment, in the source,
simply for the purpose of increasing reability of the source.
If man.subheading.divider.enabled is zero
(the default), the subheading divider is suppressed.
The Stylesheet
The param.xsl stylesheet is just a
wrapper around all of these parameters.
<xsl:stylesheet exclude-result-prefixes="src" version="1.0">
<!-- This file is generated from param.xweb -->
<!-- ********************************************************************
$Id: param.xweb 9130 2011-10-11 08:05:37Z dpawson $
********************************************************************
This file is part of the XSL DocBook Stylesheet distribution.
See ../README or http://docbook.sf.net/release/xsl/current/ for
copyright and other information.
******************************************************************** -->
<src:fragref linkend="man.authors.section.enabled.frag"></src:fragref>
<src:fragref linkend="man.break.after.slash.frag"></src:fragref>
<src:fragref linkend="man.base.url.for.relative.links.frag"></src:fragref>
<src:fragref linkend="man.charmap.enabled.frag"></src:fragref>
<src:fragref linkend="man.charmap.subset.profile.frag"></src:fragref>
<src:fragref linkend="man.charmap.subset.profile.english.frag"></src:fragref>
<src:fragref linkend="man.charmap.uri.frag"></src:fragref>
<src:fragref linkend="man.charmap.use.subset.frag"></src:fragref>
<src:fragref linkend="man.copyright.section.enabled.frag"></src:fragref>
<src:fragref linkend="man.endnotes.are.numbered.frag"></src:fragref>
<src:fragref linkend="man.endnotes.list.enabled.frag"></src:fragref>
<src:fragref linkend="man.endnotes.list.heading.frag"></src:fragref>
<src:fragref linkend="man.font.funcprototype.frag"></src:fragref>
<src:fragref linkend="man.font.funcsynopsisinfo.frag"></src:fragref>
<src:fragref linkend="man.font.links.frag"></src:fragref>
<src:fragref linkend="man.font.table.headings.frag"></src:fragref>
<src:fragref linkend="man.font.table.title.frag"></src:fragref>
<src:fragref linkend="man.funcsynopsis.style.frag"></src:fragref>
<src:fragref linkend="man.hyphenate.computer.inlines.frag"></src:fragref>
<src:fragref linkend="man.hyphenate.filenames.frag"></src:fragref>
<src:fragref linkend="man.hyphenate.frag"></src:fragref>
<src:fragref linkend="man.hyphenate.urls.frag"></src:fragref>
<src:fragref linkend="man.indent.blurbs.frag"></src:fragref>
<src:fragref linkend="man.indent.lists.frag"></src:fragref>
<src:fragref linkend="man.indent.refsect.frag"></src:fragref>
<src:fragref linkend="man.indent.verbatims.frag"></src:fragref>
<src:fragref linkend="man.indent.width.frag"></src:fragref>
<src:fragref linkend="man.justify.frag"></src:fragref>
<src:fragref linkend="man.output.base.dir.frag"></src:fragref>
<src:fragref linkend="man.output.encoding.frag"></src:fragref>
<src:fragref linkend="man.output.in.separate.dir.frag"></src:fragref>
<src:fragref linkend="man.output.lang.in.name.enabled.frag"></src:fragref>
<src:fragref linkend="man.output.manifest.enabled.frag"></src:fragref>
<src:fragref linkend="man.output.manifest.filename.frag"></src:fragref>
<src:fragref linkend="man.output.better.ps.enabled.frag"></src:fragref>
<src:fragref linkend="man.output.quietly.frag"></src:fragref>
<src:fragref linkend="man.output.subdirs.enabled.frag"></src:fragref>
<src:fragref linkend="man.segtitle.suppress.frag"></src:fragref>
<src:fragref linkend="man.string.subst.map.frag"></src:fragref>
<src:fragref linkend="man.string.subst.map.local.post.frag"></src:fragref>
<src:fragref linkend="man.string.subst.map.local.pre.frag"></src:fragref>
<src:fragref linkend="man.subheading.divider.enabled.frag"></src:fragref>
<src:fragref linkend="man.subheading.divider.frag"></src:fragref>
<src:fragref linkend="man.table.footnotes.divider.frag"></src:fragref>
<src:fragref linkend="man.th.extra1.suppress.frag"></src:fragref>
<src:fragref linkend="man.th.extra2.max.length.frag"></src:fragref>
<src:fragref linkend="man.th.extra2.suppress.frag"></src:fragref>
<src:fragref linkend="man.th.extra3.max.length.frag"></src:fragref>
<src:fragref linkend="man.th.extra3.suppress.frag"></src:fragref>
<src:fragref linkend="man.th.title.max.length.frag"></src:fragref>
<src:fragref linkend="refentry.date.profile.enabled.frag"></src:fragref>
<src:fragref linkend="refentry.date.profile.frag"></src:fragref>
<src:fragref linkend="refentry.manual.fallback.profile.frag"></src:fragref>
<src:fragref linkend="refentry.manual.profile.enabled.frag"></src:fragref>
<src:fragref linkend="refentry.manual.profile.frag"></src:fragref>
<src:fragref linkend="refentry.meta.get.quietly.frag"></src:fragref>
<src:fragref linkend="refentry.source.fallback.profile.frag"></src:fragref>
<src:fragref linkend="refentry.source.name.profile.enabled.frag"></src:fragref>
<src:fragref linkend="refentry.source.name.profile.frag"></src:fragref>
<src:fragref linkend="refentry.source.name.suppress.frag"></src:fragref>
<src:fragref linkend="refentry.version.profile.enabled.frag"></src:fragref>
<src:fragref linkend="refentry.version.profile.frag"></src:fragref>
<src:fragref linkend="refentry.version.suppress.frag"></src:fragref>
</xsl:stylesheet>