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

[Shaun McCance <shaunm gnome org>]

On Thu, 2007-07-26 at 19:06 +0200, Frederic Peters wrote:
> Stefan Kost wrote:
> 
> > what needs to be done to get the gtk-doc manual to appear on lgo (its a normal
> > docbook manual that works fine in yelp)? gtk-doc is an important piece for
> > develoeprs to get their docs generated. I invest efforts to improve the manual,
> > but distributions mostly do not package it (I stated to file bugs against some).
> > It should at least appeah on lgo.
> 
> I wanted to wait a little bit before announcing this, but I'll talk
> about it now.  At GUADEC we had a little meeting with Murray and Lucas
> (unfortunately Goran couldn't attend) about library.gnome.org, what
> was holding it up, what we would want to see before 2.20.
> 
> I worked a little bit on that on the journey back, waiting for a train in
> London, but finally decided to almost start from scratch, reusing XSLT,
> Javascript and a few ideas from current implementation, but not much more.
> 
> My current code is available with `bzr get http://www.0d.be/bzr/libgo/';
> and I should probably push it to svn since what was just an experiment
> proved a good idea.
> 
> I have been running it yesterday night on my webserver, and the output is
> available at http://lgo.0d.be/; anybody feel free to comment.

This is hot.  I'm glad you guys are pushing this forward.
I've made a few changes to gnome-doc-utils over the last
month or so, many of which were to make lgo work and look
better.

I'd like to keep lgo's (and yelp's) XSLT customizations
to a minimum.  We should push as much stuff upstream as
makes sense.  For example, I added the TOC sidebar stuff
directly to g-d-u, and Yelp can turn it off explicitly.

> What it does is iterating over GNOME tarballs, extracting gtk-doc and
> gnome-doc-utils elements, and formatting them nicely for all to see.
> 
> And here comes your question, how to add gtk-doc help manuel to lgo; the
> easiest way would be to use gnome-doc-utils; but this would create a
> circular dependency (gnome-doc-utils needs glib needs gtk-doc) and is thus
> not possible.

gnome-doc-utils only requires libxml2 and libxslt.  All
the code in g-d-u is architecture-independent (autofu,
sh, awk, xslt), and it should all be portable to other
implementations.  (GNUisms creep in from time to time,
but they're bugs, and they get fixed.)

> So I will just have to special-case gtk-doc, or add some heuristics (maybe
> considering "include $(top_srcdir)/xmldocs.make" to be proof there is
> useful documentation in the directory), and get it built along the rest.
> 
> I am very busy today and tomorrow, I will have time this weekend to add
> this.

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.

--
Shaun