source: trunk/Distribution/XSL/params/man.string.subst.map.xml@ 3

<refentry id="man.string.subst.map">
<refmeta>
<refentrytitle>man.string.subst.map</refentrytitle>
<refmiscinfo role="type">string</refmiscinfo>
</refmeta>
<refnamediv>
<refname>man.string.subst.map</refname>
<refpurpose>Specifies a set of string substitutions</refpurpose>
</refnamediv>

<refsynopsisdiv>
<src:fragment id='man.string.subst.map.frag'>
<xsl:param name="man.string.subst.map">
  <substitution oldstring="\" newstring="\\"/>
  <!-- * now, we need to restore single-backslashes in all roff -->
  <!-- * requests (because the substitution above doubled them) -->
  <substitution oldstring="\\fB" newstring="\fB"/>
  <substitution oldstring="\\fI" newstring="\fI"/>
  <substitution oldstring="\\fR" newstring="\fR"/>
  <substitution oldstring='\\%' newstring='\%'/>
  <substitution oldstring='\\&amp;' newstring='\&amp;'/>
  <substitution oldstring='.\\"' newstring='.\"'/>
  <!-- * 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="\-"/>
  <!-- * 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 oldstring=".it 1 an\-trap" newstring=".it 1 an-trap"/>
  <substitution oldstring=".nr an\-no\-space\-flag 1" newstring=".nr an-no-space-flag 1"/>
  <substitution oldstring=".nr an\-break\-flag 1" newstring=".nr an-break-flag 1"/>
  <!-- * squeeze multiple newlines before a roff request  -->
  <substitution oldstring="&#10;&#10;." newstring="&#10;."/>
  <!-- * remove any .sp occurences that directly follow a .PP  -->
  <substitution oldstring=".PP&#10;.sp" newstring=".PP"/>
  <!-- * squeeze multiple newlines after start of no-fill (verbatim) env. -->
  <substitution oldstring=".nf&#10;&#10;" newstring=".nf&#10;"/>
  <!-- * 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="&#10;'" newstring="&#10;\'"/>
  <!-- * -->
  <!-- * 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="&#x00a0;" newstring="\ "/>
  <!-- * bullet -->
  <substitution oldstring="&#x2022;" newstring="\(bu"/>
  <!-- * left double quote -->
  <substitution oldstring="&#x201c;" newstring="\(lq"/>
  <!-- * right double quote -->
  <substitution oldstring="&#x201d;" newstring="\(rq"/>
  <!-- * left single quote -->
  <substitution oldstring="&#x2018;" newstring="\(oq"/>
  <!-- * right single quote -->
  <substitution oldstring="&#x2019;" newstring="\(cq"/>
  <!-- * copyright sign -->
  <substitution oldstring="&#x00a9;" newstring="\(co"/>
  <!-- * registered sign -->
  <substitution oldstring="&#x00ae;" newstring="\(rg"/>
  <!-- * servicemark -->
  <!-- * there is no groff equivalent for it -->
  <substitution oldstring="&#x2120;" newstring="(SM)"/>
  <!-- * trademark -->
  <!-- * we don't do "\(tm" because for console output -->
  <!-- * because 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="&#x2122;" newstring="(TM)"/>
</xsl:param>
</src:fragment>
</refsynopsisdiv>

<refsect1><title>Description</title>

<para>The <parameter>man.string.subst.map</parameter> parameter
contains <link linkend="map">a map</link> 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
<parameter>man.charmap.enabled</parameter> parameter is non-zero,
before applying the roff character map.</para>

<para>You can use <parameter>man.string.subst.map</parameter> as a
"lightweight" character map to perform "essential" substitutions --
that is, substitutions that are <emphasis>always</emphasis> performed,
even if the value of the <parameter>man.charmap.enabled</parameter>
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.</para>

<warning>
  <para>Do you not change value of the
  <parameter>man.string.subst.map</parameter> 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.</para>

  <para>In particular, do not attempt to add a mapping for the
  dot/period character. Doing so will break your output. For an
  explanation, see <xref linkend="Dots"/>.</para>

</warning>

<refsect2 id="map">
  <title>Contents of the substitution map</title>
  <para>The string-substitution map contains one or more <tag
  namespace="http://docbook.sf.net/xmlns/string.subst/1.0"
  >substitution</tag> elements, each of which has two attributes:
  <variablelist>
    <varlistentry>
      <term>oldstring</term>
      <listitem>
        <simpara>string to replace</simpara>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>newstring</term>
      <listitem>
        <simpara>string with which to replace <tag class="attribute"
        >oldstring</tag></simpara>
      </listitem>
    </varlistentry>
  </variablelist>
  It may also include XML comments (that is, delimited with
  "<literal>&lt;!--</literal>" and "<literal>--></literal>").
  </para>
</refsect2>

<refsect2 id="Dots">
  <title>About adding backslashes before dots</title>
  <para>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 <literal>.TH</literal> roff macro to be
  replaced with <literal>\.TH</literal>. 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.</para>
</refsect2>

</refsect1>
</refentry>