man.string.subst.map — Specifies a set of string substitutions
<xsl:param name="man.string.subst.map"> <substitution oldstring="\" newstring="\\"></substitution> <!-- * now, we need to restore single-backslashes in all roff --> <!-- * requests (because the substitution above doubled them) --> <substitution oldstring="\\fB" newstring="\fB"></substitution> <substitution oldstring="\\fI" newstring="\fI"></substitution> <substitution oldstring="\\fR" newstring="\fR"></substitution> <substitution oldstring="\\%" newstring="\%"></substitution> <substitution oldstring="\\&" newstring="\&"></substitution> <substitution oldstring=".\\"" newstring=".\""></substitution> <!-- * although the groff docs do not make it clear, it appears that --> <!-- * the only way to get a non-breaking hyphen in roff is to put a --> <!-- * backslash in front of it; and, unfortunately, groff is not smart --> <!-- * about where it breaks things (for example, it'll break an --> <!-- * argument for a command across a line, if that argument contains --> <!-- * a dash/hyphen); so, we must globally change all hyphens to "\-" --> <substitution oldstring="-" newstring="\-"></substitution> <!-- * now, we need to restore single-hypens in all roff requests --> <!-- * (because the substitution above added backslashes before them) --> <substitution oldstring=".sp \-" newstring=".sp -"></substitution> <substitution oldstring=".it 1 an\-trap" newstring=".it 1 an-trap"></substitution> <substitution oldstring=".nr an\-no\-space\-flag 1" newstring=".nr an-no-space-flag 1"></substitution> <substitution oldstring=".nr an\-break\-flag 1" newstring=".nr an-break-flag 1"></substitution> <!-- * squeeze multiple newlines before a roff request --> <substitution oldstring=" ." newstring=" ."></substitution> <!-- * remove any .sp occurences that directly follow a .PP --> <substitution oldstring=".PP .sp" newstring=".PP"></substitution> <!-- * squeeze multiple newlines after start of no-fill (verbatim) env. --> <substitution oldstring=".nf " newstring=".nf "></substitution> <!-- * an apostrophe at the beginning of a line gets interpreted as a --> <!-- * roff request (groff(7) says it is "the non-breaking control --> <!-- * character"); so we must add backslash before any apostrophe --> <!-- * found at the start of a line --> <substitution oldstring=" '" newstring=" \'"></substitution> <!-- * --> <!-- * non-breaking space --> <!-- * --> <!-- * A no-break space can be written two ways in roff; the difference, --> <!-- * according to the "Page Motions" node in the groff info page, ixsl: --> <!-- * --> <!-- * "\ " = --> <!-- * An unbreakable and unpaddable (i.e. not expanded during filling) --> <!-- * space. --> <!-- * --> <!-- * "\~" = --> <!-- * An unbreakable space that stretches like a normal --> <!-- * inter-word space when a line is adjusted." --> <!-- * --> <!-- * Unfortunately, roff seems to do some weird things with long --> <!-- * lines that only have words separated by "\~" spaces, so it's --> <!-- * safer just to stick with the "\ " space --> <substitution oldstring=" " newstring="\ "></substitution> <!-- * bullet --> <substitution oldstring="•" newstring="\(bu"></substitution> <!-- * left double quote --> <substitution oldstring="“" newstring="\(lq"></substitution> <!-- * right double quote --> <substitution oldstring="”" newstring="\(rq"></substitution> <!-- * left single quote --> <substitution oldstring="‘" newstring="\(oq"></substitution> <!-- * right single quote --> <substitution oldstring="’" newstring="\(cq"></substitution> <!-- * copyright sign --> <substitution oldstring="©" newstring="\(co"></substitution> <!-- * registered sign --> <substitution oldstring="®" newstring="\(rg"></substitution> <!-- * servicemark --> <!-- * there is no groff equivalent for it --> <substitution oldstring="℠" newstring="(SM)"></substitution> <!-- * trademark --> <!-- * we don't do "\(tm" because for console output --> <!-- * because groff just renders that as "tm"; that is: --> <!-- * --> <!-- * Product™ -> Producttm --> <!-- * --> <!-- * So we just make it to "(TM)" instead; thus: --> <!-- * --> <!-- * Product™ -> Product(TM) --> <substitution oldstring="™" newstring="(TM)"></substitution> </xsl:param>
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. If you remove any of the default
mappings, you are likely to end up with broken output. And be very
careful about adding anything to it. Because it is 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.
In particular, do not attempt to add a mapping for the dot/period character. Doing so will break your output. For an explanation, see the section called “About adding backslashes before dots”.
The string-substitution map contains one or more substitution elements, each of which has two attributes:
oldstring
It may also include XML comments (that is, delimited with
"<!--" and "-->").
The stylesheets do not add backslashes before
periods/dots. One reason is that, because string substitution is
performed over the entire roff source of each man page, it would be
complicated to replace dots in visible contents without also causing
them to be replaced in roff requests and escapes; for example,
without causing, say, the .TH roff macro to be
replaced with \.TH. Additionally, backslashes in
front of periods/dots are needed only in the very rare case where a
period is the very first character in a line, without any space in
front of it. A better way to deal with that rare case is to add a
zero-width space in front of the offending dot(s) in your
source.