doc/xslt/params/man.string.subst.map.xml

   1 <refentry xmlns="http://docbook.org/ns/docbook"
   2           xmlns:xlink="http://www.w3.org/1999/xlink"
   3           xmlns:xi="http://www.w3.org/2001/XInclude"
   4           xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
   5           xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   6           xmlns:ss="http://docbook.sf.net/xmlns/string.subst/1.0"
   7           version="5.0" xml:id="man.string.subst.map">
   8 <refmeta>
   9 <refentrytitle>man.string.subst.map</refentrytitle>
  10 <refmiscinfo class="other" otherclass="datatype">rtf</refmiscinfo>
  11 </refmeta>
  12 <refnamediv>
  13 <refname>man.string.subst.map</refname>
  14 <refpurpose>Specifies a set of string substitutions</refpurpose>
  15 </refnamediv>
  16
  17 <refsynopsisdiv>
  18 <src:fragment xml:id="man.string.subst.map.frag">
  19 <xsl:param name="man.string.subst.map">
  20
  21   <!-- * remove no-break marker at beginning of line (stylesheet artifact) -->
  22   <ss:substitution oldstring="&#x2592;&#x2580;" newstring="&#x2592;"/>
  23   <!-- * replace U+2580 no-break marker (stylesheet-added) w/ no-break space -->
  24   <ss:substitution oldstring="&#x2580;" newstring="\ "/>
  25
  26   <!-- ==================================================================== -->
  27
  28   <!-- * squeeze multiple newlines before a roff request  -->
  29   <ss:substitution oldstring="&#10;&#10;." newstring="&#10;."/>
  30   <!-- * remove any .sp instances that directly precede a .PP  -->
  31   <ss:substitution oldstring=".sp&#10;.PP" newstring=".PP"/>
  32   <!-- * remove any .sp instances that directly follow a .PP  -->
  33   <ss:substitution oldstring=".sp&#10;.sp" newstring=".sp"/>
  34   <!-- * squeeze multiple .sp instances into a single .sp-->
  35   <ss:substitution oldstring=".PP&#10;.sp" newstring=".PP"/>
  36   <!-- * squeeze multiple newlines after start of no-fill (verbatim) env. -->
  37   <ss:substitution oldstring=".nf&#10;&#10;" newstring=".nf&#10;"/>
  38   <!-- * squeeze multiple newlines after REstoring margin -->
  39   <ss:substitution oldstring=".RE&#10;&#10;" newstring=".RE&#10;"/>
  40   <!-- * U+2591 is a marker we add before and after every Parameter in -->
  41   <!-- * Funcprototype output -->
  42   <ss:substitution oldstring="&#x2591;" newstring=" "/>
  43   <!-- * U+2592 is a marker we add for the newline before output of <sbr>; -->
  44   <ss:substitution oldstring="&#x2592;" newstring="&#10;"/>
  45   <!-- * -->
  46   <!-- * Now deal with some other characters that are added by the -->
  47   <!-- * stylesheets during processing. -->
  48   <!-- * -->
  49   <!-- * bullet -->
  50   <ss:substitution oldstring="•" newstring="\(bu"/>
  51   <!-- * left double quote -->
  52   <ss:substitution oldstring="“" newstring="\(lq"/>
  53   <!-- * right double quote -->
  54   <ss:substitution oldstring="”" newstring="\(rq"/>
  55   <!-- * left single quote -->
  56   <ss:substitution oldstring="‘" newstring="\(oq"/>
  57   <!-- * right single quote -->
  58   <ss:substitution oldstring="’" newstring="\(cq"/>
  59   <!-- * copyright sign -->
  60   <ss:substitution oldstring="©" newstring="\(co"/>
  61   <!-- * registered sign -->
  62   <ss:substitution oldstring="®" newstring="\(rg"/>
  63   <!-- * ...servicemark... -->
  64   <!-- * There is no groff equivalent for it. -->
  65   <ss:substitution oldstring="&#x2120;" newstring="(SM)"/>
  66   <!-- * ...trademark... -->
  67   <!-- * We don't do "\(tm" because for console output, -->
  68   <!-- * groff just renders that as "tm"; that is: -->
  69   <!-- * -->
  70   <!-- *   Product&#x2122; -> Producttm -->
  71   <!-- * -->
  72   <!-- * So we just make it to "(TM)" instead; thus: -->
  73   <!-- * -->
  74   <!-- *   Product&#x2122; -> Product(TM) -->
  75   <ss:substitution oldstring="™" newstring="(TM)"/>
  76
  77 </xsl:param>
  78 </src:fragment>
  79 </refsynopsisdiv>
  80
  81 <refsection><info><title>Description</title></info>
  82
  83 <para>The <parameter>man.string.subst.map</parameter> parameter
  84 contains <link linkend="map">a map</link> that specifies a set of
  85 string substitutions to perform over the entire roff source for each
  86 man page, either just before generating final man-page output (that
  87 is, before writing man-page files to disk) or, if the value of the
  88 <parameter>man.charmap.enabled</parameter> parameter is non-zero,
  89 before applying the roff character map.</para>
  90
  91 <para>You can use <parameter>man.string.subst.map</parameter> as a
  92 “lightweight” character map to perform “essential” substitutions --
  93 that is, substitutions that are <emphasis>always</emphasis> performed,
  94 even if the value of the <parameter>man.charmap.enabled</parameter>
  95 parameter is zero. For example, you can use it to replace quotation
  96 marks or other special characters that are generated by the DocBook
  97 XSL stylesheets for a particular locale setting (as opposed to those
  98 characters that are actually in source XML documents), or to replace
  99 any special characters that may be automatically generated by a
 100 particular customization of the DocBook XSL stylesheets.</para>
 101
 102 <warning>
 103   <para>Do you not change value of the
 104   <parameter>man.string.subst.map</parameter> parameter unless you are
 105   sure what you are doing. First consider adding your
 106   string-substitution mappings to either or both of the following
 107   parameters:
 108   <variablelist>
 109     <varlistentry>
 110       <term><parameter>man.string.subst.map.local.pre</parameter></term>
 111       <listitem><para>applied before
 112       <parameter>man.string.subst.map</parameter></para></listitem>
 113     </varlistentry>
 114     <varlistentry>
 115       <term><parameter>man.string.subst.map.local.post</parameter></term>
 116       <listitem><para>applied after
 117       <parameter>man.string.subst.map</parameter></para></listitem>
 118     </varlistentry>
 119   </variablelist>
 120   By default, both of those parameters contain no
 121   string substitutions. They are intended as a means for you to
 122   specify your own local string-substitution mappings.</para>
 123
 124   <para>If you remove any of default mappings from the value of the
 125   <parameter>man.string.subst.map</parameter> parameter, you are
 126   likely to end up with broken output. And be very careful about adding
 127   anything to it; it’s used for doing string substitution over the
 128   entire roff source of each man page – it causes target strings to be
 129   replaced in roff requests and escapes, not just in the visible
 130   contents of the page.</para>
 131
 132 </warning>
 133
 134 <refsection xml:id="map">
 135   <info>
 136     <title>Contents of the substitution map</title>
 137   </info>
 138   <para>The string-substitution map contains one or more
 139   <tag>ss:substitution</tag> elements, each of which has two
 140   attributes:
 141   <variablelist>
 142     <varlistentry>
 143       <term>oldstring</term>
 144       <listitem>
 145         <simpara>string to replace</simpara>
 146       </listitem>
 147     </varlistentry>
 148     <varlistentry>
 149       <term>newstring</term>
 150       <listitem>
 151         <simpara>string with which to replace <tag
 152         class="attribute">oldstring</tag></simpara>
 153       </listitem>
 154     </varlistentry>
 155   </variablelist>
 156   It may also include XML comments (that is, delimited with
 157   "<literal>&lt;!--</literal>" and "<literal>--&gt;</literal>").
 158   </para>
 159 </refsection>
 160
 161 </refsection>
 162 </refentry>