Re: gtk-doc manual on library.gnome.org (and library.gnome.org status (shining, read it now))

[Stefan Kost <ensonic hora-obscura de>]

Hi Shaun,

Shaun McCance wrote:
> On Mon, 2007-07-30 at 21:04 +0300, Stefan Kost wrote:
>> Hi Shaun,
>>
>> Shaun McCance wrote:
>> <<snip>>
>>> What do people think about using gnome-doc-utils to
>>> generate HTML from gtk-doc's DocBook output?  We'd
>>> get a more consistent style, better localization,
>>> and much faster builds.  I'm sure there would be a
>>> few problems, but we can fix them.
>> There seems to be a common misunderstanding. gtk-doc as such is really fast. The
>> issue is the index generation of the docbook stylesheets. Have a look at
>> http://bugzilla.gnome.org/show_bug.cgi?id=311857
>> I have a workaround there as a patch that reduces the time of a gtk-doc run for
>> gtk+ from many minutes to a few seconds.
> 
> I'm not talking about gtk-doc-the-perl-scripts that extracts
> information from source files to create DocBook.  I'm talking
> about the part that turns DocBook into HTML.  That's done by
> the standard DocBook XSLT, with some customizations layered
> on top.
> 
> We have a complete separate set of XSLT for DocBook to HTML
> conversions sitting in gnome-doc-utils.  We use it in Yelp
> and to build HTML for non-gtk-doc manuals for lgo.  There
> is no reason they couldn't be used to convert DocBook from
> gtk-doc into HTML.
> 
> As for speed, our XSLT is provably faster than the standard
> XSLT.  I don't think I've ever seen a test case where they
> weren't at least 50% faster.  On average, they tend to be
> about 70% faster.  I can absolutely guarantee that gtk-doc
> would be faster if it used the XSLT from gnome-doc-utils.
> 
Have you looked at the bug in bugzilla. No, right. Please do so. It has nothing
to do with the normal xslt transformation. It is only the docbook stylesheets
parts that generate an index and I'd be surprised if your stylesheets do that
faster. I've discussed that in depth with libxml/libxslt gurus as well as Norman
Walsh (docbook stylesheets).

Stefan