man.string.subst.map
Prev | Character/string substitution | Next

## Name

man.string.subst.map — Specifies a set of string substitutions

## Synopsis

    <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="\\n" newstring="\n"></substitution>
      <!-- * requests in .SH sectsions output from Refsect1-level source -->
      <!-- * end up getting capitalized... -->
      <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>
      <substitution oldstring=".ll \-" newstring=".ll -"></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>
      <!-- * squeeze multiple newlines after REstoring margin -->
      <substitution oldstring=".RE

    " newstring=".RE
    "></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>
      <!-- * x2008 is a "punctuation space"; we must replace it here because, -->
      <!-- * for certain reasons, the stylesheets add it before and after -->
      <!-- * every Parameter in Funcprototype output -->
      <substitution oldstring=" " newstring=" "></substitution>
      <substitution oldstring="⌂" newstring="	"></substitution>
      <!-- * -->
      <!-- * Now deal with some other characters that are added by the -->
      <!-- * stylesheets during processing. -->
      <!-- * -->
      <!-- * 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, -->
      <!-- * groff just renders that as "tm"; that is: -->
      <!-- * -->
      <!-- *   Product&#x2122; -> Producttm -->
      <!-- * -->
      <!-- * So we just make it to "(TM)" instead; thus: -->
      <!-- * -->
      <!-- *   Product&#x2122; -> Product(TM) -->
      <substitution oldstring="™" newstring="(TM)"></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. 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”.

### Contents of the substitution map

The string-substitution map contains one or more `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 "`-->`").

### About adding backslashes before dots

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.

Prev | Up | Next
man.charmap.subset.profile | Home | Refentry metadata gathering