Prevent hyphenation of computer inlines, filenames, and URLs.

(Closes #1124391; thanks to Ryan Hofschneider for reporting).

By default, even when hyphenation is enabled (globally),
hyphenation is now suppressed for "computer inlines" (currently,
just classname, constant, envar, errorcode, option, replaceable,
userinput, type, varname -- but probably need to add more) and for
filenames, and for URLs from Ulink.

It can be (re)enabled using the man.hyphenate.computer.inlines,
man.hyphenate.filenames, and man.hyphenate.urls params.

diff --git a/xsl/manpages/inline.xsl b/xsl/manpages/inline.xsl
index 7734e2d497016620b6c1ea431a5cd2506f2ed9cc..1cb577fb25b88aee0b2fd8cde74c8f3ce45b6cb8 100644 (file)
--- a/xsl/manpages/inline.xsl
+++ b/xsl/manpages/inline.xsl
@@ -13,10 +13,6 @@
 
      ******************************************************************** -->
 
-<xsl:param name="man.hyphenate.computer.inlines">0</xsl:param>
-<xsl:param name="man.hyphenate.filenames">0</xsl:param>
-<xsl:param name="man.hyphenate.urls">0</xsl:param>
-
 <!-- ==================================================================== -->
 
 <xsl:template match="replaceable|varname">

diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent
index 10202a6591e0bb0d7d8b1e3785eec827f51a9faf..d201fc2253083f9d1b5ec09e346aaf2e64c7d2cb 100644 (file)
--- a/xsl/manpages/param.ent
+++ b/xsl/manpages/param.ent
@@ -1,8 +1,9 @@
-<!ENTITY man.break.after.slash SYSTEM "../params/man.break.after.slash.xml">
 <!ENTITY man.hyphenate SYSTEM "../params/man.hyphenate.xml">
+<!ENTITY man.hyphenate.urls SYSTEM "../params/man.hyphenate.urls.xml">
+<!ENTITY man.hyphenate.filenames SYSTEM "../params/man.hyphenate.filenames.xml">
+<!ENTITY man.hyphenate.computer.inlines SYSTEM "../params/man.hyphenate.computer.inlines.xml">
 <!ENTITY man.justify SYSTEM "../params/man.justify.xml">
-<!ENTITY man.output.quietly SYSTEM "../params/man.output.quietly.xml">
-<!ENTITY man.output.encoding SYSTEM "../params/man.output.encoding.xml">
+<!ENTITY man.break.after.slash SYSTEM "../params/man.break.after.slash.xml">
 <!ENTITY man.links.are.numbered SYSTEM "../params/man.links.are.numbered.xml">
 <!ENTITY man.links.are.underlined SYSTEM "../params/man.links.are.underlined.xml">
 <!ENTITY man.links.list.enabled SYSTEM "../params/man.links.list.enabled.xml">
@@ -12,8 +13,6 @@
 <!ENTITY man.charmap.use.subset SYSTEM "../params/man.charmap.use.subset.xml">
 <!ENTITY man.charmap.uri SYSTEM "../params/man.charmap.uri.xml">
 <!ENTITY man.charmap.subset.profile SYSTEM "../params/man.charmap.subset.profile.xml">
-<!ENTITY man.subheading.divider SYSTEM "../params/man.subheading.divider.xml">
-<!ENTITY man.subheading.divider.enabled SYSTEM "../params/man.subheading.divider.enabled.xml">
 <!ENTITY refentry.date.profile.enabled SYSTEM "../params/refentry.date.profile.enabled.xml">
 <!ENTITY refentry.manual.profile.enabled SYSTEM "../params/refentry.manual.profile.enabled.xml">
 <!ENTITY refentry.source.name.profile.enabled SYSTEM "../params/refentry.source.name.profile.enabled.xml">
@@ -32,3 +31,7 @@
 <!ENTITY man.th.extra1.suppress SYSTEM "../params/man.th.extra1.suppress.xml">
 <!ENTITY man.th.extra2.suppress SYSTEM "../params/man.th.extra2.suppress.xml">
 <!ENTITY man.th.extra3.suppress SYSTEM "../params/man.th.extra3.suppress.xml">
+<!ENTITY man.output.quietly SYSTEM "../params/man.output.quietly.xml">
+<!ENTITY man.output.encoding SYSTEM "../params/man.output.encoding.xml">
+<!ENTITY man.subheading.divider SYSTEM "../params/man.subheading.divider.xml">
+<!ENTITY man.subheading.divider.enabled SYSTEM "../params/man.subheading.divider.enabled.xml">

diff --git a/xsl/manpages/param.xweb b/xsl/manpages/param.xweb
index cd838af1aa3a513585cd395cc1e2c774e3f0fa34..bfe83a4669c40bd0a1e66776e3b6a965814feaf5 100644 (file)
--- a/xsl/manpages/param.xweb
+++ b/xsl/manpages/param.xweb
@@ -29,10 +29,13 @@
   </preface>
 
   <reference id="general">
-  <title>General formatting</title>
-&man.break.after.slash;
+  <title>Hyphenation, justification, and breaking</title>
 &man.hyphenate;
+&man.hyphenate.urls;
+&man.hyphenate.filenames;
+&man.hyphenate.computer.inlines;
 &man.justify;
+&man.break.after.slash;
   </reference>
   <reference id="links">
   <title>Link handling</title>
@@ -105,6 +108,9 @@
 
 <src:fragref linkend="man.break.after.slash.frag"/>
 <src:fragref linkend="man.hyphenate.frag"/>
+<src:fragref linkend="man.hyphenate.urls.frag"/>
+<src:fragref linkend="man.hyphenate.filenames.frag"/>
+<src:fragref linkend="man.hyphenate.computer.inlines.frag"/>
 <src:fragref linkend="man.justify.frag"/>
 <src:fragref linkend="man.output.quietly.frag"/>
 <src:fragref linkend="man.output.encoding.frag"/>

diff --git a/xsl/params/man.hyphenate.computer.inlines.xml b/xsl/params/man.hyphenate.computer.inlines.xml
new file mode 100644 (file)
index 0000000..0af99b9
--- /dev/null
+++ b/xsl/params/man.hyphenate.computer.inlines.xml
@@ -0,0 +1,48 @@
+<refentry id="man.hyphenate.computer.inlines">
+<refmeta>
+<refentrytitle>man.hyphenate.computer.inlines</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.hyphenate.computer.inlines</refname>
+<refpurpose>Hyphenate computer inlines?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.hyphenate.computer.inlines.frag'>
+<xsl:param name="man.hyphenate.computer.inlines">0</xsl:param></src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If zero (the default), hyphenation is suppressed for
+<quote>computer inlines</quote> such as environment variables,
+constants, etc. This parameter current affects output of the following
+elements:
+<simplelist type="inline">
+  <?dbchoice choice="and" ?>
+  <member><tag>classname</tag></member>
+  <member><tag>constant</tag></member>
+  <member><tag>envar</tag></member>
+  <member><tag>errorcode</tag></member>
+  <member><tag>option</tag></member>
+  <member><tag>replaceable</tag></member>
+  <member><tag>userinput</tag></member>
+  <member><tag>type</tag></member>
+  <member><tag>varname</tag></member>
+</simplelist>
+</para>
+
+<note>
+  <para>If hyphenation is already turned off globally (that is, if
+  <parameter>man.hyphenate</parameter> is zero, setting the
+  <parameter>man.hyphenate.computer.inlines</parameter> is not
+  necessary.</para>
+</note>
+
+<para>If <parameter>man.hyphenate.computer.inlines</parameter> is
+non-zero, computer inlines will not be treated specially and will be
+hyphenated like other words when needed.</para>
+
+</refsect1>
+</refentry>

diff --git a/xsl/params/man.hyphenate.filenames.xml b/xsl/params/man.hyphenate.filenames.xml
new file mode 100644 (file)
index 0000000..23fa1cd
--- /dev/null
+++ b/xsl/params/man.hyphenate.filenames.xml
@@ -0,0 +1,42 @@
+<refentry id="man.hyphenate.filenames">
+<refmeta>
+<refentrytitle>man.hyphenate.filenames</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.hyphenate.filenames</refname>
+<refpurpose>Hyphenate filenames?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.hyphenate.filenames.frag'>
+<xsl:param name="man.hyphenate.filenames">0</xsl:param></src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If zero (the default), hyphenation is suppressed for
+<tag>filename</tag> output.</para>
+
+<note>
+  <para>If hyphenation is already turned off globally (that is, if
+  <parameter>man.hyphenate</parameter> is zero, setting
+  <parameter>man.hyphenate.filenames</parameter> is not
+  necessary.</para>
+</note>
+
+<para>If <parameter>man.hyphenate.filenames</parameter> is non-zero,
+filenames will not be treated specially and are subject to hyphenation
+just like other words.</para>
+
+<note>
+  <para>If you are thinking about setting a non-zero value for
+  <parameter>man.hyphenate.filenames</parameter> in order to make long
+  filenames/pathnames break across lines, you'd probably be better off
+  experimenting with setting the
+  <parameter>man.break.after.slash</parameter> parameter first. That
+  will cause long pathnames to be broken after slashes.</para>
+</note>
+
+</refsect1>
+</refentry>

diff --git a/xsl/params/man.hyphenate.urls.xml b/xsl/params/man.hyphenate.urls.xml
new file mode 100644 (file)
index 0000000..525b9f2
--- /dev/null
+++ b/xsl/params/man.hyphenate.urls.xml
@@ -0,0 +1,41 @@
+<refentry id="man.hyphenate.urls">
+<refmeta>
+<refentrytitle>man.hyphenate.urls</refentrytitle>
+<refmiscinfo role="type">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.hyphenate.urls</refname>
+<refpurpose>Hyphenate URLs?</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<src:fragment id='man.hyphenate.urls.frag'>
+<xsl:param name="man.hyphenate.urls">0</xsl:param></src:fragment>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+
+<para>If zero (the default), hyphenation is suppressed for output of
+the <tag>ulink</tag> <tag class="attribute">url</tag> attribute.</para>
+
+<note>
+  <para>If hyphenation is already turned off globally (that is, if
+  <parameter>man.hyphenate</parameter> is zero, setting
+  <parameter>man.hyphenate.urls</parameter> is not necessary.</para>
+</note>
+
+<para>If <parameter>man.hyphenate.urls</parameter> is non-zero, URLs
+will not be treated specially and are subject to hyphenation just like
+other words.</para>
+
+<note>
+  <para>If you are thinking about setting a non-zero value for
+  <parameter>man.hyphenate.urls</parameter> in order to make long
+  URLs break across lines, you'd probably be better off
+  experimenting with setting the
+  <parameter>man.break.after.slash</parameter> parameter first. That
+  will cause long URLs to be broken after slashes.</para>
+</note>
+
+</refsect1>
+</refentry>

diff --git a/xsl/params/man.hyphenate.xml b/xsl/params/man.hyphenate.xml
index f028911ab1710128436cb5317dbb8020a00d0249..fe04b6bac6a3071fd8d9d9db35bb1d604ade4191 100644 (file)
--- a/xsl/params/man.hyphenate.xml
+++ b/xsl/params/man.hyphenate.xml
@@ -20,15 +20,25 @@
 <note>
 <para>The default value for this parameter is zero because groff is
 not particularly smart about how it does hyphenation; it can end up
-hyphenating a lot of things that you don't want hyphenated.</para>
-
-<para>That said, justified text can look very bad unless you also
-hyphenate it; to quote the "Hypenation" node from the groff info page:
+hyphenating a lot of things that you don't want hyphenated. To
+mitigate that, the default behavior of the stylesheets is to suppress
+hyphenation of computer inlines, filenames, and URLs. (You can
+override the default behavior by setting non-zero values for the
+<parameter>man.hyphenate.urls</parameter>,
+<parameter>man.hyphenate.filenames</parameter>, and
+<parameter>man.hyphenate.computer.inlines</parameter> parameters.) But
+the best way is still to just globally disable hyphenation, as the
+stylesheets do by default.</para>
+
+<para>The only good reason to enabled hyphenation is if you have also
+enabled justification (which is disabled by default). The reason is
+that justified text can look very bad unless you also hyphenate it; to
+quote the <quote>Hypenation</quote> node from the groff info page:
 
 <blockquote>
   <para><emphasis>Since the odds are not great for finding a set of
   words, for every output line, which fit nicely on a line without
-  inserting excessive amounts of space between words, `gtroff'
+  inserting excessive amounts of space between words, 'gtroff'
   hyphenates words so that it can justify lines without inserting too
   much space between words.</emphasis></para>
 </blockquote>