Garbled man pages (.sp instead of newline)

Garbled man pages (.sp instead of newline)

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 960 bytes --]

I've spent too much time just "talking" on this list and I'd like to
start "doing" more.

I can see a lot of things that I think I could improve in the
documentation, but when I tried to build them, I'm getting broken man
pages as a result. For example with "man git" I now see:

       Git is a fast, scalable, distributed revision control system with an unusually rich
       command set that provides both high-level operations and full access to
       internals..sp See this [1]tutorial to get started, then see [2]Everyday Git for a
       useful minimum set of commands, and "man git-commandname" for documentation of each
       command. CVS users may also want to read [3]CVS migration..sp The COMMAND is either
       a name of a Git command (see below) or an alias as defined in the configuration
       file (see git-repo-config(1))..sp

I appear to be using asciidoc 7.1.2. Does anyone here know what's
causing the above and how to fix it?

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Garbled man pages (.sp instead of newline)

[Jonas Fonseca]

Carl Worth <cworth@cworth.org> wrote Fri, Dec 01, 2006:
> I can see a lot of things that I think I could improve in the
> documentation, but when I tried to build them, I'm getting broken man
> pages as a result. For example with "man git" I now see:
> 
>        Git is a fast, scalable, distributed revision control system with an unusually rich
>        command set that provides both high-level operations and full access to
>        internals..sp See this [1]tutorial to get started, then see [2]Everyday Git for a
>        useful minimum set of commands, and "man git-commandname" for documentation of each
>        command. CVS users may also want to read [3]CVS migration..sp The COMMAND is either
>        a name of a Git command (see below) or an alias as defined in the configuration
>        file (see git-repo-config(1))..sp
> 
> I appear to be using asciidoc 7.1.2. Does anyone here know what's
> causing the above and how to fix it?

The problem is that a newline is not inserted before the ".sp".  I (and
apparently a lot of other people on #git) thought it was just something
broken by the system. It appears that the DocBook XSL files got broken
between 1.69.0 and 1.69.1, but it appears to have been fixed upstream (I
didn't try it by from looking at the xsl/manpages/block.xsl file it
seems to insert a newline again before inserting a ".sp")

Git already has a custom XSL file to handle callouts so this might be
the right place to insert a workaround for this although I don't know if
it breaks systems that do not have this problem. The patch that I have
included is based on what I plan to add to tig. It would be great to
hear if it breaks manpages build on systems that do not have this ".sp"
problem.

I also have another small fix to insert an empty line after a code
block. Currently, the following paragraph will immediately follow the
code block which hurts readability a bit.

BTW, it might make sense to rename callouts.xsl to manpage.xsl if
something like this and the other fix I mentioned is acceptable.

diff --git a/Documentation/callouts.xsl b/Documentation/callouts.xsl
index ad03755..d016b3b 100644
--- a/Documentation/callouts.xsl
+++ b/Documentation/callouts.xsl
@@ -13,4 +13,44 @@
 	<xsl:apply-templates/>
 	<xsl:text>.br&#10;</xsl:text>
 </xsl:template>
+<xsl:template match="simpara">
+  <xsl:variable name="content">
+    <xsl:apply-templates/>
+  </xsl:variable>
+  <xsl:value-of select="normalize-space($content)"/>
+  <xsl:text>&#10;</xsl:text>
+  <xsl:text>.sp&#10;</xsl:text>
+</xsl:template>
+
+<xsl:template match="address|literallayout|programlisting|screen|synopsis">
+  <!-- * Yes, address and synopsis are verbatim environments. -->
+
+  <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:text>.nf&#10;</xsl:text>
+  <xsl:apply-templates/>
+  <xsl:text>&#10;</xsl:text>
+  <xsl:text>.fi&#10;</xsl:text>
+  <!-- * 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>&#10;</xsl:text>
+    <xsl:text>.sp&#10;</xsl:text>
+  </xsl:if>
+</xsl:template>
 </xsl:stylesheet>

--