Re: [PATCH] Add warning about known issues to documentation of cvsimport

[Jeff King <peff@peff.net>]

On Tue, Mar 31, 2009 at 07:28:12AM -0400, Jeff King wrote:

> On Tue, Mar 31, 2009 at 12:36:46AM +0200, Heiko Voigt wrote:
> 
> > > Note the extra blank line between each heading and its list, and the
> > > lack of a blank line between the end of the first list and the heading
> > > of the second. Your source is very readable, so it really is just
> > > asciidoc being silly, but I wonder if there is a way to work around
> > > that.
> > 
> > My xmlto is not working at the moment. I will check that.
> 
> I looked into it a little more; it happens all over the place, so it is
> a problem somewhere in the documentation toolchain. So don't worry about
> it for this particular patch.

I looked into it more and posted to the docbook-apps list.  Here's what
I found out: the problem is fixed in docbook-xsl 1.74.3. However, our
template to prevent extra .sp in manpage-base.xml prevents it.

That fix is in 7ef0435 (spurious .sp in manpages, 2006-12-13), and I get
good output by reverting it and using docbook 1.74.3.

Going back to the original discussion, it looks like it is a workaround
for docbook-xsl 1.69.0:

  http://article.gmane.org/gmane.comp.version-control.git/32957

Assuming that is correct, I think the sane choices are:

  1. drop the workaround, as that version of docbook-xsl is now several
     years old

     or

  2. turn the workaround off by default, but add a knob to turn it on
     (DOCBOOK_XSL_1690?)

Having it on by default and turning it off with a knob seems silly,
since most versions don't need it. Debian stable is shipping 1.73 these
days, which looks fine without 7ef0435. Are there other platforms still
shipping 1.69.0? Is it too old for us to care?

-Peff