From c755545ebd1f4faddc2c4b7b3b263151e2e4327a Mon Sep 17 00:00:00 2001
From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Sun, 26 Jun 2005 07:10:38 +0000
Subject: [PATCH] Checkpointing before coding and committing final
 character-map changes.

This change fully implements character-map support. I'll write up
a longer description of that in a later commit. But the brief
description is: The old Unicode character replacement mechanism
(replace-entities template) has been removed; a completely
different character-replacement mechanism is now used instead.

By default, it does replacement of all Latin-1 symbols, along with
most special spaces, dashes, and quotes (about 75 characters by
default, compared to the less than 20 special characters that were
handled previously). And the "full" character map provides support
for converting about 800 characters. The mechanism use a
"character map" (in a format compliant with the XSLT 2.0 spec and
therefore completely "forward compatible" with XSLT 2.0.

Other changes made for this commit:

  - Changed default output encoding to UTF-8.

    THIS DOES NOT MEAN THAT MAN PAGES ARE OUTPUT IN RAW UTF-8,
    because the character-map is applied before final output,
    causing all UTF-8 characters covered in the map to be
    converted to roff equivalents.

  - Removed code for adding backslashes before periods/dots and
    before hyphens (&#45;); here's why:

    * 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 for authors to add a zero-width
      space in front of the offending dot(s) in their source

    * Backslashes in front of (&#45;/&#x2D;) are needed... when?
      Myself, I don't know, so the current stylesheet does not add
      backslashes in front of them, ever. If there is a specific
      case where they are necessary or desirable, then we need to
      add code for that case, not just do a blanket conversion.

      And, anyway, my understanding from reading the groff docs is
      that \- is, specifically, a _minus sign_. So if you have a
      place where you want a minus sign to be output instead of
      (&#45;), then you should use (&#8722;/&#x2212;) in your
      source instead. And if you have a place where you want an
      en dash, (&#8211;/&#x2013;). Or if there are places where
      the stylesheets are internally generating (&#45;) where they
      should be generating &#8722; or &#8211;, then we need to fix
      those, not just do blanket conversion.

  - Consolidated all bold and italic formatting so that it is done
    by applying the mode="bold" and mode="italic" templates.

  - Consolidated handling of all instances where we want to
    prevent line breaking; they are all now processed using the
    prevent.line.breaking template.

  - Removed "quote" template. In output, this was causing anything
    marked up with the <quote> element to be preceded by two
    backticks and followed by two apostrophes  -- that is, that
    old-school hack for generating "curly" quotes in Emacs and in
    X-Windows fonts. While Emacs still seems to support that,
    I don't think X-Windows has for a long time now. And, anyway,
    it looks (and has always looked) like complete crap when
    viewed on a normal tty/console
---
 xsl/manpages/docbook.xsl  |  59 ++++--
 xsl/manpages/general.xsl  | 366 ++++++++++++++------------------------
 xsl/manpages/info.xsl     |  91 +++++-----
 xsl/manpages/inline.xsl   |  34 ++--
 xsl/manpages/lists.xsl    |  35 ++--
 xsl/manpages/other.xsl    |  21 +--
 xsl/manpages/param.ent    |   9 +-
 xsl/manpages/param.xweb   |  26 ++-
 xsl/manpages/refentry.xsl |   2 +-
 xsl/manpages/synop.xsl    |  64 +++----
 10 files changed, 302 insertions(+), 405 deletions(-)

diff --git a/xsl/manpages/docbook.xsl b/xsl/manpages/docbook.xsl
index b49169337..6ab09f354 100644
--- a/xsl/manpages/docbook.xsl
+++ b/xsl/manpages/docbook.xsl
@@ -4,6 +4,12 @@
                 exclude-result-prefixes="exsl"
                 version='1.0'>
 
+  <xsl:import href="../html/docbook.xsl"/>
+
+  <xsl:output method="text"
+              encoding="UTF-8"
+              indent="no"/>
+
 <!-- ********************************************************************
      $Id$
      ********************************************************************
@@ -16,7 +22,6 @@
 
 <!-- ==================================================================== -->
 
-  <xsl:import href="../html/docbook.xsl"/>
   <xsl:include href="param.xsl"/>
   <xsl:include href="general.xsl"/>
   <xsl:include href="info.xsl"/>
@@ -27,13 +32,27 @@
   <xsl:include href="synop.xsl"/>
   <xsl:include href="lists.xsl"/>
 
-  <!-- * Needed for chunker.xsl (for now): -->
-  <xsl:param name="chunker.output.method" select="'text'"/>
-  <xsl:param name="chunker.output.encoding" select="'ISO-8859-1'"/>
-
-  <xsl:output method="text"
-              encoding="ISO-8859-1"
-              indent="no"/>
+  <!-- * Read the character-map contents in only once per document, no -->
+  <!-- * matter how many Refentry elements it contains. For documentst -->
+  <!-- * that contain a large number or Refentry elements, this can -->
+  <!-- * result in a significant performance gain over the alternative -->
+  <!-- * (that is, reading it in once for every Refentry processed) -->
+  <xsl:variable name="man.charmap.contents">
+    <xsl:call-template name="read-character-map">
+      <xsl:with-param name="use.subset" select="$man.charmap.use.subset"/>
+      <xsl:with-param name="subset.profile" select="$man.charmap.subset.profile"/>
+      <xsl:with-param name="uri">
+        <xsl:choose>
+          <xsl:when test="$man.charmap.uri != ''">
+            <xsl:value-of select="$man.charmap.uri"/>
+          </xsl:when>
+          <xsl:otherwise>
+            <xsl:value-of select="'../manpages/charmap.groff.xsl'"/>
+          </xsl:otherwise>
+        </xsl:choose>
+      </xsl:with-param>
+    </xsl:call-template>
+  </xsl:variable>
 
   <!-- * if document does not contain at least one refentry, then emit a -->
   <!-- * message and stop -->
@@ -53,7 +72,7 @@
   <xsl:template match="refentry">
 
     <!-- * Because there are several times when we need to check *info of -->
-    <!-- * this refentry and *info of its parent, we get those and store -->
+    <!-- * each refentry and *info of its parent, we get those and store -->
     <!-- * as node-sets in memory. -->
 
     <!-- * Make a node-set with contents of *info -->
@@ -89,8 +108,8 @@
     <xsl:variable name="metadata" select="exsl:node-set($get.metadata)"/>
 
     <!-- * Assemble the various parts into a complete page, then store into -->
-    <!-- * $page.contents so that we can manipluate further. -->
-    <xsl:variable name="page.contents">
+    <!-- * $manpage.contents so that we can manipluate them further. -->
+    <xsl:variable name="manpage.contents">
       <!-- * top.comment = commented-out section at top of roff source -->
       <xsl:call-template name="top.comment"/>
       <!-- * TH.title.line = title line in header/footer of man page -->
@@ -123,18 +142,20 @@
     </xsl:variable>
 
     <!-- * Prepare the page contents for final output, then store in -->
-    <!-- * $page.contents.prepared so the we can pass it on to the -->
+    <!-- * $manpage.contents.prepared so the we can pass it on to the -->
     <!-- * write.text.chunk() function -->
-    <xsl:variable name="page.contents.prepared">
+    <xsl:variable name="manpage.contents.prepared">
       <!-- * "Preparing" the page contents involves, at a minimum, -->
-      <!-- * converting our internal @dot@, @esc & @dash@ pseudo-markup -->
-      <!-- * into real roff; that is: literal . and \ and - characters. -->
+      <!-- * doubling any backslashes found (so they aren't interpreted -->
+      <!-- * as roff escapes). But it does not any longer involve adding -->
+      <!-- * backslashes in front of periods/dots or dashes/hyphens. See -->
+      <!-- * the note in the general.xsl file about that. -->
       <!-- * -->
       <!-- * If $charmap.enabled is true, "preparing" the page contents also -->
       <!-- * involves applying a character map to convert Unicode symbols and -->
       <!-- * special characters into corresponding roff escape sequences. -->
-      <xsl:call-template name="prepare.page.contents">
-        <xsl:with-param name="content" select="$page.contents"/>
+      <xsl:call-template name="prepare.manpage.contents">
+        <xsl:with-param name="content" select="$manpage.contents"/>
       </xsl:call-template>
     </xsl:variable>
     
@@ -142,7 +163,9 @@
     <!-- * the final man page. -->
     <xsl:call-template name="write.text.chunk">
       <xsl:with-param name="filename" select="$metadata/filename"/>
-      <xsl:with-param name="content" select="$page.contents.prepared"/>
+      <xsl:with-param name="quiet" select="$man.output.quietly"/>
+      <xsl:with-param name="encoding" select="$man.output.encoding"/>
+      <xsl:with-param name="content" select="$manpage.contents.prepared"/>
     </xsl:call-template>
 
     <!-- * Finish up by generating "stub" (alias) pages (if any needed) -->
diff --git a/xsl/manpages/general.xsl b/xsl/manpages/general.xsl
index 15c68bcea..9396e33e2 100644
--- a/xsl/manpages/general.xsl
+++ b/xsl/manpages/general.xsl
@@ -1,5 +1,6 @@
 <?xml version='1.0'?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:exsl="http://exslt.org/common"
                 version='1.0'>
 
 <!-- ********************************************************************
@@ -19,16 +20,18 @@
 
 <!-- ==================================================================== -->
 
-  <!-- replace Unicode entities in all text nodes -->
-  <xsl:template match="text()">
-    <xsl:call-template name="replace-entities">
-      <xsl:with-param name="content">
-        <xsl:value-of select="."/>
-      </xsl:with-param>
-    </xsl:call-template>
-  </xsl:template>
+  <!-- * NOTE TO DEVELOPERS: For ease of maintenance, the current -->
+  <!-- * manpages stylesheets use the mode="bold" and mode="italic" -->
+  <!-- * templates for *anything and everything* that needs to get -->
+  <!-- * boldfaced or italicized.   -->
+  <!-- * -->
+  <!-- * So if you add anything that needs bold or italic character -->
+  <!-- * formatting, try to apply these templates to it rather than -->
+  <!-- * writing separate code to format it. This can be a little odd if -->
+  <!-- * the content you want to format is not element content; in those -->
+  <!-- * cases, you need to turn it into element content before applying -->
+  <!-- * the template; see examples of this in the existing code. -->
 
-  <!-- for anything that gets boldfaced -->
   <xsl:template mode="bold" match="*">
     <xsl:for-each select="node()">
       <xsl:text>\fB</xsl:text>
@@ -37,7 +40,6 @@
     </xsl:for-each>
   </xsl:template>
 
-  <!-- for anything that gets italicized -->
   <xsl:template mode="italic" match="*">
     <xsl:for-each select="node()">
       <xsl:text>\fI</xsl:text>
@@ -46,9 +48,24 @@
     </xsl:for-each>
   </xsl:template>
 
-  <!-- * currently called by funcdef and paramdef templates, to prevent their -->
-  <!-- * contents from being broken across lines -->
-  <xsl:template mode="convert.spaces.to.nobreak.spaces" match="*">
+  <!-- ================================================================== -->
+
+  <!-- * NOTE TO DEVELOPERS: For ease of maintenance, the current -->
+  <!-- * manpages stylesheets use the mode="prevent.line.breaking" -->
+  <!-- * templates for *anything and everything* that needs to have -->
+  <!-- * embedded spaces turned into no-break spaces in output - in -->
+  <!-- * order to prevent that output from getting broken across lines -->
+  <!-- * -->
+  <!-- * So if you add anything that whose output, try to apply this -->
+  <!-- * template to it rather than writing separate code to format -->
+  <!-- * it. This can be a little odd if the content you want to -->
+  <!-- * format is not element content; in those cases, you need to -->
+  <!-- * turn it into element content before applying the template; -->
+  <!-- * see examples of this in the existing code. -->
+  <!-- * -->
+  <!-- * This template is currently called by the funcdef and paramdef -->
+  <!-- * and group/arg templates. -->
+  <xsl:template mode="prevent.line.breaking" match="*">
     <xsl:variable name="rcontent">
       <xsl:apply-templates/>
     </xsl:variable>
@@ -58,75 +75,88 @@
     <xsl:call-template name="string.subst">
       <xsl:with-param name="string" select="$content"/>
       <xsl:with-param name="target" select="' '"/>
-      <xsl:with-param name="replacement" select="'\ '"/>
+      <!-- * We output a real nobreak space here (rather than, "\ ", -->
+      <!-- * the roff nobreak space) because, when we do character-map -->
+      <!-- * processing before final output, the character-map will -->
+      <!-- * handle conversion of the &#160; to "\ " for us -->
+      <xsl:with-param name="replacement" select="'&#160;'"/>
     </xsl:call-template>
   </xsl:template>
 
+  <!-- ================================================================== -->
+
+  <!-- * The nested-section-title template is called for refsect3, and any -->
+  <!-- * refsection nested more than 2 levels deep, and for formalpara. -->
   <xsl:template name="nested-section-title">
-    <xsl:text>.sp
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.br</xsl:text>
-    <xsl:text>&#10;</xsl:text>
-    <xsl:text>\fB</xsl:text>
-    <xsl:choose>
-      <xsl:when test="title">
-        <xsl:value-of select="normalize-space(title[1])"/>
-      </xsl:when>
-      <xsl:otherwise>
-        <xsl:apply-templates select="." mode="object.title.markup.textonly"/>
-      </xsl:otherwise>
-    </xsl:choose>
-    <xsl:text>\fR</xsl:text>
+    <!-- * The next few lines are some arcane roff code to control line -->
+    <!-- * spacing after headings. -->
+    <xsl:text>.sp&#10;</xsl:text>
+    <xsl:text>.it 1 an-trap&#10;</xsl:text>
+    <xsl:text>.nr an-no-space-flag 1&#10;</xsl:text>
+    <xsl:text>.nr an-break-flag 1&#10;</xsl:text>
+    <xsl:text>.br&#10;</xsl:text>
+    <!-- * make title wrapper so that we can use mode="bold" template to -->
+    <!-- * apply character formatting to it -->
+    <xsl:variable name="title.wrapper">
+      <bold><xsl:choose>
+        <xsl:when test="title">
+          <xsl:value-of select="normalize-space(title[1])"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:apply-templates select="." mode="object.title.markup.textonly"/>
+        </xsl:otherwise>
+      </xsl:choose></bold>
+    </xsl:variable>
+    <xsl:apply-templates mode="bold" select="exsl:node-set($title.wrapper)"/>
   </xsl:template>
 
-  <!-- jump through a few hoops to deal with mixed-content blocks, so that -->
-  <!-- we don't end up munging verbatim environments or lists and so that we -->
-  <!-- don't gobble up whitespace when we shouldn't -->
+  <!-- ================================================================== -->
+
+  <!-- * The mixed-block template jumps through a few hoops to deal with -->
+  <!-- * mixed-content blocks, so that we don't end up munging verbatim -->
+  <!-- * environments or lists and so that we don't gobble up whitespace -->
+  <!-- * when we shouldn't -->
   <xsl:template name="mixed-block">
     <xsl:for-each select="node()">
       <xsl:choose>
         <xsl:when test="self::address|self::literallayout|self::programlisting|
                         self::screen|self::synopsis">
-          <!-- Check to see if this node is a verbatim environment. -->
-          <!-- If so, put a line break before it. -->
-          
-          <!-- Yes, address and synopsis are vertabim environments. -->
-          
-          <!-- The code here previously also treated informaltable as a -->
-          <!-- verbatim, presumably to support some kludge; I removed it -->
+          <!-- * Check to see if this node is a verbatim environment. -->
+          <!-- * If so, put a line break before it. -->
+          <!-- * -->
+          <!-- * Yes, address and synopsis are vertabim environments. -->
+          <!-- * -->
+          <!-- * The code here previously also treated informaltable as a -->
+          <!-- * verbatim, presumably to support some kludge; I removed it -->
           <xsl:text>&#10;</xsl:text>
           <xsl:apply-templates select="."/>
-          <!-- we don't need an extra line break after verbatim environments
-               <xsl:text> &#10;</xsl:text>
-               -->
+          <!-- * we don't need an extra line break after verbatim environments -->
+          <!-- * <xsl:text> &#10;</xsl:text> -->
         </xsl:when>
         <xsl:when test="self::itemizedlist|self::orderedlist|
                         self::variablelist|self::simplelist[@type !='inline']">
-          <!-- Check to see if this node is a list; if so, -->
-          <!-- put a line break before it. -->
+          <!-- * Check to see if this node is a list; if so, -->
+          <!-- * put a line break before it. -->
           <xsl:text>&#10;</xsl:text>
           <xsl:apply-templates select="."/>
-          <!-- we don't need an extra line break after lists
-               <xsl:text> &#10;</xsl:text>
-               -->
+          <!-- * we don't need an extra line break after lists -->
+          <!-- * <xsl:text> &#10;</xsl:text> -->
         </xsl:when>
         <xsl:when test="self::text()">
-          <!-- Check to see if this is a text node. -->
-          
-          <!-- If so, take any multiple whitespace at the beginning or end of -->
-          <!-- it, and replace it with a space plus a linebreak. -->
-          
-          <!-- This hack results in some ugliness in the generated roff -->
-          <!-- source. But it ensures the whitespace around text nodes in mixed -->
-          <!-- content gets preserved; without the hack, that whitespace -->
-          <!-- effectively gets gobbled. -->
-
-          <!-- Note if the node is just space, we just pass it through -->
-          <!-- without (re)adding a line break. -->
-          
-          <!-- There must be a better way to do with this...  -->
+          <!-- * Check to see if this is a text node. -->
+          <!-- * -->
+          <!-- * If so, take any multiple whitespace at the beginning or end of -->
+          <!-- * it, and replace it with a space plus a linebreak. -->
+          <!-- * -->
+          <!-- * This hack results in some ugliness in the generated roff -->
+          <!-- * source. But it ensures the whitespace around text nodes in mixed -->
+          <!-- * content gets preserved; without the hack, that whitespace -->
+          <!-- * effectively gets gobbled. -->
+          <!-- * -->
+          <!-- * Note if the node is just space, we just pass it through -->
+          <!-- * without (re)adding a line break. -->
+          <!-- * -->
+          <!-- * There must be a better way to do with this...  -->
           <xsl:variable name="content">
             <xsl:apply-templates select="."/>
           </xsl:variable>
@@ -139,7 +169,7 @@
           </xsl:if>
           <xsl:value-of select="normalize-space($content)"/>
           <xsl:if
-              test="translate(substring(., string-length(.), 1),'&#x9;&#10;&#13; ','    ')  = ' '
+              test="translate(substring(., string-length(.), 1),'&#9;&#10;&#13; ','    ')  = ' '
                     and following-sibling::node()[name(.)!='']
                     ">
             <xsl:text> </xsl:text>
@@ -149,9 +179,9 @@
           </xsl:if>
         </xsl:when>
         <xsl:otherwise>
-          <!-- At this point, we know that this node is not a verbatim -->
-          <!-- environment, list, or text node; so we can safely -->
-          <!-- normailize-space() it. -->
+          <!-- * At this point, we know that this node is not a verbatim -->
+          <!-- * environment, list, or text node; so we can safely -->
+          <!-- * normalize-space() it. -->
           <xsl:variable name="content">
             <xsl:apply-templates select="."/>
           </xsl:variable>
@@ -161,180 +191,44 @@
     </xsl:for-each>
   </xsl:template>
 
-  <!-- deal with Unicode entities -->
-  <xsl:template name="replace-entities">
-    <xsl:param name="content" select="''"/>
-    <xsl:call-template name="replace-hellip">
-      <xsl:with-param name="content">
-        <xsl:call-template name="replace-minus">
-          <xsl:with-param name="content">
-            <xsl:call-template name="replace-mdash">
-              <xsl:with-param name="content">
-                <xsl:call-template name="replace-ndash">
-                  <xsl:with-param name="content">
-                    <xsl:call-template name="replace-dash">
-                      <xsl:with-param name="content">
-                        <xsl:call-template name="replace-setmn">
-                          <xsl:with-param name="content">
-                            <xsl:call-template name="replace-period">
-                              <xsl:with-param name="content">
-                                <xsl:call-template name="replace-nbsp">
-                                  <xsl:with-param name="content">
-                                    <xsl:call-template name="replace-ldquo">
-                                      <xsl:with-param name="content">
-                                        <xsl:call-template name="replace-rdquo">
-                                          <xsl:with-param name="content">
-                                            <xsl:call-template name="replace-backslash">
-                                              <xsl:with-param name="content" select="$content"/>
-                                            </xsl:call-template>
-                                          </xsl:with-param>
-                                        </xsl:call-template>
-                                      </xsl:with-param>
-                                    </xsl:call-template>
-                                  </xsl:with-param>
-                                </xsl:call-template>
-                              </xsl:with-param>
-                            </xsl:call-template>
-                          </xsl:with-param>
-                        </xsl:call-template>
-                      </xsl:with-param>
-                    </xsl:call-template>
-                  </xsl:with-param>
-                </xsl:call-template>
-              </xsl:with-param>
-            </xsl:call-template>
-          </xsl:with-param>
-        </xsl:call-template>
-      </xsl:with-param>
-    </xsl:call-template>
-  </xsl:template>
-
-<!-- ==================================================================== -->
-
-  <xsl:template match="dingbat.characters">
-    <!-- now that I'm using the real serializer, all that dingbat malarky -->
-    <!-- isn't necessary anymore... -->
-    <xsl:param name="dingbat">bullet</xsl:param>
-    <xsl:choose>
-      <xsl:when test="$dingbat='bullet'">\(bu</xsl:when>
-      <xsl:when test="$dingbat='copyright'">\(co</xsl:when>
-      <xsl:when test="$dingbat='trademark'">\(tm</xsl:when>
-      <xsl:when test="$dingbat='trade'">\(tm</xsl:when>
-      <xsl:when test="$dingbat='registered'">\(rg</xsl:when>
-      <xsl:when test="$dingbat='service'">(SM)</xsl:when>
-      <xsl:when test="$dingbat='nbsp'">\~</xsl:when>
-      <xsl:when test="$dingbat='ldquo'">\(lq</xsl:when>
-      <xsl:when test="$dingbat='rdquo'">\(rq</xsl:when>
-      <xsl:when test="$dingbat='lsquo'">`</xsl:when>
-      <xsl:when test="$dingbat='rsquo'">'</xsl:when>
-      <xsl:when test="$dingbat='em-dash'">\(em</xsl:when>
-      <xsl:when test="$dingbat='mdash'">\(em</xsl:when>
-      <xsl:when test="$dingbat='en-dash'">\(en</xsl:when>
-      <xsl:when test="$dingbat='ndash'">\(en</xsl:when>
-      <xsl:otherwise>
-        <xsl:text>\(bu</xsl:text>
-      </xsl:otherwise>
-    </xsl:choose>
-  </xsl:template>
-
-<!-- ==================================================================== -->
-
-  <xsl:template name="replace-dash">
-    <xsl:param name="content" select="''"/>
-    <xsl:call-template name="string.subst">
-      <xsl:with-param name="string" select="$content"/>
-      <xsl:with-param name="target" select="'-'"/>
-      <xsl:with-param name="replacement" select="'\-'"/>
-    </xsl:call-template>
-  </xsl:template>
-
-  <xsl:template name="replace-ndash">
-    <xsl:param name="content" select="''"/>
-    <xsl:call-template name="string.subst">
-      <xsl:with-param name="string" select="$content"/>
-      <xsl:with-param name="target" select="'&#8211;'"/>
-      <xsl:with-param name="replacement" select="'-'"/>
-    </xsl:call-template>
-  </xsl:template>
-
-  <xsl:template name="replace-mdash">
-    <xsl:param name="content" select="''"/>
-    <xsl:call-template name="string.subst">
-      <xsl:with-param name="string" select="$content"/>
-      <xsl:with-param name="target" select="'&#8212;'"/>
-      <xsl:with-param name="replacement" select="'--'"/>
-    </xsl:call-template>
-  </xsl:template>
-
-  <xsl:template name="replace-hellip">
-    <xsl:param name="content" select="''"/>
-    <xsl:call-template name="string.subst">
-      <xsl:with-param name="string" select="$content"/>
-      <xsl:with-param name="target" select="'&#8230;'"/>
-      <xsl:with-param name="replacement" select="'...'"/>
-    </xsl:call-template>
-  </xsl:template>
-
-  <xsl:template name="replace-setmn">
-    <xsl:param name="content" select="''"/>
-    <xsl:call-template name="string.subst">
-      <xsl:with-param name="string" select="$content"/>
-      <xsl:with-param name="target" select="'&#8726;'"/>
-      <xsl:with-param name="replacement" select="'\\'"/>
-    </xsl:call-template>
-  </xsl:template>
-
-  <xsl:template name="replace-minus">
-    <xsl:param name="content" select="''"/>
-    <xsl:value-of select="translate($content,'&#8722;','-')"/>
-  </xsl:template>
-
-  <xsl:template name="replace-nbsp">
-    <xsl:param name="content" select="''"/>
-    <xsl:call-template name="string.subst">
-      <xsl:with-param name="string" select="$content"/>
-      <xsl:with-param name="target" select="'&#x00a0;'"/>
-      <xsl:with-param name="replacement" select="'\~'"/>
-    </xsl:call-template>
-  </xsl:template>
-
-  <xsl:template name="replace-ldquo">
-    <xsl:param name="content" select="''"/>
-    <xsl:call-template name="string.subst">
-      <xsl:with-param name="string" select="$content"/>
-      <xsl:with-param name="target" select="'&#8220;'"/>
-      <xsl:with-param name="replacement" select="'\(lq'"/>
-    </xsl:call-template>
-  </xsl:template>
+  <!-- ================================================================== -->
 
-  <xsl:template name="replace-rdquo">
+  <xsl:template name="prepare.manpage.contents">
     <xsl:param name="content" select="''"/>
-    <xsl:call-template name="string.subst">
-      <xsl:with-param name="string" select="$content"/>
-      <xsl:with-param name="target" select="'&#8221;'"/>
-      <xsl:with-param name="replacement" select="'\(rq'"/>
+    <xsl:call-template name="apply-character-map">
+      <xsl:with-param name="content" select="$content"/>
+      <xsl:with-param name="character.map.contents"
+                      select="exsl:node-set($man.charmap.contents)/*"/>
     </xsl:call-template>
   </xsl:template>
 
-  <xsl:template name="replace-backslash">
-    <xsl:param name="content" select="''"/>
-    <xsl:call-template name="string.subst">
-      <xsl:with-param name="string" select="$content"/>
-      <xsl:with-param name="target" select="'\'"/>
-      <xsl:with-param name="replacement" select="'\\'"/>
-    </xsl:call-template>
-  </xsl:template>
-
-  <!-- if a period character is output at the beginning of a line
-       it will be interpreted as a groff macro, so prefix all periods
-       with "\&", a zero-width space. -->
-  <xsl:template name="replace-period">
-    <xsl:param name="content" select="''"/>
-    <xsl:call-template name="string.subst">
-      <xsl:with-param name="string" select="$content"/>
-      <xsl:with-param name="target" select="'.'"/>
-      <xsl:with-param name="replacement" select="'\&#38;.'"/>
-    </xsl:call-template>
-  </xsl:template>
+  <!-- * We don't add backslashes before periods/dots or hyphens (&#45;) -->
+  <!-- * Here's why: -->
+  <!-- * -->
+  <!-- * - 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 for authors to add a zero-width space in front of -->
+  <!-- *   the offending dot(s) in their source -->
+  <!-- * -->
+  <!-- * - Backslashes in front of (&#45;/&#x2D;) are needed... when? -->
+  <!-- *   Myself, I don't know, so the current stylesheet does not add -->
+  <!-- *   backslashes in front of them, ever. If there is a specific case -->
+  <!-- *   where they are necessary or desirable, then we need to add code -->
+  <!-- *   for that case, not just do a blanket conversion. -->
+  <!-- * -->
+  <!-- *   And, anyway, my understanding from reading the groff docs -->
+  <!-- *   is that \- is, specifically, a _minus sign_. So if users -->
+  <!-- *   have places where they want a minus sign to be output -->
+  <!-- *   instead of (&#45;), then they should use (&#8722;/&#x2212;) -->
+  <!-- *   in their source instead. And if they have a place where -->
+  <!-- *   they want an en dash, (&#8211;/&#x2013;). Or if there are -->
+  <!-- *   places where the stylesheets are internally generating -->
+  <!-- *   (&#45;) where they should be generating &#8722; or &#8211;, -->
+  <!-- *   then we need to fix those, not just do blanket conversion. -->
+
+<!--   TODO: We do need to add backslash in front of single-quote if it is -->
+<!--   the first character in a line. And escaping of -->
+<!--   backslashes need to be restored before release. -->
 
 </xsl:stylesheet>
diff --git a/xsl/manpages/info.xsl b/xsl/manpages/info.xsl
index 27911c815..ea824d1e0 100644
--- a/xsl/manpages/info.xsl
+++ b/xsl/manpages/info.xsl
@@ -1,8 +1,7 @@
 <?xml version='1.0'?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                xmlns:exsl="http://exslt.org/common"
                 xmlns:date="http://exslt.org/dates-and-times"
-                exclude-result-prefixes="exsl date"
+                exclude-result-prefixes="date"
                 version='1.0'>
 
 <!-- ********************************************************************
@@ -15,7 +14,7 @@
 
      ******************************************************************** -->
 
-<!-- ==================================================================== -->
+  <!-- ==================================================================== -->
 
   <xsl:template name="get.metadata">
     <xsl:param name="info"/>
@@ -91,49 +90,45 @@
 
     <!-- * <date> is a date :-) If we can't find one, we add one; see below -->
     <date>
-      <xsl:call-template name="replace-entities">
-        <xsl:with-param name="content">
-          <xsl:choose>
-            <!-- look for date or pubdate in *info -->
-            <xsl:when test="$info/date|$info/pubdate">
-              <xsl:copy>
-                <xsl:apply-templates
-                    select="($info/date/node()|$info/pubdate/node())[1]"/>
-              </xsl:copy>
-            </xsl:when>
-            <!-- look for date or pubdate in parent's *info -->
-            <xsl:when test="$parentinfo/date|$parentinfo/pubdate">
-              <xsl:copy>
-                <xsl:apply-templates
-                    select="($parentinfo/date/node()|$parentinfo/pubdate/node())[1]"/>
-              </xsl:copy>
-            </xsl:when>
-            <!-- * If we can't find a date, then we generate a date. -->
-            <!-- * And we make it an appropriately localized date. -->
-            <xsl:otherwise>
-              <xsl:call-template name="datetime.format">
-                <xsl:with-param name="date">
-                  <xsl:choose>
-                    <xsl:when test="function-available('date:date-time')">
-                      <xsl:value-of select="date:date-time()"/>
-                    </xsl:when>
-                    <xsl:when test="function-available('date:dateTime')">
-                      <!-- Xalan quirk -->
-                      <xsl:value-of select="date:dateTime()"/>
-                    </xsl:when>
-                  </xsl:choose>
-                </xsl:with-param>
-                <xsl:with-param name="format">
-                  <xsl:call-template name="gentext.template">
-                    <xsl:with-param name="context" select="'datetime'"/>
-                    <xsl:with-param name="name" select="'format'"/>
-                  </xsl:call-template>
-                </xsl:with-param>
+      <xsl:choose>
+        <!-- look for date or pubdate in *info -->
+        <xsl:when test="$info/date|$info/pubdate">
+          <xsl:copy>
+            <xsl:apply-templates
+                select="($info/date/node()|$info/pubdate/node())[1]"/>
+          </xsl:copy>
+        </xsl:when>
+        <!-- look for date or pubdate in parent's *info -->
+        <xsl:when test="$parentinfo/date|$parentinfo/pubdate">
+          <xsl:copy>
+            <xsl:apply-templates
+                select="($parentinfo/date/node()|$parentinfo/pubdate/node())[1]"/>
+          </xsl:copy>
+        </xsl:when>
+        <!-- * If we can't find a date, then we generate a date. -->
+        <!-- * And we make it an appropriately localized date. -->
+        <xsl:otherwise>
+          <xsl:call-template name="datetime.format">
+            <xsl:with-param name="date">
+              <xsl:choose>
+                <xsl:when test="function-available('date:date-time')">
+                  <xsl:value-of select="date:date-time()"/>
+                </xsl:when>
+                <xsl:when test="function-available('date:dateTime')">
+                  <!-- Xalan quirk -->
+                  <xsl:value-of select="date:dateTime()"/>
+                </xsl:when>
+              </xsl:choose>
+            </xsl:with-param>
+            <xsl:with-param name="format">
+              <xsl:call-template name="gentext.template">
+                <xsl:with-param name="context" select="'datetime'"/>
+                <xsl:with-param name="name" select="'format'"/>
               </xsl:call-template>
-            </xsl:otherwise>
-          </xsl:choose>
-        </xsl:with-param>
-      </xsl:call-template>
+            </xsl:with-param>
+          </xsl:call-template>
+        </xsl:otherwise>
+      </xsl:choose>
     </date>
 
     <!-- * <versionorname> = (in the best case) we just want to find some kind -->
@@ -265,10 +260,4 @@
     <xsl:text>&gt;</xsl:text>
   </xsl:template>
 
-  <xsl:template match="copyright">
-    <xsl:text>Copyright \(co  </xsl:text>
-    <xsl:apply-templates select="./year" />
-    <xsl:text>.Sp&#10;</xsl:text>
-  </xsl:template>
-
 </xsl:stylesheet>
diff --git a/xsl/manpages/inline.xsl b/xsl/manpages/inline.xsl
index 49cf4da09..6727dc772 100644
--- a/xsl/manpages/inline.xsl
+++ b/xsl/manpages/inline.xsl
@@ -1,5 +1,6 @@
 <?xml version='1.0'?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:exsl="http://exslt.org/common"
                 version='1.0'>
 
 <!-- ********************************************************************
@@ -33,12 +34,6 @@
   </xsl:choose>
 </xsl:template>
 
-<xsl:template match="quote">
-  <xsl:text>``</xsl:text>
-  <xsl:apply-templates/>
-  <xsl:text>''</xsl:text>
-</xsl:template>
-
 <xsl:template match="optional">
   <xsl:value-of select="$arg.choice.opt.open.str"/>
   <xsl:apply-templates/>
@@ -48,8 +43,10 @@
 <xsl:template name="do-citerefentry">
   <xsl:param name="refentrytitle" select="''"/>
   <xsl:param name="manvolnum" select="''"/>
-
-  <xsl:apply-templates mode="bold" select="$refentrytitle"/>
+  <xsl:variable name="title">
+    <bold><xsl:value-of select="$refentrytitle"/></bold>
+  </xsl:variable>
+  <xsl:apply-templates mode="bold" select="exsl:node-set($title)"/>
   <xsl:text>(</xsl:text>
   <xsl:value-of select="$manvolnum"/>
   <xsl:text>)</xsl:text>
@@ -70,19 +67,14 @@
     <xsl:apply-templates/>
   </xsl:variable>
   <xsl:variable name="url" select="@url"/>
-  <xsl:choose>
-    <xsl:when test="$url=$content or $content=''">
-      <xsl:text>\fI</xsl:text>
-      <xsl:value-of select="$url"/>
-      <xsl:text>\fR</xsl:text>
-    </xsl:when>
-    <xsl:otherwise>
-      <xsl:value-of select="$content"/>
-      <xsl:text>: \fI</xsl:text>
-      <xsl:value-of select="$url"/>
-      <xsl:text>\fR</xsl:text>
-    </xsl:otherwise>
-  </xsl:choose>
+  <xsl:if test="$url != $content and $content != ''">
+    <xsl:value-of select="$content"/>
+    <xsl:text>: </xsl:text>
+  </xsl:if>
+  <xsl:variable name="url.wrapper">
+    <italic><xsl:value-of select="@url"/></italic>
+  </xsl:variable>
+  <xsl:apply-templates mode="italic" select="exsl:node-set($url.wrapper)"/>
 </xsl:template>
 
 </xsl:stylesheet>
diff --git a/xsl/manpages/lists.xsl b/xsl/manpages/lists.xsl
index 568a665a3..4510d11c3 100644
--- a/xsl/manpages/lists.xsl
+++ b/xsl/manpages/lists.xsl
@@ -21,8 +21,8 @@
   <xsl:if test="following-sibling::para or
 	  following-sibling::simpara or
 	  following-sibling::remark">
-    <!-- Make sure multiple paragraphs within a list item don't -->
-    <!-- merge together.                                        -->
+    <!-- * Make sure multiple paragraphs within a list item don't -->
+    <!-- * merge together.                                        -->
     <xsl:text>&#10;</xsl:text>
   </xsl:if>
 </xsl:template>
@@ -37,8 +37,8 @@
   <xsl:if test="following-sibling::para or
 		following-sibling::simpara or
 		following-sibling::remark">
-    <!-- Make sure multiple paragraphs within a list item don't -->
-    <!-- merge together.                                        -->
+    <!-- * Make sure multiple paragraphs within a list item don't -->
+    <!-- * merge together.                                        -->
     <xsl:text>&#10;</xsl:text>
   </xsl:if>
 </xsl:template>
@@ -83,7 +83,11 @@
 </xsl:template>
 
 <xsl:template match="itemizedlist/listitem">
-  <xsl:text>\(bu&#10;</xsl:text>
+  <!-- * We output a real bullet here (rather than, "\(bu", -->
+  <!-- * the roff bullet) because, when we do character-map -->
+  <!-- * processing before final output, the character-map will -->
+  <!-- * handle conversion of the &#x2022; to "\(bu" for us -->
+  <xsl:text>&#x2022;&#10;</xsl:text>
   <xsl:apply-templates/>
   <xsl:if test="following-sibling::listitem">
     <xsl:text>.TP&#10;</xsl:text>
@@ -108,24 +112,27 @@
 <xsl:template match="itemizedlist[ancestor::listitem or ancestor::step]|
 	             orderedlist[ancestor::listitem or ancestor::step]|
 		     procedure[ancestor::listitem or ancestor::step]">
-  <xsl:text>.RS&#10;.TP 3&#10;</xsl:text>
+  <xsl:text>.RS&#10;</xsl:text>
+  <xsl:text>.TP 3&#10;</xsl:text>
   <xsl:apply-templates/>
-  <xsl:text>.LP&#10;.RE&#10;.IP&#10;</xsl:text>
+  <xsl:text>.LP&#10;</xsl:text>
+  <xsl:text>.RE&#10;</xsl:text>
+  <xsl:text>.IP&#10;</xsl:text>
 </xsl:template>
 
-<!-- for simplelist type="inline", render it as a comma-separated list -->
+<!-- * for simplelist type="inline", render it as a comma-separated list -->
 <xsl:template match="simplelist[@type='inline']">
 
-  <!-- if dbchoice PI exists, use that to determine the choice separator -->
-  <!-- (that is, equivalent of "and" or "or" in current locale), or literal -->
-  <!-- value of "choice" otherwise -->
+  <!-- * if dbchoice PI exists, use that to determine the choice separator -->
+  <!-- * (that is, equivalent of "and" or "or" in current locale), or literal -->
+  <!-- * value of "choice" otherwise -->
   <xsl:variable name="localized-choice-separator">
     <xsl:choose>
       <xsl:when test="processing-instruction('dbchoice')">
 	<xsl:call-template name="select.choice.separator"/>
       </xsl:when>
       <xsl:otherwise>
-	<!-- empty -->
+	<!-- * empty -->
       </xsl:otherwise>
     </xsl:choose>
   </xsl:variable>
@@ -148,8 +155,8 @@
   <xsl:text>&#10;</xsl:text>
 </xsl:template>
 
-<!-- if simplelist type is not inline, render it as a one-column vertical -->
-<!-- list (ignoring the values of the type and columns attributes) -->
+<!-- * if simplelist type is not inline, render it as a one-column vertical -->
+<!-- * list (ignoring the values of the type and columns attributes) -->
 <xsl:template match="simplelist">
   <xsl:for-each select="member">
     <xsl:text>.IP&#10;</xsl:text>
diff --git a/xsl/manpages/other.xsl b/xsl/manpages/other.xsl
index 0e3315e1a..576dba307 100644
--- a/xsl/manpages/other.xsl
+++ b/xsl/manpages/other.xsl
@@ -23,21 +23,16 @@
 <!-- ==================================================================== -->
 
   <xsl:template name="top.comment">
-    <xsl:text>@dot@@esc@" ** You probably do not want to</xsl:text>
+    <xsl:text>.\" ** You probably do not want to</xsl:text>
     <xsl:text> edit this file directly **&#10;</xsl:text>
-    <xsl:text>@dot@@esc@" It was generated using the DocBook</xsl:text>
+    <xsl:text>.\" It was generated using the DocBook</xsl:text>
     <xsl:text> XSL Stylesheets (version </xsl:text>
-    <xsl:call-template name="string.subst">
-      <xsl:with-param name="string" select="$VERSION" />
-      <xsl:with-param name="target" select="'.'" />
-      <xsl:with-param name="replacement" select="'@dot@'" />
-    </xsl:call-template>
-    <xsl:text>)@dot@</xsl:text>
-    <xsl:text>&#10;</xsl:text>
-    <xsl:text>@dot@@esc@" Instead of manually editing it, you</xsl:text>
+    <xsl:value-of select="$VERSION"/>
+    <xsl:text>).&#10;</xsl:text>
+    <xsl:text>.\" Instead of manually editing it, you</xsl:text>
     <xsl:text> probably should edit the DocBook XML&#10;</xsl:text>
-    <xsl:text>@dot@@esc@" source for it and then use the DocBook</xsl:text>
-    <xsl:text> XSL Stylesheets to regenerate it@dot@&#10;</xsl:text>
+    <xsl:text>.\" source for it and then use the DocBook</xsl:text>
+    <xsl:text> XSL Stylesheets to regenerate it.&#10;</xsl:text>
   </xsl:template>
 
 <!-- ==================================================================== -->
@@ -75,7 +70,7 @@
     <!-- * user-configurable parameter -->
     <xsl:variable name="th.title.max.length" select="'20'"/>
 
-    <xsl:text>@dot@TH "</xsl:text>
+    <xsl:text>.TH "</xsl:text>
     <xsl:value-of select="translate(
                           substring($title, 1, $th.title.max.length),
                           'abcdefghijklmnopqrstuvwxyz',
diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent
index 276afacf2..44596f98f 100644
--- a/xsl/manpages/param.ent
+++ b/xsl/manpages/param.ent
@@ -1,2 +1,7 @@
-<!ENTITY hyphenate SYSTEM "../params/hyphenate.xml">
-<!ENTITY alignment SYSTEM "../params/alignment.xml">
\ No newline at end of file
+<!ENTITY man.hyphenate SYSTEM "../params/man.hyphenate.xml">
+<!ENTITY man.alignment SYSTEM "../params/man.alignment.xml">
+<!ENTITY man.output.quietly SYSTEM "../params/man.output.quietly.xml">
+<!ENTITY man.output.encoding SYSTEM "../params/man.output.encoding.xml">
+<!ENTITY man.charmap.use.subset SYSTEM "../params/man.charmap.use.subset.xml">
+<!ENTITY man.charmap.subset.profile SYSTEM "../params/man.charmap.subset.profile.xml">
+<!ENTITY man.charmap.uri SYSTEM "../params/man.charmap.uri.xml">
\ No newline at end of file
diff --git a/xsl/manpages/param.xweb b/xsl/manpages/param.xweb
index 93517c06e..187deec88 100644
--- a/xsl/manpages/param.xweb
+++ b/xsl/manpages/param.xweb
@@ -30,14 +30,23 @@
   </preface>
 
   <reference>
-  <title>Parameters</title>
-&alignment;
-&hyphenate;
+  <title>General</title>
+&man.alignment;
+&man.hyphenate;
+&man.output.quietly;
+&man.output.encoding;
+  </reference>
+  <reference>
+  <title>Character map</title>
+&man.charmap.uri;
+&man.charmap.use.subset;
+&man.charmap.subset.profile;
   </reference>
   <appendix>
     <title>The Stylesheet</title>
 
-    <para>The <filename>param.xsl</filename> stylesheet is just a wrapper around all of these parameters.</para>
+    <para>The <filename>param.xsl</filename> stylesheet is just a
+    wrapper around all of these parameters.</para>
 
     <src:fragment id='top' mundane-result-prefixes='xsl'>
 <xsl:stylesheet xmlns='http://www.w3.org/1999/XSL/Transform'
@@ -56,8 +65,13 @@
 
      ******************************************************************** -->
 
-<src:fragref linkend="alignment.frag"/>
-<src:fragref linkend="hyphenate.frag"/>
+<src:fragref linkend="man.alignment.frag"/>
+<src:fragref linkend="man.hyphenate.frag"/>
+<src:fragref linkend="man.output.quietly.frag"/>
+<src:fragref linkend="man.output.encoding.frag"/>
+<src:fragref linkend="man.charmap.uri.frag"/>
+<src:fragref linkend="man.charmap.use.subset.frag"/>
+<src:fragref linkend="man.charmap.subset.profile.frag"/>
 </xsl:stylesheet>
     </src:fragment>
 
diff --git a/xsl/manpages/refentry.xsl b/xsl/manpages/refentry.xsl
index 9f696bc35..3a9bb3344 100644
--- a/xsl/manpages/refentry.xsl
+++ b/xsl/manpages/refentry.xsl
@@ -38,7 +38,7 @@
       </xsl:if>
       <xsl:value-of select="."/>
     </xsl:for-each>
-    <xsl:text> \- </xsl:text>
+    <xsl:text> - </xsl:text>
     <xsl:value-of select="normalize-space (refpurpose)"/>
     <xsl:text>&#10;</xsl:text>
   </xsl:template>
diff --git a/xsl/manpages/synop.xsl b/xsl/manpages/synop.xsl
index 7a30bf8d6..365f3239c 100644
--- a/xsl/manpages/synop.xsl
+++ b/xsl/manpages/synop.xsl
@@ -14,21 +14,14 @@
 
      ******************************************************************** -->
 
-<!-- * Note: If you are looking for the <synopsis> element, you won't find -->
-<!-- * any code here for handling it. It is a verbatim environment; check the -->
-<!-- * block.xsl file instead. -->
+<!-- * Note: If you are looking for the <synopsis> element, you won't -->
+<!-- * find any code here for handling it. It is a _verbatim_ -->
+<!-- * environment; check the block.xsl file instead. -->
 
 <xsl:template match="synopfragment">
-<xsl:text>.PP&#10;</xsl:text>
-<xsl:apply-templates/>
+  <xsl:text>.PP&#10;</xsl:text>
+  <xsl:apply-templates/>
 </xsl:template>
-<!--
-  there's a bug where an <arg> that's not inside a <group> isn't made bold
--->
-
-<!-- * 2005-06-02: Check to see if above comment (arg not inside group -->
-<!-- * doesn't get bolded) is still true or not. If turns out it is not, -->
-<!-- * remove the comment -->
 
 <xsl:template match="group|arg">
   <xsl:variable name="choice" select="@choice"/>
@@ -46,7 +39,7 @@
   <xsl:if test="position()>1"><xsl:value-of select="$sepchar"/></xsl:if>
   <xsl:choose>
     <xsl:when test="$choice='plain'">
-      <!-- do nothing -->
+      <!-- * do nothing -->
     </xsl:when>
     <xsl:when test="$choice='req'">
       <xsl:value-of select="$arg.choice.req.open.str"/>
@@ -63,12 +56,12 @@
   </xsl:variable>
   <xsl:choose>
     <xsl:when test="local-name(.) = 'arg' and not(ancestor::arg)">
-      <!-- Prevent breaking up an argument by wrapping it -->
-      <xsl:call-template name="string.subst">
-        <xsl:with-param name="string" select="normalize-space($arg)"/>
-        <xsl:with-param name="target" select="' '"/>
-        <xsl:with-param name="replacement" select="'\ '"/>
-      </xsl:call-template>
+      <!-- * Prevent arg contents from getting wrapped and broken up -->
+      <xsl:variable name="arg.wrapper">
+        <Arg><xsl:value-of select="normalize-space($arg)"/></Arg>
+      </xsl:variable>
+      <xsl:apply-templates mode="prevent.line.breaking"
+                           select="exsl:node-set($arg.wrapper)"/>
     </xsl:when>
     <xsl:otherwise>
       <xsl:value-of select="$arg"/>
@@ -103,23 +96,6 @@
   </xsl:choose>
 </xsl:template>
 
-<xsl:template match="group/arg">
-  <xsl:if test="position()>1">
-    <xsl:value-of select="$arg.or.sep"/>
-  </xsl:if>
-  <xsl:variable name="arg">
-    <xsl:apply-templates/>
-  </xsl:variable>
-  <xsl:variable name="space-escaped-arg">
-    <xsl:call-template name="string.subst">
-      <xsl:with-param name="string" select="normalize-space($arg)"/>
-      <xsl:with-param name="target" select="' '"/>
-      <xsl:with-param name="replacement" select="'\ '"/>
-    </xsl:call-template>
-  </xsl:variable>
-  <xsl:apply-templates mode="bold" select="exsl:node-set($space-escaped-arg)"/>
-</xsl:template>
-
 <xsl:template match="command">
   <xsl:apply-templates mode="bold" select="."/>
 </xsl:template>
@@ -138,13 +114,15 @@
 </xsl:template>
 
 <xsl:template match="cmdsynopsis">
-  <xsl:text>.ad l&#10;.hy 0&#10;</xsl:text>
+  <xsl:text>.ad l&#10;</xsl:text>
+  <xsl:text>.hy 0&#10;</xsl:text>
   <xsl:text>.HP </xsl:text>
   <xsl:value-of select="string-length (normalize-space (command)) + 1"/>
   <xsl:text>&#10;</xsl:text>
   <xsl:apply-templates/>
   <xsl:text>&#10;</xsl:text>
-  <xsl:text>.ad&#10;.hy&#10;</xsl:text>
+  <xsl:text>.ad&#10;</xsl:text>
+  <xsl:text>.hy&#10;</xsl:text>
 </xsl:template>
 
 <xsl:template match="funcsynopsisinfo">
@@ -154,9 +132,9 @@
   <xsl:text>.sp&#10;</xsl:text>
 </xsl:template>
 
-<!-- disable hyphenation, and use left-aligned filling for the duration
-     of the synopsis, so that line breaks only occur between 
-     separate paramdefs. -->
+<!-- * Within funcsynopis output, disable hyphenation, and use -->
+<!-- * left-aligned filling for the duration of the synopsis, so that -->
+<!-- * line breaks only occur between separate paramdefs. -->
 <xsl:template match="funcsynopsis">
   <xsl:text>.ad l&#10;</xsl:text>
   <xsl:text>.hy 0&#10;</xsl:text>
@@ -179,7 +157,7 @@
 </xsl:template>
 
 <xsl:template match="funcdef">
-  <xsl:apply-templates select="." mode="convert.spaces.to.nobreak.spaces"/>
+  <xsl:apply-templates select="." mode="prevent.line.breaking"/>
 </xsl:template>
 
 <xsl:template match="funcdef/function">
@@ -195,7 +173,7 @@
 </xsl:template>
 
 <xsl:template match="paramdef">
-  <xsl:apply-templates select="." mode="convert.spaces.to.nobreak.spaces"/>
+  <xsl:apply-templates select="." mode="prevent.line.breaking"/>
   <xsl:choose>
     <xsl:when test="following-sibling::*">
       <xsl:text>, </xsl:text>
-- 
2.40.0