Re: gtk-app-devel-list Digest, Vol 34, Issue 25

[Fabricio Rocha <rocha_fabricio yahoo com br>]

Whoa!! Flame war going on! As a "still beginner", could I put my two 
cents on it?

As a GTK "pre-intermediate" user, I share some of the feelings that 
Gerald has about the documentation. There are the GTK Tutorial and the 
GTK Reference manuals, and the Libglade Reference manual is very much 
like them, really. They are pretty useful. But, reading the latest 
messages in the list, this was the FIRST TIME I have ever really heard 
about the "test-libglade.c" file. I know some of you would say "you 
should know what´s being installed in your PC, moron". But, hey, if a 
certain documentation is installed along with the library, you suppose 
that IT is THE documentation -- and, there, the ONLY reference to 
"test-libglade.c" I found was the following:

	"In fact, if you use the glade_xml_signal_autoconnect() function, the 
GUI code could be as simple as the test-libglade.c example that comes 
with libglade."

This surely is not something that tells the reader about the importance 
of this example file. And a good example file in a package is not really 
useful if the user isn´t told about its existante -- unless the user is 
a "bit-brusher" type with a lot of spare time to open and study all the 
files installed by packages.

Although I find the GTK Reference Manual very useful, I miss some 
examples and better explanations for some functions (c´mon. Many of the 
references only enumerate the arguments and the product and type of what 
is returned, kinda like Ctrl-C/Ctrl-V). The GTK Tutorial looks very good 
for this purpose, but it looks like it is not evolving together with 
each GTK 2.x release, and it still misses a lot of information.

I don´t want to blame the developers. I know what Free Software is and 
how much of it is made -- although I REALLY disagree about this "it´s 
all developers could do, if you don´t like it, pay or do it yourself" 
stuff. I have the opinion that Free Software, more than any other, NEEDS 
good documentation, so it can really grow and attract users and 
developers. I know some nice and interesting softwares which simply 
don´t provide docs. And some of the collaboration methods available for 
documentation are good only for those same bit-brushers I mentioned 
before. I don´t want nor feel the need to learn EMACS, TeX, SGML and a 
lot of other old stuff just for adding to an official documentation my 
own observations and experiences which might be useful to other people. 
Most of all, I really can not remember now (I am not saying that there 
isn´t any) an example of software or library which stimulates people to 
write documentation and makes things easier for collaborators.

I think that there could be an official GTK/Glade/Libglade wiki in 
GTK.org, with everything we see in the GTK Tutorial and Reference 
manuals as its base. And then those same manuals should be updated from 
the wiki and distributed in the packages. I am sure that not even my 
mother would say "oh my, you´re a genius!". But I really have no idea 
about why a GTK wiki isn´t implemented yet...

Regards,

Fabricio Rocha
Brasilia, Brasil
The RADiola Project - http://radiola.sourceforge.net

                
_______________________________________________________ 
Yahoo! Mail - Sempre a melhor opção para você! 
Experimente já e veja as novidades. 
http://br.yahoo.com/mailbeta/tudonovo/