X-Git-Url: https://git.stg.codes/stg.git/blobdiff_plain/793149f04ce52bf75dc4efb7b83a3f8ed30d1fff..35ec793690104efdd610964d255302a0310a2daf:/doc/xslt/manpages/param.xml diff --git a/doc/xslt/manpages/param.xml b/doc/xslt/manpages/param.xml deleted file mode 100644 index 706c99d1..00000000 --- a/doc/xslt/manpages/param.xml +++ /dev/null @@ -1,3220 +0,0 @@ - - - - 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> - - - -