Where to get Gtk-Perl documentation

# Some notes on Gtk-Perl documentation

Firstly, make sure that you have the latest Gtk-Perl (or at least version 0.6123). Older versions have too many errors and omissions.

## HTML

Stephen Wilhelm has finished 21 chapters (14 April 2000) of his excellent online Gtk-Perl tutorial for Gtk-Perl. It follows the Gtk+ style and has some very pretty syntax highlighting for the code examples :)

The Gtk-Perl maintainers have automated the building of documention for the bindings and if you build Gtk-Perl yourself docs should be produced then. Examples of what is produced are the reference manual of modules and functions, and some data structures and types (currently enumerations and flags).

## Gtk-Perl package documentation

- Pod versions of the files are in the build/ directory of each module after you have called 'perl Makefile.PL'.
  You can turn them into cross referenced HTML files by calling e.g.:

            pod2html perl-gtk-ref.pod > perl-gtk-ref.html
            pod2html perl-gtk-ds.pod  > perl-gtk-ds.html

- You may be able to learn something from the Gtk-Perl distribution .xs files
- The file NOTES in Gtk-Perl also gives some programming guidelines and information about Gtk-Perl naming.

## Distribution and source files

- ### Gtk documentation

  Since Gtk-Perl mimics the toolkits so regularly, I use the Gtk+ documentation gtk-docs-html-1.1.1 IIRC a tar.gz from the gtk+ download site There is also a tutorial at www.gtk.org/pub/gtk/tutorial/

  If you have the gtk+ sources, read the .[ch] files

  All the source files are clearly named but the main confusion is likely to come from the Gtk-Perl structure which is much more obviously object oriented. For example, gtk_container_add is bound as Gtk::Container->add() and this method is inherited by all containers. So, to add a widget to a TreeItem that inherits as follows

               GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBin
                                     +----GtkItem
                                           +----GtkTreeItem

  you must get a ref $ti_ref to the TreeItem and then call $ti_ref->add() rather than gtk_conatiner_add() as you would in C.

###

- ### Gnome documentation

  Again, if you have the gnome sources, read the .[ch] files

  /usr/doc/gnome-libs-devel-1.0.8/devel-docs/ in my gnome-libs-devel rpm package or directory devel-docs/ in the CVS dir.

## Mailing lists

A good new source of information about using the Gtk-Perl bindings and Gtk programming in general is the gtk-perl-list mailing list. You can subscribe by sending an email to gtk-perl-list-request@redhat.com with a subject of 'subscribe' (without the quotes). Then follow the instructions that will be emailed to you and confirm the request.

The gtk-perl-list grew out of gtk-list@redhat.com and there is still plenty to learn from that list too.

Please don't post long code examples or attachments and definitely no HTML :-) Also use a meaningful subject line, 'How do I add text to a List in Gtk-Perl' is much better than 'Help, I'm a newbie'