X-Git-Url: https://git.stg.codes/stg.git/blobdiff_plain/0c9c28efcd43f53ac54aa60b2dfefa69c70dbadf..6b6d9b29e9e9e91f79507a8bf193fb30de311dcc:/doc/help/xslt/params/man.string.subst.map.xml

diff --git a/doc/help/xslt/params/man.string.subst.map.xml b/doc/help/xslt/params/man.string.subst.map.xml
new file mode 100644
index 00000000..0feed4aa
--- /dev/null
+++ b/doc/help/xslt/params/man.string.subst.map.xml
@@ -0,0 +1,162 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+          xmlns:ss="http://docbook.sf.net/xmlns/string.subst/1.0"
+          version="5.0" xml:id="man.string.subst.map">
+<refmeta>
+<refentrytitle>man.string.subst.map</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">rtf</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.string.subst.map</refname>
+<refpurpose>Specifies a set of string substitutions</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment xml:id="man.string.subst.map.frag">
+<xsl:param name="man.string.subst.map">
+
+  <!-- * remove no-break marker at beginning of line (stylesheet artifact) --> 
+  <ss:substitution oldstring="&#x2592;&#x2580;" newstring="&#x2592;"/>
+  <!-- * replace U+2580 no-break marker (stylesheet-added) w/ no-break space -->
+  <ss:substitution oldstring="&#x2580;" newstring="\ "/>
+
+  <!-- ==================================================================== -->
+
+  <!-- * squeeze multiple newlines before a roff request  -->
+  <ss:substitution oldstring="&#10;&#10;." newstring="&#10;."/>
+  <!-- * remove any .sp instances that directly precede a .PP  -->
+  <ss:substitution oldstring=".sp&#10;.PP" newstring=".PP"/>
+  <!-- * remove any .sp instances that directly follow a .PP  -->
+  <ss:substitution oldstring=".sp&#10;.sp" newstring=".sp"/>
+  <!-- * squeeze multiple .sp instances into a single .sp-->
+  <ss:substitution oldstring=".PP&#10;.sp" newstring=".PP"/>
+  <!-- * squeeze multiple newlines after start of no-fill (verbatim) env. -->
+  <ss:substitution oldstring=".nf&#10;&#10;" newstring=".nf&#10;"/>
+  <!-- * squeeze multiple newlines after REstoring margin -->
+  <ss:substitution oldstring=".RE&#10;&#10;" newstring=".RE&#10;"/>
+  <!-- * U+2591 is a marker we add before and after every Parameter in -->
+  <!-- * Funcprototype output -->
+  <ss:substitution oldstring="&#x2591;" newstring=" "/>
+  <!-- * U+2592 is a marker we add for the newline before output of <sbr>; -->
+  <ss:substitution oldstring="&#x2592;" newstring="&#10;"/>
+  <!-- * -->
+  <!-- * Now deal with some other characters that are added by the -->
+  <!-- * stylesheets during processing. -->
+  <!-- * -->
+  <!-- * bullet -->
+  <ss:substitution oldstring="•" newstring="\(bu"/>
+  <!-- * left double quote -->
+  <ss:substitution oldstring="“" newstring="\(lq"/>
+  <!-- * right double quote -->
+  <ss:substitution oldstring="”" newstring="\(rq"/>
+  <!-- * left single quote -->
+  <ss:substitution oldstring="‘" newstring="\(oq"/>
+  <!-- * right single quote -->
+  <ss:substitution oldstring="’" newstring="\(cq"/>
+  <!-- * copyright sign -->
+  <ss:substitution oldstring="©" newstring="\(co"/>
+  <!-- * registered sign -->
+  <ss:substitution oldstring="®" newstring="\(rg"/>
+  <!-- * ...servicemark... -->
+  <!-- * There is no groff equivalent for it. -->
+  <ss:substitution oldstring="&#x2120;" newstring="(SM)"/>
+  <!-- * ...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) -->
+  <ss:substitution oldstring="™" newstring="(TM)"/>
+
+</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsection><info><title>Description</title></info>
+
+<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. First consider adding your
+  string-substitution mappings to either or both of the following
+  parameters:
+  <variablelist>
+    <varlistentry>
+      <term><parameter>man.string.subst.map.local.pre</parameter></term>
+      <listitem><para>applied before
+      <parameter>man.string.subst.map</parameter></para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><parameter>man.string.subst.map.local.post</parameter></term>
+      <listitem><para>applied after
+      <parameter>man.string.subst.map</parameter></para></listitem>
+    </varlistentry>
+  </variablelist>
+  By default, both of those parameters contain no
+  string substitutions. They are intended as a means for you to
+  specify your own local string-substitution mappings.</para>
+
+  <para>If you remove any of default mappings from the value of the
+  <parameter>man.string.subst.map</parameter> parameter, you are
+  likely to end up with broken output. And be very careful about adding
+  anything to it; it’s 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 of the page.</para>
+
+</warning>
+
+<refsection xml:id="map">
+  <info>
+    <title>Contents of the substitution map</title>
+  </info>
+  <para>The string-substitution map contains one or more
+  <tag>ss: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>--&gt;</literal>").
+  </para>
+</refsection>
+
+</refsection>
+</refentry>