Re: GTK+ ref docs - extra introductory sections

[Owen Taylor <otaylor redhat com>]

Damon Chaplin <damon@karuna.freeserve.co.uk> writes:

> I think the GTK+ reference documentation needs a couple of extra introductory
> sections to give an overview of the main features of GTK+.
> 
> Possible sections:
> 
>   The GTK+ object system -
> 	how the structs fit together.
>         the class functions, and how they relate to signals.
>         the standard macros for using objects e.g. GTK_WIDGET ()
>           (I need to update gtk-doc so it adds these to each widget's page as
>            well, with a link to the standard description)
> 	reference counting.

I had imagined this as being in the intro to GtkObject, but
I suppose we can make it an independent section. 
 
>   Signals -
> 	how they are emitted.
> 	what happens during an emission.
> 	how it relates to events from X Windows.
> 	stopping emissions.

We already have a section on signals, right? 

>   Widget layout -
>         how sizes are calculated - size_request/size_allocate, set_usize(),
> 	  default window size.
>         how dynamic changes take place - queuing resizes, the idle function.
>         what is stored in widget->allocation & widget->requisition.
>         how widgets relate to X windows (and maybe MS Windows eventually).
> 	related signals - size_request, size_allocate, configure_event.

This would be useful.
 
>   Widget redrawing -
> 	queuing redraws, queuing clears, APP_PAINTABLE flag,
>         related signals - expose, draw, draw_default, draw_focus.
> 	how it relates to styles & themes.

Hmmm, I had imagined this being in the section for GtkWidget.
I suppose GtkWidget will get rather long though...
 
>   Keyboard handling -
> 	what happens to keyboard events.
> 	keyboard focus & the default widget.
> 	how it relates to keyboard accelerators & bindings.

Sounds reasonable. I had imagined this stuff being scattered
over GtkWidget GtkAccelGroup and Bindings.

> I think these sections are probably more important than most of the
> other docs.  Once people understand the underlying architecture,
> everything else becomes much easier to understand. (Having recently
> understood how the main GLib event loop works, I myself feel a lot
> more confident with GTK+.)
 
We shouldn't lose sight of the fact that this is supposed
to be reference documentation. So, while we definitely
need to document how this all works in detail, I don't
think either Tim or I is going to want to write extensively
tutorial descriptions of this stuff. (Since we are 
already doing that for the non-RDP sections of the
book we are working on).

If somebody else wants to, that's all for the better, of
course.

Regards,
                                        Owen