]> granicus.if.org Git - docbook-dsssl/commitdiff
Adjusted manpages stylesheet to use U+2593 as the internal
authorMichael Smith <xmldoc@users.sourceforge.net>
Thu, 18 Jan 2007 15:44:19 +0000 (15:44 +0000)
committerMichael Smith <xmldoc@users.sourceforge.net>
Thu, 18 Jan 2007 15:44:19 +0000 (15:44 +0000)
representation for the backslash character within the stylesheet.
This prevents backslashes in source content from getting eaten.
Closes #1609425. Thanks to Paul DuBois for reporting the bug.

xsl/manpages/info.xsl
xsl/manpages/links.xsl
xsl/manpages/lists.xsl
xsl/manpages/other.xsl
xsl/manpages/refentry.xsl
xsl/manpages/table.xsl
xsl/manpages/utility.xsl
xsl/params/man.string.subst.map.xml

index a6e7840149961099bff390713c2ed47c5eef40a3..66cd06cdd5ab8152fd6a5b709e1b3a47e30f7381 100644 (file)
@@ -25,7 +25,7 @@
         <!-- * preserving the original default indent value -->
         <!-- * when $man.indent.refsect is non-zero; -->
         <!-- * "u" is a roff unit specifier -->
-        <xsl:text>\n(zqu</xsl:text>
+        <xsl:text>&#x2593;n(zqu</xsl:text>
       </xsl:when>
       <xsl:otherwise/> <!-- * otherwise, just leave it empty -->
     </xsl:choose>
     <!-- * angle bracket and before the closing angle bracket is to -->
     <!-- * prevent groff from inserting a linebreak at those points and -->
     <!-- * outputting a hyphen character where the break occurs -->
-    <xsl:text>&lt;\&amp;</xsl:text>
+    <xsl:text>&lt;&#x2593;&amp;</xsl:text>
     <xsl:choose>
       <xsl:when test="self::email">
         <xsl:variable name="contents">
         <xsl:value-of select="normalize-space($contents)"/>
       </xsl:when>
     </xsl:choose>
-    <xsl:text>\&amp;&gt;</xsl:text>
+    <xsl:text>&#x2593;&amp;&gt;</xsl:text>
     <xsl:choose>
       <xsl:when test="not(following-sibling::*[descendant-or-self::email]
                       or following-sibling::address/otheraddr/ulink
index ccbefc1146a09fa9d511999e8ed2d533547875e9..a332539e1bdb255ab0aed394959c1968e8052e4a 100644 (file)
         <xsl:if test="$man.hyphenate.urls = 0 and
                       $man.break.after.slash = 0">
           <xsl:call-template name="suppress.hyphenation"/>
-          <xsl:text>\%</xsl:text>
+          <xsl:text>&#x2593;%</xsl:text>
         </xsl:if>
         <xsl:value-of select="$earmark"/>
       </xsl:otherwise>
     <!-- * This formatting should probably be made user-configurable, -->
     <!-- * to allow something other than just square brackets; e.g., -->
     <!-- * Angle brackets<10> or Braces{10}  -->
-    <xsl:text>\&amp;[</xsl:text>
+    <xsl:text>&#x2593;&amp;[</xsl:text>
     <xsl:value-of select="$notesource.number"/>
     <xsl:text>]</xsl:text>
     <!-- * Note that the reason for the \& before the opening bracket -->
       <xsl:if test="$man.hyphenate.urls = 0
                     and $man.break.after.slash = 0">
         <xsl:call-template name="suppress.hyphenation"/>
-        <xsl:text>\%</xsl:text>
+        <xsl:text>&#x2593;%</xsl:text>
       </xsl:if>
       <xsl:value-of select="@url"/>
       <xsl:text>&#10;</xsl:text>
index dbdb3beea0eb489163a2459f1a5ffd2f99204b65..8f5094c6b94a50be927c945846961349fabfaba7 100644 (file)
@@ -22,7 +22,7 @@
       <!-- * preserving the original default indent value -->
       <!-- * when $man.indent.refsect is non-zero; -->
       <!-- * "u" is a roff unit specifier -->
-      <xsl:text>\n(zqu</xsl:text>
+      <xsl:text>&#x2593;n(zqu</xsl:text>
     </xsl:when>
     <xsl:otherwise/> <!-- * otherwise, just leave it empty -->
   </xsl:choose>
     <xsl:value-of select="$list-indent"/>
   </xsl:if>
   <xsl:text>&#10;</xsl:text>
-  <xsl:text>\h'&#x2591;</xsl:text>
+  <xsl:text>&#x2593;h'&#x2591;</xsl:text>
     <xsl:if test="not($list-indent = '')">
     <xsl:text>0</xsl:text>
     <xsl:value-of select="$list-indent"/>
   </xsl:if>
   <xsl:text>'</xsl:text>
   <xsl:text>&#x2022;</xsl:text>
-  <xsl:text>\h'+</xsl:text>
+  <xsl:text>&#x2593;h'+</xsl:text>
     <xsl:if test="not($list-indent = '')">
     <xsl:text>0</xsl:text>
     <xsl:value-of select="$list-indent - 1"/>
     <xsl:value-of select="$list-indent"/>
   </xsl:if>
   <xsl:text>&#10;</xsl:text>
-  <xsl:text>\h'&#x2591;</xsl:text>
+  <xsl:text>&#x2593;h'&#x2591;</xsl:text>
     <xsl:if test="not($list-indent = '')">
     <xsl:text>0</xsl:text>
     <xsl:value-of select="$list-indent"/>
     <xsl:text> </xsl:text>
   </xsl:if>
   <xsl:number format="1."/>
-  <xsl:text>\h'+</xsl:text>
+  <xsl:text>&#x2593;h'+</xsl:text>
     <xsl:if test="not($list-indent = '')">
     <xsl:text>0</xsl:text>
     <xsl:value-of select="$list-indent - 2"/>
     <xsl:apply-templates mode="bold" select="title"/>
     <xsl:text>&#10;</xsl:text>
   </xsl:if>
-  <xsl:text>&#x2302;\" line length increase to cope w/ tbl weirdness&#10;</xsl:text>
-  <xsl:text>&#x2302;ll +(\n(LLu * 62u / 100u)&#10;</xsl:text>
+  <xsl:text>&#x2302;&#x2593;" line length increase to cope w/ tbl weirdness&#10;</xsl:text>
+  <xsl:text>&#x2302;ll +(&#x2593;n(LLu * 62u / 100u)&#10;</xsl:text>
   <!-- * .TS = "Table Start" -->
   <xsl:text>&#x2302;TS&#10;</xsl:text>
     <!-- * first output the table "format" spec, which tells tbl(1) how -->
   <xsl:apply-templates/>
   <!-- * .TE = "Table End" -->
   <xsl:text>&#x2302;TE&#10;</xsl:text>
-  <xsl:text>&#x2302;\" line length decrease back to previous value&#10;</xsl:text>
-  <xsl:text>&#x2302;ll &#x2591;(\n(LLu * 62u / 100u)&#10;</xsl:text>
+  <xsl:text>&#x2302;&#x2593;" line length decrease back to previous value&#10;</xsl:text>
+  <xsl:text>&#x2302;ll &#x2591;(&#x2593;n(LLu * 62u / 100u)&#10;</xsl:text>
   <!-- * put a blank line of space below the table -->
   <xsl:text>&#x2302;sp&#10;</xsl:text>
 </xsl:template>
index 532758b396cc5d505d5e08bedfebd314b9e5dd5e..27434ba7f40d4fe9b504780bfa17643d944803de 100644 (file)
@@ -169,12 +169,12 @@ db:manvolnum
     <xsl:param name="title"/>
     <xsl:param name="manual"/>
     <xsl:param name="source"/>
-    <xsl:text>&#x2302;\"     Title: </xsl:text>
+    <xsl:text>&#x2302;&#x2593;"     Title: </xsl:text>
     <xsl:call-template name="replace.dots.and.dashes">
       <xsl:with-param name="content" select="$title"/>
     </xsl:call-template>
     <xsl:text>&#10;</xsl:text>
-    <xsl:text>&#x2302;\"    Author: </xsl:text>
+    <xsl:text>&#x2302;&#x2593;"    Author: </xsl:text>
     <xsl:call-template name="replace.dots.and.dashes">
       <xsl:with-param name="content">
         <xsl:call-template name="make.roff.metadata.author">
@@ -183,28 +183,28 @@ db:manvolnum
       </xsl:with-param>
     </xsl:call-template>
     <xsl:text>&#10;</xsl:text>
-    <xsl:text>&#x2302;\" Generator: DocBook XSL Stylesheets v</xsl:text>
+    <xsl:text>&#x2302;&#x2593;" Generator: DocBook XSL Stylesheets v</xsl:text>
     <xsl:call-template name="replace.dots.and.dashes">
       <xsl:with-param name="content" select="$VERSION"/>
     </xsl:call-template>
     <xsl:text> &lt;http://docbook&#x2302;sf&#x2302;net/></xsl:text>
     <xsl:text>&#10;</xsl:text>
-    <xsl:text>&#x2302;\"      Date: </xsl:text>
+    <xsl:text>&#x2302;&#x2593;"      Date: </xsl:text>
     <xsl:call-template name="replace.dots.and.dashes">
       <xsl:with-param name="content" select="$date"/>
     </xsl:call-template>
     <xsl:text>&#10;</xsl:text>
-    <xsl:text>&#x2302;\"    Manual: </xsl:text>
+    <xsl:text>&#x2302;&#x2593;"    Manual: </xsl:text>
     <xsl:call-template name="replace.dots.and.dashes">
       <xsl:with-param name="content" select="$manual"/>
     </xsl:call-template>
     <xsl:text>&#10;</xsl:text>
-    <xsl:text>&#x2302;\"    Source: </xsl:text>
+    <xsl:text>&#x2302;&#x2593;"    Source: </xsl:text>
     <xsl:call-template name="replace.dots.and.dashes">
       <xsl:with-param name="content" select="$source"/>
     </xsl:call-template>
     <xsl:text>&#10;</xsl:text>
-    <xsl:text>&#x2302;\"</xsl:text>
+    <xsl:text>&#x2302;&#x2593;"</xsl:text>
     <xsl:text>&#10;</xsl:text>
   </xsl:template>
 
@@ -315,31 +315,31 @@ db:manvolnum
     <!-- * If the value of man.hypenate is zero (the default), then -->
     <!-- * disable hyphenation (".nh" = "no hyphenation") -->
     <xsl:if test="$man.hyphenate = 0">
-      <xsl:text>&#x2302;\" disable hyphenation&#10;</xsl:text>
+      <xsl:text>&#x2302;&#x2593;" disable hyphenation&#10;</xsl:text>
       <xsl:text>&#x2302;nh&#10;</xsl:text>
     </xsl:if>
     <!-- * If the value of man.justify is zero (the default), then -->
     <!-- * disable justification (".ad l" means "adjust to left only") -->
     <xsl:if test="$man.justify = 0">
-      <xsl:text>&#x2302;\" disable justification</xsl:text>
+      <xsl:text>&#x2302;&#x2593;" disable justification</xsl:text>
       <xsl:text> (adjust text to left margin only)&#10;</xsl:text>
       <xsl:text>&#x2302;ad l&#10;</xsl:text>
     </xsl:if>
     <xsl:if test="not($man.indent.refsect = 0)">
-      <xsl:text>&#x2302;\" store initial "default indentation value"&#10;</xsl:text>
-      <xsl:text>&#x2302;nr zq \n(IN&#10;</xsl:text>
-      <xsl:text>&#x2302;\" adjust default indentation&#10;</xsl:text>
+      <xsl:text>&#x2302;&#x2593;" store initial "default indentation value"&#10;</xsl:text>
+      <xsl:text>&#x2302;nr zq &#x2593;n(IN&#10;</xsl:text>
+      <xsl:text>&#x2302;&#x2593;" adjust default indentation&#10;</xsl:text>
       <xsl:text>&#x2302;nr IN </xsl:text>
       <xsl:value-of select="$man.indent.width"/>
       <xsl:text>&#10;</xsl:text>
-      <xsl:text>&#x2302;\" adjust indentation of SS headings&#10;</xsl:text>
-      <xsl:text>&#x2302;nr SN \n(IN&#10;</xsl:text>
+      <xsl:text>&#x2302;&#x2593;" adjust indentation of SS headings&#10;</xsl:text>
+      <xsl:text>&#x2302;nr SN &#x2593;n(IN&#10;</xsl:text>
     </xsl:if>
     <!-- * Unless the value of man.break.after.slash is zero (the -->
     <!-- * default), tell groff that it is OK to break a line -->
     <!-- * after a slash when needed. -->
     <xsl:if test="$man.break.after.slash != 0">
-      <xsl:text>&#x2302;\" enable line breaks after slashes&#10;</xsl:text>
+      <xsl:text>&#x2302;&#x2593;" enable line breaks after slashes&#10;</xsl:text>
       <xsl:text>&#x2302;cflags 4 /&#10;</xsl:text>
     </xsl:if>
   </xsl:template>
index a1a25373a1441c85f4c9485df94b671490c6f12b..b5463684dc997ed79c71f31074f506e447c4ca1b 100644 (file)
         <!-- * actually means the title is indented by the value of -->
         <!-- * the SN register, which appears by default to be -->
         <!-- * about half of the default indentation value -->
-        <xsl:text>&#x2302;ti (\n(SNu * 5u / 3u)&#10;</xsl:text>
+        <xsl:text>&#x2302;ti (&#x2593;n(SNu * 5u / 3u)&#10;</xsl:text>
         <xsl:call-template name="nested-section-title"/>
         <xsl:apply-templates/>
       </xsl:otherwise>
       <xsl:if test="not($man.indent.refsect = 0)">
         <!-- * If default-indentation adjustment is on, then indent the -->
         <!-- * child content of this Refsect3 or Refsection. -->
-        <xsl:text>(\n(SNu)&#10;</xsl:text>
+        <xsl:text>(&#x2593;n(SNu)&#10;</xsl:text>
       </xsl:if>
     </xsl:variable>
     <xsl:call-template name="nested-section-title"/>
-    <xsl:text>&#x2302;RS (\n(SNu)&#10;</xsl:text>
+    <xsl:text>&#x2302;RS (&#x2593;n(SNu)&#10;</xsl:text>
     <xsl:apply-templates/>
     <xsl:text>&#x2302;RE&#10;</xsl:text>
   </xsl:template>
index 24873d76f5929efa510b98e8672358244992a039..a49fda14756519c3b6c3ca0c91ef5158ad2bd94d 100644 (file)
               >tbl convert : Extracted a nested table</xsl:text>
             </xsl:with-param>
           </xsl:call-template>
-          <xsl:text>[\fInested&#160;table\fR]*&#10;</xsl:text>
+          <xsl:text>[&#x2593;fInested&#160;table&#x2593;fR]*&#10;</xsl:text>
         </xsl:when>
         <xsl:otherwise>
           <!-- * Apply templates to the child contents of this cell, to -->
index ba953e0ae56ddea3b9db596383bdede614694ca0..8c83baaae0d8144c7e37b8fd0355d52b1e5fce3e 100644 (file)
 
   <xsl:template mode="bold" match="*">
     <xsl:for-each select="node()">
-      <xsl:text>\fB</xsl:text>
+      <xsl:text>&#x2593;fB</xsl:text>
       <xsl:apply-templates select="."/>
-      <xsl:text>\fR</xsl:text>
+      <xsl:text>&#x2593;fR</xsl:text>
     </xsl:for-each>
   </xsl:template>
 
   <xsl:template mode="italic" match="*">
     <xsl:for-each select="node()">
-      <xsl:text>\fI</xsl:text>
+      <xsl:text>&#x2593;fI</xsl:text>
       <xsl:apply-templates select="."/>
-      <xsl:text>\fR</xsl:text>
+      <xsl:text>&#x2593;fR</xsl:text>
     </xsl:for-each>
   </xsl:template>
 
@@ -95,7 +95,7 @@
     <xsl:if test="$man.hyphenate != 0 and
                   not(ancestor::cmdsynopsis) and
                   not(ancestor::funcsynopsis)">
-      <xsl:text>\%</xsl:text>
+      <xsl:text>&#x2593;%</xsl:text>
     </xsl:if>
   </xsl:template>
 
   <!-- * in roff source (just to make things easier to read). -->
   <xsl:template name="mark.subheading">
     <xsl:if test="$man.subheading.divider.enabled != 0">
-      <xsl:text>&#x2302;\" </xsl:text>
+      <xsl:text>&#x2302;&#x2593;" </xsl:text>
       <xsl:value-of select="$man.subheading.divider"/>
       <xsl:text>&#10;</xsl:text>
     </xsl:if>
index 13cfcbf3ab97890f5b5c430bece5c8b6538f20d4..e133ba1cee41150c14933d345ec348ba8259c7dc 100644 (file)
 <refsynopsisdiv>
 <src:fragment id='man.string.subst.map.frag'>
 <xsl:param name="man.string.subst.map">
+
+  <!-- ******************************************************************** -->
+  <!-- *  -->
+  <!-- * The backslash and dot (\, .) characters have special meaning -->
+  <!-- * for roff, so we escape those characters when they appear in -->
+  <!-- * the source content, and we use certain (arbitrarily -->
+  <!-- * selected) Unicode characters as the internal representations -->
+  <!-- * for those characters, then replace them with real -->
+  <!-- * backslashes and dots in output. In addition, for certain -->
+  <!-- * reasons, we do the same thing for dashes. The mappings of -->
+  <!-- * those characters to the Unicode characters we use to -->
+  <!-- * represent them is hard-coded: -->
+  <!-- *  -->
+  <!-- *   - U+2591 = dash -->
+  <!-- *   - U+2593 = backslash -->
+  <!-- *   - U+2302 = dot -->
+  <!-- *  -->
+  <!-- ******************************************************************** -->
+
+  <!-- * escape dashes in content -->
+  <substitution oldstring="-" newstring="\-"/>
+  <!-- * replace U+2591 marker with dash -->
+  <substitution oldstring="&#x2591;" newstring="-"/>
+  <!-- * escape backslashes in content -->
   <substitution oldstring="\" newstring="\\"/>
-  <!-- * escape all dots at the beginnings of lines (because roff -->
-  <!-- * interprets them as the start of roff requests) -->
+  <!-- * fix bad font-request capitalization in .SH (stylesheet artifact) -->
+  <substitution oldstring="&#x2593;FB" newstring="\fB"/>
+  <substitution oldstring="&#x2593;FI" newstring="\fI"/>
+  <substitution oldstring="&#x2593;FR" newstring="\fR"/>
+  <!-- * replace U+2593 marker with backslash --> 
+  <substitution oldstring="&#x2593;" newstring="\"/>
+  <!-- * escape dashes in content (only at line beginnings) -->
   <substitution oldstring="&#10;." newstring="&#10;\&amp;."/>
-  <!-- * the stylesheets use U+2302 internally to represent the start of a -->
-  <!-- * roff request; for output, we need to convert that internal -->
-  <!-- * representation to the character that roff actually uses to mark -->
-  <!-- * the start of requests, which is a dot -->
+  <!-- * replace U+2302 marker with dot -->
   <substitution oldstring="&#x2302;" newstring="."/>
-  <!-- * now, we need to restore single-backslashes in all roff -->
-  <!-- * requests (because slash substitution above doubled them) -->
-  <substitution oldstring="\\fB" newstring="\fB"/>
-  <substitution oldstring="\\fI" newstring="\fI"/>
-  <substitution oldstring="\\fR" newstring="\fR"/>
-  <substitution oldstring="\\n"  newstring="\n"/>
-  <substitution oldstring="\\h"  newstring="\h"/>
-  <!-- * requests in .SH sectsions output from Refsect1-level source -->
-  <!-- * end up getting capitalized; the following changes fix that -->
-  <substitution oldstring="\\FB" newstring="\fB"/>
-  <substitution oldstring="\\FI" newstring="\fI"/>
-  <substitution oldstring="\\FR" newstring="\fR"/>
-  <substitution oldstring='\\%' newstring='\%'/>
-  <substitution oldstring='\\&amp;' newstring='\&amp;'/>
-  <substitution oldstring='.\\"' newstring='.\"'/>
-  <!-- * although the groff docs do not make it clear, it appears that -->
-  <!-- * the only way to get a non-breaking hyphen in roff is to put a -->
-  <!-- * backslash in front of it; and, unfortunately, groff is not smart -->
-  <!-- * about where it breaks things (for example, it'll break an -->
-  <!-- * argument for a command across a line, if that argument contains -->
-  <!-- * a dash/hyphen); so, we must globally change all hyphens to "\-" -->
-  <substitution oldstring="-" newstring="\-"/>
-  <!-- * restore dashes in all roff requests and comments -->
-  <substitution oldstring="&#x2591;" newstring="-"/>
+
+  <!-- ==================================================================== -->
+
   <!-- * squeeze multiple newlines before a roff request  -->
   <substitution oldstring="&#10;&#10;." newstring="&#10;."/>
   <!-- * remove any .sp occurences that directly follow a .PP  -->
@@ -147,10 +152,6 @@ particular customization of the DocBook XSL stylesheets.</para>
   causes target strings to be replaced in roff requests and escapes,
   not just in the visible contents.</para>
 
-  <para>In particular, do not attempt to add a mapping for the
-  dot/period character. Doing so will break your output. For an
-  explanation, see <xref linkend="Dots"/>.</para>
-
 </warning>
 
 <refsect2 id="map">
@@ -178,20 +179,44 @@ particular customization of the DocBook XSL stylesheets.</para>
   </para>
 </refsect2>
 
-<refsect2 id="Dots">
-  <title>About adding backslashes before dots</title>
-  <para>The stylesheets do not add backslashes before
-  periods/dots. One reason is that, because string substitution is
-  performed over the entire roff source of each man page, it would be
-  complicated to replace dots in visible contents without also causing
-  them to be replaced in roff requests and escapes; for example,
-  without causing, say, the <literal>.TH</literal> roff macro to be
-  replaced with <literal>\.TH</literal>. Additionally, 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 to add a
-  zero-width space in front of the offending dot(s) in your
-  source.</para>
+<refsect2 id="escape-replace">
+  <title>About escaping and replacing backslash, dot, and dash</title>
+  <para>The backslash and dot (\, .) characters have special meaning
+  for roff, so we:
+
+  <itemizedlist>
+    <listitem>
+      <para>escape backslashes and dots where they appear in the
+      source content</para>
+    </listitem>
+    <listitem>
+      <para>use certain (arbitrarily selected) Unicode characters as
+      “markers” – internal representations within the stylesheet – for
+      backslashes and dots</para>
+    </listitem>
+    <listitem>
+      <para>replace the Unicode characters with real backslashes and
+      dotes before output gets serialized</para>
+    </listitem>
+  </itemizedlist>
+  
+   In addition, for certain reasons, we do the same thing for
+   dashes.</para>
+
+  <para>The mappings of dash, backslash, and dot to the Unicode
+  characters we use to represent them is hard-coded in the stylesheet:
+
+  <itemizedlist>
+    <listitem><para><literal>U+2591</literal> = dash</para></listitem>
+    <listitem><para><literal>U+2593</literal> = backslash</para></listitem>
+    <listitem><para><literal>U+2302</literal> = dot</para></listitem>
+  </itemizedlist>
+
+  Those Unicode characters were chosen on the assumption that they are
+  never used in content intended for output to man pages. It would be
+  possible to provide a way for configuring the mappings (using XSLT
+  parameters), but doing so would make the stylesheet code much more
+  verbose and harder to read.</para>
 </refsect2>
 
 </refsect1>