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="▒▀" newstring="▒"/>
|
---|
23 | <!-- * replace U+2580 no-break marker (stylesheet-added) w/ no-break space -->
|
---|
24 | <ss:substitution oldstring="▀" newstring="\ "/>
|
---|
25 |
|
---|
26 | <!-- ==================================================================== -->
|
---|
27 |
|
---|
28 | <!-- * squeeze multiple newlines before a roff request -->
|
---|
29 | <ss:substitution oldstring=" ." newstring=" ."/>
|
---|
30 | <!-- * remove any .sp instances that directly precede a .PP -->
|
---|
31 | <ss:substitution oldstring=".sp .PP" newstring=".PP"/>
|
---|
32 | <!-- * remove any .sp instances that directly follow a .PP -->
|
---|
33 | <ss:substitution oldstring=".sp .sp" newstring=".sp"/>
|
---|
34 | <!-- * squeeze multiple .sp instances into a single .sp-->
|
---|
35 | <ss:substitution oldstring=".PP .sp" newstring=".PP"/>
|
---|
36 | <!-- * squeeze multiple newlines after start of no-fill (verbatim) env. -->
|
---|
37 | <ss:substitution oldstring=".nf " newstring=".nf "/>
|
---|
38 | <!-- * squeeze multiple newlines after REstoring margin -->
|
---|
39 | <ss:substitution oldstring=".RE " newstring=".RE "/>
|
---|
40 | <!-- * U+2591 is a marker we add before and after every Parameter in -->
|
---|
41 | <!-- * Funcprototype output -->
|
---|
42 | <ss:substitution oldstring="░" newstring=" "/>
|
---|
43 | <!-- * U+2592 is a marker we add for the newline before output of <sbr>; -->
|
---|
44 | <ss:substitution oldstring="▒" newstring=" "/>
|
---|
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="℠" 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™ -> Producttm -->
|
---|
71 | <!-- * -->
|
---|
72 | <!-- * So we just make it to "(TM)" instead; thus: -->
|
---|
73 | <!-- * -->
|
---|
74 | <!-- * Product™ -> 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><!--</literal>" and "<literal>--></literal>").
|
---|
158 | </para>
|
---|
159 | </refsection>
|
---|
160 |
|
---|
161 | </refsection>
|
---|
162 | </refentry>
|
---|