From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Fri, 19 Jan 2007 08:33:52 +0000 (+0000)
Subject: Added the man.string.subst.map.local.pre and
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=3b8838925f1b81e1c587f99957cd3967c25b2d4b;p=docbook-dsssl

Added the man.string.subst.map.local.pre and
man.string.subst.map.local.post parameters. Those parameters
enable local additions and changes to string-substitution mappings
without the need to change the value of man.string.subst.map
parameter (which is for standard system mappings). Closes
#1456738. Thanks to Sam Steingold for constructing a true
stylesheet torture test (the clisp docs) that exposed the need for
these params.
---

diff --git a/xsl/manpages/other.xsl b/xsl/manpages/other.xsl
index 27434ba7f..88394aa56 100644
--- a/xsl/manpages/other.xsl
+++ b/xsl/manpages/other.xsl
@@ -346,31 +346,76 @@ db:manvolnum
 
   <!-- ================================================================== -->
 
-  <!-- * The prepare.manpage.contents template is called after -->
-  <!-- * everything else has been done, just before writing the actual -->
-  <!-- * man-page files to the filesystem. It works on the entire roff -->
-  <!-- * source for each man page (not just the visible contents). -->
+  <!-- * The prepare.manpage.contents template is called after all -->
+  <!-- * other processing has been done, before serializing the -->
+  <!-- * result of all the other processing. It basically works on -->
+  <!-- * the result as one big string. -->
   <xsl:template name="prepare.manpage.contents">
     <xsl:param name="content" select="''"/>
 
-    <!-- * First do "essential" string/character substitutions; for -->
-    <!-- * example, the backslash character _must_ be substituted with -->
-    <!-- * a double backslash, to prevent it from being interpreted as -->
-    <!-- * a roff escape -->
+    <!-- * If user has provided a "local" string-substitution map to -->
+    <!-- * be applied /before/ the standard string-substitution map, -->
+    <!-- * apply it. -->
+    <xsl:variable name="pre.adjusted.content">
+      <xsl:choose>
+        <xsl:when test="$man.string.subst.map.local.pre">
+          <!-- * normalized value of man.string.subst.map.local.pre -->
+          <!-- * is non-empty, so get contents of map and apply them -->
+          <xsl:call-template name="apply-string-subst-map">
+            <xsl:with-param name="content" select="$content"/>
+            <xsl:with-param name="map.contents"
+                            select="exsl:node-set($man.string.subst.map.local.pre)/*"/>
+          </xsl:call-template>
+        </xsl:when>
+        <xsl:otherwise>
+          <!-- * value of man.string.subst.map.local.pre is empty, -->
+          <!-- * so just copy original contents -->
+          <xsl:value-of select="$content"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+
+    <!-- * Apply standard string-substitution map. The main purpose -->
+    <!-- * of this map is to escape certain characters that have -->
+    <!-- * special meaning in roff, and to replace certain characters -->
+    <!-- * used within the stylesheet internally to represent roff -->
+    <!-- * markup characters. -->
     <xsl:variable name="adjusted.content">
       <xsl:call-template name="apply-string-subst-map">
-        <xsl:with-param name="content" select="$content"/>
+        <xsl:with-param name="content" select="$pre.adjusted.content"/>
         <xsl:with-param name="map.contents"
                         select="exsl:node-set($man.string.subst.map)/*"/>
       </xsl:call-template>
     </xsl:variable>
 
+    <!-- * If user has provided a "local" string-substitution map to -->
+    <!-- * be applied /after/ the standard string-substitution map, -->
+    <!-- * apply it. -->
+    <xsl:variable name="post.adjusted.content">
+      <xsl:choose>
+        <xsl:when test="$man.string.subst.map.local.post">
+          <!-- * normalized value of man.string.subst.map.local.post -->
+          <!-- * is non-empty, so get contents of map and apply them -->
+          <xsl:call-template name="apply-string-subst-map">
+            <xsl:with-param name="content" select="$adjusted.content"/>
+            <xsl:with-param name="map.contents"
+                            select="exsl:node-set($man.string.subst.map.local.post)/*"/>
+          </xsl:call-template>
+        </xsl:when>
+        <xsl:otherwise>
+          <!-- * value of man.string.subst.map.local.post is empty, -->
+          <!-- * so just copy original contents -->
+          <xsl:value-of select="$adjusted.content"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+
     <!-- * Optionally, apply a character map to replace Unicode -->
     <!-- * symbols and special characters. -->
     <xsl:choose>
       <xsl:when test="$man.charmap.enabled != 0">
         <xsl:call-template name="apply-character-map">
-          <xsl:with-param name="content" select="$adjusted.content"/>
+          <xsl:with-param name="content" select="$post.adjusted.content"/>
           <xsl:with-param name="map.contents"
                           select="exsl:node-set($man.charmap.contents)/*"/>
         </xsl:call-template>
diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent
index 28792abb6..e80096e43 100644
--- a/xsl/manpages/param.ent
+++ b/xsl/manpages/param.ent
@@ -15,7 +15,9 @@
 <!ENTITY man.links.list.heading SYSTEM "../params/man.links.list.heading.xml">
 <!ENTITY variablelist.term.separator SYSTEM "../params/variablelist.term.separator.xml">
 <!ENTITY variablelist.term.break.after SYSTEM "../params/variablelist.term.break.after.xml">
+<!ENTITY man.string.subst.map.local.pre SYSTEM "../params/man.string.subst.map.local.pre.xml">
 <!ENTITY man.string.subst.map SYSTEM "../params/man.string.subst.map.xml">
+<!ENTITY man.string.subst.map.local.post SYSTEM "../params/man.string.subst.map.local.post.xml">
 <!ENTITY man.charmap.enabled SYSTEM "../params/man.charmap.enabled.xml">
 <!ENTITY man.charmap.use.subset SYSTEM "../params/man.charmap.use.subset.xml">
 <!ENTITY man.charmap.uri SYSTEM "../params/man.charmap.uri.xml">
diff --git a/xsl/manpages/param.xweb b/xsl/manpages/param.xweb
index 16f6a1b76..52f61b87e 100644
--- a/xsl/manpages/param.xweb
+++ b/xsl/manpages/param.xweb
@@ -73,7 +73,9 @@
 &man.charmap.uri;
 &man.charmap.use.subset;
 &man.charmap.subset.profile;
+&man.string.subst.map.local.pre;
 &man.string.subst.map;
+&man.string.subst.map.local.post;
   </reference>
   <reference id="refmeta">
   <title>Refentry metadata gathering</title>
@@ -162,7 +164,9 @@
 <src:fragref linkend="man.output.in.separate.dir.frag"/>
 <src:fragref linkend="man.output.base.dir.frag"/>
 <src:fragref linkend="man.output.subdirs.enabled.frag"/>
+<src:fragref linkend="man.string.subst.map.local.pre.frag"/>
 <src:fragref linkend="man.string.subst.map.frag"/>
+<src:fragref linkend="man.string.subst.map.local.post.frag"/>
 <src:fragref linkend="man.links.are.numbered.frag"/>
 <src:fragref linkend="man.links.are.underlined.frag"/>
 <src:fragref linkend="man.links.list.enabled.frag"/>
diff --git a/xsl/params/man.string.subst.map.local.post.xml b/xsl/params/man.string.subst.map.local.post.xml
new file mode 100644
index 000000000..698e1ad93
--- /dev/null
+++ b/xsl/params/man.string.subst.map.local.post.xml
@@ -0,0 +1,32 @@
+<refentry xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+          id="man.string.subst.map.local.post">
+<refmeta>
+<refentrytitle>man.string.subst.map.local.post</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.string.subst.map.local.post</refname>
+<refpurpose>Specifies “local” string substitutions</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.string.subst.map.local.post.frag'>
+<xsl:param name="man.string.subst.map.local.post"></xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>Use the <parameter>man.string.subst.map.local.post</parameter>
+parameter to specify any “local” string substitutions to perform over
+the entire roff source for each man page <emphasis>after</emphasis>
+performing the string substitutions specified by the <parameter
+>man.string.subst.map</parameter> parameter.</para>
+
+<para>For details about the format of this parameter, see the
+documentation for the <parameter>man.string.subst.map</parameter>
+parameter.</para>
+
+</refsect1>
+</refentry>
diff --git a/xsl/params/man.string.subst.map.local.pre.xml b/xsl/params/man.string.subst.map.local.pre.xml
new file mode 100644
index 000000000..b51767dff
--- /dev/null
+++ b/xsl/params/man.string.subst.map.local.pre.xml
@@ -0,0 +1,32 @@
+<refentry xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+          id="man.string.subst.map.local.pre">
+<refmeta>
+<refentrytitle>man.string.subst.map.local.pre</refentrytitle>
+<refmiscinfo role="type">string</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.string.subst.map.local.pre</refname>
+<refpurpose>Specifies “local” string substitutions</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.string.subst.map.local.pre.frag'>
+  <xsl:param name="man.string.subst.map.local.pre"></xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>Use the <parameter>man.string.subst.map.local.pre</parameter>
+parameter to specify any “local” string substitutions to perform over
+the entire roff source for each man page <emphasis>before</emphasis>
+performing the string substitutions specified by the <parameter
+>man.string.subst.map</parameter> parameter.</para>
+
+<para>For details about the format of this parameter, see the
+documentation for the <parameter>man.string.subst.map</parameter>
+parameter.</para>
+
+</refsect1>
+</refentry>
diff --git a/xsl/params/man.string.subst.map.xml b/xsl/params/man.string.subst.map.xml
index 2af0ff685..fb718d9dc 100644
--- a/xsl/params/man.string.subst.map.xml
+++ b/xsl/params/man.string.subst.map.xml
@@ -143,7 +143,7 @@ is, before writing man-page files to disk) or, if the value of the
 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 --
+“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
@@ -155,13 +155,33 @@ 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>
+  <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 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>