Re: Gtk::perl documentation?

[Tom Jennings <tomj wps com>]

On Wed, 2003-04-16 at 15:20, muppet wrote:

> [see below for the answer!]

Yow! No kidding! But first

> the 40k-foot overviews in the API reference and tutorials are good, because
> they introduce the basic concepts for the hard stuff, like TreeView and
> TextBuffer and other such things.

In my mind, the API ref overviews are ground troop implementor level...
as a user of library functions I specifically do *NOT* want to know how
they work, not that it's not interesting... 

Now Stephen Wilhelm's toot
http://personal.riverusers.com/~swilhelm/gtkperl-tutorial/index.html
is great because it describes Gtk in terms of *what it does*; 'buttons
and boxes relate like so'. (The examples are a big help obviously). He
shows what widgets have in common, etc; it's specifically *not* an
alphabetical listing of function calls, which is all the ref provides.
Once I have an idea what a bunch of functions *do*, then I can rummage
around in the ref for specifics and trivia.

At this point I'm either just grousing, or wishing :-) Mostly wishing, I
hope, since there's not a Big Document that I'm missing. Alas, I'm not
an interface sorta person (system & hardware work mostly) so I'll never
be able to devote the time necessary to extend the tutorial.


> ....  there are too many GTK functions to
> document in perl, especially if the docs would be 95% copied.   it's wasteful
> and error-prone.   i think we'd be best off providing a document which
> describes the general principles behind how the bindings map C to perl, and
> detail specific places where the perl API is different from the C one.

Agreed, certainly, as it applies to library interface.


> here's a brain-dump that might serve as the beginnings of that document for
> new-gtk2-perl, which is modelled after gtk-perl:

No kidding! So I take it new-gtk2-perl is more orthogonal than gtk is
now? Are there that many inconsistencies?

>   thus, b = gtk_button_new_with_mnemonic (str); becomes
>   $b = Gtk2::Button->new_with_mnemonic ($str);

Aargh, I guess this should have been obvious, in that a button with a
mnemonic label & a keyboard shortcut is likely a superset of Button, so
it just needs a funny constructor, but once constructed, it's a Button.

Now that I know the answer it's 'obvious' but the line of reasoning
isn't so automatic... (this is turned to design philosophy and highly
subjective, YMMV) I could argue that the above is more inconsistent than
a new class Button_with_mnemonic with a simple constructor 'new' since
we already have many classes (the various button types) all based upon a
more basic class. It's coin-toss time.

I'll have to take a look at what you're doing with new-gtk2-perl, if
only that you're cleaning up the name space! :-) I'd be perfectly happy
if (1) you shotgunned it all down to a vastly reduced number of base
classes (buttons, for instance) and a zillion special
constructor/methods that create all the variants and (2) it became very
popular so I wouldn't have to swim upstream :-( alas, when I write
system tools they gotta run on base install machines, no extra CPAN or
installing modules, an unfortunate but required constraint for me.


>  you can catch a
> croak very easily by wrapping the function in an eval:
>
>    eval { $pixbuf = Gtk2::Gdk::Pixbuf->new_from_file ($filename); };
>    if ($@) {
>         # couldn't open the file, $@ has the message
>    } else {
>         # do something with $pixbuf
>    }

(I wish more people would actually anticipate errors; one python package
I run to glue my email together on my laptop tracebacks when I invoked
it with "--version"! Sheesh! My rule of thumb is: programming is all
error handling. Just look at TCP/IP...)


> there.  just about everything you need to know.  what else?  =)

Umm, can you write my program for me? That would be a big help... 

Seriously, thanks a million for the interface overview. I've actually
saved it and will refer to it. I know it's for new-gtk2, but it appears
to reveal the (better parts of) gtk-perl...

I guess the short answer to my question is, no, there is no other
documentation. However, I will review or at least write up how useful I
find the Linux GTK book when I get it.

tomj