Re: GNOME document autogeneration...

[Elliot Lee <sopwith redhat com>]

On Thu, 19 Nov 1998, Jeff Garzik wrote:

> Look in gnome-libs/tools/gnome-doc.  It's there, it works, it produces
> DocBook, HTML, or text.


Hmm, the problem is that this is a million millimetres from doing what the
GTK+ system does. :|

gnome-doc is what we can definitely use for the inline documentation (aka
project "source code will be readable" :), but it is not flexible enough
or powerful enough to practically allow doing things like usage examples,
many paragraphs of description, sidebars, etc. which the GTK+ system does.

> I have already started doc'ing libgnomeui using this, so your
> announcement took me by surprise.

Your work isn't wasted - all the code will need to get these comments in
there. gnome-doc is the right solution for literate programming, source
code clarification, etc. But, gnome-doc isn't the right solution for heavy
duty docs. We were using docbook for that. This docbook system (the one
that gnome-libs/devel-docs/libgnorba.sgml currently uses, for example) is
too verbose and generic to use easily for these docs (documenting a
function has an minimum overhead of ~20 tags, compared to a minimum of 4
or 5 for the GTK+ system). In addition, it doesn't produce nearly as nice
HTML output as the GTK+ system (see http://glade.pn.org/glibdocs/ for GTK+
glib/gtk+ docs).

Also, using the GTK+ system will help keep the GNOME docs consistent with
the GTK+ docs, which is important because a large portion of GNOME
programming involves using GTK+.

Hope MHO explains why gnome-doc is far from dead, and why we do need the
gtk+ system :)
-- Elliot
"In film you will find four basic story lines. Man versus man, man
 versus nature, nature versus nature, and dog versus vampire."
    - Steven Spielberg