This change closes bug 2013441 and makes man-page output generally

usable again on Solaris and other platforms that use AT&T troff
instead of groff.

The change was to add man.output.better.ps.enabled parameter, with
its default value set to zero.

If the value of the man.output.better.ps.enabled parameter is
non-zero, certain markup is embedded in each generated man page
such that PostScript output from the man -Tps command for that
page will include a number of enhancements designed to improve the
quality of that output.

If man.output.better.ps.enabled is zero (the default), no such
markup is embedded in generated man pages, and no enhancements are
included in the PostScript output generated from those man pages
by the man -Tps command.

WARNING: The enhancements provided by this parameter rely on
features that are specific to groff (GNU troff) and that are not
part of "classic" AT&T troff or any of its derivatives. Therefore,
any man pages you generate with this parameter enabled will be
readable only on systems on which the groff (GNU troff) program is
installed, such as GNU/Linux systems.  The pages will not not be
readable on systems on with the classic troff (AT&T troff) command
is installed.

NOTE: The value of this parameter only affects PostScript output
generated from the man command. It has no effect on output
generated using the FO backend.

TIP: You can generate PostScript output for any man page by
running the following command:

man FOO -Tps > FOO.ps

You can then generate PDF output by running the following command:

ps2pdf FOO.ps

diff --git a/xsl/manpages/block.xsl b/xsl/manpages/block.xsl
index 9e25bb1d35aa3a87ed2c0b619baa8c01308454cf..d662979c1ef7dee5a373db5df642cc95c89c3a17 100644 (file)
--- a/xsl/manpages/block.xsl
+++ b/xsl/manpages/block.xsl
@@ -23,7 +23,9 @@
   <xsl:text>.sp&#10;</xsl:text>
   <xsl:call-template name="roff-if-end"/>
   <xsl:text>.RS 4&#10;</xsl:text>
-  <xsl:text>.BM yellow&#10;</xsl:text>
+  <xsl:if test="not($man.output.better.ps.enabled = 0)">
+    <xsl:text>.BM yellow&#10;</xsl:text>
+  </xsl:if>
   <xsl:call-template name="pinch.together"/>
   <xsl:text>.ps +1&#10;</xsl:text>
   <xsl:call-template name="make.bold.title"/>
@@ -31,7 +33,9 @@
   <xsl:text>.br&#10;</xsl:text>
   <xsl:apply-templates/>
   <xsl:text>.sp .5v&#10;</xsl:text>
-  <xsl:text>.EM yellow&#10;</xsl:text>
+  <xsl:if test="not($man.output.better.ps.enabled = 0)">
+    <xsl:text>.EM yellow&#10;</xsl:text>
+  </xsl:if>
   <xsl:text>.RE&#10;</xsl:text>
 </xsl:template> 
 
@@ -205,9 +209,11 @@
       <xsl:choose>
         <xsl:when test="self::literallayout|self::programlisting|self::screen
           and not(ancestor::*[local-name() = 'refsynopsisdiv'])
+          and not($man.output.better.ps.enabled = 0)
           ">
-          <!-- * if this is a literallayout|programlisting|screen, then -->
-          <!-- * we put a background behind it in non-TTY output; except -->
+          <!-- * if this is a literallayout|programlisting|screen, -->
+          <!-- * and user has set man.output.better.ps.enabled to non-zero, -->
+          <!-- * then we put a background behind it in non-TTY output; except -->
           <!-- * if it’s a descendant of a refsynopsisdiv (as can be -->
           <!-- * found in the git docs) -->
           <xsl:choose>

diff --git a/xsl/manpages/docbook.xsl b/xsl/manpages/docbook.xsl
index 31a5cf57fc590be396b2dea7408758523c4fb174..2fab8a7759f928dc27ea4ab4d76ffe293705b486 100644 (file)
--- a/xsl/manpages/docbook.xsl
+++ b/xsl/manpages/docbook.xsl
@@ -227,7 +227,9 @@
       <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <!-- * (re)define some macros -->
       <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
-      <xsl:call-template name="define.macros"/>
+      <xsl:if test="not($man.output.better.ps.enabled = 0)">
+        <xsl:call-template name="define.macros"/>
+      </xsl:if>
       <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <!-- * Set default hyphenation, justification, indentation, and -->
       <!-- * line-breaking -->

diff --git a/xsl/manpages/other.xsl b/xsl/manpages/other.xsl
index 2cc065968b62425aaab022a6e4f7d3bf49e0a088..4a2816572a5d7f78747b09735750a1d9de23ece2 100644 (file)
--- a/xsl/manpages/other.xsl
+++ b/xsl/manpages/other.xsl
@@ -747,7 +747,7 @@ manvolnum
 .if \\n[.$] \&\\$*
 ..&#10;</xsl:text>
     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
-    <xsl:text>.\" BB/BE - put background/screen (filled box) around block of text&#10;</xsl:text>
+    <xsl:text>.\" BB/EB - put background/screen (filled box) around block of text&#10;</xsl:text>
     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
     <xsl:text>.de BB
 .if t \{\

diff --git a/xsl/manpages/param.ent b/xsl/manpages/param.ent
index 2d41f8c0e5ff18295b0eae7248cc7e1a2632c130..4c61466123a0c2d3224746af87c528b9eb9eaafe 100644 (file)
--- a/xsl/manpages/param.ent
+++ b/xsl/manpages/param.ent
@@ -32,6 +32,7 @@
 <!ENTITY man.output.lang.in.name.enabled SYSTEM "../params/man.output.lang.in.name.enabled.xml">
 <!ENTITY man.output.manifest.enabled SYSTEM "../params/man.output.manifest.enabled.xml">
 <!ENTITY man.output.manifest.filename SYSTEM "../params/man.output.manifest.filename.xml">
+<!ENTITY man.output.better.ps.enabled SYSTEM "../params/man.output.better.ps.enabled.xml">
 <!ENTITY man.output.quietly SYSTEM "../params/man.output.quietly.xml">
 <!ENTITY man.output.subdirs.enabled SYSTEM "../params/man.output.subdirs.enabled.xml">
 <!ENTITY man.segtitle.suppress SYSTEM "../params/man.segtitle.suppress.xml">

diff --git a/xsl/manpages/param.xweb b/xsl/manpages/param.xweb
index 450a0125a6a0eca39d72ba79501d993ca8c7b06f..bf603ed60d9e6f24799bde8e5dfdbda9a0de5da5 100644 (file)
--- a/xsl/manpages/param.xweb
+++ b/xsl/manpages/param.xweb
@@ -121,6 +121,7 @@
 &man.output.subdirs.enabled;
 &man.output.quietly;
 &man.output.encoding;
+&man.output.better.ps.enabled;
   </reference>
   <reference xml:id="other">
   <title>Other</title>
@@ -185,6 +186,7 @@
 <src:fragref linkend="man.output.lang.in.name.enabled.frag"/>
 <src:fragref linkend="man.output.manifest.enabled.frag"/>
 <src:fragref linkend="man.output.manifest.filename.frag"/>
+<src:fragref linkend="man.output.better.ps.enabled.frag"/>
 <src:fragref linkend="man.output.quietly.frag"/>
 <src:fragref linkend="man.output.subdirs.enabled.frag"/>
 <src:fragref linkend="man.segtitle.suppress.frag"/>

diff --git a/xsl/manpages/refentry.xsl b/xsl/manpages/refentry.xsl
index 09e8f61c96164ecb9f97ca02804426985f4ec161..875b30a10cd16f6068832d887f52165cffe69255 100644 (file)
--- a/xsl/manpages/refentry.xsl
+++ b/xsl/manpages/refentry.xsl
@@ -297,14 +297,23 @@
 
   <xsl:template name="process.SH.xref">
     <xsl:param name="title"/>
-    <xsl:text>\c</xsl:text>
-    <xsl:text>&#x2592;</xsl:text>
-    <xsl:text>.SH-xref </xsl:text>
-    <xsl:text>"</xsl:text>
-    <xsl:value-of select="$title"/>
-    <xsl:text>\c"</xsl:text>
-    <xsl:text>&#x2592;</xsl:text>
-    <xsl:text>\&amp;</xsl:text>
+    <xsl:choose>
+      <xsl:when test="not($man.output.better.ps.enabled = 0)">
+        <xsl:text>\c</xsl:text>
+        <xsl:text>&#x2592;</xsl:text>
+        <xsl:text>.SH-xref </xsl:text>
+        <xsl:text>"</xsl:text>
+        <xsl:value-of select="$title"/>
+        <xsl:text>\c"</xsl:text>
+        <xsl:text>&#x2592;</xsl:text>
+        <xsl:text>\&amp;</xsl:text>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:call-template name="string.upper">
+          <xsl:with-param name="string" select="$title"/>
+        </xsl:call-template>
+      </xsl:otherwise>
+    </xsl:choose>
   </xsl:template>
 
 </xsl:stylesheet>

diff --git a/xsl/manpages/utility.xsl b/xsl/manpages/utility.xsl
index d752e3495a6d7d13cfa8dccb5b08b77e94037962..641cee97fc3ae03c7ed6501767135727bf9b4164 100644 (file)
--- a/xsl/manpages/utility.xsl
+++ b/xsl/manpages/utility.xsl
@@ -79,21 +79,29 @@
   <!-- ================================================================== -->
 
   <xsl:template name="verbatim-block-start">
-    <xsl:text>.fam C&#10;</xsl:text>
-    <xsl:text>.ps -1&#10;</xsl:text>
+    <xsl:if test="not($man.output.better.ps.enabled = 0)">
+      <xsl:text>.fam C&#10;</xsl:text>
+      <xsl:text>.ps -1&#10;</xsl:text>
+    </xsl:if>
   </xsl:template>
 
   <xsl:template name="verbatim-block-end">
-    <xsl:text>.fam&#10;</xsl:text>
-    <xsl:text>.ps +1&#10;</xsl:text>
+    <xsl:if test="not($man.output.better.ps.enabled = 0)">
+      <xsl:text>.fam&#10;</xsl:text>
+      <xsl:text>.ps +1&#10;</xsl:text>
+    </xsl:if>
   </xsl:template>
 
   <xsl:template name="synopsis-block-start">
-    <xsl:text>.fam C&#10;</xsl:text>
+    <xsl:if test="not($man.output.better.ps.enabled = 0)">
+      <xsl:text>.fam C&#10;</xsl:text>
+    </xsl:if>
   </xsl:template>
 
   <xsl:template name="synopsis-block-end">
-    <xsl:text>.fam&#10;</xsl:text>
+    <xsl:if test="not($man.output.better.ps.enabled = 0)">
+      <xsl:text>.fam&#10;</xsl:text>
+    </xsl:if>
   </xsl:template>
 
   <!-- ================================================================== -->
@@ -490,7 +498,16 @@
     <xsl:text>.SH</xsl:text>
     <xsl:text> </xsl:text>
     <xsl:text>"</xsl:text>
-    <xsl:value-of select="$title"/>
+    <xsl:choose>
+      <xsl:when test="not($man.output.better.ps.enabled = 0)">
+        <xsl:value-of select="$title"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:call-template name="string.upper">
+          <xsl:with-param name="string" select="$title"/>
+        </xsl:call-template>
+      </xsl:otherwise>
+    </xsl:choose>
     <xsl:text>"</xsl:text>
     <xsl:text>&#10;</xsl:text>
     <xsl:call-template name="mark.subheading"/>

diff --git a/xsl/params/man.output.better.ps.enabled.xml b/xsl/params/man.output.better.ps.enabled.xml
new file mode 100644 (file)
index 0000000..82d15dd
--- /dev/null
+++ b/xsl/params/man.output.better.ps.enabled.xml
@@ -0,0 +1,61 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          xmlns:src="http://nwalsh.com/xmlns/litprog/fragment"
+          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+          version="5.0" xml:id="man.output.better.ps.enabled">
+<refmeta>
+<refentrytitle>man.output.better.ps.enabled</refentrytitle>
+<refmiscinfo class="other" otherclass="datatype">boolean</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>man.output.better.ps.enabled</refname>
+<refpurpose>Enable enhanced print/PostScript output?</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<src:fragment xml:id="man.output.better.ps.enabled.frag">
+<xsl:param name="man.output.better.ps.enabled">0</xsl:param>
+</src:fragment>
+</refsynopsisdiv>
+<refsection><info><title>Description</title></info>
+
+<para>If the value of the
+<parameter>man.output.better.ps.enabled</parameter> parameter is
+non-zero, certain markup is embedded in each generated man page
+such that PostScript output from the <command>man -Tps</command>
+command for that page will include a number of enhancements
+designed to improve the quality of that output.</para>
+
+<para>If <parameter>man.output.better.ps.enabled</parameter> is
+zero (the default), no such markup is embedded in generated man
+pages, and no enhancements are included in the PostScript
+output generated from those man pages by the <command>man
+ -Tps</command> command.</para>
+
+<warning>
+  <para>The enhancements provided by this parameter rely on
+    features that are specific to groff (GNU troff) and that are
+    not part of “classic” AT&amp;T troff or any of its
+    derivatives. Therefore, any man pages you generate with this
+    parameter enabled will be readable only on systems on which
+    the groff (GNU troff) program is installed, such as GNU/Linux
+    systems. The pages <emphasis role="bold">will not not be
+      readable on systems on with the classic troff (AT&amp;T
+      troff) command is installed</emphasis>.</para>
+</warning>
+
+<para>The value of this parameter only affects PostScript output
+  generated from the <command>man</command> command. It has no
+  effect on output generated using the FO backend.</para>
+
+<tip>
+  <para>You can generate PostScript output for any man page by
+    running the following command:</para>
+  <programlisting>  man <replaceable>FOO</replaceable> -Tps > <replaceable>FOO</replaceable>.ps</programlisting>
+  <para>You can then generate PDF output by running the following
+    command:</para>
+  <programlisting>  ps2pdf <replaceable>FOO</replaceable>.ps</programlisting>
+</tip>
+
+</refsection>
+</refentry>