Re: Speeding up gtk-doc

[Shaun McCance <shaunm gnome org>]

On Wed, 2003-12-17 at 23:29, Callum McKenzie wrote:
> As everyone knows gtk-doc is horribly slow when converting docbook to
> html. The problem lies partly in docbook being so painfully huge and
> partly in it's poor handling of chunking. The yelp people solved this
> problem by rewriting the xsl stylesheets to only support the subset of
> docbook that they used. It strikes me that since gtk-doc uses an even
> more restricted version of docbook (except for the template files, which
> aren't restricted) it shouldn't be too difficult to write a replacement
> stand-alone gtk-doc.xsl that is an order of magnitude faster than
> docbook's xsl (and probably faster than yelp's). 
> 
> I have had a brief go at this problem, it isn't functional but suggests
> that the order of magnitude speed-up is feasible and is worth pursuing.
> I am prepared to continue with this and see what happens, but I have a
> few questions :
> 
> 1) What about the template code ? Handling the list Aaron suggests in
> the proposed authors.html file is easy but general docbook isn't. Is it
> acceptable to reject (or silently ignore) stuff that isn't understood by
> my style-sheet ?
> 
> 2) Is there serious interest in this ? i.e. is it desirable to sacrifice
> docbook compliance for speed ? (I'm prepared to accept a "we'll see what
> it looks like" answer.)

The subset of DocBook that Yelp is intended to support is quite large. 
I don't believe there even exists a DocBook processing system that works
with any valid DocBook file.  DocBook is an intentionally loose format,
and processing systems are basically expected to place limitations on
what you can do.

The subset of DocBook that Yelp currently does support is smaller than
what it should support.  There are about 100 elements that aren't being
handled right now, but they will be done.  Unfortunately, most of the
elements that deal with code aren't there yet, and I suspect those are
essential to gtk-doc.

So you're very likely to get faster transformations if you ditch Norm's
stylesheets.  The speed problems go far beyond just being too general. 
There's a lot of stuff in there that's just really suboptimal.  I think
you're unlikely to get significantly faster than Yelp's stylesheets,
even with supporting a smaller subset.  I'm sure you can squeeze a bit
more speed out, but not a whole lot.

So as a heads-up, DocBook is a beast.  I decided to write new XSLT for
Yelp quite a while ago, and I'm still not done.  I'm sticking with my
new stylesheets, of course, because the speed difference is enough to
justify the work.  But you may be getting yourself into a lot of work
with this, and I'm not sure the payoff will be that much.

Of course, it'll be less work than what I have to do, since you don't
need all of DocBook.  But it could still be more work than you expect. 
Yelp's stylesheets are there for you, if you want to use them.

--
Shaun