From: Jonas Fonseca <fonseca@diku.dk>
Date: Thu, 19 Jul 2007 11:37:43 GMT
Subject: [PATCH] Force listingblocks to be monospaced in manpages
Message-ID: <20070719113743.GA27553@diku.dk>
In-Reply-To: <Pine.LNX.4.64.0707190157430.1964@beast.quantumfyre.co.uk>

For the html output we can use a stylesheet to make sure that the
listingblocks are presented in a monospaced font.  For the manpages do
it manually by inserting a ".ft C" before and ".ft" after the block in
question.

In addition, also add an empty line after all verbatim blocks.

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
---

  Julian Phillips <julian@quantumfyre.co.uk> wrote Thu, Jul 19, 2007:
  > On Wed, 18 Jul 2007, Junio C Hamano wrote:
  > 
  > >I tried with your patch, both with asciidoc7 and asciidoc8.  Did
  > >you really mean "&#x2302;" above?  Replacing them with "."  gave
  > >me a series of these changes (diff between output before and
  > >after your patch with the "s/\&#x2302;/./g" fixup):
  > 
  > I did mean it.  I originally just had .ft, but I was getting \&.ft in the 
  > manpage, which then just came out as .ft in the console.
  
  This is because AsciiDoc does the escaping. I think it would be cleaner
  to do this thing when converting from DocBook to roff like we already
  do for other things.

  While fixing the above, a fix for separating verbatim blocks from any
  following blocks is easy to apply.

diff --git a/Documentation/callouts.xsl b/Documentation/callouts.xsl
index 6a361a2..44ab77d 100644
--- a/Documentation/callouts.xsl
+++ b/Documentation/callouts.xsl
@@ -27,4 +27,93 @@
   </xsl:if>
 </xsl:template>
 
+<!-- * Yes, address, synopsis, and funcsynopsisinfo are verbatim environments. -->
+<xsl:template match="literallayout|programlisting|screen|
+                     address|synopsis|funcsynopsisinfo">
+  <xsl:param name="indent">
+    <!-- * Only indent this verbatim if $man.indent.verbatims is -->
+    <!-- * non-zero and it is not a child of a *synopsis element -->
+    <xsl:if test="not($man.indent.verbatims = 0) and
+                  not(substring(local-name(..),
+                  string-length(local-name(..))-7) = 'synopsis')">
+      <xsl:text>Yes</xsl:text>
+    </xsl:if>
+  </xsl:param>
+
+  <xsl:choose>
+    <!-- * Check to see if this verbatim item is within a parent element that -->
+    <!-- * allows mixed content. -->
+    <!-- * -->
+    <!-- * If it is within a mixed-content parent, then a line space is -->
+    <!-- * already added before it by the mixed-block template, so we don't -->
+    <!-- * need to add one here. -->
+    <!-- * -->
+    <!-- * If it is not within a mixed-content parent, then we need to add a -->
+    <!-- * line space before it. -->
+    <xsl:when test="parent::caption|parent::entry|parent::para|
+                    parent::td|parent::th" /> <!-- do nothing -->
+    <xsl:otherwise>
+      <xsl:text>&#10;</xsl:text>
+      <xsl:text>.sp&#10;</xsl:text>
+    </xsl:otherwise>
+  </xsl:choose>
+  <xsl:if test="$indent = 'Yes'">
+    <!-- * start indented section -->
+    <xsl:text>.RS</xsl:text>
+    <xsl:if test="not($man.indent.width = '')">
+      <xsl:text> </xsl:text>
+      <xsl:value-of select="$man.indent.width"/>
+    </xsl:if>
+    <xsl:text>&#10;</xsl:text>
+  </xsl:if>
+  <xsl:choose>
+    <xsl:when test="self::funcsynopsisinfo">
+      <!-- * All Funcsynopsisinfo content is by default rendered in bold, -->
+      <!-- * because the man(7) man page says this: -->
+      <!-- * -->
+      <!-- *   For functions, the arguments are always specified using -->
+      <!-- *   italics, even in the SYNOPSIS section, where the rest of -->
+      <!-- *   the function is specified in bold -->
+      <!-- * -->
+      <!-- * Look through the contents of the man/man2 and man3 directories -->
+      <!-- * on your system, and you'll see that most existing pages do follow -->
+      <!-- * this "bold everything in function synopsis" rule. -->
+      <!-- * -->
+      <!-- * Users who don't want the bold output can choose to adjust the -->
+      <!-- * man.font.funcsynopsisinfo parameter on their own. So even if you -->
+      <!-- * don't personally like the way it looks, please don't change the -->
+      <!-- * default to be non-bold - because it's a convention that's -->
+      <!-- * followed is the vast majority of existing man pages that document -->
+      <!-- * functions, and we need to follow it by default, like it or no. -->
+      <xsl:text>.ft </xsl:text>
+      <xsl:value-of select="$man.font.funcsynopsisinfo"/>
+      <xsl:text>&#10;</xsl:text>
+      <xsl:text>.nf&#10;</xsl:text>
+      <xsl:apply-templates/>
+      <xsl:text>&#10;</xsl:text>
+      <xsl:text>.fi&#10;</xsl:text>
+      <xsl:text>.ft&#10;</xsl:text>
+    </xsl:when>
+    <xsl:otherwise>
+      <!-- * Other verbatims do not need to get bolded -->
+      <xsl:text>.nf&#10;</xsl:text>
+      <xsl:text>.ft C&#10;</xsl:text>
+      <xsl:apply-templates/>
+      <xsl:text>&#10;</xsl:text>
+      <xsl:text>.ft&#10;</xsl:text>
+      <xsl:text>&#10;</xsl:text>
+      <xsl:text>&#10;.fi&#10;</xsl:text>
+    </xsl:otherwise>
+  </xsl:choose>
+  <xsl:if test="$indent = 'Yes'">
+    <!-- * end indented section -->
+    <xsl:text>.RE&#10;</xsl:text>
+  </xsl:if>
+  <!-- * if first following sibling node of this verbatim -->
+  <!-- * environment is a text node, output a line of space before it -->
+  <xsl:if test="following-sibling::node()[1][name(.) = '']">
+    <xsl:text>.sp&#10;</xsl:text>
+  </xsl:if>
+</xsl:template>
+
 </xsl:stylesheet>
-- 
Jonas Fonseca