Re: libglade frustration redux

["Gerald I. Evenden" <geraldi evenden gmail com>]

On Friday 16 February 2007 11:17 pm, Michael Torrie wrote:
> On Fri, 2007-02-16 at 22:13 -0500, Gerald I. Evenden wrote:
> > I believe that much of the above and following issues are reasonably well
> > resolved but there are serious problems with the adequacy of some
> > sections (glib) but I will address these to a specific issue on a
> > subsequent email
>
> I'm not quite sure what kind of documentation you require.  This is the
> second time you've made an assertion like this without specifying a) how
> has the documentation failed you, and b) how can it be improved.  Please
> do so.
>
> thanks.
>
> Michael
From a gnome.org web page there are four example programs from which I will 
select example2 as an sample of incomplete/non-existant documentation.  See

http://www.gnome.org/~newren/tutorials/developing-with-gnome/html/apcs02.html#libglade-example-2-gtk

for the C code.

On line 72 in module main there is a reference to function g_signal_connect.  
I cannot find any reference to this entry in the index

http://developer.gnome.org/doc/API/2.0/gtk/ix01.html
    or
http://developer.gnome.org/doc/API/2.0/glib/ix01.html

By following the glib.h include at the beginning of the example-1.c file I 
managed to grep out a definition in /usr/include/glib-2.0/gobject/g_signal.h 
which is a redefinition of the entry g_signal_connect_data.

If the *.h files are any indication there is a whole group of g_signal_* 
entries BUT I cannot find any description of their usage, even in a printed 
manual on GTK+.

The author of example2.c is probably a GTK guru who (as has been suggested) 
digested all of the sources of GTK/Glib and thus new how to include this 
statement and assumed that everyone else was equally conversant with GTK, et 
al..  But for wet-behind-the-ears beginners the example is of dubious value 
when the documentation of the usage of ALL the GTK/Glib functions included in 
the program is incomplete.

Do I blame the author of example1.c or the authors of the GTK manual?  Someone 
is surely deserving a thousand lashes of a wet noodle.

The reason I was researching this example was that I felt that the example's 
usage of the progress bar widget was not functioning properly; the pulse 
operation does not create any visible effect.

-- 
The whole religious complexion of the modern world is due
to the absence from Jerusalem of a lunatic asylum.
-- Havelock Ellis (1859-1939)  British psychologist