Re: Documentation

[Matthew D Allen <s2mdalle titan vcu edu>]

>As seen from many mails, often there are complains about the
>documentation of GTK. IMHO these complains are very important. From my
>own experience i can say it's very frustrating to have to dive into the
>source, to find out what a certain function does (after all, the
>intention of the toolkit is i don't have to bother about a great deal of
>functionality). Maybe this should be the first priority of the
>GTK-project: first mak sure the docs are OK. IMHO GTK is now in a stage,
>we're completion will be reached quickly, so writing the documentation
>and the tutorials should be important now. Don't get me wrong, i think
>GTK is a great toolkit, but what's a great toolkit if one does not (or
>not quite) know how to use it. 

I *used* to be in the same boat with you on this one, but I'm not really
anymore.  It used to be that the RDP wasn't really all that complete, but
I've been checking it out as time passes and it's getting sweeter and
sweeter.

(BTW, the RDP is the "reference documentation project" specific to GTK+
and glib, and is at www.gtk.org/rdp/gtk/  (not really, but that will
redirect you to the corect URL which I can't remember))

The RDP is for me at least, the dream of what a library documentation
should be AFTER you've got the basics of the library down.  It gives a
list of each widget, each function that they provide for each widgets,
with detailed information on what you pass in, what it does, and what you
get out of it.  Note that this will probably not help you in the least
unless you have a basic idea of what's going on with GTK+.  (See the
harlow book for that - Havoc's book is great for GNOME, but the GTK+
treatment is a little thin since it's not a book about GTK+ primarily)

Failing the RDP and the Harlow book (which is how I got the basics under
my belt when the RDP was still a little weak), I know you think that
diving straight into the source is annoying, but it's the best way.
Learning by immersion I supposed you might say.  God knows there isn't a
lack of GTK+ code out there that is obtainable.  :)

Generally though, I've found that if you want to learn GTK+, you should
just learn in a very general sense how things are done, and then most of
the rest is either a no brainer or something you simply need to RTFM on.
Example:  when I started coding with GTK+, I noticed that to create a new
button with text, it was gtk_button_new_with_label().  To create a label,
it's gtk_label_new().  To create a toggle button, it's
gtk_toggle_button_new().  Hmmm...there seems to be a pattern here..does
this mean that if I try gtk_option_menu_new() it will give me an option
menu?  Of course, because that's what a consistant interface should do.
:)  Now,  most of these calls require arguments, which falls under the
second part of what I mentioned - RTFM.  How do I find what I should give
for the arguments?  Well that's what the RDP is for.  :)

And things like "what does that call return?" are answered usually with
just "GtkWidget *".  (which I think of in my uncouth way as a "thingy")

Hope some of this helps

David

http://opop.nols.com/ Free Software Development
==========================================================================
Der Horizont vieler Menschen ist ein Kreis mit Radius Null -- und das
nennen sie ihren Standpunkt.
==========================================================================
perl -e 'print $i=pack(c5,(41*2),sqrt(7056),(unpack(c,H)-2),oct(115),10);'