Implemented "character map" system for replacing Unicode

characters. (closes #1226009).

::PROBLEM:
The existing manpages mechanism for replacing Unicode symbols and
special characters with roff equivalents is not scalable and not
anywhere near as complete as it should be.

For example, the mechanism currently only handles a (somewhat
arbitrary) selection of less than 20 or so Unicode characters.

But there are potentially more than _800_ Unicode special
characters that have some groff equivalent they can be mapped to.

And there are about 34 symbols in the Latin-1 (ISO-8859-1) block
alone. Users might reasonably expect that if they include any of
those Latin-1 characters in their DocBook source documents, they
will get correctly convered to known roff equivalents in output.

In addition to those common symbols, certain users may have a need
to use symbols from other Unicode blocks.

Say, somebody who is documenting an application related to math
might need to use a bunch of symbols from the "Mathematical
Operators" Unicode block (there are about 65 characters in that
block that have reasonable roff equivalents).

Or somebody else might really like Dingbats -- such as the
checkmark character (I like that one myself) and so might use a
bunch of things from the "Dingbat" block (141 characters in that
that have roff equivalents or that can at least be "degraded"
somewhat gracefully into roff).

So we need a mechanism that is capable of handling all those 800
Unicode characters that have roff equivalents -- and/or of
allowing users to choose which Unicode blocks to use (through
tuning the value of a parameter or something).

::FIX:
Replaced the current Unicode character-substitution mechanism
(replace-entities template) with a completely different
character-substitution mechanism that is based on use of a
"character map" (in a format compliant with the XSLT 2.0 spec and
therefore completely "forward compatible" with XSLT 2.0).

By default, the new "character map" mechanism 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 is controlled through the following parameters:

  - man.charmap.enabled:
      turns character-map support on/off

  - man.charmap.use.subset.xml
      specifies that a subset of the character map is used instead
      of the full character map

  - man.charmap.subset.profile.xml
      specifies profile of character-map subset

  - man.charmap.uri.xml
      specifies an alternate character map to use instead of the
      "standard" character map provided in the distribution

For more details, see the current documention at:

  http://docbook.sf.net/snapshot/xsl/doc/manpages/charmap.html

diff --git a/xsl/manpages/docbook.xsl b/xsl/manpages/docbook.xsl
index 6ab09f354f22ca027e1ab8eb5db1a302b4b4d1ee..9505e3347f272248332ac696cf6d644775f01686 100644 (file)
--- a/xsl/manpages/docbook.xsl
+++ b/xsl/manpages/docbook.xsl
@@ -33,25 +33,27 @@
   <xsl:include href="lists.xsl"/>
 
   <!-- * Read the character-map contents in only once per document, no -->
-  <!-- * matter how many Refentry elements it contains. For documentst -->
+  <!-- * matter how many Refentry elements it contains. For documents -->
   <!-- * 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:if test="$man.charmap.enabled != '0'">
+      <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:if>
   </xsl:variable>
 
   <!-- * if document does not contain at least one refentry, then emit a -->
@@ -147,9 +149,7 @@
     <xsl:variable name="manpage.contents.prepared">
       <!-- * "Preparing" the page contents involves, at a minimum, -->
       <!-- * 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. -->
+      <!-- * as roff escapes). -->
       <!-- * -->
       <!-- * If $charmap.enabled is true, "preparing" the page contents also -->
       <!-- * involves applying a character map to convert Unicode symbols and -->

diff --git a/xsl/manpages/general.xsl b/xsl/manpages/general.xsl
index 9396e33e2a3f2fa43921dbf7d30d4553d0ea4f6d..7f50a267ceb411b8e65bfe03295c348af71d7788 100644 (file)
--- a/xsl/manpages/general.xsl
+++ b/xsl/manpages/general.xsl
@@ -15,8 +15,8 @@
 
 <!-- ==================================================================== -->
 
-<!-- This file contains named and "non element" templates that are called -->
-<!-- by templates in the other manpages stylesheet files. -->
+<!-- * This file contains named and "non element" templates that are -->
+<!-- * called by templates in the other manpages stylesheet files. -->
 
 <!-- ==================================================================== -->
 
@@ -193,42 +193,41 @@
 
   <!-- ================================================================== -->
 
+  <!-- * 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). -->
   <xsl:template name="prepare.manpage.contents">
     <xsl:param name="content" select="''"/>
-    <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>
 
-  <!-- * 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. -->
+    <!-- * 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 -->
+    <xsl:variable name="adjusted.content">
+      <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)/*"/>
+      </xsl:call-template>
+    </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="map.contents"
+                          select="exsl:node-set($man.charmap.contents)/*"/>
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:otherwise>
+        <!-- * if we reach here, value of $man.charmap.enabled is zero, -->
+        <!-- * so we just pass the adjusted contents through "as is" -->
+        <xsl:value-of select="$adjusted.content"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
 
 </xsl:stylesheet>

diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent
index 44596f98f0f03795bb2ec3c631214f8fc74ee4cc..e118313e986c4326bcca9a5a906d6046158a4db7 100644 (file)
--- a/xsl/manpages/param.ent
+++ b/xsl/manpages/param.ent
@@ -2,6 +2,8 @@
 <!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.string.subst.map SYSTEM "../params/man.string.subst.map.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.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