Re: volunteers needed for gtk2-perl documentation

[Matthew Weier OPhinney <matthew-lists weierophinney net>]

-- James Curbo <hannibal adtrw org> wrote
(on Monday, 11 August 2003, 12:40 AM -0500):
> Aha, you've read my mind. I've been pondering on the documentation
> lately (since I sent in that SimpleList patch). I'd be happy to help. 
>
> Something I was thinking about though.. what do you think of pods for
> each class, like gtk-perl had? One side of me thinks they would be nice,
> but another side thinks they'd be hard to keep up and that people should
> just read Gtk2::api and the C docs. I believe a good middle ground would
> be a short example page for each class and *maybe* a listing of methods,

That would be perfect, in my opinion. I've found myself following this
process:

    1. look at the C API
    2. turn to the gtk-demo/ examples to see how to do it in gtk2-perl,
    3. if (2) doesn't have a corresponding example, hammering at it with
       a variety of different methods, until
    4. turning to the list to find out if somebody knows how.
    
A brief example, followed by the methods available, for *each* class
would be tremendously helpful. Particularly helpful, too, would be
documentation when the gtk2-perl method takes different arguments or
different numbers of arguments than the C API.

> with "go read the C docs for more extensive info" at the end. I know a
> couple of times already I've done 'perldoc Gtk2::Treeview' (for
> example)...
>
> James
>
> On Sun, 2003-08-10 at 19:50, muppet wrote:
> > we have several manpages so far, and in 0.93 they are actually linked 
> > together, but we still need:
> >
> > - a FAQ document, e.g. Gtk2::faq, suitable for putting up on the 
> > project homepage as well
> > - a Cookbook/quickstart document -- Gtk2::cookbook and/or 
> > Gtk2::quickstart
> > - extensive editing and proofreading of what we already have
> >
> > any volunteers?
> >
> > everything should be in POD format, of course.
> >
> > i'm already working on binding developer documentation for Glib and 
> > Gtk2, but i think i'm a little too close to the code to write something 
> > aimed at people who don't already know how it works.

-- 
Matthew Weier O'Phinney
http://weierophinney.net/matthew/