Re: Garbled man pages (.sp instead of newline)
- From
Jonas Fonseca <fonseca@diku.dk>
- Date
- Dec 1, 2006, 19:01 UTC
- Message-ID
- <20061201190159.GA31028@diku.dk>
- In-Reply-To
- <87r6vjfqij.wl%cworth@cworth.org>
Carl Worth <cworth@cworth.org> wrote Fri, Dec 01, 2006:
Show 14 quoted lines
> 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 </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> </xsl:text> + <xsl:text>.sp </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> </xsl:text> + <xsl:text>.sp </xsl:text> + </xsl:otherwise> + </xsl:choose> + <xsl:text>.nf </xsl:text> + <xsl:apply-templates/> + <xsl:text> </xsl:text> + <xsl:text>.fi </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> </xsl:text> + <xsl:text>.sp </xsl:text> + </xsl:if> +</xsl:template> </xsl:stylesheet>