{"thread":{"id":"43663","subject":"Re: Garbled man pages (.sp instead of newline)","startedAt":"2006-12-01T17:57:24Z","lastAt":"2006-12-01T19:01:59Z","messageCount":2,"participants":["Jonas Fonseca","Carl Worth"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"296947","messageId":"87r6vjfqij.wl%cworth@cworth.org","threadId":"43663","inReplyTo":null,"subject":"Garbled man pages (.sp instead of newline)","fromName":"Carl Worth","fromEmail":"cworth@cworth.org","sentAt":"2006-12-01T17:57:24Z","receivedAt":"2006-12-01T17:57:24Z","isPatch":false,"sender":{"key":"cworth@cworth.org","avatar":"https://gravatar.com/avatar/3746dc28cde609bdbd7f939058356e7e2bbd16d21e32274df0725eb3d998bc5b?d=mp&s=160"},"body":"I've spent too much time just \"talking\" on this list and I'd like to\nstart \"doing\" more.\n\nI can see a lot of things that I think I could improve in the\ndocumentation, but when I tried to build them, I'm getting broken man\npages as a result. For example with \"man git\" I now see:\n\n       Git is a fast, scalable, distributed revision control system with an unusually rich\n       command set that provides both high-level operations and full access to\n       internals..sp See this [1]tutorial to get started, then see [2]Everyday Git for a\n       useful minimum set of commands, and \"man git-commandname\" for documentation of each\n       command. CVS users may also want to read [3]CVS migration..sp The COMMAND is either\n       a name of a Git command (see below) or an alias as defined in the configuration\n       file (see git-repo-config(1))..sp\n\nI appear to be using asciidoc 7.1.2. Does anyone here know what's\ncausing the above and how to fix it?\n\n-Carl\n"},{"id":"296428","messageId":"20061201190159.GA31028@diku.dk","threadId":"43663","inReplyTo":"87r6vjfqij.wl%cworth@cworth.org","subject":"Re: Garbled man pages (.sp instead of newline)","fromName":"Jonas Fonseca","fromEmail":"fonseca@diku.dk","sentAt":"2006-12-01T19:01:59Z","receivedAt":"2006-12-01T19:01:59Z","isPatch":false,"sender":{"key":"fonseca@diku.dk","avatar":"https://gravatar.com/avatar/f82f3ad698717c51873b020c750a92438c820a24056dc39fe4d07baa10a92264?d=mp&s=160"},"body":"Carl Worth <cworth@cworth.org> wrote Fri, Dec 01, 2006:\n> I can see a lot of things that I think I could improve in the\n> documentation, but when I tried to build them, I'm getting broken man\n> pages as a result. For example with \"man git\" I now see:\n> \n>        Git is a fast, scalable, distributed revision control system with an unusually rich\n>        command set that provides both high-level operations and full access to\n>        internals..sp See this [1]tutorial to get started, then see [2]Everyday Git for a\n>        useful minimum set of commands, and \"man git-commandname\" for documentation of each\n>        command. CVS users may also want to read [3]CVS migration..sp The COMMAND is either\n>        a name of a Git command (see below) or an alias as defined in the configuration\n>        file (see git-repo-config(1))..sp\n> \n> I appear to be using asciidoc 7.1.2. Does anyone here know what's\n> causing the above and how to fix it?\n\nThe problem is that a newline is not inserted before the \".sp\".  I (and\napparently a lot of other people on #git) thought it was just something\nbroken by the system. It appears that the DocBook XSL files got broken\nbetween 1.69.0 and 1.69.1, but it appears to have been fixed upstream (I\ndidn't try it by from looking at the xsl/manpages/block.xsl file it\nseems to insert a newline again before inserting a \".sp\")\n\nGit already has a custom XSL file to handle callouts so this might be\nthe right place to insert a workaround for this although I don't know if\nit breaks systems that do not have this problem. The patch that I have\nincluded is based on what I plan to add to tig. It would be great to\nhear if it breaks manpages build on systems that do not have this \".sp\"\nproblem.\n\nI also have another small fix to insert an empty line after a code\nblock. Currently, the following paragraph will immediately follow the\ncode block which hurts readability a bit.\n\nBTW, it might make sense to rename callouts.xsl to manpage.xsl if\nsomething like this and the other fix I mentioned is acceptable.\n\ndiff --git a/Documentation/callouts.xsl b/Documentation/callouts.xsl\nindex ad03755..d016b3b 100644\n--- a/Documentation/callouts.xsl\n+++ b/Documentation/callouts.xsl\n@@ -13,4 +13,44 @@\n \t<xsl:apply-templates/>\n \t<xsl:text>.br&#10;</xsl:text>\n </xsl:template>\n+<xsl:template match=\"simpara\">\n+  <xsl:variable name=\"content\">\n+    <xsl:apply-templates/>\n+  </xsl:variable>\n+  <xsl:value-of select=\"normalize-space($content)\"/>\n+  <xsl:text>&#10;</xsl:text>\n+  <xsl:text>.sp&#10;</xsl:text>\n+</xsl:template>\n+\n+<xsl:template match=\"address|literallayout|programlisting|screen|synopsis\">\n+  <!-- * Yes, address and synopsis are verbatim environments. -->\n+\n+  <xsl:choose>\n+    <!-- * Check to see if this verbatim item is within a parent element that -->\n+    <!-- * allows mixed content. -->\n+    <!-- * -->\n+    <!-- * If it is within a mixed-content parent, then a line space is -->\n+    <!-- * already added before it by the mixed-block template, so we don't -->\n+    <!-- * need to add one here. -->\n+    <!-- * -->\n+    <!-- * If it is not within a mixed-content parent, then we need to add a -->\n+    <!-- * line space before it. -->\n+    <xsl:when test=\"parent::caption|parent::entry|parent::para|\n+                    parent::td|parent::th\" /> <!-- do nothing -->\n+    <xsl:otherwise>\n+      <xsl:text>&#10;</xsl:text>\n+      <xsl:text>.sp&#10;</xsl:text>\n+    </xsl:otherwise>\n+  </xsl:choose>\n+  <xsl:text>.nf&#10;</xsl:text>\n+  <xsl:apply-templates/>\n+  <xsl:text>&#10;</xsl:text>\n+  <xsl:text>.fi&#10;</xsl:text>\n+  <!-- * if first following sibling node of this verbatim -->\n+  <!-- * environment is a text node, output a line of space before it -->\n+  <xsl:if test=\"following-sibling::node()[1][name(.) = '']\">\n+    <xsl:text>&#10;</xsl:text>\n+    <xsl:text>.sp&#10;</xsl:text>\n+  </xsl:if>\n+</xsl:template>\n </xsl:stylesheet>\n\n-- \n"}]}