X-Git-Url: https://git.stg.codes/stg.git/blobdiff_plain/0c9c28efcd43f53ac54aa60b2dfefa69c70dbadf..6b6d9b29e9e9e91f79507a8bf193fb30de311dcc:/doc/help/xslt/manpages/param.xml diff --git a/doc/help/xslt/manpages/param.xml b/doc/help/xslt/manpages/param.xml new file mode 100644 index 00000000..706c99d1 --- /dev/null +++ b/doc/help/xslt/manpages/param.xml @@ -0,0 +1,3220 @@ + + + + Manpages Parameter Reference + + $Id: param.xweb 8235 2009-02-09 16:22:14Z xmldoc $ + + + The DocBook Project + + + 2005-2007 + 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 HTML stylesheet parameters + to control manpages output (in addition to the + manpages-specific parameters listed in this section). + + + + 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 +refsectioninstances) 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 IThe + 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 man2html (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., + + but in a text-only output format, the + numbered-notesources/endnotes-listing mechanism is the only + practical way to handle this kind of content. + + 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 man2html (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 roff character map that is compliant with the XSLT character +map format as detailed in the XSLT 2.0 specification. The map +contains more than 800 character mappings and can be considered the +standard roff character map for the distribution. + +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 XSLT character +map. That character map can be considered the standard roff +character map for the distribution. + +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 roff character map that is compliant with the XSLT character +map format as detailed in the XSLT 2.0 specification. The map +contains more than 800 character mappings and can be considered the +standard roff character map for the distribution. + + +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 standard roff character map included in the distribution are: + + + 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 standard roff character map provided in the distribution, and +then adding to, changing, and/or deleting from that. + + +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. + + + + C1 Controls And Latin-1 Supplement (Latin-1 Supplement) (x00a0 to x00ff) + class values + + + symbols + + + letters + + + + + Latin Extended-A (x0100 to x017f, partial) + + + Spacing Modifier Letters (x02b0 to x02ee, partial) + + + Greek and Coptic (x0370 to x03ff, partial) + + + General Punctuation (x2000 to x206f, partial) + class values + + + spaces + + + dashes + + + quotes + + + daggers + + + bullets + + + leaders + + + primes + + + + + + Superscripts and Subscripts (x2070 to x209f) + + + Currency Symbols (x20a0 to x20b1) + + + Letterlike Symbols (x2100 to x214b) + + + Number Forms (x2150 to x218f) + + + Arrows (x2190 to x21ff, partial) + + + Mathematical Operators (x2200 to x22ff, partial) + + + Control Pictures (x2400 to x243f) + + + Enclosed Alphanumerics (x2460 to x24ff) + + + Geometric Shapes (x25a0 to x25f7, partial) + + + Miscellaneous Symbols (x2600 to x26ff, partial) + + + Dingbats (x2700 to x27be, partial) + + + Alphabetic Presentation Forms (xfb00 to xfb04 only) + + + + + + + + +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&#x2122; -> Producttm --> + <!-- * --> + <!-- * So we just make it to "(TM)" instead; thus: --> + <!-- * --> + <!-- * Product&#x2122; -> Product(TM) --> + <ss:substitution oldstring="™" newstring="(TM)"></ss:substitution> + +</xsl:param> + + + +Description + +The man.string.subst.map parameter +contains a map that specifies a set of +string substitutions to perform over the entire roff source for each +man page, either just before generating final man-page output (that +is, before writing man-page files to disk) or, if the value of the +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 8235 2009-02-09 16:22:14Z xmldoc $ + ******************************************************************** + + 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> + + + +