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

[Shaun McCance <shaunm gnome org>]

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.

--
Shaun