Re: [gtk-list] Re: Documentation

[Jeroen Benckhuijsen <jeroen benck demon nl>]

I sure did RFTM, but i noticed that some parts of the RDP are very
unclear. I'm not talking about the simple stuff, like creating a label
or a button. It's more the advanced stuff. Looking at the GDK part of
the RDP I see only 50% of it if filled out. There just sits there
without any comment. During development of my app, it's been a hell of a
job to search through all the source files of gdk, just to know
something about e.g. a GdkImage or something like that. I'm not saying
the docs aren't good. The basic stuff is filled out, but when developing
a bit more complicated app, you'll have to dive into the sources. 

Example: in our app (image viewer) i had the choice between a GtkImage,
GtkPreview, GtkDrawArea and a GtkPreview. I couldn't find the difference
between these image widgets anywhere. Also information about all
enumerations of GDK and GTK. There are a lot of them ,and although the
names are often very clear, a few aren't. 

I admit, it was my first app to write using Gtk, there was a time
pressure ,etc, so it could be i didn't took enough time to search other
sources, etc , to find things out. Sometimes writing to this mailing
list helped, which IMHO is a good thing. However, i believe the function
of a doc like the RDP is to make sure i don't have to search everywhere
for info how to do this or that. While developing my app, i just
noticed, that the RDP didn't fullfill this need YET. Hence my mail as a
advice to increase the work on the RDP. 

I believe Gtk can (and will) be used in commercial enviroments ( our app
was written for a hospital ,so that's not really a commercial enviroment
(at least not here in Holland)). However this requieres a good
documentation. Programmers at a company don't have time to look into
"thousands" of source codes or to find information all over the net. 

I think it's important ,gtk will be used in commercial enviroments. This
will show the real demands for Gtk. Non-commercial projects don't do
this, because there's not much at stake. If one does not find some info
in the RDP, he/she will go find in indeed on the net, because there is
time avialebele for this. 

Conclusion: i think gtk is a very good toolkit, however, when
programming some advanced programs, or using some advanced features,
there is a lack of documentation, which is a shame.

Jeroen

Matthew D Allen wrote:
> 
> >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);'
> 
> --
> To unsubscribe: mail -s unsubscribe gtk-list-request@redhat.com < /dev/null