Replace hyphens with "\-".

<sigh/> Although the old-school gnomes who maintain groff
apparently don't figure it's necessary to document this anywhere,
there is apparently only one reliable way to make a non-breaking
hyphen in groff: with "\-". At least that it what testing in my
environment seems to indicate.

And because groff is not at all smart in the way it breaks things
at hyphens (it will, for example, break command arguments across
lines if they contain hyphens), we must globally replace all
hyphens with "\-".

God in heaven, please let me live to see a day when roff and all
is (r)offspring have disappeared from the face of the earth.

diff --git a/xsl/params/man.string.subst.map.xml b/xsl/params/man.string.subst.map.xml
index a035576b283bd2894b95186e9d654f210a5d2f91..d73dfa0704fb365157b250f42819d4b6e56ad303 100644 (file)
--- a/xsl/params/man.string.subst.map.xml
+++ b/xsl/params/man.string.subst.map.xml
@@ -12,11 +12,28 @@
 <src:fragment id='man.string.subst.map.frag'>
 <xsl:param name="man.string.subst.map">
   <substitution oldstring="\" newstring="\\"/>
+  <!-- * now, we need to restore single-backslashes in all roff -->
+  <!-- * requests (because the substitution above doubled them) -->
   <substitution oldstring="\\fB" newstring="\fB"/>
   <substitution oldstring="\\fI" newstring="\fI"/>
   <substitution oldstring="\\fR" newstring="\fR"/>
   <substitution oldstring='.\\"' newstring='.\"'/>
-  <!-- add backslash before any apostrophe at start of a line -->
+  <!-- * 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="\-"/>
+  <!-- * now, we need to restore single-hypens in all roff requests -->
+  <!-- * (because the substitution above added backslashes before them) -->
+  <substitution oldstring=".it 1 an\-trap" newstring=".it 1 an-trap"/>
+  <substitution oldstring=".nr an\-no\-space\-flag 1" newstring=".nr an-no-space-flag 1"/>
+  <substitution oldstring=".nr an\-break\-flag 1" newstring=".nr an-break-flag 1"/>
+  <!-- * an apostrophe at the beginning of a line gets interpreted as a -->
+  <!-- * roff request (groff(7) says it is "the non-breaking control -->
+  <!-- * character"); so we must add backslash before any apostrophe -->
+  <!-- * found at the start of a line -->
   <substitution oldstring="&#10;'" newstring="&#10;\'"/>
 </xsl:param>
 </src:fragment>
@@ -42,10 +59,9 @@ before applying the roff character map.</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 mappings for the
-  dot/period character or hyphen/minus character
-  (&amp;#45;/&amp;#x2D;). Doing so will break your output. For an
-  explanation, see <xref linkend="DotsAndHyphens"/>.</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>
 
@@ -68,46 +84,20 @@ each of which has two attributes:
 </variablelist>
 </para>
 
-<refsect2 id="DotsAndHyphens">
-  <title>About adding backslashes before dots and hyphens</title>
-  <para>The stylesheets do not add backslashes before periods/dots or
-  hyphens (&amp;#45;). 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 and hyphens 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:
-
-  <itemizedlist>
-
-    <listitem>
-      <para>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>
-    </listitem>
-    <listitem>
-      <para>Backslashes in front of &amp;#45;/&amp;#x2D; are
-      needed... when?  Myself, I don't know, so the current
-      stylesheets do 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.</para>
-      <para>And, anyway, my understanding from reading the groff docs
-      is that <literal>\-</literal> is, specifically, a
-      <emphasis>minus sign</emphasis>. So if you have places where you
-      want a minus sign to be output instead of &amp;#45;, then use
-      &amp;#8722;/&amp;#x2212; in your source instead. And if you have
-      places where you want an en dash, &amp;#8211;/&amp;#x2013;. Or
-      if there are places where the stylesheets are internally
-      generating &amp;#45; where they should be generating &amp;#8722;
-      or &amp;#8211;, then we need to fix those, not just do blanket
-      conversion.</para>
-    </listitem>
-  </itemizedlist>
-</para>
+<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>
 
 </refsect1>