[1-1-0-Merge]

Fri May 29 13:53:57 BST 1998  Tony Gale  <gale@gtk.org>
        [1-1-0-Merge]

        * docs/gtk_tut.sgml:
          - new section on Events
          - change all delete_event callbacks to include
            a GdkEvent parameter
          - clean up the formatting

        * examples - helloworld.c, helloworld2.c, notebook.c,
          packbox.c, pixmap.c, progressbar.c, radiobuttons.c,
          rulers.c, table.c, wheelbarrow.c: change all delete_event
           callbacks to include a GdkEvent parameter.

2 files changed, 2720 insertions, 2330 deletions

diff --git a/docs/gtk_tut.sgml b/docs/gtk_tut.sgml
index 82c381d48..a896d66f4 100644
--- a/docs/gtk_tut.sgml
+++ b/docs/gtk_tut.sgml
@@ -10,7 +10,7 @@
 			      name="&lt;imain@gtk.org&gt;"></tt>,
 Tony Gale <tt><htmlurl url="mailto:gale@gtk.org"
 			      name="&lt;gale@gtk.org&gt;"></tt>
-<date>May 24th, 1998
+<date>May 29th, 1998
 
 <!-- ***************************************************************** -->
 <sect>Introduction
@@ -18,8 +18,8 @@ Tony Gale <tt><htmlurl url="mailto:gale@gtk.org"
 <p>
 GTK (GIMP Toolkit) was originally developed as a toolkit for the GIMP
 (General Image Manipulation Program).  GTK is built on top of GDK (GIMP
-Drawing Kit)  which is basically wrapper around the Xlib functions.  It's
-called the GIMP toolkit because it was original written for developing
+Drawing Kit) which is basically a wrapper around the Xlib functions.  It's
+called the GIMP toolkit because it was originally written for developing
 the GIMP, but has now been used in several free software projects.  The
 authors are
 <itemize>
@@ -31,12 +31,11 @@ authors are
 			   name="jmacd@xcf.berkeley.edu"></tt>
 </itemize>
 
-<p>
 GTK is essentially an object oriented application programmers interface (API).  
 Although written completely in
 C, it is implemented using the idea of classes and callback functions
 (pointers to functions).
-<p>
+
 There is also a third component called glib which contains a few
 replacements for some standard calls, as well as some additional functions
 for handling linked lists etc.  The replacement functions are used to 
@@ -44,7 +43,7 @@ increase GTK's portability, as some of the functions implemented
 here are not available or are nonstandard on other unicies such as 
 g_strerror().   Some also contain enhancements to the libc versions, such as
 g_malloc that has enhanced debugging utilities.
-<p>
+
 This tutorial is an attempt to document as much as possible of GTK, it is by 
 no means complete.  This
 tutorial assumes a good understanding of C, and how to create C programs.
@@ -54,9 +53,9 @@ first widget set, please comment on how you found this tutorial, and what
 you had trouble with.
 Note that there is also a C++ API for GTK (GTK--) in the works, so if you
 prefer to use C++, you should look into this instead.  There's also an
-Objective C wrapper, and guile bindings available, but I don't follow these.
-<p>
-I would very much like to hear any problems you have learning GTK from this
+Objective C wrapper, and Guile bindings available, but I don't follow these.
+
+I would very much like to hear of any problems you have learning GTK from this
 document, and would appreciate input as to how it may be improved.
 
 <!-- ***************************************************************** -->
@@ -70,7 +69,7 @@ You can also view other sources of GTK information on http://www.gtk.org/
 <htmlurl url="http://www.gtk.org/" name="http://www.gtk.org/">.
 GTK uses GNU autoconf for
 configuration.  Once untar'd, type ./configure --help to see a list of options.
-<p>
+
 To begin our introduction to GTK, we'll start with the simplest program 
 possible.  This program will
 create a 200x200 pixel window and has no way of exiting except to be
@@ -94,10 +93,10 @@ int main (int argc, char *argv[])
 }
 </verb></tscreen>
 
-All programs will of course include the gtk/gtk.h which declares the
+All programs will of course include gtk/gtk.h which declares the
 variables, functions, structures etc. that will be used in your GTK 
 application.
-<p>
+
 The next line:
 
 <tscreen><verb>
@@ -119,12 +118,14 @@ of the following:
 <item> <tt/--sync/
 <item> <tt/--show-events/
 <item> <tt/--no-show-events/
+<item> <tt/--name/
+<item> <tt/--class/
 </itemize>
-<p>
+
 It removes these from the argument list, leaving anything it does
-not recognize for your application to parse or ignore.	This creates a set
+not recognize for your application to parse or ignore. This creates a set
 of standard arguments accepted by all GTK applications.
-<p>
+
 The next two lines of code create and display a window.
 
 <tscreen><verb>
@@ -136,10 +137,10 @@ The GTK_WINDOW_TOPLEVEL argument specifies that we want the window to
 undergo window manager decoration and placement. Rather than create a
 window of 0x0 size, a window without children is set to 200x200 by default
 so you can still manipulate it.
-<p>
-The gtk_widget_show() function, lets GTK know that we are done setting the
-attributes of this widget, and it can display it.
-<p>
+
+The gtk_widget_show() function lets GTK know that we are done setting the
+attributes of this widget, and that it can display it.
+
 The last line enters the GTK main processing loop.
 
 <tscreen><verb>
@@ -158,7 +159,7 @@ OK, now for a program with a widget (a button).  It's the classic hello
 world ala GTK.
 
 <tscreen><verb>
-/* helloworld.c */
+/* example-start helloworld/helloworld.c */
 
 #include <gtk/gtk.h>
 
@@ -169,7 +170,7 @@ void hello (GtkWidget *widget, gpointer data)
     g_print ("Hello World\n");
 }
 
-gint delete_event(GtkWidget *widget, gpointer data)
+gint delete_event(GtkWidget *widget, GdkEvent *event, gpointer data)
 {
     g_print ("delete event occured\n");
     /* if you return FALSE in the "delete_event" signal handler,
@@ -204,10 +205,10 @@ int main (int argc, char *argv[])
     window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
     
     /* when the window is given the "delete_event" signal (this is given
-    * by the window manager (usually the 'close' option, or on the
+    * by the window manager, usually by the 'close' option, or on the
     * titlebar), we ask it to call the delete_event () function
     * as defined above.  The data passed to the callback
-    * function is NULL and is ignored in the callback. */
+    * function is NULL and is ignored in the callback function. */
     gtk_signal_connect (GTK_OBJECT (window), "delete_event",
 			GTK_SIGNAL_FUNC (delete_event), NULL);
     
@@ -251,6 +252,7 @@ int main (int argc, char *argv[])
     
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
@@ -262,7 +264,6 @@ To compile use:
 gcc -Wall -g helloworld.c -o hello_world `gtk-config --cflags` \
     `gtk-config --libs`
 </verb></tscreen>
-<p>
 
 This uses the program <tt>gtk-config</>, which comes with gtk. This
 program 'knows' what compiler switches are needed to compile programs
@@ -271,7 +272,6 @@ directories for the compiler to look in, and <tt>gtk-config --libs</>
 will output the list of libraries for the compiler to link with and
 the directories to find them in.
 
-<p>
 The libraries that are usually linked in are:
 <itemize>
 <item>The GTK library (-lgtk), the widget library, based on top of GDK.
@@ -289,65 +289,72 @@ pixmaps and other X extensions.
 <!-- ----------------------------------------------------------------- -->
 <sect1>Theory of Signals and Callbacks
 <p>
-Before we look in detail at hello world, we'll discuss events and callbacks.
+Before we look in detail at hello world, we'll discuss signals and callbacks.
 GTK is an event driven toolkit, which means it will sleep in
 gtk_main until an event occurs and control is passed to the appropriate
 function.
-<p>
+
 This passing of control is done using the idea of "signals".  When an 
 event occurs, such as the press of a mouse button, the
 appropriate signal will be "emitted" by the widget that was pressed.  
-This is how GTK does
-most of its useful work.  To make a button perform an action, 
-we set up a signal handler to catch these
+This is how GTK does most of its useful work. There are a set of signals
+that all widgets inherit, such as "destroy", and there are signals that are
+widget specific, such as "toggled" on a toggle button.
+
+To make a button perform an action, we set up a signal handler to catch these
 signals and call the appropriate function.  This is done by using a 
 function such as:
 
 <tscreen><verb>
-gint gtk_signal_connect (GtkObject *object,
-                         gchar *name,
-			 GtkSignalFunc func,
-			 gpointer func_data);
+gint gtk_signal_connect( GtkObject     *object,
+                         gchar         *name,
+                         GtkSignalFunc  func,
+                         gpointer       func_data );
 </verb></tscreen>
-<p>
+
 Where the first argument is the widget which will be emitting the signal, and
 the second, the name of the signal you wish to catch.  The third is the function
 you wish to be called when it is caught, and the fourth, the data you wish
 to have passed to this function.
-<p>
+
 The function specified in the third argument is called a "callback
-function", and should be of the form:
+function", and should generally be of the form:
 
 <tscreen><verb>
-void callback_func(GtkWidget *widget, gpointer callback_data);
+void callback_func( GtkWidget *widget,
+                    gpointer   callback_data );
 </verb></tscreen>
-<p>
-Where the first argument will be a pointer to the widget that emitted the signal, and
-the second, a pointer to the data given as the last argument to the
-gtk_signal_connect() function as shown above.
-<p>
+
+Where the first argument will be a pointer to the widget that emitted the 
+signal, and the second, a pointer to the data given as the last argument
+to the gtk_signal_connect() function as shown above.
+
+Note that the above form for a signal callback function declaration is
+only a general guide, as some widget specific signals generate different
+calling parameters. For example, the GtkCList "select_row" signal provides
+both row and column parameters.
+
 Another call used in the hello world example, is:
 
 <tscreen><verb>
-gint gtk_signal_connect_object (GtkObject *object,
-                                gchar  *name,
-				GtkSignalFunc func,
-				GtkObject *slot_object);
+gint gtk_signal_connect_object( GtkObject     *object,
+                                gchar         *name,
+                                GtkSignalFunc  func,
+                                GtkObject     *slot_object );
 </verb></tscreen>
-<p>
+
 gtk_signal_connect_object() is the same as gtk_signal_connect() except that
-the callback function only uses one argument, a
-pointer to a GTK 
-object.  So when using this function to connect signals, the callback should be of
-the form:
+the callback function only uses one argument, a pointer to a GTK 
+object.  So when using this function to connect signals, the callback
+should be of the form:
 
 <tscreen><verb>
-void callback_func (GtkObject *object);
+void callback_func( GtkObject *object );
 </verb></tscreen>
-<p>
+
 Where the object is usually a widget.  We usually don't setup callbacks for
 gtk_signal_connect_object however.  They are usually used 
-to call a GTK function that accept a single widget or object as an
+to call a GTK function that accepts a single widget or object as an
 argument, as is the case in our hello world example.
 
 The purpose of having two functions to connect signals is simply to allow
@@ -357,11 +364,133 @@ want to use the gtk_signal_connect_object() for these, whereas for your
 functions, you may need to have additional data supplied to the callbacks.
 
 <!-- ----------------------------------------------------------------- -->
+<sect1>Events
+<p>
+In addition to the signal mechanism described above, there are a set of
+<em>events</em> that reflect the X event mechanism. Callbacks may also be
+attached to these events. These events are:
+
+<itemize>
+<item> event
+<item> button_press_event
+<item> button_release_event
+<item> motion_notify_event
+<item> delete_event
+<item> destroy_event
+<item> expose_event
+<item> key_press_event
+<item> key_release_event
+<item> enter_notify_event
+<item> leave_notify_event
+<item> configure_event
+<item> focus_in_event
+<item> focus_out_event
+<item> map_event
+<item> unmap_event
+<item> property_notify_event
+<item> selection_clear_event
+<item> selection_request_event
+<item> selection_notify_event
+<item> proximity_in_event
+<item> proximity_out_event
+<item> drag_begin_event
+<item> drag_request_event
+<item> drag_end_event
+<item> drop_enter_event
+<item> drop_leave_event
+<item> drop_data_available_event
+<item> other_event
+</itemize>
+
+In order to connect a callback function to one of these events, you use
+the function gtk_signal_connect, as described above, using one of the
+above event names as the <tt/name/ parameter. The callback function for
+events has a slighty different form than that for signals:
+
+<tscreen><verb>
+void callback_func( GtkWidget *widget,
+                    GdkEvent  *event,
+                    gpointer   callback_data );
+</verb></tscreen>
+
+GdkEvent is a C <tt/union/ structure whose type will depend upon which of the
+above events has occured. In order for us to tell which event has been issued
+each of the possible alternatives has a <tt/type/ parameter which reflects the
+event being issued. The other components of the event structure will depend
+upon the type of the event. Possible values for the type are:
+
+<tscreen><verb>
+  GDK_NOTHING
+  GDK_DELETE
+  GDK_DESTROY
+  GDK_EXPOSE
+  GDK_MOTION_NOTIFY
+  GDK_BUTTON_PRESS
+  GDK_2BUTTON_PRESS
+  GDK_3BUTTON_PRESS
+  GDK_BUTTON_RELEASE
+  GDK_KEY_PRESS
+  GDK_KEY_RELEASE
+  GDK_ENTER_NOTIFY
+  GDK_LEAVE_NOTIFY
+  GDK_FOCUS_CHANGE
+  GDK_CONFIGURE
+  GDK_MAP
+  GDK_UNMAP
+  GDK_PROPERTY_NOTIFY
+  GDK_SELECTION_CLEAR
+  GDK_SELECTION_REQUEST
+  GDK_SELECTION_NOTIFY
+  GDK_PROXIMITY_IN
+  GDK_PROXIMITY_OUT
+  GDK_DRAG_BEGIN
+  GDK_DRAG_REQUEST
+  GDK_DROP_ENTER
+  GDK_DROP_LEAVE
+  GDK_DROP_DATA_AVAIL
+  GDK_CLIENT_EVENT
+  GDK_VISIBILITY_NOTIFY
+  GDK_NO_EXPOSE
+  GDK_OTHER_EVENT	/* Deprecated, use filters instead */
+</verb></tscreen>
+
+So, to connect a callback function to one of these events we would use
+something like
+
+<tscreen><verb>
+gtk_signal_connect( GTK_OBJECT(button), "button_press_event",
+                    GTK_SIGNAL_FUNC(button_press_callback), 
+		        NULL);
+</verb></tscreen>
+
+This assumes that <tt/button/ is a GtkButton widget. Now, when the mouse is
+over the button and a mouse button is pressed, the function 
+<tt/button_press_callback/ will be called. This function may be declared as:
+
+<tscreen><verb>
+static gint button_press_event (GtkWidget      *widget, 
+                                GdkEventButton *event,
+                                gpointer        data);
+</verb></tscreen>
+
+Note that we can declare the second argument as type <tt/GdkEventButton/
+as we know what type of event will occur for this function to be called.
+
+<!-- Need an Annex with all the event types in it - TRG -->
+
+<!-- Need to check this - TRG
+The value returned from this function indicates whether the event should
+be processed further by the GTK event handling mechanism. Returning
+TRUE indicates that the event has been handled, and that it should not
+propogate further. Returning FALSE continues the normal event handling.
+-->
+
+<!-- ----------------------------------------------------------------- -->
 <sect1>Stepping Through Hello World
 <p>
 Now that we know the theory behind this, lets clarify by walking through 
 the example hello world program.
-<p>
+
 Here is the callback function that will be called when the button is
 "clicked".  We ignore both the widget and the data in this example, but it 
 is not hard to do things with them.  The next example will use the data 
@@ -374,7 +503,6 @@ void hello (GtkWidget *widget, gpointer data)
 }
 </verb></tscreen>
 
-<p>
 This callback is a bit special.  The "delete_event" occurs when the
 window manager sends this event to the application.  We have a choice here
 as to what to do about these events.  We can ignore them, make some sort of
@@ -387,7 +515,7 @@ ask that "destroy" is emitted, which in turn will call our "destroy"
 signal handler.
 
 <tscreen><verb>
-gint delete_event(GtkWidget *widget, gpointer data)
+gint delete_event(GtkWidget *widget, GdkEvent *event, gpointer data)
 {
     g_print ("delete event occured\n");
 
@@ -395,7 +523,6 @@ gint delete_event(GtkWidget *widget, gpointer data)
 }
 </verb></tscreen>
 
-<p>
 Here is another callback function which causes the program to quit by calling
 gtk_main_quit().  This function tells GTK that it is to exit from gtk_main
 when control is returned to it.
@@ -407,73 +534,79 @@ void destroy (GtkWidget *widget, gpointer data)
 }
 </verb></tscreen>
 
-<p>
 I assume you know about the main() function... yes, as with other
 applications, all GTK applications will also have one of these.
+
 <tscreen><verb>
 int main (int argc, char *argv[])
 {
 </verb></tscreen>
-<p>
+
 This next part, declares a pointer to a structure of type GtkWidget.  These
 are used below to create a window and a button.
+
 <tscreen><verb>
     GtkWidget *window;
     GtkWidget *button;
 </verb></tscreen>
-<p>
-Here is our gtk_init again.  As before, this initializes the toolkit, and
+
+Here is our gtk_init again. As before, this initializes the toolkit, and
 parses the arguments found on the command line.  Any argument it
 recognizes from the command line, it removes from the list, and modifies
 argc and argv to make it look like they never existed, allowing your
 application to parse the remaining arguments.
+
 <tscreen><verb>
     gtk_init (&amp;argc, &amp;argv);
 </verb></tscreen>
-<p>
+
 Create a new window.  This is fairly straight forward.  Memory is allocated
 for the GtkWidget *window structure so it now points to a valid structure.
-It sets up a new window, but it is not displayed until below where we call
+It sets up a new window, but it is not displayed until we call
 gtk_widget_show(window) near the end of our program.
+
 <tscreen><verb>
     window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
 </verb></tscreen>
-<p>
-Here is an example of connecting a signal handler to an object, in this case, the
-window.  Here, the "destroy" signal is caught.  This is emitted when we use
-the window manager to kill the window (and we return TRUE in the
-"delete_event" handler), or when we use the
+
+Here is an example of connecting a signal handler to an object, in
+this case, the window.  Here, the "destroy" signal is caught.  This is
+emitted when we use the window manager to kill the window (and we return
+TRUE in the "delete_event" handler), or when we use the
 gtk_widget_destroy() call passing in the window widget as the object to
-destroy.  By setting this up, we handle both cases with a single call.
+destroy. By setting this up, we handle both cases with a single call.
 Here, it just calls the destroy() function defined above with a NULL
 argument, which quits GTK for us.  
-<p>
-The GTK_OBJECT and GTK_SIGNAL_FUNC are macros that perform type casting and
-checking for us, as well as aid the readability of the code.
+
+The GTK_OBJECT and GTK_SIGNAL_FUNC are macros that perform type 
+casting and checking for us, as well as aid the readability of the code.
+
 <tscreen><verb>
     gtk_signal_connect (GTK_OBJECT (window), "destroy",
-			GTK_SIGNAL_FUNC (destroy), NULL);
+                        GTK_SIGNAL_FUNC (destroy), NULL);
 </verb></tscreen>
-<p>
+
 This next function is used to set an attribute of a container object.  
 This just sets the window
 so it has a blank area along the inside of it 10 pixels wide where no
 widgets will go.  There are other similar functions which we will look at 
 in the section on 
 <ref id="sec_setting_widget_attributes" name="Setting Widget Attributes">
-<p>
+
 And again, GTK_CONTAINER is a macro to perform type casting.
+
 <tscreen><verb>
     gtk_container_border_width (GTK_CONTAINER (window), 10);
 </verb></tscreen>
-<p>
+
 This call creates a new button.  It allocates space for a new GtkWidget
 structure in memory, initializes it, and makes the button pointer point to
-it.  It will have the label "Hello World" on it when displayed.
+it. It will have the label "Hello World" on it when displayed.
+
 <tscreen><verb>
     button = gtk_button_new_with_label ("Hello World");
 </verb></tscreen>
-<p>
+
 Here, we take this button, and make it do something useful.  We attach a
 signal handler to it so when it emits the "clicked" signal, our hello()
 function is called.  The data is ignored, so we simply pass in NULL to the
@@ -482,71 +615,78 @@ we click the button with our mouse pointer.
 
 <tscreen><verb>
     gtk_signal_connect (GTK_OBJECT (button), "clicked",
-			GTK_SIGNAL_FUNC (hello), NULL);
+                        GTK_SIGNAL_FUNC (hello), NULL);
 </verb></tscreen>
-<p>
+
 We are also going to use this button to exit our program.  This will
 illustrate how the "destroy"
 signal may come from either the window manager, or our program.  When the
 button is "clicked", same as above, it calls the first hello() callback function,
 and then this one in the order they are set up.  You may have as many
-callback function as you need, and all will be executed in the order you
+callback functions as you need, and all will be executed in the order you
 connected them.  Because the gtk_widget_destroy() function accepts only a
 GtkWidget *widget as an argument, we use the gtk_signal_connect_object()
 function here instead of straight gtk_signal_connect().
 
 <tscreen><verb>
-    gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
-			       GTK_SIGNAL_FUNC (gtk_widget_destroy),
-			       GTK_OBJECT (window));
+gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
+                           GTK_SIGNAL_FUNC (gtk_widget_destroy),
+                           GTK_OBJECT (window));
 </verb></tscreen>
-<p>
+
 This is a packing call, which will be explained in depth later on.  But it
 is fairly easy to understand.  It simply tells GTK that the button is to be 
-placed in the window where it will be displayed.
+placed in the window where it will be displayed. Note that a GTK container
+can only contain one widget. There are other widgets, that are described later,
+which are designed to layout multiple widgets in various ways.
+ 
 <tscreen><verb>
     gtk_container_add (GTK_CONTAINER (window), button);
 </verb></tscreen>
-<p>
+
 Now that we have everything setup the way we want it to be.  With all the
 signal handlers in place, and the button placed in the window where it
 should be, we ask GTK to "show" the widgets on the screen.  The window
 widget is shown last so the whole window will pop up at once rather than
 seeing the window pop up, and then the button form inside of it.  Although
-with such simple example, you'd never notice.
+with such a simple example, you'd never notice.
+
 <tscreen><verb>
     gtk_widget_show (button);
 
     gtk_widget_show (window);
 </verb></tscreen>
-<p>
+
 And of course, we call gtk_main() which waits for events to come from the X
 server and will call on the widgets to emit signals when these events come.
+
 <tscreen><verb>
     gtk_main ();
 </verb></tscreen>
+
 And the final return.  Control returns here after gtk_quit() is called.
+
 <tscreen><verb>
     return 0;
 </verb></tscreen>
-<p>
+
 Now, when we click the mouse button on a GTK button, the
-widget emits a "clicked" signal.  In order for us to use this information, our
-program sets up a signal handler to catch that signal, which dispatches the function 
-of our choice. In our example, when the button we created is "clicked", the 
-hello() function is called with a NULL
+widget emits a "clicked" signal.  In order for us to use this
+information, our program sets up a signal handler to catch that signal, 
+which dispatches the function of our choice. In our example, when the 
+button we created is "clicked", the hello() function is called with a NULL
 argument, and then the next handler for this signal is called.  This calls
 the gtk_widget_destroy() function, passing it the window widget as it's
 argument, destroying the window widget.  This causes the window to emit the 
-"destroy" signal, which is
-caught, and calls our destroy() callback function, which simply exits GTK.
-<p>
+"destroy" signal, which is caught, and calls our destroy() callback 
+function, which simply exits GTK.
+
 Another course of events, is to use the window manager to kill the window.
 This will cause the "delete_event" to be emitted.  This will call our
 "delete_event" handler.  If we return TRUE here, the window will be left as
 is and nothing will happen.  Returning FALSE will cause GTK to emit the
 "destroy" signal which of course, calls the "destroy" callback, exiting GTK.
-<p>
+
 Note that these signals are not the same as the Unix system
 signals, and are not implemented using them, although the terminology is
 almost identical.
@@ -559,17 +699,17 @@ almost identical.
 <sect1>Data Types
 <p>
 There are a few things you probably noticed in the previous examples that
-need explaining.  The 
-gint, gchar etc. that you see are typedefs to int and char respectively.  This is done
-to get around that nasty dependency on the size of simple data types when doing calculations.
-A good example is "gint32" which will be
-typedef'd to a 32 bit integer for any given platform, whether it be the 64 bit
-alpha, or the 32 bit i386.  The
+need explaining.  The gint, gchar etc. that you see are typedefs to int and 
+char respectively.  This is done to get around that nasty dependency on the 
+size of simple data types when doing calculations.
+
+A good example is "gint32" which will be typedef'd to a 32 bit integer for
+any given platform, whether it be the 64 bit alpha, or the 32 bit i386.  The
 typedefs are very straight forward and intuitive.  They are all defined in
 glib/glib.h (which gets included from gtk.h).
-<p>
-You'll also notice the ability to use GtkWidget when the function calls for a GtkObject.  
-GTK is an object oriented design, and a widget is an object.
+
+You'll also notice the ability to use GtkWidget when the function calls for 
+a GtkObject. GTK is an object oriented design, and a widget is an object.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>More on Signal Handlers
@@ -577,20 +717,24 @@ GTK is an object oriented design, and a widget is an object.
 Lets take another look at the gtk_signal_connect declaration.
 
 <tscreen><verb>
-gint gtk_signal_connect (GtkObject *object, gchar *name,
-			 GtkSignalFunc func, gpointer func_data);
+gint gtk_signal_connect( GtkObject *object,
+                         gchar *name,
+                         GtkSignalFunc func,
+                         gpointer func_data );
 </verb></tscreen>
 
 Notice the gint return value ?  This is a tag that identifies your callback
 function.  As said above, you may have as many callbacks per signal and per
 object as you need, and each will be executed in turn, in the order they 
-were attached.  
+were attached.
 
 This tag allows you to remove this callback from the list by using:
+
 <tscreen><verb>
-void gtk_signal_disconnect (GtkObject *object,
-                            gint id);
+void gtk_signal_disconnect( GtkObject *object,
+                            gint id );
 </verb></tscreen>
+
 So, by passing in the widget you wish to remove the handler from, and the
 tag or id returned by one of the signal_connect functions, you can
 disconnect a signal handler.
@@ -598,7 +742,7 @@ disconnect a signal handler.
 Another function to remove all the signal handers from an object is:
 
 <tscreen><verb>
-gtk_signal_handlers_destroy (GtkObject *object);
+void gtk_signal_handlers_destroy( GtkObject *object );
 </verb></tscreen>
 
 This call is fairly self explanatory.  It simply removes all the current
@@ -612,7 +756,7 @@ of callbacks.  This will also introduce us to our next topic, packing
 widgets.
 
 <tscreen><verb>
-/* helloworld2.c */
+/* example-start helloworld2/helloworld2.c */
 
 #include <gtk/gtk.h>
 
@@ -624,7 +768,7 @@ void callback (GtkWidget *widget, gpointer data)
 }
 
 /* another callback */
-void delete_event (GtkWidget *widget, gpointer data)
+void delete_event (GtkWidget *widget, GdkEvent *event, gpointer data)
 {
     gtk_main_quit ();
 }
@@ -703,6 +847,7 @@ int main (int argc, char *argv[])
 
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 Compile this program using the same linking arguments as our first example.
@@ -720,42 +865,41 @@ differently and should be used for transient windows.
 <!-- ***************************************************************** -->
 <sect>Packing Widgets
 <!-- ***************************************************************** -->
-
 <p>
-When creating an application, you'll want to put more than one button
+When creating an application, you'll want to put more than one widget
 inside a window.  Our first hello world example only used one widget so we
 could simply use a gtk_container_add call to "pack" the widget into the
 window.  But when you want to put more than one widget into a window, how
-do you control where that widget is positioned ?  This is where packing
+do you control where that widget is positioned? This is where packing
 comes in.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Theory of Packing Boxes
 <p>
 Most packing is done by creating boxes as in the example above.  These are
-invisible widget containers that we can pack our widgets into and come in
+invisible widget containers that we can pack our widgets into which come in
 two forms, a horizontal box, and a vertical box.  When packing widgets
 into a horizontal box, the objects are inserted horizontally from left to
 right or right to left depending on the call used. In a vertical box,
 widgets are packed from top to bottom or vice versa.  You may use any
 combination of boxes inside or beside other boxes to create the desired
 effect.
-<p>
+
 To create a new horizontal box, we use a call to gtk_hbox_new(), and for
-vertical boxes, gtk_vbox_new().  The gtk_box_pack_start() and
+vertical boxes, gtk_vbox_new(). The gtk_box_pack_start() and
 gtk_box_pack_end() functions are used to place objects inside of these
 containers.  The gtk_box_pack_start() function will start at the top and
 work its way down in a vbox, and pack left to right in an hbox.
 gtk_box_pack_end() will do the opposite, packing from bottom to top in a
 vbox, and right to left in an hbox.  Using these functions allow us to
 right justify or left justify our widgets and may be mixed in any way to
-achieve the desired effect.  We will use gtk_box_pack_start() in most of
-our examples.  An object may be another container or a widget.	And in
-fact, many widgets are actually containers themselves including the
+achieve the desired effect. We will use gtk_box_pack_start() in most of
+our examples.  An object may be another container or a widget. In
+fact, many widgets are actually containers themselves, including the
 button, but we usually only use a label inside a button.
-<p>
+
 By using these calls, GTK knows where you want to place your widgets so it
-can do automatic resizing and other nifty things.  there's also a number
+can do automatic resizing and other nifty things. There's also a number
 of options as to how your widgets should be packed. As you can imagine,
 this method gives us a quite a bit of flexibility when placing and
 creating widgets.
@@ -766,9 +910,8 @@ creating widgets.
 Because of this flexibility, packing boxes in GTK can be confusing at
 first. There are a lot of options, and it's not immediately obvious how
 they all fit together.	In the end however, there are basically five
-different styles you can get.
+different styles.
 
-<p>
 <? <CENTER> >
 <?
 <IMG SRC="gtk_tut_packbox1.gif" VSPACE="15" HSPACE="10" WIDTH="528" HEIGHT="235"
@@ -779,51 +922,50 @@ ALT="Box Packing Example Image">
 Each line contains one horizontal box (hbox) with several buttons. The
 call to gtk_box_pack is shorthand for the call to pack each of the buttons
 into the hbox. Each of the buttons is packed into the hbox the same way
-(i.e. same arguments to the gtk_box_pack_start () function).
-<p>
+(i.e. same arguments to the gtk_box_pack_start() function).
+
 This is the declaration of the gtk_box_pack_start function.
 
 <tscreen><verb>
-void gtk_box_pack_start (GtkBox    *box,
-			 GtkWidget *child,
-			 gint	    expand,
-			 gint	    fill,
-			 gint	    padding);
+void gtk_box_pack_start( GtkBox    *box,
+                         GtkWidget *child,
+                         gint       expand,
+                         gint       fill,
+                         gint       padding );
 </verb></tscreen>
 
 The first argument is the box you are packing the object into, the second
-is this object.  The objects will all be buttons for now, so we'll be
+is the object. The objects will all be buttons for now, so we'll be
 packing buttons into boxes.
-<p>
-The expand argument to gtk_box_pack_start() or gtk_box_pack_end() controls
+
+The expand argument to gtk_box_pack_start() and gtk_box_pack_end() controls
 whether the widgets are laid out in the box to fill in all the extra space
 in the box so the box is expanded to fill the area alloted to it (TRUE).
-Or the box is shrunk to just fit the widgets (FALSE).  Setting expand to
-FALSE will allow you to do right and left
-justifying of your widgets.  Otherwise, they will all expand to fit in the
-box, and the same effect could be achieved by using only one of
-gtk_box_pack_start or pack_end functions.
-<p>
+Or the box is shrunk to just fit the widgets (FALSE). Setting expand to
+FALSE will allow you to do right and left justification of your widgets.
+Otherwise, they will all expand to fit into the box, and the same effect
+could be achieved by using only one of gtk_box_pack_start or pack_end functions.
+
 The fill argument to the gtk_box_pack functions control whether the extra
 space is allocated to the objects themselves (TRUE), or as extra padding
 in the box around these objects (FALSE). It only has an effect if the
 expand argument is also TRUE.
-<p>
+
 When creating a new box, the function looks like this:
 
 <tscreen><verb>
-GtkWidget * gtk_hbox_new (gint homogeneous,
-			  gint spacing);
+GtkWidget *gtk_hbox_new (gint homogeneous,
+                         gint spacing);
 </verb></tscreen>
 
 The homogeneous argument to gtk_hbox_new (and the same for gtk_vbox_new)
 controls whether each object in the box has the same size (i.e. the same
 width in an hbox, or the same height in a vbox). If it is set, the expand
 argument to the gtk_box_pack routines is always turned on.
-<p>
+
 What's the difference between spacing (set when the box is created) and
 padding (set when elements are packed)? Spacing is added between objects,
-and padding is added on either side of an object.  The following figure
+and padding is added on either side of an object. The following figure
 should make it clearer:
 
 <? <CENTER> >
@@ -834,19 +976,19 @@ VSPACE="15" HSPACE="10" ALT="Box Packing Example Image">
 <? </CENTER> >
 
 Here is the code used to create the above images.  I've commented it fairly
-heavily so hopefully you won't have any problems following it.  Compile it yourself
-and play with it.
+heavily so hopefully you won't have any problems following it.  Compile it 
+yourself and play with it.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Packing Demonstration Program
 <p>
 <tscreen><verb>
-/* packbox.c */
+/* example-start packbox/packbox.c */
 
 #include "gtk/gtk.h"
 
 void
-delete_event (GtkWidget *widget, gpointer data)
+delete_event (GtkWidget *widget, GdkEvent *event, gpointer data)
 {
     gtk_main_quit ();
 }
@@ -1124,6 +1266,7 @@ main (int argc, char *argv[])
     
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
@@ -1132,26 +1275,27 @@ main (int argc, char *argv[])
 Let's take a look at another way of packing - Tables.  These can be
 extremely useful in certain situations.
 
-Using tables, we create a grid that we can place widgets in.  The widgets
+Using tables, we create a grid that we can place widgets in. The widgets
 may take up as many spaces as we specify.
 
 The first thing to look at of course, is the gtk_table_new function:
 
 <tscreen><verb>
-GtkWidget* gtk_table_new (gint rows,
+GtkWidget *gtk_table_new( gint rows,
                           gint columns,
-                          gint homogeneous);
+                          gint homogeneous );
 </verb></tscreen>
-<p>
+
 The first argument is the number of rows to make in the table, while the
-second, obviously, the number of columns.
+second, obviously, is the number of columns.
 
-The homogeneous argument has to do with how the table's boxes are sized.  If homogeneous 
-is TRUE, the table boxes are resized to the size of the largest widget in the table.
-If homogeneous is FALSE, the size of a table boxes is dictated by the tallest widget 
-in its same row, and the widest widget in its column.
+The homogeneous argument has to do with how the table's boxes are sized. If
+homogeneous is TRUE, the table boxes are resized to the size of the largest
+widget in the table. If homogeneous is FALSE, the size of a table boxes is 
+dictated by the tallest widget in its same row, and the widest widget in its
+column.
 
-The rows and columnts are laid out starting with 0 to n, where n was the
+The rows and columnts are laid out from 0 to n, where n was the
 number specified in the call to gtk_table_new.  So, if you specify rows = 2 and 
 columns = 2, the layout would look something like this:
 
@@ -1163,35 +1307,34 @@ columns = 2, the layout would look something like this:
  |          |          |
 2+----------+----------+
 </verb></tscreen>
-<p>
+
 Note that the coordinate system starts in the upper left hand corner.  To place a 
 widget into a box, use the following function:
 
 <tscreen><verb>
-void gtk_table_attach (GtkTable      *table,
-                       GtkWidget     *child,
-		       gint           left_attach,
-		       gint           right_attach,
-		       gint           top_attach,
-		       gint           bottom_attach,
-		       gint           xoptions,
-		       gint           yoptions,
-		       gint           xpadding,
-		       gint           ypadding);
+void gtk_table_attach( GtkTable  *table,
+                       GtkWidget *child,
+                       gint       left_attach,
+                       gint       right_attach,
+                       gint       top_attach,
+                       gint       bottom_attach,
+                       gint       xoptions,
+                       gint       yoptions,
+                       gint       xpadding,
+                       gint       ypadding );
 </verb></tscreen>				       
-<p>
+
 Where the first argument ("table") is the table you've created and the second
 ("child") the widget you wish to place in the table.
 
-The left and right attach 
-arguments specify where to place the widget, and how many boxes to use.  If you want 
-a button in the lower right table entry 
+The left and right attach arguments specify where to place the widget, and how
+many boxes to use. If you want a button in the lower right table entry 
 of our 2x2 table, and want it to fill that entry ONLY.  left_attach would be = 1, 
 right_attach = 2, top_attach = 1, bottom_attach = 2.
 
 Now, if you wanted a widget to take up the whole 
-top row of our 2x2 table, you'd use left_attach = 0, right_attach =2, top_attach = 0, 
-bottom_attach = 1.
+top row of our 2x2 table, you'd use left_attach = 0, right_attach = 2,
+top_attach = 0, bottom_attach = 1.
 
 The xoptions and yoptions are used to specify packing options and may be OR'ed 
 together to allow multiple options.  
@@ -1217,31 +1360,33 @@ specified in pixels.
 gtk_table_attach() has a LOT of options.  So, there's a shortcut:
 
 <tscreen><verb>
-void gtk_table_attach_defaults (GtkTable   *table,
-                                GtkWidget  *widget,
-				gint        left_attach,
-				gint        right_attach,
-				gint        top_attach,
-				gint        bottom_attach);
+void gtk_table_attach_defaults( GtkTable  *table,
+                                GtkWidget *widget,
+                                gint       left_attach,
+                                gint       right_attach,
+                                gint       top_attach,
+                                gint       bottom_attach );
 </verb></tscreen>
 
 The X and Y options default to GTK_FILL | GTK_EXPAND, and X and Y padding
-are set to 0.  The rest of the arguments are identical to the previous
+are set to 0. The rest of the arguments are identical to the previous
 function.
 
-We also have gtk_table_set_row_spacing() and gtk_table_set_col_spacing(). 
+We also have gtk_table_set_row_spacing() and gtk_table_set_col_spacing().
 This places spacing between the rows at the specified row or column.
 
 <tscreen><verb>
-void gtk_table_set_row_spacing (GtkTable      *table,
-                                gint           row,
-				gint           spacing);
+void gtk_table_set_row_spacing( GtkTable *table,
+                                gint      row,
+                                gint      spacing );
 </verb></tscreen>
+
 and
+
 <tscreen><verb>
-void       gtk_table_set_col_spacing  (GtkTable      *table,
-                                       gint           column,
-				       gint           spacing);
+void gtk_table_set_col_spacing ( GtkTable *table,
+                                 gint      column,
+                                 gint      spacing );
 </verb></tscreen>
 
 Note that for columns, the space goes to the right of the column, and for 
@@ -1250,16 +1395,17 @@ rows, the space goes below the row.
 You can also set a consistent spacing of all rows and/or columns with:
 
 <tscreen><verb>
-void gtk_table_set_row_spacings (GtkTable *table,
-                                 gint      spacing);
+void gtk_table_set_row_spacings( GtkTable *table,
+                                 gint      spacing );
 </verb></tscreen>
-<p>
+
 And,
+
 <tscreen><verb>
-void gtk_table_set_col_spacings (GtkTable  *table,
-                                 gint       spacing);
+void gtk_table_set_col_spacings( GtkTable *table,
+                                 gint      spacing );
 </verb></tscreen>
-<p>
+
 Note that with these calls, the last row and last column do not get any 
 spacing.
 
@@ -1270,7 +1416,7 @@ Here we make a window with three buttons in a 2x2 table.
 The first two buttons will be placed in the upper row.
 A third, quit button, is placed in the lower row, spanning both columns.
 Which means it should look something like this:
-<p>
+
 <? <CENTER> >
 <?
 <IMG SRC="gtk_tut_table.gif" VSPACE="15" HSPACE="10" 
@@ -1281,7 +1427,7 @@ ALT="Table Packing Example Image" WIDTH="180" HEIGHT="120">
 Here's the source code:
 
 <tscreen><verb>
-/* table.c */
+/* example-start table/table.c */
 #include <gtk/gtk.h>
 
 /* our callback.
@@ -1292,7 +1438,7 @@ void callback (GtkWidget *widget, gpointer data)
 }
 
 /* this callback quits the program */
-void delete_event (GtkWidget *widget, gpointer data)
+void delete_event (GtkWidget *widget, GdkEvent *event, gpointer data)
 {
     gtk_main_quit ();
 }
@@ -1373,18 +1519,20 @@ int main (int argc, char *argv[])
 
     return 0;
 }
+/* example-end */
 </verb></tscreen>
+
 <!-- ***************************************************************** -->
 <sect>Widget Overview
 <!-- ***************************************************************** -->
-
 <p>
 The general steps to creating a widget in GTK are:
 <enum>
 <item> gtk_*_new - one of various functions to create a new widget.  These
 are all detailed in this section.
 
-<item> Connect all signals we wish to use to the appropriate handlers.
+<item> Connect all signals and events we wish to use to the
+appropriate handlers.
 
 <item> Set the attributes of the widget.
 
@@ -1393,16 +1541,15 @@ gtk_container_add() or gtk_box_pack_start().
 
 <item> gtk_widget_show() the widget.
 </enum>
-<p>
+
 gtk_widget_show() lets GTK know that we are done setting the attributes
 of the widget, and it is ready to be displayed.  You may also use
 gtk_widget_hide to make it disappear again.  The order in which you
 show the widgets is not important, but I suggest showing the window
 last so the whole window pops up at once rather than seeing the individual
 widgets come up on the screen as they're formed.  The children of a widget
-(a window is a widget too)
-will not be displayed until the window itself is shown using the
-gtk_widget_show() function.
+(a window is a widget too) will not be displayed until the window itself
+is shown using the gtk_widget_show() function.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Casting
@@ -1425,23 +1572,23 @@ examples, and can usually tell when to use them simply by looking at the
 function's declaration.
 
 As you can see below in the class hierarchy, all GtkWidgets are derived from
-the GtkObject base class.  This means you can use an widget in any place the 
+the GtkObject base class.  This means you can use a widget in any place the 
 function asks for an object - simply use the GTK_OBJECT() macro.
 
 For example:
 
 <tscreen><verb>
-gtk_signal_connect(GTK_OBJECT(button), "clicked",
-                   GTK_SIGNAL_FUNC(callback_function), callback_data);
+gtk_signal_connect( GTK_OBJECT(button), "clicked",
+                    GTK_SIGNAL_FUNC(callback_function), callback_data);
 </verb></tscreen> 
 
 This casts the button into an object, and provides a cast for the function
 pointer to the callback.
 
 Many widgets are also containers.  If you look in the class hierarchy below,
-you'll notice that many widgets drive from the GtkContainer class.  Any one
-of those widgets may use with the GTK_CONTAINER macro to
-pass them to functions that ask for containers.
+you'll notice that many widgets derive from the GtkContainer class.  Any one
+of these widgets may be used with the GTK_CONTAINER macro to pass them to
+functions that ask for containers.
 
 Unfortunately, these macros are not extensively covered in the tutorial, but I
 recomend taking a look through the GTK header files.  It can be very
@@ -1563,7 +1710,7 @@ GtkHBox
 GtkVSeparator
 GtkHSeparator
 </verb></tscreen>
-<p>
+
 We'll further our exploration of GTK by examining each widget in turn,
 creating a few simple functions to display them.  Another good source is
 the testgtk.c program that comes with GTK.  It can be found in
@@ -1576,20 +1723,20 @@ gtk/testgtk.c.
 <!-- ----------------------------------------------------------------- -->
 <sect1>Normal Buttons
 <p>
-We've almost seen all there is to see of the button widget.  It's pretty
-simple.  There is however two ways to create a button.	You can use the
+We've almost seen all there is to see of the button widget. It's pretty
+simple.  There is however two ways to create a button. You can use the
 gtk_button_new_with_label() to create a button with a label, or use
-gtk_button_new() to create a blank button.  It's then up to you to pack a
-label or pixmap into this new button.  To do this, create a new box, and
+gtk_button_new() to create a blank button. It's then up to you to pack a
+label or pixmap into this new button. To do this, create a new box, and
 then pack your objects into this box using the usual gtk_box_pack_start,
 and then use gtk_container_add to pack the box into the button.
-<p>
+
 Here's an example of using gtk_button_new to create a button with a
 picture and a label in it.  I've broken the code to create a box up from
 the rest so you can use it in your programs.
 
 <tscreen><verb>
-/* buttons.c */
+/* example-start buttons/buttons.c */
 
 #include <gtk/gtk.h>
 
@@ -1693,45 +1840,56 @@ int main (int argc, char *argv[])
 
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 The xpm_label_box function could be used to pack xpm's and labels into any
 widget that can be a container.
 
+The Buton widget has the following signals:
+
+<itemize>
+<item> pressed
+<item> released
+<item> clicked
+<item> enter
+<item> leave
+</itemize>
+
 <!-- ----------------------------------------------------------------- -->
 <sect1> Toggle Buttons
 <p>
-Toggle buttons are very similar to normal buttons, except they will always
-be in one of two states, alternated by a click.  They may be depressed, and
-when you click again, they will pop back up.  Click again, and they will pop
-back down. 
+Toggle buttons are derived from normal buttons and are very similar, except
+they will always be in one of two states, alternated by a click.  They may
+be depressed, and when you click again, they will pop back up. Click again,
+and they will pop back down. 
 
 Toggle buttons are the basis for check buttons and radio buttons, as such,
 many of the calls used for toggle buttons are inherited by radio and check
-buttons.  I will point these out when we come to them.
+buttons. I will point these out when we come to them.
 
 Creating a new toggle button:
 
 <tscreen><verb>
-GtkWidget* gtk_toggle_button_new (void);
+GtkWidget *gtk_toggle_button_new( void );
 
-GtkWidget* gtk_toggle_button_new_with_label (gchar *label);
+GtkWidget *gtk_toggle_button_new_with_label( gchar *label );
 </verb></tscreen>
-<p>
+
 As you can imagine, these work identically to the normal button widget
-calls.  The first creates a blank toggle button, and the second, a button 
+calls. The first creates a blank toggle button, and the second, a button 
 with a label widget already packed into it.
-<p>
+
 To retrieve the state of the toggle widget, including radio and check
 buttons, we use a macro as shown in our example below.  This tests the state
-of the toggle in a callback.  The signal of interest emitted to us by toggle
+of the toggle in a callback. The signal of interest emitted to us by toggle
 buttons (the toggle button, check button, and radio button widgets), is the
 "toggled" signal.  To check the state of these buttons, set up a signal
 handler to catch the toggled signal, and use the macro to determine it's
-state.  The callback will look something like:
+state. The callback will look something like:
 
 <tscreen><verb>
-void toggle_button_callback (GtkWidget *widget, gpointer   data)
+void toggle_button_callback (GtkWidget *widget, gpointer data)
 {
     if (GTK_TOGGLE_BUTTON (widget)->active) 
     {
@@ -1744,61 +1902,41 @@ void toggle_button_callback (GtkWidget *widget, gpointer   data)
 }
 </verb></tscreen>
 
-<!--
-
-COMMENTED!
-
-<tscreen><verb>
-guint gtk_toggle_button_get_type (void);
-</verb></tscreen>
-<p>
-No idea... they all have this, but I dunno what it is :)
-
-
 <tscreen><verb>
-void gtk_toggle_button_set_mode (GtkToggleButton *toggle_button,
-                                 gint draw_indicator);
+void gtk_toggle_button_set_state( GtkToggleButton *toggle_button,
+                                  gint             state );
 </verb></tscreen>
-<p>
-No idea.
--->
 
-<tscreen><verb>
-void gtk_toggle_button_set_state (GtkToggleButton *toggle_button,
-                                  gint state);
-</verb></tscreen>
-<p>
 The above call can be used to set the state of the toggle button, and it's
-children the radio and check buttons.  Passing
-in your created button as the first argument, and a TRUE or FALSE
-for the second state argument to specify whether it should be up (released) or
-down (depressed).  Default is up, or FALSE.
+children the radio and check buttons. Passing in your created button as
+the first argument, and a TRUE or FALSE for the second state argument to
+specify whether it should be up (released) or down (depressed).  Default
+is up, or FALSE.
 
 Note that when you use the gtk_toggle_button_set_state() function, and the
-state is actually changed, it causes
-the "clicked" signal to be emitted from the button.
+state is actually changed, it causes the "clicked" signal to be emitted 
+from the button.
 
 <tscreen><verb>
-void       gtk_toggle_button_toggled        (GtkToggleButton *toggle_button);
+void gtk_toggle_button_toggled (GtkToggleButton *toggle_button);
 </verb></tscreen>
-<p>
+
 This simply toggles the button, and emits the "toggled" signal.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Check Buttons
 <p>
-Check buttons inherent many properties and functions from the the toggle buttons above, 
-but look a little
-different.  Rather than being buttons with text inside them, they are small
-squares with the text to the right of them.  These are often seen for
-toggling options on and off in applications.
+Check buttons inherent many properties and functions from the the toggle
+buttons above, but look a little different. Rather than being buttons with
+text inside them, they are small squares with the text to the right of 
+them. These are often used for toggling options on and off in applications.
 
-The two creation functions are the same as for the normal button.
+The two creation functions are similar to those of the normal button.
 
 <tscreen><verb>
-GtkWidget* gtk_check_button_new (void);
+GtkWidget *gtk_check_button_new( void );
 
-GtkWidget* gtk_check_button_new_with_label (gchar *label);
+GtkWidget *gtk_check_button_new_with_label ( gchar *label );
 </verb></tscreen>
 
 The new_with_label function creates a check button with a label beside it.
@@ -1810,27 +1948,26 @@ button.
 <sect1> Radio Buttons
 <p>
 Radio buttons are similar to check buttons except they are grouped so that
-only one may be selected/depressed at a time.  This is good for places in
+only one may be selected/depressed at a time. This is good for places in
 your application where you need to select from a short list of options.
 
 Creating a new radio button is done with one of these calls:
 
 <tscreen><verb>
-GtkWidget* gtk_radio_button_new (GSList *group);
+GtkWidget *gtk_radio_button_new( GSList *group );
 
-GtkWidget* gtk_radio_button_new_with_label (GSList *group,
-                                            gchar *label);
+GtkWidget *gtk_radio_button_new_with_label( GSList *group,
+                                            gchar  *label );
 </verb></tscreen>
-<p>
+
 You'll notice the extra argument to these calls.  They require a group to
-perform they're duty properly.  The first call should pass NULL as the first
-argument.  Then create a group using:
+perform they're duty properly. The first call should pass NULL as the first
+argument. Then create a group using:
 
 <tscreen><verb>
-GSList* gtk_radio_button_group (GtkRadioButton *radio_button);
+GSList *gtk_radio_button_group( GtkRadioButton *radio_button );
 </verb></tscreen>
 
-<p>
 The important thing to remember is that gtk_radio_button_group must be
 called for each new button added to the group, with the previous button
 passed in as an argument. The result is then passed into the call to
@@ -1842,22 +1979,22 @@ It is also a good idea to explicitly set which button should be the
 default depressed button with:
 
 <tscreen><verb>
-void gtk_toggle_button_set_state (GtkToggleButton *toggle_button,
-                                  gint state);
+void gtk_toggle_button_set_state( GtkToggleButton *toggle_button,
+                                  gint             state );
 </verb></tscreen>
-<p>
+
 This is described in the section on toggle buttons, and works in exactly the
 same way.
-<p>
+
 The following example creates a radio button group with three buttons.
 
 <tscreen><verb>
-/* radiobuttons.c */
+/* example-start radiobuttons/radiobuttons.c */
 
 #include <gtk/gtk.h>
 #include <glib.h>
 
-void close_application( GtkWidget *widget, gpointer data ) {
+void close_application( GtkWidget *widget, GdkEvent *event, gpointer data ) {
   gtk_main_quit();
 }
 
@@ -1937,6 +2074,8 @@ removes the need for a variable to hold the list of buttons:
                  "button2");
 </verb></tscreen>
 
+<!-- TODO: checout out gtk_radio_button_new_from_widget function - TRG -->
+
 <!-- ***************************************************************** -->
 <sect> Miscallaneous Widgets
 <!-- ***************************************************************** -->
@@ -1944,14 +2083,14 @@ removes the need for a variable to hold the list of buttons:
 <!-- ----------------------------------------------------------------- -->
 <sect1> Labels
 <p>
-Labels are used a lot in GTK, and are relatively simple.  Labels emit no
-signals as they do not have an associated X window.  If you need to catch
+Labels are used a lot in GTK, and are relatively simple. Labels emit no
+signals as they do not have an associated X window. If you need to catch
 signals, or do clipping, use the EventBox widget.
 
 To create a new label, use:
 
 <tscreen><verb>
-GtkWidget* gtk_label_new (char *str);
+GtkWidget *gtk_label_new( char *str );
 </verb></tscreen>
 
 Where the sole argument is the string you wish the label to display.
@@ -1959,11 +2098,11 @@ Where the sole argument is the string you wish the label to display.
 To change the label's text after creation, use the function:
 
 <tscreen><verb>
-void gtk_label_set (GtkLabel  *label,
-		    char      *str);
+void gtk_label_set( GtkLabel *label,
+                    char     *str );
 </verb></tscreen>
-<p>
-Where the first argument is the label you created previously (casted using
+
+Where the first argument is the label you created previously (cast using
 the GTK_LABEL() macro), and the second is the new string.
 
 The space needed for the new string will be automatically adjusted if needed.
@@ -1971,8 +2110,8 @@ The space needed for the new string will be automatically adjusted if needed.
 To retrieve the current string, use:
 
 <tscreen><verb>
-void gtk_label_get (GtkLabel  *label,
-		    char     **str);
+void gtk_label_get( GtkLabel  *label,
+                    char     **str );
 </verb></tscreen>
 
 Where the first arguement is the label you've created, and the second, the
@@ -1982,34 +2121,37 @@ return for the string.
 <sect1>The Tooltips Widget
 <p>
 These are the little text strings that pop up when you leave your pointer
-over a button or other widget for a few seconds.  They are easy to use, so I
-will just explain them without giving an example.  If you want to see some
+over a button or other widget for a few seconds. They are easy to use, so I
+will just explain them without giving an example. If you want to see some
 code, take a look at the testgtk.c program distributed with GDK.
-<p>
+
 Some widgets (such as the label) will not work with tooltips.
-<p>
-The first call you will use to create a new tooltip.  You only need to do
-this once in a given function.	The <tt/GtkTooltip/ this function 
+
+The first call you will use to create a new tooltip. You only need to do
+this once in a given function. The <tt/GtkTooltip/ object this function 
 returns can be used to create multiple tooltips.
 
 <tscreen><verb>
-GtkTooltips *gtk_tooltips_new (void);
+GtkTooltips *gtk_tooltips_new( void );
 </verb></tscreen>
 
 Once you have created a new tooltip, and the widget you wish to use it on,
-simply use this call to set it.
+simply use this call to set it:
 
 <tscreen><verb>
-void gtk_tooltips_set_tip (GtkTooltips *tooltips,
+void gtk_tooltips_set_tip( GtkTooltips *tooltips,
                            GtkWidget   *widget,
                            const gchar *tip_text,
-                           const gchar *tip_private);
+                           const gchar *tip_private );
 </verb></tscreen>
 
 The first argument is the tooltip you've already created, followed by the
 widget you wish to have this tooltip pop up for, and the text you wish it to
-say. The last argument can be set to NULL.
-<p>
+say. The last argument is a text string that can be used as an identifier when using
+GtkTipsQuery to implement context sensitive help. For now, you can set
+it to NULL.
+<!-- TODO: sort out what how to do the context sensitive help -->
+
 Here's a short example:
 
 <tscreen><verb>
@@ -2022,53 +2164,41 @@ button = gtk_button_new_with_label ("button 1");
 gtk_tooltips_set_tip (tooltips, button, "This is button 1", NULL);
 </verb></tscreen>
 
-There are other calls used with tooltips.  I will just list them with a
-brief description of what they do.
-
-<tscreen><verb>
-void gtk_tooltips_destroy    (GtkTooltips *tooltips);
-</verb></tscreen>
-
-Destroy the created tooltips.
+There are other calls that can be used with tooltips.  I will just
+list them with a brief description of what they do.
 
 <tscreen><verb>
-void gtk_tooltips_enable     (GtkTooltips *tooltips);
+void gtk_tooltips_enable( GtkTooltips *tooltips );
 </verb></tscreen>
 
 Enable a disabled set of tooltips.
 
 <tscreen><verb>
-void gtk_tooltips_disable    (GtkTooltips *tooltips);
+void gtk_tooltips_disable( GtkTooltips *tooltips );
 </verb></tscreen>
 
 Disable an enabled set of tooltips.
 
 <tscreen><verb>
-void gtk_tooltips_set_delay  (GtkTooltips *tooltips,
-			      gint	   delay);
+void gtk_tooltips_set_delay( GtkTooltips *tooltips,
+                             gint         delay );
 
 </verb></tscreen>
-Sets how many milliseconds you have to hold you pointer over the widget before the
-tooltip will pop up.  The default is 1000 milliseconds or 1 second.
 
-<tscreen><verb>
-void	  gtk_tooltips_set_tips (GtkTooltips *tooltips,
-			         GtkWidget   *widget,
-			         gchar	  *tips_text);
-</verb></tscreen>
-
-Change the tooltip text of an already created tooltip.
+Sets how many milliseconds you have to hold your pointer over the 
+widget before the tooltip will pop up.  The default is 1000 milliseconds
+or 1 second.
 
 <tscreen><verb>
-void gtk_tooltips_set_colors (GtkTooltips *tooltips,
-			      GdkColor	  *background,
-			      GdkColor	  *foreground);
+void gtk_tooltips_set_colors( GtkTooltips *tooltips,
+                              GdkColor    *background,
+                              GdkColor    *foreground );
 </verb></tscreen>
 
-Set the foreground and background color of the tooltips.  Again, I have no
+Set the foreground and background color of the tooltips. Again, I have no
 idea how to specify the colors.
-<p>
-And that's all the functions associated with tooltips.  More than you'll
+
+And that's all the functions associated with tooltips. More than you'll
 ever want to know :)
 
 <!-- ----------------------------------------------------------------- -->
@@ -2079,18 +2209,20 @@ easy to use, as you will see with the code below. But first lets start out
 with the call to create a new progress bar.
 
 <tscreen><verb>
-GtkWidget *gtk_progress_bar_new (void);
+GtkWidget *gtk_progress_bar_new( void );
 </verb></tscreen>
 
 Now that the progress bar has been created we can use it.
 
 <tscreen><verb>
-void gtk_progress_bar_update (GtkProgressBar *pbar, gfloat percentage);
+void gtk_progress_bar_update( GtkProgressBar *pbar,
+                              gfloat          percentage );
 </verb></tscreen>
 
 The first argument is the progress bar you wish to operate on, and the second 
 argument is the amount 'completed', meaning the amount the progress bar has 
-been filled from 0-100% (a real number between 0 and 1).
+been filled from 0-100%. This is passed to the function as a real number
+ranging from 0 to 1.
 
 Progress Bars are usually used with timeouts or other such functions (see
 section on <ref id="sec_timeouts" name="Timeouts, I/O and Idle Functions">) 
@@ -2101,7 +2233,7 @@ Here is an example of the progress bar, updated using timeouts.  This
 code also shows you how to reset the Progress Bar.
 
 <tscreen><verb>
-/* progressbar.c */
+/* example-start progressbar/progressbar.c */
 
 #include <gtk/gtk.h>
 
@@ -2134,7 +2266,7 @@ void progress_r (void)
     pstat = FALSE;  
 }
 
-void destroy (GtkWidget *widget, gpointer data)
+void destroy (GtkWidget *widget, GdkEvent *event, gpointer data)
 {
     gtk_main_quit ();
 }
@@ -2192,32 +2324,33 @@ int main (int argc, char *argv[])
     
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 In this small program there are four areas that concern the general operation
 of Progress Bars, we will look at them in the order they are called.
 
 <tscreen><verb>
-pbar = gtk_progress_bar_new ();
+    pbar = gtk_progress_bar_new ();
 </verb></tscreen>
 
 This code creates a new progress bar, called pbar.
 
 <tscreen><verb>
-ptimer = gtk_timeout_add (100, progress, pbar);
+    ptimer = gtk_timeout_add (100, progress, pbar);
 </verb></tscreen>
 
-This code, uses timeouts to enable a constant time interval, timeouts are 
+This code uses timeouts to enable a constant time interval, timeouts are 
 not necessary in the use of Progress Bars. 
 
 <tscreen><verb>
-pvalue = GTK_PROGRESS_BAR (data)->percentage;
+    pvalue = GTK_PROGRESS_BAR (data)->percentage;
 </verb></tscreen>
 
 This code assigns the current value of the percentage bar to pvalue.
 
 <tscreen><verb>
-gtk_progress_bar_update (GTK_PROGRESS_BAR (data), pvalue);
+    gtk_progress_bar_update (GTK_PROGRESS_BAR (data), pvalue);
 </verb></tscreen>
 
 Finally, this code updates the progress bar with the value of pvalue
@@ -2227,9 +2360,8 @@ And that is all there is to know about Progress Bars, enjoy.
 <!-- ----------------------------------------------------------------- -->
 <sect1> Dialogs
 <p>
-
 The Dialog widget is very simple, and is actually just a window with a few
-things pre-packed into it for you.  The structure for a Dialog is:
+things pre-packed into it for you. The structure for a Dialog is:
 
 <tscreen><verb>
 struct GtkDialog
@@ -2241,7 +2373,7 @@ struct GtkDialog
 };
 </verb></tscreen>
 
-So you see, it simple creates a window, and then packs a vbox into the top,
+So you see, it simply creates a window, and then packs a vbox into the top,
 then a seperator, and then an hbox for the "action_area".
 
 The Dialog widget can be used for pop-up messages to the user, and 
@@ -2249,7 +2381,7 @@ other similar tasks.  It is really basic, and there is only one
 function for the dialog box, which is:
 
 <tscreen><verb>
-GtkWidget* gtk_dialog_new (void);
+GtkWidget *gtk_dialog_new( void );
 </verb></tscreen>
 
 So to create a new dialog box, use,
@@ -2260,7 +2392,7 @@ window = gtk_dialog_new ();
 </verb></tscreen>
 
 This will create the dialog box, and it is now up to you to use it.
-you could pack a button in the action_area by doing something like so:
+you could pack a button in the action_area by doing something like this:
 
 <tscreen><verb>
 button = ...
@@ -2285,64 +2417,69 @@ area, asking the user a question or giving an error etc.  Then you could
 attach a different signal to each of the buttons and perform the 
 operation the user selects.
 
+If the simple functionality provided by the default vertical and
+horizontal boxes in the two areas don't give you enough control for your
+application, then you can simply pack another layout widget into the boxes
+provided. For example, you could pack a table into the vertical box.
+
 <!-- ----------------------------------------------------------------- -->
 <sect1> Pixmaps
 <p>
-Pixmaps are data structures that contain pictures.  These pictures can be
+Pixmaps are data structures that contain pictures. These pictures can be
 used in various places, but most visibly as icons on the X-Windows desktop,
-or as cursors.  A bitmap is a 2-color pixmap.
+or as cursors. A bitmap is a 2-color pixmap.
 
 To use pixmaps in GTK, we must first build a GdkPixmap structure using
-routines from the GDK layer.  Pixmaps can either be created from in-memory
-data, or from data read from a file.  We'll go through each of the calls
+routines from the GDK layer. Pixmaps can either be created from in-memory
+data, or from data read from a file. We'll go through each of the calls
 to create a pixmap.
 
 <tscreen><verb>
 GdkPixmap *gdk_bitmap_create_from_data( GdkWindow *window,
                                         gchar     *data,
-                                        gint      width,
-                                        gint      height );
+                                        gint       width,
+                                        gint       height );
 </verb></tscreen>
-<p>
+
 This routine is used to create a single-plane pixmap (2 colors) from data in
-memory.  Each bit of the data represents whether that pixel is off or on.
-Width and height are in pixels.  The GdkWindow pointer is to the current
+memory. Each bit of the data represents whether that pixel is off or on.
+Width and height are in pixels. The GdkWindow pointer is to the current
 window, since a pixmap resources are meaningful only in the context of the
 screen where it is to be displayed.
 
 <tscreen><verb>
-GdkPixmap* gdk_pixmap_create_from_data( GdkWindow  *window,
-                                        gchar      *data,
-                                        gint        width,
-                                        gint        height,
-                                        gint        depth,
-                                        GdkColor   *fg,
-                                        GdkColor   *bg );
+GdkPixmap *gdk_pixmap_create_from_data( GdkWindow *window,
+                                        gchar     *data,
+                                        gint       width,
+                                        gint       height,
+                                        gint       depth,
+                                        GdkColor  *fg,
+                                        GdkColor  *bg );
 </verb></tscreen>
 
 This is used to create a pixmap of the given depth (number of colors) from
-the bitmap data specified.  fg and bg are the foreground and background
-color to use.
+the bitmap data specified. <tt/fg/ and <tt/bg/ are the foreground and
+background color to use.
 
 <tscreen><verb>
-GdkPixmap* gdk_pixmap_create_from_xpm( GdkWindow  *window,
-                                       GdkBitmap **mask,
-                                       GdkColor   *transparent_color,
+GdkPixmap *gdk_pixmap_create_from_xpm( GdkWindow   *window,
+                                       GdkBitmap  **mask,
+                                       GdkColor    *transparent_color,
                                        const gchar *filename );
 </verb></tscreen>
 
 XPM format is a readable pixmap representation for the X Window System.  It
 is widely used and many different utilities are available for creating image
 files in this format.  The file specified by filename must contain an image
-in that format and it is loaded into the pixmap structure.  The mask specifies
-what bits of the pixmap are opaque.  All other bits are colored using the
-color specified by transparent_color.  An example using this follows below.  
+in that format and it is loaded into the pixmap structure. The mask specifies
+which bits of the pixmap are opaque. All other bits are colored using the
+color specified by transparent_color. An example using this follows below.  
 
 <tscreen><verb>
-GdkPixmap* gdk_pixmap_create_from_xpm_d (GdkWindow  *window,
+GdkPixmap *gdk_pixmap_create_from_xpm_d( GdkWindow  *window,
                                          GdkBitmap **mask,
                                          GdkColor   *transparent_color,
-                                         gchar     **data);
+                                         gchar     **data );
 </verb></tscreen>
 
 Small images can be incorporated into a program as data in the XPM format.
@@ -2374,42 +2511,39 @@ static const char * xpm_data[] = {
 "                "};
 </verb></tscreen>
 
-<tscreen><verb>
-void gdk_pixmap_destroy( GdkPixmap  *pixmap );
-</verb></tscreen>
-<p>
 When we're done using a pixmap and not likely to reuse it again soon,
-it is a good idea to release the resource using gdk_pixmap_destroy.  Pixmaps
+it is a good idea to release the resource using gdk_pixmap_unref(). Pixmaps
 should be considered a precious resource.
 
-
-Once we've created a pixmap, we can display it as a GTK widget.  We must
-create a pixmap widget to contain the GDK pixmap.  This is done using
+Once we've created a pixmap, we can display it as a GTK widget. We must
+create a pixmap widget to contain the GDK pixmap. This is done using
 
 <tscreen><verb>
-GtkWidget* gtk_pixmap_new( GdkPixmap  *pixmap,
-                           GdkBitmap  *mask );
+GtkWidget *gtk_pixmap_new( GdkPixmap *pixmap,
+                           GdkBitmap *mask );
 </verb></tscreen>
-<p>
+
 The other pixmap widget calls are
 
 <tscreen><verb>
 guint gtk_pixmap_get_type( void );
+
 void  gtk_pixmap_set( GtkPixmap  *pixmap,
                       GdkPixmap  *val,
-                      GdkBitmap  *mask);
+                      GdkBitmap  *mask );
+
 void  gtk_pixmap_get( GtkPixmap  *pixmap,
                       GdkPixmap **val,
                       GdkBitmap **mask);
 </verb></tscreen>
-<p>
+
 gtk_pixmap_set is used to change the pixmap that the widget is currently
-managing.  Val is the pixmap created using GDK.
+managing. Val is the pixmap created using GDK.
 
 The following is an example of using a pixmap in a button.
 
 <tscreen><verb>
-/* pixmap.c */
+/* example-start pixmap/pixmap.c */
 
 #include <gtk/gtk.h>
 
@@ -2440,7 +2574,7 @@ static const char * xpm_data[] = {
 
 /* when invoked (via signal delete_event), terminates the application.
  */
-void close_application( GtkWidget *widget, gpointer data ) {
+void close_application( GtkWidget *widget, GdkEvent *event, gpointer data ) {
     gtk_main_quit();
 }
 
@@ -2492,9 +2626,9 @@ int main( int argc, char *argv[] )
           
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
-
 To load a file from an XPM data file called icon0.xpm in the current
 directory, we would have created the pixmap thus
 
@@ -2508,24 +2642,20 @@ directory, we would have created the pixmap thus
     gtk_container_add( GTK_CONTAINER(window), pixmapwid );
 </verb></tscreen>
 
-
-
-Using Shapes
-<p>
 A disadvantage of using pixmaps is that the displayed object is always
-rectangular, regardless of the image.  We would like to create desktops
-and applications with icons that have more natural shapes.  For example,
-for a game interface, we would like to have round buttons to push.  The
+rectangular, regardless of the image. We would like to create desktops
+and applications with icons that have more natural shapes. For example,
+for a game interface, we would like to have round buttons to push. The
 way to do this is using shaped windows.
 
 A shaped window is simply a pixmap where the background pixels are
-transparent.  This way, when the background image is multi-colored, we
+transparent. This way, when the background image is multi-colored, we
 don't overwrite it with a rectangular, non-matching border around our
-icon.  The following example displays a full wheelbarrow image on the
+icon. The following example displays a full wheelbarrow image on the
 desktop.
 
 <tscreen><verb>
-/* wheelbarrow.c */
+/* example-start wheelbarrow/wheelbarrow.c */
 
 #include <gtk/gtk.h>
 
@@ -2648,7 +2778,7 @@ static char * WheelbarrowFull_xpm[] = {
 
 /* when invoked (via signal delete_event), terminates the application.
  */
-void close_application( GtkWidget *widget, gpointer data ) {
+void close_application( GtkWidget *widget, GdkEvent *event, gpointer data ) {
     gtk_main_quit();
 }
 
@@ -2697,7 +2827,7 @@ int main (int argc, char *argv[])
     return 0;
 }
 </verb></tscreen>
-<p>
+
 To make the wheelbarrow image sensitive, we could attach the button press
 event signal to make it do something.  The following few lines would make
 the picture sensitive to a mouse button being pressed which makes the
@@ -2706,7 +2836,7 @@ application terminate.
 <tscreen><verb>
 gtk_widget_set_events( window,
                        gtk_widget_get_events( window ) |
-		       GDK_BUTTON_PRESS_MASK );
+                       GDK_BUTTON_PRESS_MASK );
 
 gtk_signal_connect( GTK_OBJECT(window), "button_press_event",
                     GTK_SIGNAL_FUNC(close_application), NULL );
@@ -2716,26 +2846,26 @@ gtk_signal_connect( GTK_OBJECT(window), "button_press_event",
 <sect1>Rulers
 <p>
 Ruler widgets are used to indicate the location of the mouse pointer
-in a given window.  A window can have a vertical ruler spanning across
+in a given window. A window can have a vertical ruler spanning across
 the width and a horizontal ruler spanning down the height.  A small
 triangular indicator on the ruler shows the exact location of the
 pointer relative to the ruler.
 
-A ruler must first be created.  Horizontal and vertical rulers are
+A ruler must first be created. Horizontal and vertical rulers are
 created using
 
 <tscreen><verb>
-GtkWidget *gtk_hruler_new(void);    /* horizontal ruler */
-GtkWidget *gtk_vruler_new(void);    /* vertical ruler   */
+GtkWidget *gtk_hruler_new( void );    /* horizontal ruler */
+GtkWidget *gtk_vruler_new( void );    /* vertical ruler   */
 </verb></tscreen>
 
-Once a ruler is created, we can define the unit of measurement.  Units
+Once a ruler is created, we can define the unit of measurement. Units
 of measure for rulers can be GTK_PIXELS, GTK_INCHES or
-GTK_CENTIMETERS.  This is set using
+GTK_CENTIMETERS. This is set using
 
 <tscreen><verb>
-void gtk_ruler_set_metric( GtkRuler        *ruler,
-                           GtkMetricType   metric );
+void gtk_ruler_set_metric( GtkRuler      *ruler,
+                           GtkMetricType  metric );
 </verb></tscreen>
 
 The default measure is GTK_PIXELS.
@@ -2745,18 +2875,18 @@ gtk_ruler_set_metric( GTK_RULER(ruler), GTK_PIXELS );
 </verb></tscreen>
 
 Other important characteristics of a ruler are how to mark the units
-of scale and where the position indicator is initially placed.  These
+of scale and where the position indicator is initially placed. These
 are set for a ruler using
 
 <tscreen><verb>
-void  gtk_ruler_set_range  (GtkRuler       *ruler,
-                            gfloat          lower,
-                            gfloat          upper,
-                            gfloat          position,
-                            gfloat          max_size);
+void gtk_ruler_set_range( GtkRuler *ruler,
+                          gfloat    lower,
+                          gfloat    upper,
+                          gfloat    position,
+                          gfloat    max_size );
 </verb></tscreen>
 
-The lower and upper arguments define the extents of the ruler, and
+The lower and upper arguments define the extent of the ruler, and
 max_size is the largest possible number that will be displayed.
 Position defines the initial position of the pointer indicator within
 the ruler.
@@ -2768,7 +2898,7 @@ gtk_ruler_set_range( GTK_RULER(vruler), 0, 800, 0, 800);
 </verb></tscreen>
 
 The markings displayed on the ruler will be from 0 to 800, with
-a number for every 100 pixels.  If instead we wanted the ruler to
+a number for every 100 pixels. If instead we wanted the ruler to
 range from 7 to 16, we would code
 
 <tscreen><verb>
@@ -2776,7 +2906,7 @@ gtk_ruler_set_range( GTK_RULER(vruler), 7, 16, 0, 20);
 </verb></tscreen>
 
 The indicator on the ruler is a small triangular mark that indicates
-the position of the pointer relative to the ruler.  If the ruler is
+the position of the pointer relative to the ruler. If the ruler is
 used to follow the mouse pointer, the motion_notify_event signal
 should be connected to the motion_notify_event method of the ruler.
 To follow all mouse movements within a window area, we would use
@@ -2791,13 +2921,13 @@ gtk_signal_connect_object( GTK_OBJECT(area), "motion_notify_event",
 
 The following example creates a drawing area with a horizontal ruler
 above it and a vertical ruler to the left of it.  The size of the
-drawing area is 600 pixels wide by 400 pixels high.  The horizontal
+drawing area is 600 pixels wide by 400 pixels high. The horizontal
 ruler spans from 7 to 13 with a mark every 100 pixels, while the
 vertical ruler spans from 0 to 400 with a mark every 100 pixels.
 Placement of the drawing area and the rulers are done using a table.
 
 <tscreen><verb>
-/* rulers.c */
+/* example-start rulers/rulers.c */
 
 #include <gtk/gtk.h>
 
@@ -2808,7 +2938,7 @@ Placement of the drawing area and the rulers are done using a table.
 
 /* this routine gets control when the close button is clicked
  */
-void close_application( GtkWidget *widget, gpointer data ) {
+void close_application( GtkWidget *widget, GdkEvent *event, gpointer data ) {
     gtk_main_quit();
 }
 
@@ -2870,57 +3000,64 @@ int main( int argc, char *argv[] ) {
 
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Statusbars
 <p>
-Statusbars are simple widgets used to display a text message. They keep a stack 
-of the messages pushed onto them, so that popping the current message 
-will re-display the previous text message.
+Statusbars are simple widgets used to display a text message. They keep
+a stack  of the messages pushed onto them, so that popping the current
+message will re-display the previous text message.
 
-In order to allow different parts of an application to use the same statusbar to display
-messages, the statusbar widget issues Context Identifiers which are used to identify
-different 'users'. The message on top of the stack is the one displayed, no matter what context
-it is in. Messages are stacked in last-in-first-out order, not context identifier order.
+In order to allow different parts of an application to use the same
+statusbar to display messages, the statusbar widget issues Context
+Identifiers which are used to identify different 'users'. The message on
+top of the stack is the one displayed, no matter what context it is in.
+Messages are stacked in last-in-first-out order, not context identifier order.
 
 A statusbar is created with a call to:
+
 <tscreen><verb>
-GtkWidget* gtk_statusbar_new (void);
+GtkWidget *gtk_statusbar_new( void );
 </verb></tscreen>
 
-A new Context Identifier is requested using a call to the following function with a short
-textual description of the context:
+A new Context Identifier is requested using a call to the following 
+function with a short textual description of the context:
+
 <tscreen><verb>
-guint gtk_statusbar_get_context_id (GtkStatusbar *statusbar,
-                                    const gchar  *context_description);
+guint gtk_statusbar_get_context_id( GtkStatusbar *statusbar,
+                                    const gchar  *context_description );
 </verb></tscreen>
 
-There are three functions that can operate on statusbars.
+There are three functions that can operate on statusbars:
+
 <tscreen><verb>
-guint       gtk_statusbar_push           (GtkStatusbar *statusbar,
-                                         guint          context_id,
-                                         gchar         *text);
+guint gtk_statusbar_push( GtkStatusbar *statusbar,
+                          guint         context_id,
+                          gchar        *text );
+
+void gtk_statusbar_pop( GtkStatusbar *statusbar)
+                        guint         context_id );
 
-void       gtk_statusbar_pop            (GtkStatusbar *statusbar)
-                                         guint         context_id);
-void       gtk_statusbar_remove         (GtkStatusbar *statusbar,
-                                         guint         context_id,
-                                         guint         message_id); 
+void gtk_statusbar_remove( GtkStatusbar *statusbar,
+                           guint         context_id,
+                           guint         message_id ); 
 </verb></tscreen>
 
 The first, gtk_statusbar_push, is used to add a new message to the statusbar. 
-It returns a Message Identifier, which can be passed later to the function gtk_statusbar_remove
-to remove the message with the given Message and Context Identifiers from the statusbar's stack.
+It returns a Message Identifier, which can be passed later to the function
+gtk_statusbar_remove to remove the message with the given Message and Context
+Identifiers from the statusbar's stack.
 
-The function gtk_statusbar_pop removes the message highest in the stack with the given
-Context Identifier.
+The function gtk_statusbar_pop removes the message highest in the stack with
+the given Context Identifier.
 
 The following example creates a statusbar and two buttons, one for pushing items
 onto the statusbar, and one for popping the last item back off.
 
 <tscreen><verb>
-/* statusbar.c */
+/* example-start statusbar/statusbar.c */
 
 #include <gtk/gtk.h>
 #include <glib.h>
@@ -2992,86 +3129,99 @@ int main (int argc, char *argv[])
 
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Text Entries
 <p>
-The Entry widget allows text to be typed and displayed in a single line text box. 
-The text may be set with functions calls that allow new text to replace, 
-prepend or append the current contents of the Entry widget.
+The Entry widget allows text to be typed and displayed in a single line
+text box. The text may be set with function calls that allow new text
+to replace, prepend or append the current contents of the Entry widget.
 
 There are two functions for creating Entry widgets:
+
 <tscreen><verb>
-GtkWidget* gtk_entry_new (void);
+GtkWidget *gtk_entry_new( void );
 
-GtkWidget* gtk_entry_new_with_max_length (guint16 max);
+GtkWidget *gtk_entry_new_with_max_length( guint16 max );
 </verb></tscreen>
 
-The first just creates a new Entry widget, whilst the second creates a new Entry and 
-sets a limit on the length of the text within the Entry..
+The first just creates a new Entry widget, whilst the second creates a
+new Entry and sets a limit on the length of the text within the Entry.
+
+There are several functions for altering the text which is currently
+within the Entry widget.
 
-There are several functions for altering the text which is currently within the Entry widget.
 <tscreen><verb>
-void gtk_entry_set_text       (GtkEntry    *entry,
-                               const gchar *text);
-void gtk_entry_append_text    (GtkEntry    *entry,
-                               const gchar *text);
-void gtk_entry_prepend_text   (GtkEntry    *entry,
-                               const gchar *text);
+void gtk_entry_set_text( GtkEntry    *entry,
+                         const gchar *text );
+
+void gtk_entry_append_text( GtkEntry    *entry,
+                            const gchar *text );
+
+void gtk_entry_prepend_text( GtkEntry    *entry,
+                             const gchar *text );
 </verb></tscreen>
 
-The function gtk_entry_set_text sets the contents of the Entry widget, replacing the
-current contents. The functions gtk_entry_append_text and gtk_entry_prepend_text allow
-the current contents to be appended and prepended to.
+The function gtk_entry_set_text sets the contents of the Entry widget,
+replacing the current contents. The functions gtk_entry_append_text and
+gtk_entry_prepend_text allow the current contents to be appended and
+prepended to.
 
 The next function allows the current insertion point to be set.
+
 <tscreen><verb>
-void gtk_entry_set_position   (GtkEntry *entry,
-                               gint     position);
+void gtk_entry_set_position( GtkEntry *entry,
+                             gint      position );
 </verb></tscreen>
 
-The contents of the Entry can be retrieved by using a call to the following function. This
-is useful in the callback functions described below.
+The contents of the Entry can be retrieved by using a call to the
+following function. This is useful in the callback functions described below.
+
 <tscreen><verb>
-gchar* gtk_entry_get_text (GtkEntry *entry);
+gchar *gtk_entry_get_text( GtkEntry *entry );
 </verb></tscreen>
 
-If we don't want the contents of the Entry to be changed by someone typing into it, we
-can change it's edittable state.
+If we don't want the contents of the Entry to be changed by someone typing
+into it, we can change it's editable state.
+
 <tscreen><verb>
-void gtk_entry_set_editable (GtkEntry *entry,
-                             gboolean editable);
+void gtk_entry_set_editable( GtkEntry *entry,
+                             gboolean  editable );
 </verb></tscreen>
 
-This function allows us to toggle the edittable state of the Entry widget by passing in
-TRUE or FALSE values for the editable argument.
+This function allows us to toggle the edittable state of the Entry widget 
+by passing in a TRUE or FALSE value for the <tt/editable/ argument.
+
+If we are using the Entry where we don't want the text entered to be visible,
+for example when a password is being entered, we can use the following
+function, which also takes a boolean flag.
 
-If we are using the Entry where we don't want the text entered to be visible, for
-example when a password is being entered, we can use the following function, which
-also takes a boolean flag.
 <tscreen><verb>
-void gtk_entry_set_visibility (GtkEntry *entry,
-                               gboolean visible);
+void gtk_entry_set_visibility( GtkEntry *entry,
+                               gboolean  visible );
 </verb></tscreen>
 
-A region of the text may be set as selected by using the following function. This would
-most often be used after setting some default text in an Entry, making it easy for the user
-to remove it.
+A region of the text may be set as selected by using the following 
+function. This would most often be used after setting some default text 
+in an Entry, making it easy for the user to remove it.
+
 <tscreen><verb>
-void gtk_entry_select_region (GtkEntry *entry,
-                              gint     start,
-                              gint     end);
+void gtk_entry_select_region( GtkEntry *entry,
+                              gint      start,
+                              gint      end );
 </verb></tscreen>
 
 If we want to catch when the user has entered text, we can connect to the
 <tt/activate/ or <tt/changed/ signal. Activate is raised when the user hits 
-the enter key within the Entry widget. Changed is raised when the text changes at all, 
-e.g. for every character entered or removed.
+the enter key within the Entry widget. Changed is raised when the text
+changes at all, e.g. for every character entered or removed.
 
 The following code is an example of using an Entry widget.
+
 <tscreen><verb>
-/* entry.c */
+/* example-start entry/entry.c */
 
 #include <gtk/gtk.h>
 
@@ -3161,80 +3311,90 @@ int main (int argc, char *argv[])
     gtk_main();
     return(0);
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Color Selection
-<P>
+<p>
 The color selection widget is, not surprisingly, a widget for interactive
-selection of colors. This composite widget lets the user select a color by manipulating
-RGB (Red, Green, Blue) and HSV (Hue, Saturation, Value) triples. This is done
-either by adjusting single values with sliders or entries, or by picking the desired
-color from a hue-saturation wheel/value bar. Optionally, the opacity of the color can also
-be set.
+selection of colors. This composite widget lets the user select a color by
+manipulating RGB (Red, Green, Blue) and HSV (Hue, Saturation, Value) triples.
+This is done either by adjusting single values with sliders or entries, or
+by picking the desired color from a hue-saturation wheel/value bar.
+Optionally, the opacity of the color can also be set.
 
-The color selection widget currently emits only one signal, "color_changed", which is emitted
-whenever the current color in the widget changes, either when the user changes it or if
-it's set explicitly through gtk_color_selection_set_color().
+The color selection widget currently emits only one signal,
+"color_changed", which is emitted whenever the current color in the widget
+changes, either when the user changes it or if it's set explicitly through
+gtk_color_selection_set_color().
 
-Lets have a look at what the color selection widget has to offer us. The widget comes
-in two flavours; gtk_color_selection and gtk_color_selection_dialog:
+Lets have a look at what the color selection widget has to offer us. The
+widget comes in two flavours; gtk_color_selection and
+gtk_color_selection_dialog:
 
 <tscreen><verb>
-GtkWidget *gtk_color_selection_new(void);
+GtkWidget *gtk_color_selection_new( void );
 </verb></tscreen>
 	
 You'll probably not be using this constructor directly. It creates an orphan
-GtkColorSelection widget which you'll have to parent yourself. The GtkColorSelection widget
-inherits from the GtkVBox widget.
+GtkColorSelection widget which you'll have to parent yourself. The
+GtkColorSelection widget inherits from the GtkVBox widget.
 
 <tscreen><verb> 
-GtkWidget *gtk_color_selection_dialog_new(const gchar *title);
+GtkWidget *gtk_color_selection_dialog_new( const gchar *title );
 </verb></tscreen>
 
-This is the most common color selection constructor. It creates a GtkColorSelectionDialog, which
-inherits from a GtkDialog. It consists of a GtkFrame containing a GtkColorSelection widget, a
-GtkHSeparator and a GtkHBox with three buttons, "Ok", "Cancel" and "Help". You can reach these
-buttons by accessing the "ok_button", "cancel_button" and "help_button" widgets in the
-GtkColorSelectionDialog structure, (i.e. GTK_COLOR_SELECTION_DIALOG(colorseldialog)->ok_button).
+This is the most common color selection constructor. It creates a 
+GtkColorSelectionDialog, which inherits from a GtkDialog. It consists
+of a GtkFrame containing a GtkColorSelection widget, a GtkHSeparator and a
+GtkHBox with three buttons, "Ok", "Cancel" and "Help". You can reach these
+buttons by accessing the "ok_button", "cancel_button" and "help_button"
+widgets in the GtkColorSelectionDialog structure, 
+(i.e. GTK_COLOR_SELECTION_DIALOG(colorseldialog)->ok_button).
 
 <tscreen><verb>
-void gtk_color_selection_set_update_policy(GtkColorSelection *colorsel, 
-                                           GtkUpdateType policy);
+void gtk_color_selection_set_update_policy( GtkColorSelection *colorsel, 
+                                            GtkUpdateType      policy );
 </verb></tscreen>
 
-This function sets the update policy. The default policy is GTK_UPDATE_CONTINOUS which means that
-the current color is updated continously when the user drags the sliders or presses the mouse and drags
-in the hue-saturation wheel or value bar. If you experience performance problems, you may
-want to set the policy to GTK_UPDATE_DISCONTINOUS or GTK_UPDATE_DELAYED.
+This function sets the update policy. The default policy is
+GTK_UPDATE_CONTINOUS which means that the current color is updated 
+continously when the user drags the sliders or presses the mouse and drags
+in the hue-saturation wheel or value bar. If you experience performance
+problems, you may want to set the policy to GTK_UPDATE_DISCONTINOUS or 
+GTK_UPDATE_DELAYED.
 
 <tscreen><verb>
-void gtk_color_selection_set_opacity(GtkColorSelection *colorsel,
-                                     gint use_opacity);
+void gtk_color_selection_set_opacity( GtkColorSelection *colorsel,
+                                      gint               use_opacity );
 </verb></tscreen>
 
-The color selection widget supports adjusting the opacity of a color (also known as the alpha channel).
-This is disabled by default. Calling this function with use_opacity set to TRUE enables opacity.
-Likewise, use_opacity set to FALSE will disable opacity.
+The color selection widget supports adjusting the opacity of a color
+(also known as the alpha channel). This is disabled by default. Calling
+this function with use_opacity set to TRUE enables opacity. Likewise,
+use_opacity set to FALSE will disable opacity.
 
 <tscreen><verb>
-void gtk_color_selection_set_color(GtkColorSelection *colorsel,
-                                   gdouble *color);
+void gtk_color_selection_set_color( GtkColorSelection *colorsel,
+                                    gdouble           *color );
 </verb></tscreen>
 
-You can set the current color explicitly by calling this function with a pointer to an array
-of colors (gdouble). The length of the array depends on whether opacity is enabled or not.
-Position 0 contains the red component, 1 is green, 2 is blue and opacity is at position 3 (only if
-opacity is enabled, see gtk_color_selection_set_opacity()). All values are between 0.0 and 1.0.
+You can set the current color explicitly by calling this function with
+a pointer to an array of colors (gdouble). The length of the array depends
+on whether opacity is enabled or not. Position 0 contains the red component,
+1 is green, 2 is blue and opacity is at position 3 (only if opacity is enabled,
+see gtk_color_selection_set_opacity()). All values are between 0.0 and 1.0.
 
 <tscreen><verb>
-void gtk_color_selection_get_color(GtkColorSelection *colorsel,
-                                   gdouble *color);
+void gtk_color_selection_get_color( GtkColorSelection *colorsel,
+                                    gdouble           *color );
 </verb></tscreen>
 
-When you need to query the current color, typically when you've received a "color_changed" signal,
-you use this function. Color is a pointer to the array of colors to fill in. See the
-gtk_color_selection_set_color() function for the description of this array.
+When you need to query the current color, typically when you've received a
+"color_changed" signal, you use this function. Color is a pointer to the
+array of colors to fill in. See the gtk_color_selection_set_color() function
+for the description of this array.
 
 <!-- Need to do a whole section on DnD - TRG
 Drag and drop
@@ -3247,11 +3407,14 @@ on) or 1.0 (opacity off) followed by the red, green and blue values at positions
 If opacity is enabled, the opacity is passed in the value at position 4.
 -->
 
-Here's a simple example demonstrating the use of the GtkColorSelectionDialog. The program displays a window
-containing a drawing area. Clicking on it opens a color selection dialog, and changing the color in the
-color selection dialog changes the background color.
+Here's a simple example demonstrating the use of the GtkColorSelectionDialog.
+The program displays a window containing a drawing area. Clicking on it opens
+a color selection dialog, and changing the color in the color selection dialog
+changes the background color.
 
 <tscreen><verb>
+/* example-start colorsel/colorsel.c */
+
 #include <glib.h>
 #include <gdk/gdk.h>
 #include <gtk/gtk.h>
@@ -3387,7 +3550,9 @@ gint main (gint argc, gchar *argv[])
 
   return 0;
 }
+/* example-end */
 </verb></tscreen>
+
 <!-- ----------------------------------------------------------------- -->
 <sect1> File Selections
 <p>
@@ -3398,21 +3563,22 @@ to cut down on programming time.
 To create a new file selection box use:
 
 <tscreen><verb>
-GtkWidget* gtk_file_selection_new (gchar *title);
+GtkWidget *gtk_file_selection_new( gchar *title );
 </verb></tscreen>
 
 To set the filename, for example to bring up a specific directory, or
 give a default filename, use this function: 
 
 <tscreen><verb>
-void gtk_file_selection_set_filename (GtkFileSelection *filesel, gchar *filename);
+void gtk_file_selection_set_filename( GtkFileSelection *filesel,
+                                      gchar            *filename );
 </verb></tscreen>
 
 To grab the text that the user has entered or clicked on, use this 
 function:
 
 <tscreen><verb>
-gchar* gtk_file_selection_get_filename (GtkFileSelection *filesel);
+gchar *gtk_file_selection_get_filename( GtkFileSelection *filesel );
 </verb></tscreen>
 
 There are also pointers to the widgets contained within the file 
@@ -3434,11 +3600,11 @@ help_button pointers in signaling their use.
 
 Included here is an example stolen from testgtk.c, modified to run
 on it's own.  As you will see, there is nothing much to creating a file 
-selection widget.  While, in this example, the Help button appears on the 
+selection widget.  While in this example the Help button appears on the 
 screen, it does nothing as there is not a signal attached to it. 
 
 <tscreen><verb>
-/* filesel.c */
+/* example-start filesel/filesel.c */
 
 #include <gtk/gtk.h>
 
@@ -3482,6 +3648,7 @@ int main (int argc, char *argv[])
     gtk_main ();
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ***************************************************************** -->
@@ -3500,21 +3667,22 @@ The first function call you will need to know, as you can probably
 guess by now, is used to create a new notebook widget.
 
 <tscreen><verb>
-GtkWidget* gtk_notebook_new (void);
+GtkWidget *gtk_notebook_new( void );
 </verb></tscreen>
 
 Once the notebook has been created, there are 12 functions that 
-operate on the notebook widget.  Let's look at them individually.
+operate on the notebook widget. Let's look at them individually.
 
 The first one we will look at is how to position the page indicators.
 These page indicators or 'tabs' as they are referred to, can be positioned
-in four ways; top, bottom, left, or right.
+in four ways: top, bottom, left, or right.
 
 <tscreen><verb>
-void gtk_notebook_set_tab_pos (GtkNotebook *notebook, GtkPositionType pos);
+void gtk_notebook_set_tab_pos( GtkNotebook     *notebook,
+                               GtkPositionType  pos );
 </verb></tscreen>
 
-GtkPostionType will be one of the following, and they are pretty self explanatory.
+GtkPostionType will be one of the following, and they are pretty self explanatory:
 <itemize>
 <item> GTK_POS_LEFT
 <item> GTK_POS_RIGHT
@@ -3524,89 +3692,102 @@ GtkPostionType will be one of the following, and they are pretty self explanator
 
 GTK_POS_TOP is the default.
 
-Next we will look at how to add pages to the notebook.  There are three
+Next we will look at how to add pages to the notebook. There are three
 ways to add pages to the NoteBook.  Let's look at the first two together as 
 they are quite similar.
 
 <tscreen><verb>
-void gtk_notebook_append_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label);
+void gtk_notebook_append_page( GtkNotebook *notebook,
+                               GtkWidget   *child,
+                               GtkWidget   *tab_label );
 
-void gtk_notebook_prepend_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label);
+void gtk_notebook_prepend_page( GtkNotebook *notebook,
+                                GtkWidget   *child,
+                                GtkWidget   *tab_label );
 </verb></tscreen>
 
 These functions add pages to the notebook by inserting them from the 
 back of the notebook (append), or the front of the notebook (prepend).  
-*child is the widget that is placed within the notebook page, and *tab_label is
-the label for the page being added.
+<tt/child/ is the widget that is placed within the notebook page, and
+<tt/tab_label/ is the label for the page being added.
 
 The final function for adding a page to the notebook contains all of 
 the properties of the previous two, but it allows you to specify what position
 you want the page to be in the notebook.
 
 <tscreen><verb>
-void gtk_notebook_insert_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label, gint position);
+void gtk_notebook_insert_page( GtkNotebook *notebook,
+                               GtkWidget   *child,
+                               GtkWidget   *tab_label,
+                               gint         position );
 </verb></tscreen>
 
 The parameters are the same as _append_ and _prepend_ except it 
-contains an extra parameter, position.  This parameter is used to specify what
-place this page will inserted to.
+contains an extra parameter, <tt/position/.  This parameter is used to
+specify what place this page will be inserted into.
 
 Now that we know how to add a page, lets see how we can remove a page 
 from the notebook.
 
 <tscreen><verb>
-void gtk_notebook_remove_page (GtkNotebook *notebook, gint page_num);
+void gtk_notebook_remove_page( GtkNotebook *notebook,
+                               gint         page_num );
 </verb></tscreen>
 
 This function takes the page specified by page_num and removes it from 
-the widget *notebook.
+the widget pointed to by <tt/notebook/.
 
 To find out what the current page is in a notebook use the function:
 
 <tscreen><verb>
-gint gtk_notebook_current_page (GtkNotebook *notebook);
+gint gtk_notebook_current_page( GtkNotebook *notebook );
 </verb></tscreen>
 
 These next two functions are simple calls to move the notebook page 
-forward or backward.  Simply provide the respective function call with the
-notebook widget you wish to operate on.  Note:  When the NoteBook is currently
+forward or backward. Simply provide the respective function call with the
+notebook widget you wish to operate on.  Note: when the NoteBook is currently
 on the last page, and gtk_notebook_next_page is called, the notebook will 
-wrap back to the first page.  Likewise, if the NoteBook is on the first page, 
+wrap back to the first page. Likewise, if the NoteBook is on the first page, 
 and gtk_notebook_prev_page is called, the notebook will wrap to the last page.
 
 <tscreen><verb>
-void gtk_notebook_next_page (GtkNoteBook *notebook);
-void gtk_notebook_prev_page (GtkNoteBook *notebook);
+void gtk_notebook_next_page( GtkNoteBook *notebook );
+
+void gtk_notebook_prev_page( GtkNoteBook *notebook );
 </verb></tscreen>
 
-This next function sets the 'active' page.  If you wish the
+This next function sets the 'active' page. If you wish the
 notebook to be opened to page 5 for example, you would use this function.  
 Without using this function, the notebook defaults to the first page.
 
 <tscreen><verb>
-void gtk_notebook_set_page (GtkNotebook *notebook, gint page_num);
+void gtk_notebook_set_page( GtkNotebook *notebook,
+                            gint         page_num );
 </verb></tscreen>
 
 The next two functions add or remove the notebook page tabs and the 
 notebook border respectively.
 
 <tscreen><verb>
-void gtk_notebook_set_show_tabs (GtkNotebook *notebook, gint show_tabs);
-void gtk_notebook_set_show_border (GtkNotebook *notebook, gint show_border);
+void gtk_notebook_set_show_tabs( GtkNotebook *notebook,
+                                 gint         show_tabs);
+
+void gtk_notebook_set_show_border( GtkNotebook *notebook,
+                                   gint         show_border );
 </verb></tscreen>
 
-show_tabs and show_border can both be either TRUE or FALSE (0 or 1).
+show_tabs and show_border can be either TRUE or FALSE.
 
 Now lets look at an example, it is expanded from the testgtk.c code 
 that comes with the GTK distribution, and it shows all 13 functions. This 
-small program, creates a window with a notebook and six buttons.  The notebook 
+small program creates a window with a notebook and six buttons. The notebook 
 contains 11 pages, added in three different ways, appended, inserted, and 
-prepended.  The buttons allow you rotate the tab positions, add/remove the tabs
+prepended. The buttons allow you rotate the tab positions, add/remove the tabs
 and border, remove a page, change pages in both a forward and backward manner,
 and exit the program. 
 
 <tscreen><verb>
-/* notebook.c */
+/* example-start notebooknotebook.c */
 
 #include <gtk/gtk.h>
 
@@ -3642,7 +3823,7 @@ void remove_book (GtkButton *button, GtkNotebook *notebook)
     gtk_widget_draw(GTK_WIDGET(notebook), NULL);
 }
 
-void delete (GtkWidget *widget, gpointer data)
+void delete (GtkWidget *widget, GtkWidget *event, gpointer data)
 {
     gtk_main_quit ();
 }
@@ -3778,39 +3959,40 @@ int main (int argc, char *argv[])
     
     return 0;
 }
+/* example-end */
 </verb></tscreen>
-<p>
+
 Hopefully this helps you on your way with creating notebooks for your
 GTK applications.
 
 <!-- ----------------------------------------------------------------- -->
-<sect1> Scrolled Windows
+<sect1>Scrolled Windows
 <p>
 Scrolled windows are used to create a scrollable area inside a real window.  
-You may insert any types of widgets to these scrolled windows, and they will
-all be accessable regardless of the size by using the scrollbars.
+You may insert any type of widget into a scrolled window, and it will
+be accessable regardless of the size by using the scrollbars.
 
 The following function is used to create a new scolled window.
 
 <tscreen><verb>
-GtkWidget* gtk_scrolled_window_new (GtkAdjustment *hadjustment,
-                                    GtkAdjustment *vadjustment);
+GtkWidget *gtk_scrolled_window_new( GtkAdjustment *hadjustment,
+                                    GtkAdjustment *vadjustment );
 </verb></tscreen>
-<p>
+
 Where the first argument is the adjustment for the horizontal
 direction, and the second, the adjustment for the vertical direction.
 These are almost always set to NULL.
 
 <tscreen><verb>
-void gtk_scrolled_window_set_policy (GtkScrolledWindow *scrolled_window,
+void gtk_scrolled_window_set_policy( GtkScrolledWindow *scrolled_window,
                                      GtkPolicyType      hscrollbar_policy,
-				     GtkPolicyType      vscrollbar_policy);
+                                     GtkPolicyType      vscrollbar_policy );
 </verb></tscreen>
 
 This sets the policy to be used with respect to the scrollbars.
 The first arguement is the scrolled window you wish to change. The second
-sets the policiy for the horizontal scrollbar, and the third, 
-the vertical scrollbar.  
+sets the policiy for the horizontal scrollbar, and the third the policy for 
+the vertical scrollbar.
 
 The policy may be one of GTK_POLICY AUTOMATIC, or GTK_POLICY_ALWAYS.
 GTK_POLICY_AUTOMATIC will automatically decide whether you need
@@ -3821,7 +4003,7 @@ Here is a simple example that packs 100 toggle buttons into a scrolled window.
 I've only commented on the parts that may be new to you.
 
 <tscreen><verb>
-/* scrolledwin.c */
+/* example-start scrolledwin/scrolledwin.c */
 
 #include <gtk/gtk.h>
 
@@ -3913,11 +4095,12 @@ int main (int argc, char *argv[])
     
     return(0);
 }
+/* example-end */
 </verb></tscreen>
-<p>
-Try playing with resizing the window.  You'll notice how the scrollbars
-react.  You may also wish to use the gtk_widget_set_usize() call to set the default
-size of the window or other widgets.
+
+Try playing with resizing the window. You'll notice how the scrollbars
+react. You may also wish to use the gtk_widget_set_usize() call to set
+the default size of the window or other widgets.
 
 <!-- ----------------------------------------------------------------- -->   
 <sect1> Paned Window Widgets
@@ -3931,16 +4114,18 @@ be horizontal (HPaned) or vertical (VPaned).
 To create a new paned window, call one of:
    
 <tscreen><verb>
-GtkWidget* gtk_hpaned_new (void)
-GtkWidget* gtk_vpaned_new (void)
+GtkWidget *gtk_hpaned_new (void);
+
+GtkWidget *gtk_vpaned_new (void);
 </verb></tscreen>
 
 After creating the paned window widget, you need to add child widgets
 to its two halves. To do this, use the functions:
    
 <tscreen><verb>
-void gtk_paned_add1 (GtkPaned *paned, GtkWidget *child)
-void gtk_paned_add2 (GtkPaned *paned, GtkWidget *child)
+void gtk_paned_add1 (GtkPaned *paned, GtkWidget *child);
+
+void gtk_paned_add2 (GtkPaned *paned, GtkWidget *child);
 </verb></tscreen>
    
 <tt/gtk_paned_add1()/ adds the child widget to the left or top half of
@@ -3951,7 +4136,7 @@ As an example, we will create part of the user interface of an
 imaginary email program. A window is divided into two portions
 vertically, with the top portion being a list of email messages and
 the bottom portion the text of the email message. Most of the program
-is pretty straightforward. A couple of points to note are: Text can't
+is pretty straightforward. A couple of points to note: text can't
 be added to a Text widget until it is realized. This could be done by
 calling <tt/gtk_widget_realize()/, but as a demonstration of an alternate
 technique, we connect a handler to the "realize" signal to add the
@@ -3961,7 +4146,7 @@ that when the bottom portion is made smaller, the correct portions
 shrink instead of being pushed off the bottom of the window.
 
 <tscreen><verb>
-/* paned.c */
+/* example-start paned/paned.c */
 
 #include <gtk/gtk.h>
    
@@ -4097,7 +4282,7 @@ main (int argc, char *argv[])
     gtk_main ();
     return 0;
 }
-
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->   
@@ -4111,14 +4296,14 @@ preview a larger image. The size of the preview should vary when
 the user resizes the window, but the aspect ratio needs to always match
 the original image.
    
-To create a new aspect frame, use:
+To create a new aspect frame use:
    
 <tscreen><verb>
-GtkWidget* gtk_aspect_frame_new	 (const gchar *label,
-   					gfloat xalign,
-   					gfloat yalign,
-   					gfloat ratio,
-   					gint obey_child)
+GtkWidget *gtk_aspect_frame_new( const gchar *label,
+                                 gfloat       xalign,
+                                 gfloat       yalign,
+                                 gfloat       ratio,
+                                 gint         obey_child);
 </verb></tscreen>
    
 <tt/xalign/ and <tt/yalign/ specifiy alignment as with Alignment
@@ -4129,20 +4314,19 @@ Otherwise, it is given by <tt/ratio/.
 To change the options of an existing aspect frame, you can use:
    
 <tscreen><verb>
-void gtk_aspect_frame_set (GtkAspectFrame *aspect_frame,
-			   gfloat xalign,
-			   gfloat yalign,
-			   gfloat ratio,
-			   gint obey_child)
+void gtk_aspect_frame_set( GtkAspectFrame *aspect_frame,
+                           gfloat          xalign,
+                           gfloat          yalign,
+                           gfloat          ratio,
+                           gint            obey_child);
 </verb></tscreen>
    
-<p>
 As an example, the following program uses an AspectFrame to
 present a drawing area whose aspect ratio will always be 2:1, no
 matter how the user resizes the top-level window.
    
 <tscreen><verb>
-/* aspectframe.c */
+/* example-start aspectframe/aspectframe.c */
 
 #include <gtk/gtk.h>
    
@@ -4157,7 +4341,7 @@ main (int argc, char *argv[])
     window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
     gtk_window_set_title (GTK_WINDOW (window), "Aspect Frame");
     gtk_signal_connect (GTK_OBJECT (window), "destroy",
-    GTK_SIGNAL_FUNC (gtk_main_quit), NULL);
+                        GTK_SIGNAL_FUNC (gtk_main_quit), NULL);
     gtk_container_border_width (GTK_CONTAINER (window), 10);
    
     /* Create an aspect_frame and add it to our toplevel window */
@@ -4184,14 +4368,16 @@ main (int argc, char *argv[])
     gtk_widget_show (window);
     gtk_main ();
     return 0;
-}  
+}
+/* example-end */
 </verb></tscreen>
                               
 <!-- ***************************************************************** -->
 <sect> List Widgets
 <!-- ***************************************************************** -->
-
 <p>
+NOTE: The GtkList widget has been superseded by the GtkCList widget.
+
 The GtkList widget is designed to act as a vertical container for widgets
 that should be of the type GtkListItem.
 
@@ -4201,7 +4387,7 @@ GtkContainer it can be treated as such by using the GTK_CONTAINER(List)
 macro, see the GtkContainer widget for more on this.
 One should already be familar whith the usage of a GList and its
 related functions g_list_*() to be able to use the GtkList widget to
-its fully extends.
+it full extent.
 
 There is one field inside the structure definition of the GtkList widget
 that will be of greater interest to us, this is:
@@ -4217,53 +4403,53 @@ struct _GtkList
 </verb></tscreen>
 
 The selection field of a GtkList points to a linked list of all items
-that are cureently selected, or `NULL' if the selection is empty.
+that are curently selected, or NULL if the selection is empty.
 So to learn about the current selection we read the GTK_LIST()->selection
 field, but do not modify it since the internal fields are maintained by
 the gtk_list_*() functions.
 
 The selection_mode of the GtkList determines the selection facilities
 of a GtkList and therefore the contents of the GTK_LIST()->selection
-field:
+field. The selection_mode may be one of the following:
 
-The selection_mode may be one of the following:
 <itemize>
-<item> GTK_SELECTION_SINGLE -   The selection is either `NULL'
-                        or contains a GList* pointer
+<item> GTK_SELECTION_SINGLE - The selection is either NULL
+                        or contains a GList pointer
                         for a single selected item.
 
-<item> GTK_SELECTION_BROWSE -  The selection is `NULL' if the list
+<item> GTK_SELECTION_BROWSE -  The selection is NULL if the list
                         contains no widgets or insensitive
                         ones only, otherwise it contains
                         a GList pointer for one GList
                         structure, and therefore exactly
                         one list item.
 
-<item> GTK_SELECTION_MULTIPLE -  The selection is `NULL' if no list
+<item> GTK_SELECTION_MULTIPLE -  The selection is NULL if no list
                         items are selected or a GList pointer
                         for the first selected item. That
                         in turn points to a GList structure
                         for the second selected item and so
                         on.
 
-<item> GTK_SELECTION_EXTENDED - The selection is always `NULL'.
+<item> GTK_SELECTION_EXTENDED - The selection is always NULL.
 </itemize>
-<p>
+
 The default is GTK_SELECTION_MULTIPLE.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Signals
 <p>
 <tscreen><verb>
-void selection_changed (GtkList *LIST)
+void selection_changed( GtkList *list );
 </verb></tscreen>
 
-This signal will be invoked whenever a the selection field
+This signal will be invoked whenever the selection field
 of a GtkList has changed. This happens when a child of
-the GtkList got selected or unselected.
+the GtkList got selected or deselected.
 
 <tscreen><verb>
-void select_child (GtkList *LIST, GtkWidget *CHILD)
+void select_child( GtkList   *list,
+                   GtkWidget *child);
 </verb></tscreen>
 
 This signal is invoked when a child of the GtkList is about
@@ -4273,11 +4459,12 @@ and sometimes indirectly triggered on some else occasions where
 children get added to or removed from the GtkList.
 
 <tscreen><verb>
-void unselect_child (GtkList *LIST, GtkWidget *CHILD)
+void unselect_child( GtkList   *list,
+                     GtkWidget *child );
 </verb></tscreen>
 
 This signal is invoked when a child of the GtkList is about
-to get unselected. This happens mainly on calls to
+to get deselected. This happens mainly on calls to
 gtk_list_unselect_item(), gtk_list_unselect_child(), button presses
 and sometimes indirectly triggered on some else occasions where
 children get added to or removed from the GtkList.
@@ -4286,116 +4473,128 @@ children get added to or removed from the GtkList.
 <sect1> Functions
 <p>
 <tscreen><verb>
-guint gtk_list_get_type (void)
+guint gtk_list_get_type( void );
 </verb></tscreen>
 
 Returns the `GtkList' type identifier.
 
 <tscreen><verb>
-GtkWidget* gtk_list_new (void)
+GtkWidget *gtk_list_new( void );
 </verb></tscreen>
 
-Create a new `GtkList' object. The new widget is
-returned as a pointer to a `GtkWidget' object.
-`NULL' is returned on failure.
+Create a new GtkList object. The new widget is returned as a pointer to a
+GtkWidget object. NULL is returned on failure.
 
 <tscreen><verb>
-void gtk_list_insert_items (GtkList *LIST, GList *ITEMS, gint POSITION)
+void gtk_list_insert_items( GtkList *list,
+                            GList   *items,
+                            gint     position );
 </verb></tscreen>
 
-Insert list items into the LIST, starting at POSITION.
-ITEMS is a doubly linked list where each nodes data
+Insert list items into the list, starting at <tt/position/.
+<tt/items/ is a doubly linked list where each nodes data
 pointer is expected to point to a newly created GtkListItem.
-The GList nodes of ITEMS are taken over by the LIST.
+The GList nodes of <tt/items/ are taken over by the list.
 
 <tscreen><verb>
-void gtk_list_append_items (GtkList *LIST, GList *ITEMS)
+void gtk_list_append_items( GtkList *list,
+                            GList   *items);
 </verb></tscreen>
 
 Insert list items just like gtk_list_insert_items() at the end
-of the LIST. The GList nodes of ITEMS are taken over by the LIST.
+of the list. The GList nodes of <tt/items/ are taken over by the list.
 
 <tscreen><verb>
-void gtk_list_prepend_items (GtkList *LIST, GList *ITEMS)
+void gtk_list_prepend_items( GtkList *list,
+                             GList   *items);
 </verb></tscreen>
 
 Insert list items just like gtk_list_insert_items() at the very
-beginning of the LIST. The GList nodes of ITEMS are taken over
-by the LIST.
+beginning of the list. The GList nodes of <tt/items/ are taken over
+by the list.
 
 <tscreen><verb>
-void gtk_list_remove_items (GtkList *LIST, GList *ITEMS)
+void gtk_list_remove_items( GtkList *list,
+                            GList   *items);
 </verb></tscreen>
 
-Remove list items from the LIST. ITEMS is a doubly linked
+Remove list items from the list. <tt/items/ is a doubly linked
 list where each nodes data pointer is expected to point to a
-direct child of LIST. It is the callers responsibility to make a
-call to g_list_free(ITEMS) afterwards. Also the caller has to
+direct child of list. It is the callers responsibility to make a
+call to g_list_free(items) afterwards. Also the caller has to
 destroy the list items himself.
 
 <tscreen><verb>
-void gtk_list_clear_items (GtkList *LIST, gint START, gint END)
+void gtk_list_clear_items( GtkList *list,
+                           gint start,
+                           gint end );
 </verb></tscreen>
 
-Remove and destroy list items from the LIST. a widget is affected if
-its current position within LIST is in the range specified by START
-and END.
+Remove and destroy list items from the list. A widget is affected if
+its current position within the list is in the range specified by
+<tt/start/ and <tt/end/.
 
 <tscreen><verb>
-void gtk_list_select_item (GtkList *LIST, gint ITEM)
+void gtk_list_select_item( GtkList *list,
+                           gint     item );
 </verb></tscreen>
 
 Invoke the select_child signal for a list item
-specified through its current position within LIST.
+specified through its current position within the list.
 
 <tscreen><verb>
-void gtk_list_unselect_item (GtkList *LIST, gint ITEM)
+void gtk_list_unselect_item( GtkList *list,
+                             gint     item);
 </verb></tscreen>
 
 Invoke the unselect_child signal for a list item
-specified through its current position within LIST.
+specified through its current position within the list.
 
 <tscreen><verb>
-void gtk_list_select_child (GtkList *LIST, GtkWidget *CHILD)
+void gtk_list_select_child( GtkList *list,
+                            GtkWidget *child);
 </verb></tscreen>
 
-Invoke the select_child signal for the specified CHILD.
+Invoke the select_child signal for the specified child.
 
 <tscreen><verb>
-void gtk_list_unselect_child (GtkList *LIST, GtkWidget *CHILD)
+void gtk_list_unselect_child( GtkList   *list,
+                              GtkWidget *child);
 </verb></tscreen>
 
-Invoke the unselect_child signal for the specified CHILD.
+Invoke the unselect_child signal for the specified child.
 
 <tscreen><verb>
-gint gtk_list_child_position (GtkList *LIST, GtkWidget *CHILD)
+gint gtk_list_child_position( GtkList *list,
+                              GtkWidget *child);
 </verb></tscreen>
 
-Return the position of CHILD within LIST. `-1' is returned on failure.
+Return the position of <tt/child/ within the list. "-1" is returned on failure.
 
 <tscreen><verb>
-void gtk_list_set_selection_mode (GtkList *LIST, GtkSelectionMode MODE)
+void gtk_list_set_selection_mode( GtkList         *list,
+                                  GtkSelectionMode mode );
 </verb></tscreen>
 
-Set LIST to the selection mode MODE wich can be of GTK_SELECTION_SINGLE,
+Set the selection mode MODE which can be of GTK_SELECTION_SINGLE,
 GTK_SELECTION_BROWSE, GTK_SELECTION_MULTIPLE or GTK_SELECTION_EXTENDED.
 
 <tscreen><verb>
-GtkList* GTK_LIST (gpointer OBJ)
+GtkList *GTK_LIST( gpointer obj );
 </verb></tscreen>
 
-Cast a generic pointer to `GtkList*'. *Note Standard Macros::, for
+Cast a generic pointer to `GtkList *'. *Note Standard Macros::, for
 more info.
 
 <tscreen><verb>
-GtkListClass* GTK_LIST_CLASS (gpointer CLASS)
+GtkListClass *GTK_LIST_CLASS( gpointer class);
 </verb></tscreen>
 
 Cast a generic pointer to `GtkListClass*'. *Note Standard Macros::,
 for more info.
 
 <tscreen><verb>
-gint GTK_IS_LIST (gpointer OBJ)
+gint GTK_IS_LIST( gpointer obj);
 </verb></tscreen>
 
 Determine if a generic pointer refers to a `GtkList' object. *Note
@@ -4406,10 +4605,10 @@ Standard Macros::, for more info.
 <p>
 Following is an example program that will print out the changes
 of the selection of a GtkList, and lets you "arrest" list items
-into a prison by selecting them with the rightmost mouse button:
+into a prison by selecting them with the rightmost mouse button.
 
 <tscreen><verb>
-/* list.c */
+/* example-start list/list.c */
 
 /* include the gtk+ header files
  * include stdio.h, we need that for the printf() function
@@ -4691,6 +4890,7 @@ sigh_print_selection    (GtkWidget      *gtklist,
     }
     g_print("\n");
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
@@ -4707,7 +4907,7 @@ As it is directly derived from a
 GtkItem it can be treated as such by using the GTK_ITEM(ListItem)
 macro, see the GtkItem widget for more on this.
 Usualy a GtkListItem just holds a label to identify e.g. a filename
-within a GtkList -- therefore the convenient function
+within a GtkList -- therefore the convenience function
 gtk_list_item_new_with_label() is provided.  The same effect can be
 achieved by creating a GtkLabel on its own, setting its alignment
 to xalign=0 and yalign=0.5 with a subsequent container addition
@@ -4725,32 +4925,29 @@ the signals of a GtkItem. *Note GtkItem::, for more info.
 <!-- ----------------------------------------------------------------- -->
 <sect1> Functions
 <p>
-
 <tscreen><verb>
-guint gtk_list_item_get_type (void)
+guint gtk_list_item_get_type( void );
 </verb></tscreen>
 
 Returns the `GtkListItem' type identifier.
 
 <tscreen><verb>
-GtkWidget* gtk_list_item_new (void)
+GtkWidget *gtk_list_item_new( void );
 </verb></tscreen>
 
-Create a new `GtkListItem' object. The new widget is
-returned as a pointer to a `GtkWidget' object.
-`NULL' is returned on failure.
+Create a new GtkListItem object. The new widget is returned as a pointer
+to a GtkWidget object. NULL is returned on failure.
 
 <tscreen><verb>
-GtkWidget* gtk_list_item_new_with_label (gchar *LABEL)
+GtkWidget *gtk_list_item_new_with_label( gchar *label );
 </verb></tscreen>
 
-Create a new `GtkListItem' object, having a single GtkLabel as
+Create a new GtkListItem object, having a single GtkLabel as
 the sole child. The new widget is returned as a pointer to a
-`GtkWidget' object.
-`NULL' is returned on failure.
+GtkWidget object. NULL is returned on failure.
 
 <tscreen><verb>
-void gtk_list_item_select (GtkListItem *LIST_ITEM)
+void gtk_list_item_select( GtkListItem *list_item );
 </verb></tscreen>
 
 This function is basicaly a wrapper around a call to
@@ -4759,7 +4956,7 @@ select signal.
 *Note GtkItem::, for more info.
 
 <tscreen><verb>
-void gtk_list_item_deselect (GtkListItem *LIST_ITEM)
+void gtk_list_item_deselect( GtkListItem *list_item );
 </verb></tscreen>
 
 This function is basicaly a wrapper around a call to
@@ -4768,21 +4965,21 @@ deselect signal.
 *Note GtkItem::, for more info.
 
 <tscreen><verb>
-GtkListItem* GTK_LIST_ITEM (gpointer OBJ)
+GtkListItem *GTK_LIST_ITEM( gpointer obj );
 </verb></tscreen>
 
 Cast a generic pointer to `GtkListItem*'. *Note Standard Macros::,
 for more info.
 
 <tscreen><verb>
-GtkListItemClass* GTK_LIST_ITEM_CLASS (gpointer CLASS)
+GtkListItemClass *GTK_LIST_ITEM_CLASS( gpointer class );
 </verb></tscreen>
 
-Cast a generic pointer to `GtkListItemClass*'. *Note Standard
+Cast a generic pointer to GtkListItemClass*. *Note Standard
 Macros::, for more info.
 
 <tscreen><verb>
-gint GTK_IS_LIST_ITEM (gpointer OBJ)
+gint GTK_IS_LIST_ITEM( gpointer obj );
 </verb></tscreen>
 
 Determine if a generic pointer refers to a `GtkListItem' object.
@@ -4797,17 +4994,16 @@ GtkListItem as well.
 <!-- ***************************************************************** -->
 <sect>Menu Widgets
 <!-- ***************************************************************** -->
-
 <p>
 There are two ways to create menus, there's the easy way, and there's the
-hard way.  Both have their uses, but you can usually use the menufactory
-(the easy way).  The "hard" way is to create all the menus using the calls
-directly.  The easy way is to use the gtk_menu_factory calls.  This is
+hard way. Both have their uses, but you can usually use the menufactory
+(the easy way). The "hard" way is to create all the menus using the calls
+directly. The easy way is to use the gtk_menu_factory calls. This is
 much simpler, but there are advantages and disadvantages to each approach.
 
 The menufactory is much easier to use, and to add new menus to, although
 writing a few wrapper functions to create menus using the manual method 
-could go a long way towards usability.  With the menufactory, it is not 
+could go a long way towards usability. With the menufactory, it is not 
 possible to add images or the character '/' to the menus.
 
 <!-- ----------------------------------------------------------------- -->
@@ -4815,7 +5011,7 @@ possible to add images or the character '/' to the menus.
 <p>
 In the true tradition of teaching, we'll show you the hard
 way first. <tt>:)</>
-<p>
+
 There are three widgets that go into making a menubar and submenus:
 <itemize>
 <item>a menu item, which is what the user wants to select, e.g. 'Save'
@@ -4823,15 +5019,16 @@ There are three widgets that go into making a menubar and submenus:
 <item>a menubar, which is a container for each of the individual menus,
 </itemize>
 
-This is slightly complicated by the fact that menu item widgets are used for two different things. They are
-both the widets that are packed into the menu, and the widget that is packed into the menubar, which,
+This is slightly complicated by the fact that menu item widgets are used
+for two different things. They are both the widets that are packed into
+the menu, and the widget that is packed into the menubar, which,
 when selected, activiates the menu.
 
 Let's look at the functions that are used to create menus and menubars.
 This first function is used to create a new menubar.
 
 <tscreen><verb>
-GtkWidget *gtk_menu_bar_new(void);
+GtkWidget *gtk_menu_bar_new( void );
 </verb></tscreen>
 
 This rather self explanatory function creates a new menubar.  You use
@@ -4839,41 +5036,41 @@ gtk_container_add to pack this into a window, or the box_pack functions to
 pack it into a box - the same as buttons.
 
 <tscreen><verb>
-GtkWidget *gtk_menu_new();
+GtkWidget *gtk_menu_new( void );
 </verb></tscreen>
 
 This function returns a pointer to a new menu, it is never actually shown
 (with gtk_widget_show), it is just a container for the menu items.  Hopefully this will
 become more clear when you look at the example below.
-<p>
+
 The next two calls are used to create menu items that are packed into
 the menu (and menubar).
 
 <tscreen><verb>
-GtkWidget *gtk_menu_item_new();
+GtkWidget *gtk_menu_item_new( void );
 </verb></tscreen>
 
 and
 
 <tscreen><verb>
-GtkWidget *gtk_menu_item_new_with_label(const char *label);
+GtkWidget *gtk_menu_item_new_with_label( const char *label );
 </verb></tscreen>
 
 These calls are used to create the menu items that are to be displayed.
 Remember to differentiate between a "menu" as created with gtk_menu_new
-and a "menu item" as created by the gtk_menu_item_new functions.  The
+and a "menu item" as created by the gtk_menu_item_new functions. The
 menu item will be an actual button with an associated action,
 whereas a menu will be a container holding menu items.
 
 The gtk_menu_new_with_label and gtk_menu_new functions are just as you'd expect after
-reading about the buttons.  One creates a new menu item with a label
+reading about the buttons. One creates a new menu item with a label
 already packed into it, and the other just creates a blank menu item.
 
-Once you've created a menu item you have to put it into a menu. This is done using the function
-gtk_menu_append. In order to capture when the item is selected by the user, we need to connect
-to the <tt/activate/ signal in the usual way.
-So, if we wanted to create a standard <tt/File/ menu, with the options <tt/Open/, 
-<tt/Save/ and <tt/Quit/ the code would look something like
+Once you've created a menu item you have to put it into a menu. This is 
+done using the function gtk_menu_append. In order to capture when the item
+is selected by the user, we need to connect to the <tt/activate/ signal in
+the usual way. So, if we wanted to create a standard <tt/File/ menu, with
+the options <tt/Open/, <tt/Save/ and <tt/Quit/ the code would look something like
 
 <tscreen><verb>
 file_menu = gtk_menu_new();    /* Don't need to show menus */
@@ -4904,8 +5101,8 @@ gtk_widget_show( save_item );
 gtk_widget_show( quit_item );
 </verb></tscreen>
 
-At this point we have our menu. Now we need to create a menubar and a menu item for the <tt/File/ entry,
-to which we add our menu. The code looks like this 
+At this point we have our menu. Now we need to create a menubar and a menu
+item for the <tt/File/ entry, to which we add our menu. The code looks like this 
 
 <tscreen><verb>
 menu_bar = gtk_menu_bar_new();
@@ -4916,20 +5113,22 @@ file_item = gtk_menu_item_new_with_label("File");
 gtk_widget_show(file_item);
 </verb></tscreen>
 
-Now we need to associate the menu with <tt/file_item/. This is done with the function
+Now we need to associate the menu with <tt/file_item/. This is done with the
+function
 
 <tscreen>
 void gtk_menu_item_set_submenu( GtkMenuItem *menu_item,
-                                GtkWidget *submenu);
+                                GtkWidget   *submenu );
 </tscreen>
 
 So, our example would continue with
 
 <tscreen><verb>
-gtk_menu_item_set_submenu( GTK_MENU_ITEM(file_item), file_menu);
+gtk_menu_item_set_submenu( GTK_MENU_ITEM(file_item), file_menu );
 </verb></tscreen>
 
-All that is left to do is to add the menu to the menubar, which is accomplished using the function
+All that is left to do is to add the menu to the menubar, which is accomplished
+using the function
 
 <tscreen>
 void gtk_menu_bar_append( GtkMenuBar *menu_bar, GtkWidget *menu_item);
@@ -4941,39 +5140,43 @@ which in our case looks like this:
 gtk_menu_bar_append( GTK_MENU_BAR (menu_bar), file_item );
 </verb></tscreen>
 
-If we wanted the menu right justified on the menubar, such as help menus often are, we can
-use the following function (again on <tt/file_item/ in the current example) before attaching 
-it to the menubar.
+If we wanted the menu right justified on the menubar, such as help menus
+often are, we can use the following function (again on <tt/file_item/
+in the current example) before attaching it to the menubar.
+
 <tscreen><verb>
-void gtk_menu_item_right_justify (GtkMenuItem *menu_item);
+void gtk_menu_item_right_justify( GtkMenuItem *menu_item );
 </verb></tscreen>
 
 Here is a summary of the steps needed to create a menu bar with menus attached:
+
 <itemize>
-<item>	Create a new menu using gtk_menu_new()
-<item>	Use multiple calls to gtk_menu_item_new() for each item you wish to have on
-  your menu.  And use gtk_menu_append() to put each of these new items on
-  to the menu.
-<item>	Create a menu item using gtk_menu_item_new().  This will be the root of
-  the menu, the text appearing here will be on the menubar itself.
-<item>	Use gtk_menu_item_set_submenu() to attach the menu to
-  the root menu item (The one created in the above step).
-<item>	Create a new menubar using gtk_menu_bar_new.  This step only needs
-  to be done once when creating a series of menus on one menu bar.
+<item> Create a new menu using gtk_menu_new()
+<item> Use multiple calls to gtk_menu_item_new() for each item you wish to have
+on your menu. And use gtk_menu_append() to put each of these new items on 
+to the menu.
+<item> Create a menu item using gtk_menu_item_new(). This will be the root of
+the menu, the text appearing here will be on the menubar itself.
+<item>Use gtk_menu_item_set_submenu() to attach the menu to the root menu 
+item (the one created in the above step).
+<item> Create a new menubar using gtk_menu_bar_new. This step only needs
+to be done once when creating a series of menus on one menu bar.
 <item> Use gtk_menu_bar_append to put the root menu onto the menubar.
 </itemize>
-<p>
-Creating a popup menu is nearly the same.  The difference is that the
-menu is not posted `automatically' by a menubar, but explicitly
-by calling the function gtk_menu_popup() from a button-press event, for example.
+
+Creating a popup menu is nearly the same. The difference is that the
+menu is not posted `automatically' by a menubar, but explicitly by calling
+the function gtk_menu_popup() from a button-press event, for example.
 Take these steps:
+
 <itemize>
-<item>Create an event handling function.  It needs to have the prototype
+<item>Create an event handling function. It needs to have the prototype
 <tscreen>
-static gint handler(GtkWidget *widget, GdkEvent *event);
+static gint handler( GtkWidget *widget,
+                     GdkEvent  *event );
 </tscreen>
 and it will use the event to find out where to pop up the menu.
-<item>In the event handler, if event is a mouse button press, treat
+<item>In the event handler, if the event is a mouse button press, treat
 <tt>event</tt> as a button event (which it is) and use it as
 shown in the sample code to pass information to gtk_menu_popup().
 <item>Bind that event handler to a widget with
@@ -4993,7 +5196,7 @@ as shown in the sample code.
 That should about do it.  Let's take a look at an example to help clarify.
 
 <tscreen><verb>
-/* menu.c */
+/* example-start menu/menu.c */
 
 #include <gtk/gtk.h>
 
@@ -5094,8 +5297,6 @@ int main (int argc, char *argv[])
     return 0;
 }
 
-
-
 /* Respond to a button-press by posting a menu passed in as widget.
  *
  * Note that the "widget" argument is the menu being posted, NOT
@@ -5125,6 +5326,7 @@ static void menuitem_response (gchar *string)
 {
     printf("%s\n", string);
 }
+/* example-end */
 </verb></tscreen>
 
 You may also set a menu item to be insensitive and, using an accelerator
@@ -5140,11 +5342,11 @@ gtk_menu_factory calls.
 <sect1>Menu Factory Example
 <p>
 Here is an example using the GTK menu factory.  This is the first file,
-menufactory.h.  We keep a separate menufactory.c and mfmain.c because of the global variables used
-in the menufactory.c file.  
+menufactory.h.  We keep a separate menufactory.c and mfmain.c because
+of the global variables used in the menufactory.c file.  
 
 <tscreen><verb>
-/* menufactory.h */
+/* example-start menu/menufactory.h */
 
 #ifndef __MENUFACTORY_H__
 #define __MENUFACTORY_H__
@@ -5161,12 +5363,13 @@ void menus_create(GtkMenuEntry *entries, int nmenu_entries);
 #endif /* __cplusplus */
 
 #endif /* __MENUFACTORY_H__ */
+/* example-end */
 </verb></tscreen>
-<p>
+
 And here is the menufactory.c file.
 
 <tscreen><verb>
-/* menufactory.c */
+/* example-start menu/menufactory.c */
 
 #include <gtk/gtk.h>
 #include <strings.h>
@@ -5315,13 +5518,13 @@ void menus_set_sensitive(char *path, int sensitive)
     else
 	    g_warning("Unable to set sensitivity for menu which doesn't exist: %s", path);
 }
-
+/* example-end */
 </verb></tscreen>
-<p>
+
 And here's the mfmain.h
 
 <tscreen><verb>
-/* mfmain.h */
+/* example-start menu/mfmain.h */
 
 #ifndef __MFMAIN_H__
 #define __MFMAIN_H__
@@ -5338,12 +5541,13 @@ void file_quit_cmd_callback(GtkWidget *widget, gpointer data);
 #endif /* __cplusplus */
 
 #endif /* __MFMAIN_H__ */
+/* example-end */
 </verb></tscreen>
-<p>
+
 And mfmain.c
 
 <tscreen><verb>
-/* mfmain.c */
+/* example-start menu/mfmain.c */
 
 #include <gtk/gtk.h>
 
@@ -5393,8 +5597,9 @@ void file_quit_cmd_callback (GtkWidget *widget, gpointer data)
     g_print ("%s\n", (char *) data);
     gtk_exit(0);
 }
+/* example-end */
 </verb></tscreen>
-<p>
+
 And a makefile so it'll be easier to compile it.
 
 <tscreen><verb>
@@ -5421,7 +5626,7 @@ clean:
 distclean: clean 
 	rm -f *~
 </verb></tscreen>
-<p>
+
 For now, there's only this example.  An explanation and lots 'o' comments
 will follow later.
 
@@ -5429,38 +5634,40 @@ will follow later.
 <sect> Text Widget
 <!-- ***************************************************************** -->
 <p>
-The Text widget allows multiple lines of text to be displayed and edited. It supports both
-multi-colored and multi-font text, allowing them to be mixed in any way we wish. It also has
-a wide set of key based text editing commands, which are compatible with Emacs.
+The Text widget allows multiple lines of text to be displayed and edited.
+It supports both multi-colored and multi-font text, allowing them to be
+mixed in any way we wish. It also has a wide set of key based text editing
+commands, which are compatible with Emacs.
 
-The text widget supports full cut-and-paste facilities, including the use of double- and
-triple-click to select a word and a whole line, respectively.
+The text widget supports full cut-and-paste facilities, including the use
+of double- and triple-click to select a word and a whole line, respectively.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Creating and Configuring a Text box
 <p>
 There is only one function for creating a new Text widget.
 <tscreen><verb>
-GtkWidget* gtk_text_new (GtkAdjustment *hadj,
-                         GtkAdjustment *vadj);
+GtkWidget *gtk_text_new( GtkAdjustment *hadj,
+                         GtkAdjustment *vadj );
 </verb></tscreen>
 
-The arguments allow us to give the Text widget pointers to Adjustments that can be used 
-to track the viewing position of the widget. Passing NULL values to either or both of
-these arguments will cause the gtk_text_new function to create it's own.
+The arguments allow us to give the Text widget pointers to Adjustments
+that can be used to track the viewing position of the widget. Passing NULL
+values to either or both of these arguments will cause the gtk_text_new
+function to create it's own.
 
 <tscreen><verb>
-void gtk_text_set_adjustments (GtkText       *text,
+void gtk_text_set_adjustments( GtkText       *text,
                                GtkAdjustment *hadj,
-                               GtkAdjustment *vadj);
+                               GtkAdjustment *vadj );
 </verb></tscreen>
 
-The above function allows the horizontal and vertical adjustments of a Text widget to be
-changed at any time.
+The above function allows the horizontal and vertical adjustments of a
+Text widget to be changed at any time.
 
-The text widget will not automatically create it's own scrollbars when the amount of text
-to be displayed is too long for the display window. We therefore have to create and add
-them to the display layout ourselves.
+The text widget will not automatically create it's own scrollbars when
+the amount of text to be displayed is too long for the display window. We
+therefore have to create and add them to the display layout ourselves.
 
 <tscreen><verb>
   vscrollbar = gtk_vscrollbar_new (GTK_TEXT(text)->vadj);
@@ -5468,111 +5675,129 @@ them to the display layout ourselves.
   gtk_widget_show (vscrollbar);
 </verb></tscreen>
 
-The above code snippet creates a new vertical scrollbar, and attaches it to the vertical
-adjustment of the text widget, <tt/text/. It then packs it into a box in the normal way.
+The above code snippet creates a new vertical scrollbar, and attaches
+it to the vertical adjustment of the text widget, <tt/text/. It then packs
+it into a box in the normal way.
 
-There are two main ways in which a Text widget can be used: to allow the user to edit a
-body of text, or to allow us to display multiple lines of text to the user. In order for
-us to switch between these modes of operation, the text widget has the following function:
+Note, currently the GtkText widget does not support horizontal scrollbars.
+
+There are two main ways in which a Text widget can be used: to allow the
+user to edit a body of text, or to allow us to display multiple lines of
+text to the user. In order for us to switch between these modes of
+operation, the text widget has the following function:
 
 <tscreen><verb>
-void gtk_text_set_editable    (GtkText *text,
-                               gint    editable);
+void gtk_text_set_editable( GtkText *text,
+                            gint     editable );
 </verb></tscreen>
 
-The <tt/editable/ argument is a TRUE or FALSE value that specifies whether the user is
-permitted to edit the contents of the Text widget. When the text widget is editable, it
-will display a cursor at the current insertion point.
+The <tt/editable/ argument is a TRUE or FALSE value that specifies whether
+the user is permitted to edit the contents of the Text widget. When the
+text widget is editable, it will display a cursor at the current insertion
+point.
 
-You are not, however, restricted to just using the text widget in these two modes. You can
-toggle the editable state of the text widget at any time, and can insert text at any time.
+You are not, however, restricted to just using the text widget in these
+two modes. You can toggle the editable state of the text widget at any
+time, and can insert text at any time.
 
-The text widget is capable of wrapping lines of text that are too long to fit onto a single
-line of the display window. It's default behaviour is to break words across line breaks. This
-can be changed using the next function:
+The text widget wraps lines of text that are too long to
+fit onto a single line of the display window. It's default behaviour is
+to break words across line breaks. This can be changed using the next
+function:
 
 <tscreen><verb>
-void gtk_text_set_word_wrap (GtkText *text,
-                             gint    word_wrap);
+void gtk_text_set_word_wrap( GtkText *text,
+                             gint     word_wrap );
 </verb></tscreen>
 
-Using this function allows us to specify that the text widget should wrap long lines on word
-boundaries. The <tt/word_wrap/ argument is a TRUE or FALSE value.
+Using this function allows us to specify that the text widget should
+wrap long lines on word boundaries. The <tt/word_wrap/ argument is a
+TRUE or FALSE value.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Text Manipulation
 <P>
 The current insertion point of a Text widget can be set using
 <tscreen><verb>
-void gtk_text_set_point (GtkText *text,
-                         guint   index);
+void gtk_text_set_point( GtkText *text,
+                         guint    index );
 </verb></tscreen>
+
 where <tt/index/ is the position to set the insertion point.
 
 Analogous to this is the function for getting the current insertion point:
+
 <tscreen><verb>
-guint gtk_text_get_point (GtkText *text);
+guint gtk_text_get_point( GtkText *text );
 </verb></tscreen>
 
 A function that is useful in combination with the above two functions is
+
 <tscreen><verb>
-guint gtk_text_get_length (GtkText *text);
+guint gtk_text_get_length( GtkText *text );
 </verb></tscreen>
-which returns the current length of the Text widget. The length is the number of characters
-that are within the text block of the widget, including characters such as carriage-return,
-which marks the end of lines.
 
-In order to insert text at the current insertion point of a Text widget, the function
-gtk_text_insert is used, which also allows us to specify background and foreground colors and a 
-font for the text.
+which returns the current length of the Text widget. The length is the
+number of characters that are within the text block of the widget,
+including characters such as carriage-return, which marks the end of lines.
+
+In order to insert text at the current insertion point of a Text
+widget, the function gtk_text_insert is used, which also allows us to
+specify background and foreground colors and a font for the text.
 
 <tscreen><verb>
-void gtk_text_insert (GtkText    *text,
+void gtk_text_insert( GtkText    *text,
                       GdkFont    *font,
                       GdkColor   *fore,
                       GdkColor   *back,
                       const char *chars,
-                      gint       length);
+                      gint        length );
 </verb></tscreen>
 
-Passing a value of <tt/NULL/ in as the value for the foreground color, background colour or
-font will result in the values set within the widget style to be used. Using a value of <tt/-1/ for
-the length parameter will result in the whole of the text string given being inserted.
+Passing a value of <tt/NULL/ in as the value for the foreground color,
+background colour or font will result in the values set within the widget
+style to be used. Using a value of <tt/-1/ for the length parameter will
+result in the whole of the text string given being inserted.
 
-The text widget is one of the few within GTK that redraws itself dynamically, outside of the gtk_main
-function. This means that all changes to the contents of the text widget take effect immediately. This
-may be undesirable when performing multiple changes to the text widget. In order to allow us to perform
-multiple updates to the text widget without it continuously redrawing, we can freeze the widget, which
-temporarily stops it from automatically redrawing itself every time it is changed. We can then thaw the
-widget after our updates are complete.
+The text widget is one of the few within GTK that redraws itself
+dynamically, outside of the gtk_main function. This means that all changes
+to the contents of the text widget take effect immediately. This may be
+undesirable when performing multiple changes to the text widget. In order
+to allow us to perform multiple updates to the text widget without it
+continuously redrawing, we can freeze the widget, which temporarily stops
+it from automatically redrawing itself every time it is changed. We can
+then thaw the widget after our updates are complete.
 
 The following two functions perform this freeze and thaw action:
 
 <tscreen><verb>
-void gtk_text_freeze (GtkText *text);
-void gtk_text_thaw   (GtkText *text);         
+void gtk_text_freeze( GtkText *text );
+
+void gtk_text_thaw( GtkText *text );         
 </verb></tscreen>
 
-Text is deleted from the text widget relative to the current insertion point by the following
-two functions:
+Text is deleted from the text widget relative to the current insertion
+point by the following two functions. The return value is a TRUE or
+FALSE indicator of whether the operation was successful.
 
 <tscreen><verb>
-gint gtk_text_backward_delete (GtkText *text,
-                               guint   nchars);
-gint gtk_text_forward_delete  (GtkText *text,
-                               guint   nchars);
+gint gtk_text_backward_delete( GtkText *text,
+                               guint    nchars );
+
+gint gtk_text_forward_delete ( GtkText *text,
+                               guint    nchars );
 </verb></tscreen>
 
 If you want to retrieve the contents of the text widget, then the macro 
-<tt/GTK_TEXT_INDEX(t, index)/ allows you to retrieve the character at position
-<tt/index/ within the text widget <tt/t/.
+<tt/GTK_TEXT_INDEX(t, index)/ allows you to retrieve the character at
+position <tt/index/ within the text widget <tt/t/.
 
 To retrieve larger blocks of text, we can use the function
 
 <tscreen><verb>
-gchar *gtk_editable_get_chars (GtkEditable *editable,
-                               gint        start_pos,
-                               gint        end_pos);   
+gchar *gtk_editable_get_chars( GtkEditable *editable,
+                               gint         start_pos,
+                               gint         end_pos );   
 </verb></tscreen>
 
 This is a function of the parent class of the text widget. A value of -1 as
@@ -5585,24 +5810,24 @@ to free it with a call to g_free when you have finished with it.
 <sect1>Keyboard Shortcuts
 <p>
 The text widget has a number of pre-installed keyboard shotcuts for common
-editing, motion and selection functions. These are accessed using Control and Alt
-key combinations.
+editing, motion and selection functions. These are accessed using Control
+and Alt key combinations.
 
-In addition to these, holding down the Control key whilst using cursor key movement
-will move the cursor by words rather than characters. Holding down Shift whilst using
-cursor movement will extend the selection.
+In addition to these, holding down the Control key whilst using cursor key
+movement will move the cursor by words rather than characters. Holding down
+Shift whilst using cursor movement will extend the selection.
 
 <sect2>Motion Shotcuts
 <p>
 <itemize>
 <item> Ctrl-A   Beginning of line
-<item> Ctrl-E	End of line
+<item> Ctrl-E   End of line
 <item> Ctrl-N   Next Line
-<item> Ctrl-P	Previous Line
+<item> Ctrl-P   Previous Line
 <item> Ctrl-B   Backward one character
 <item> Ctrl-F   Forward one character
 <item> Alt-B    Backward one word
-<item> Alt-F	Forward one word
+<item> Alt-F    Forward one word
 </itemize>
 
 <sect2>Editing Shortcuts
@@ -5610,10 +5835,10 @@ cursor movement will extend the selection.
 <itemize>
 <item> Ctrl-H   Delete Backward Character (Backspace)
 <item> Ctrl-D   Delete Forward Character (Delete)
-<item> Ctrl-W	Delete Backward Word
+<item> Ctrl-W   Delete Backward Word
 <item> Alt-D    Delete Forward Word
-<item> Ctrl-K	Delete to end of line
-<item> Ctrl-U	Delete line
+<item> Ctrl-K   Delete to end of line
+<item> Ctrl-U   Delete line
 </itemize>
 
 <sect2>Selection Shortcuts
@@ -5621,30 +5846,44 @@ cursor movement will extend the selection.
 <itemize>
 <item> Ctrl-X   Cut to clipboard
 <item> Ctrl-C   Copy to clipboard
-<item> Ctrl-V	Paste from clipboard
+<item> Ctrl-V   Paste from clipboard
 </itemize>
 
 <!-- ***************************************************************** -->
 <sect> Undocumented Widgets
 <!-- ***************************************************************** -->
-
 <p>
 These all require authors! :)  Please consider contributing to our tutorial.
 
 If you must use one of these widgets that are undocumented, I strongly
-suggest you take a look at their respective header files in the GTK distro.
-GTK's function names are very descriptive.  Once you have an understanding
-of how things work, it's not difficult to figure out how to use a widget simply
-by looking at it's function declarations.  This, along with a few examples
-from others' code, and it should be no problem.
+suggest you take a look at their respective header files in the GTK
+distribution. GTK's function names are very descriptive.  Once you have an
+understanding of how things work, it's not difficult to figure out how to
+use a widget simply by looking at it's function declarations.  This, along
+with a few examples from others' code, and it should be no problem.
 
 When you do come to understand all the functions of a new undocumented
-widget, please consider writing a tutorial on it so others may benifit from
-your time.
+widget, please consider writing a tutorial on it so others may benifit
+from your time.
 
 <!-- ----------------------------------------------------------------- -->
+<sect1> Adjustments
+<p>
+<!-- ----------------------------------------------------------------- -->
+<sect1> Toolbar
+<p>
+<!-- ----------------------------------------------------------------- -->
+<sect1> Fixed Container
+<p>
+<!-- ----------------------------------------------------------------- -->
+<sect1> CList
+<p>
+<!-- ----------------------------------------------------------------- -->
 <sect1> Range Controls
-
+<p>
+<!-- ----------------------------------------------------------------- -->
+<sect1> Curves
+<p>
 <!-- ----------------------------------------------------------------- -->
 <sect1> Previews
 <p>
@@ -6088,53 +6327,45 @@ That's all, folks!
 
 </verb></tscreen>
 
-<!-- ----------------------------------------------------------------- -->
-<sect1> Curves
-<p>
-
 <!-- ***************************************************************** -->
 <sect>The EventBox Widget<label id="sec_The_EventBox_Widget">
 <!-- ***************************************************************** -->
-
 <p> 
 Some gtk widgets don't have associated X windows, so they just draw on 
-thier parents.  Because of this, they cannot recieve events
+their parents. Because of this, they cannot recieve events
 and if they are incorrectly sized, they don't clip so you can get
-messy overwritting etc.  If you require more from these widgets, the
+messy overwritting etc. If you require more from these widgets, the
 EventBox is for you.
 
 At first glance, the EventBox widget might appear to be totally
 useless. It draws nothing on the screen and responds to no
-events.  However, it does serve a function - it provides an X window for
+events. However, it does serve a function - it provides an X window for
 its child widget. This is important as many GTK widgets do not
-have an associated X window.  Not having an X window saves memory and
+have an associated X window. Not having an X window saves memory and
 improves performance, but also has some drawbacks. A widget without an
 X window cannot receive events, and does not perform any clipping on
-it's contents. Although the name ``EventBox'' emphasizes the
-event-handling function, the widget also can be used for clipping. 
+it's contents. Although the name <em/EventBox/ emphasizes the
+event-handling function, the widget can also be used for clipping. 
 (And more ... see the example below.)
 
-<p>
 To create a new EventBox widget, use:
 
 <tscreen><verb>
-GtkWidget* gtk_event_box_new (void);
+GtkWidget *gtk_event_box_new( void );
 </verb></tscreen>
 
-<p>
 A child widget can then be added to this EventBox:
 
 <tscreen><verb>
-gtk_container_add (GTK_CONTAINER(event_box), widget);
+gtk_container_add( GTK_CONTAINER(event_box), widget );
 </verb></tscreen>
 
-<p>
 The following example demonstrates both uses of an EventBox - a label
-is created that clipped to a small box, and set up so that a
+is created that is clipped to a small box, and set up so that a
 mouse-click on the label causes the program to exit.
 
 <tscreen><verb>
-/* eventbox.c */
+/* example-start eventbox/eventbox.c */
 
 #include <gtk/gtk.h>
 
@@ -6187,12 +6418,12 @@ main (int argc, char *argv[])
     
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ***************************************************************** -->
 <sect>Setting Widget Attributes<label id="sec_setting_widget_attributes">
 <!-- ***************************************************************** -->
-
 <p>
 This describes the functions used to operate on widgets.  These can be used
 to set style, padding, size etc.
@@ -6200,44 +6431,46 @@ to set style, padding, size etc.
 (Maybe I should make a whole section on accelerators.)
 
 <tscreen><verb>
-void       gtk_widget_install_accelerator (GtkWidget           *widget,
-					   GtkAcceleratorTable *table,
-					   gchar               *signal_name,
-					   gchar                key,
-					   guint8               modifiers);
+void gtk_widget_install_accelerator( GtkWidget           *widget,
+                                     GtkAcceleratorTable *table,
+                                     gchar               *signal_name,
+                                     gchar                key,
+                                     guint8               modifiers );
 
-void       gtk_widget_remove_accelerator  (GtkWidget           *widget,
-					   GtkAcceleratorTable *table,
-					   gchar               *signal_name);
+void gtk_widget_remove_accelerator ( GtkWidget           *widget,
+                                     GtkAcceleratorTable *table,
+                                     gchar               *signal_name);
 
-void       gtk_widget_activate            (GtkWidget           *widget);
+void gtk_widget_activate( GtkWidget *widget );
 
-void       gtk_widget_set_name            (GtkWidget           *widget,
-					   gchar               *name);
-gchar*     gtk_widget_get_name            (GtkWidget           *widget);
+void gtk_widget_set_name( GtkWidget *widget,
+                          gchar     *name );
 
-void       gtk_widget_set_sensitive       (GtkWidget           *widget,
-					   gint                 sensitive);
+gchar *gtk_widget_get_name( GtkWidget *widget );
 
-void       gtk_widget_set_style           (GtkWidget           *widget,
-					   GtkStyle            *style);
+void gtk_widget_set_sensitive( GtkWidget *widget,
+                               gint       sensitive );
+
+void gtk_widget_set_style( GtkWidget *widget,
+                           GtkStyle  *style );
 					   
-GtkStyle*    gtk_widget_get_style     (GtkWidget *widget);
+GtkStyle *gtk_widget_get_style( GtkWidget *widget );
+
+GtkStyle *gtk_widget_get_default_style( void );
 
-GtkStyle*    gtk_widget_get_default_style    (void);
+void gtk_widget_set_uposition( GtkWidget *widget,
+                               gint       x,
+                               gint       y );
 
-void       gtk_widget_set_uposition       (GtkWidget           *widget,
-					   gint                 x,
-					   gint                 y);
-void       gtk_widget_set_usize           (GtkWidget           *widget,
-					   gint                 width,
-					   gint                 height);
+void gtk_widget_set_usize( GtkWidget *widget,
+                           gint       width,
+                           gint       height );
 
-void       gtk_widget_grab_focus          (GtkWidget           *widget);
+void gtk_widget_grab_focus( GtkWidget *widget );
 
-void       gtk_widget_show                (GtkWidget           *widget);
+void gtk_widget_show( GtkWidget *widget );
 
-void       gtk_widget_hide                (GtkWidget           *widget);
+void gtk_widget_hide( GtkWidget *widget );
 </verb></tscreen>
 
 <!-- ***************************************************************** -->
@@ -6248,33 +6481,33 @@ void       gtk_widget_hide                (GtkWidget           *widget);
 <sect1>Timeouts
 <p>
 You may be wondering how you make GTK do useful work when in gtk_main.
-Well, you have several options.  Using the following functions you can
-create a timeout function that will be called every "interval" milliseconds.
+Well, you have several options. Using the following functions you can
+create a timeout function that will be called every "interval"
+milliseconds.
 
 <tscreen><verb>
-gint gtk_timeout_add (guint32 interval,
-		      GtkFunction function,
-		      gpointer data);
+gint gtk_timeout_add( guint32     interval,
+                      GtkFunction function,
+                      gpointer    data );
 </verb></tscreen>
 
-The first argument is the number of milliseconds
-between calls to your function.  The second argument is the function
-you wish to have called, and
-the third, the data passed to this callback function.  The return value is
+The first argument is the number of milliseconds between calls to your
+function.  The second argument is the function you wish to have called, and
+the third, the data passed to this callback function. The return value is
 an integer "tag" which may be used to stop the timeout by calling:
 
 <tscreen><verb>
-void gtk_timeout_remove (gint tag);
+void gtk_timeout_remove( gint tag );
 </verb></tscreen>
 
 You may also stop the timeout function by returning zero or FALSE from
-your callback function.  Obviously this means if you want your function to
+your callback function. Obviously this means if you want your function to
 continue to be called, it should return a non-zero value, ie TRUE.
 
 The declaration of your callback should look something like this:
 
 <tscreen><verb>
-gint timeout_callback (gpointer data);
+gint timeout_callback( gpointer data );
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
@@ -6285,61 +6518,64 @@ file descriptor for you (as returned by open(2) or socket(2)).	This is
 especially useful for networking applications.	The function:
 
 <tscreen><verb>
-gint gdk_input_add (gint source,
-		    GdkInputCondition condition,
-		    GdkInputFunction  function,
-		    gpointer data);
+gint gdk_input_add( gint              source,
+                    GdkInputCondition condition,
+                    GdkInputFunction  function,
+                    gpointer          data );
 </verb></tscreen>
 
 Where the first argument is the file descriptor you wish to have watched,
 and the second specifies what you want GDK to look for.  This may be one of:
-<p>
-GDK_INPUT_READ - Call your function when there is data ready for reading on
-your file descriptor.
-<p>
-GDK_INPUT_WRITE - Call your function when the file descriptor is ready for
-writing.
-<p>
+
+<itemize>
+<item>GDK_INPUT_READ - Call your function when there is data ready for
+reading on your file descriptor.
+
+<item>GDK_INPUT_WRITE - Call your function when the file descriptor is
+ready for writing.
+</itemize>
+
 As I'm sure you've figured out already, the third argument is the function
 you wish to have called when the above conditions are satisfied, and the
 fourth is the data to pass to this function.
-<p>
+
 The return value is a tag that may be used to stop GDK from monitoring this
 file descriptor using the following function.
-<p>
+
 <tscreen><verb>
-void gdk_input_remove (gint tag);
+void gdk_input_remove( gint tag );
 </verb></tscreen>
-<p>
-The callback function should be declared:
-<p>
+
+The callback function should be declared as:
+
 <tscreen><verb>
-void input_callback (gpointer data, gint source, 
-                     GdkInputCondition condition);
+void input_callback( gpointer          data,
+                     gint              source, 
+                     GdkInputCondition condition );
 </verb></tscreen>
-<p>
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Idle Functions
 <p>
+<!-- Need to check on idle priorities - TRG -->
 What if you have a function you want called when nothing else is
 happening ?
 
 <tscreen><verb>
-gint gtk_idle_add (GtkFunction function,
-		   gpointer data);
+gint gtk_idle_add( GtkFunction function,
+                   gpointer    data );
 </verb></tscreen>
 
 This causes GTK to call the specified function whenever nothing else is
 happening.
 
 <tscreen><verb>
-void gtk_idle_remove (gint tag);
+void gtk_idle_remove( gint tag );
 </verb></tscreen>
-<p>
+
 I won't explain the meaning of the arguments as they follow very much like
-the ones above.  The function pointed to by the first argument to
-gtk_idle_add will be called whenever the opportunity arises.  As with the
+the ones above. The function pointed to by the first argument to
+gtk_idle_add will be called whenever the opportunity arises. As with the
 others, returning FALSE will stop the idle function from being called.
 
 <!-- ***************************************************************** -->
@@ -6348,22 +6584,19 @@ others, returning FALSE will stop the idle function from being called.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Overview
-
 <p>
-
 One type of interprocess communication supported by GTK is
 <em>selections</em>. A selection identifies a chunk of data, for
 instance, a portion of text, selected by the user in some fashion, for
 instance, by dragging with the mouse. Only one application on a
-display, (he <em>owner</em>_ can own a particular selection at one
+display, (the <em>owner</em> can own a particular selection at one
 time, so when a selection is claimed by one application, the previous
 owner must indicate to the user that selection has been
 relinquished. Other applications can request the contents of a
-selection in different forms, called <em>targets</em>.  There can be
+selection in different forms, called <em>targets</em>. There can be
 any number of selections, but most X applications only handle one, the
 <em>primary selection</em>.
 
-<p>
 In most cases, it isn't necessary for a GTK application to deal with
 selections itself. The standard widgets, such as the Entry widget,
 already have the capability to claim the selection when appropriate
@@ -6374,11 +6607,10 @@ cases in which you want to give other widgets the ability to supply
 the selection, or you wish to retrieve targets not supported by
 default.
 
-<p>
 A fundamental concept needed to understand selection handling is that
 of the <em>atom</em>. An atom is an integer that uniquely identifies a
 string (on a certain display). Certain atoms are predefined by the X
-server, and in some cases there are constants in in <tt>gtk.h</tt>
+server, and in some cases there are constants in <tt>gtk.h</tt>
 corresponding to these atoms. For instance the constant
 <tt>GDK_PRIMARY_SELECTION</tt> corresponds to the string "PRIMARY".
 In other cases, you should use the functions
@@ -6388,28 +6620,25 @@ selections and targets are identifed by atoms.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Retrieving the selection
-
 <p>
-
 Retrieving the selection is an asynchronous process. To start the
 process, you call:
 
 <tscreen><verb>
-gint gtk_selection_convert   (GtkWidget 	  *widget, 
-			      GdkAtom    	   selection, 
-			      GdkAtom    	   target,
-			      guint32    	   time)
+gint gtk_selection_convert( GtkWidget *widget, 
+                            GdkAtom    selection, 
+                            GdkAtom    target,
+                            guint32    time );
 </verb</tscreen>
 
 This <em>converts</em> the selection into the form specified by
-<tt/target/. If it all possible, the time field should be the time
+<tt/target/. If at all possible, the time field should be the time
 from the event that triggered the selection. This helps make sure that
-events occur in the order that the user requested them.
- However, if it is not available (for instance, if the conversion was
-triggered by a "clicked" signal), then you can use the constant
+events occur in the order that the user requested them. However, if it
+is not available (for instance, if the conversion was triggered by
+a "clicked" signal), then you can use the constant
 <tt>GDK_CURRENT_TIME</tt>.
 
-<p>
 When the selection owner responds to the request, a
 "selection_received" signal is sent to your application. The handler
 for this signal receives a pointer to a <tt>GtkSelectionData</tt>
@@ -6434,7 +6663,7 @@ possible values are "STRING", a string of latin-1 characters, "ATOM",
 a series of atoms, "INTEGER", an integer, etc. Most targets can only
 return one type. <tt/format/ gives the length of the units (for
 instance characters) in bits. Usually, you don't care about this when
-receiving data.  <tt>data</tt> is a pointer to the returned data, and
+receiving data. <tt>data</tt> is a pointer to the returned data, and
 <tt>length</tt> gives the length of the returned data, in bytes. If
 <tt>length</tt> is negative, then an error occurred and the selection
 could not be retrieved. This might happen if no application owned the
@@ -6443,13 +6672,12 @@ support. The buffer is actually guaranteed to be one byte longer than
 <tt>length</tt>; the extra byte will always be zero, so it isn't
 necessary to make a copy of strings just to null terminate them.
 
-<p>
 In the following example, we retrieve the special target "TARGETS",
 which is a list of all targets into which the selection can be
 converted.
 
 <tscreen><verb>
-/* gettargets.c */
+/* example-start selection/gettargets.c */
 
 #include <gtk/gtk.h>
 
@@ -6545,39 +6773,37 @@ main (int argc, char *argv[])
   
   return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Supplying the selection 
-
 <p>
-
 Supplying the selection is a bit more complicated. You must register 
 handlers that will be called when your selection is requested. For
 each selection/target pair you will handle, you make a call to:
 
 <tscreen><verb>
-void gtk_selection_add_handler (GtkWidget           *widget, 
-				GdkAtom              selection,
-				GdkAtom              target,
-				GtkSelectionFunction function,
-				GtkRemoveFunction    remove_func,
-				gpointer             data);
+void gtk_selection_add_handler( GtkWidget            *widget, 
+                                GdkAtom               selection,
+                                GdkAtom               target,
+                                GtkSelectionFunction  function,
+                                GtkRemoveFunction     remove_func,
+                                gpointer              data );
 </verb></tscreen>
 
 <tt/widget/, <tt/selection/, and <tt/target/ identify the requests
-this handler will manage.  <tt/remove_func/ if not
+this handler will manage.  <tt/remove_func/, if not
 NULL, will be called when the signal handler is removed. This is
 useful, for instance, for interpreted languages which need to
 keep track of a reference count for <tt/data/.
 
-<p>
 The callback function has the signature:
 
 <tscreen><verb>
-typedef void (*GtkSelectionFunction) (GtkWidget *widget, 
+typedef void (*GtkSelectionFunction)( GtkWidget        *widget, 
                                       GtkSelectionData *selection_data,
-				      gpointer data);
+                                      gpointer          data );
 
 </verb></tscreen>
 
@@ -6590,25 +6816,24 @@ character - or 32 - <em/i.e./ a. integer.) This is done by calling the
 function:
 
 <tscreen><verb>
-void gtk_selection_data_set (GtkSelectionData *selection_data,
-			     GdkAtom           type,
-			     gint              format,
-			     guchar           *data,
-			     gint              length);
+void gtk_selection_data_set( GtkSelectionData *selection_data,
+                             GdkAtom           type,
+                             gint              format,
+                             guchar           *data,
+                             gint              length );
 </verb></tscreen>
 
 This function takes care of properly making a copy of the data so that
 you don't have to worry about keeping it around. (You should not fill
 in the fields of the GtkSelectionData structure by hand.)
 
-<p>
 When prompted by the user, you claim ownership of the selection by
 calling:
 
 <tscreen><verb>
-gint gtk_selection_owner_set (GtkWidget 	  *widget,
-			      GdkAtom    	   selection,
-			      guint32    	   time);
+gint gtk_selection_owner_set( GtkWidget *widget,
+                              GdkAtom    selection,
+                              guint32    time );
 </verb></tscreen>
 
 If another application claims ownership of the selection, you will
@@ -6622,7 +6847,7 @@ itself), is the "STRING" target. When this target is requested, a
 string representation of the time is returned.
 
 <tscreen><verb>
-/* setselection.c */
+/* example-start selection/setselection.c */
 
 #include <gtk/gtk.h>
 #include <time.h>
@@ -6726,20 +6951,19 @@ main (int argc, char *argv[])
   
   return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 
 <!-- ***************************************************************** -->
 <sect>glib<label id="sec_glib">
 <!-- ***************************************************************** -->
-
 <p>
-glib provides many useful functions and definitions available for use 
-when creating GDK
-and GTK applications.  I will list them all here with a brief explanation.
-Many are duplicates of standard libc functions so I won't go into
-detail on those.  This is mostly to be used as a reference, so you know what is
-available for use.
+glib provides many useful functions and definitions available for use
+when creating GDK and GTK applications. I will list them all here with
+a brief explanation. Many are duplicates of standard libc functions so
+I won't go into detail on those. This is mostly to be used as a reference,
+so you know what is available for use.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Definitions
@@ -6759,9 +6983,9 @@ G_MINLONG
 G_MAXLONG
 </verb></tscreen>
 
-Also, the following typedefs.  The ones left unspecified are dynamically set
-depending on the architecture.  Remember to avoid counting on the size of a
-pointer if you want to be portable!  Eg, a pointer on an Alpha is 8 bytes, but 4
+Also, the following typedefs. The ones left unspecified are dynamically set
+depending on the architecture. Remember to avoid counting on the size of a
+pointer if you want to be portable! Eg, a pointer on an Alpha is 8 bytes, but 4
 on Intel.
 
 <tscreen><verb>
@@ -6799,90 +7023,90 @@ of this document to explain them.  Of course, it's not required that you
 know these for general use of GTK, but they are nice to know.
 
 <tscreen><verb>
-GList* g_list_alloc       (void);
+GList *g_list_alloc( void );
 
-void   g_list_free        (GList     *list);
+void g_list_free( GList *list );
 
-void   g_list_free_1      (GList     *list);
+void g_list_free_1( GList *list );
 
-GList* g_list_append      (GList     *list,
-                           gpointer   data);
+GList *g_list_append( GList     *list,
+                      gpointer   data );
 			   
-GList* g_list_prepend     (GList     *list,
-                           gpointer   data);
+GList *g_list_prepend( GList    *list,
+                       gpointer  data );
 			
-GList* g_list_insert      (GList     *list,
-                           gpointer   data,
-			   gint       position);
+GList *g_list_insert( GList    *list,
+                      gpointer  data,
+			    gint      position );
 
-GList* g_list_remove      (GList     *list,
-                           gpointer   data);
+GList *g_list_remove( GList    *list,
+                      gpointer  data );
 			   
-GList* g_list_remove_link (GList     *list,
-                           GList     *link);
+GList *g_list_remove_link( GList *list,
+                           GList *link );
 
-GList* g_list_reverse     (GList     *list);
+GList *g_list_reverse( GList *list );
 
-GList* g_list_nth         (GList     *list,
-                           gint       n);
+GList *g_list_nth( GList *list,
+                   gint   n );
 			   
-GList* g_list_find        (GList     *list,
-                           gpointer   data);
+GList *g_list_find( GList    *list,
+                    gpointer  data );
 
-GList* g_list_last        (GList     *list);
+GList *g_list_last( GList *list );
 
-GList* g_list_first       (GList     *list);
+GList *g_list_first( GList *list );
 
-gint   g_list_length      (GList     *list);
+gint g_list_length( GList *list );
 
-void   g_list_foreach     (GList     *list,
-                           GFunc      func,
-			   gpointer   user_data);
+void g_list_foreach( GList    *list,
+                     GFunc     func,
+                     gpointer  user_data );
 </verb></tscreen>					      
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Singly Linked Lists
 <p>
 Many of the above functions for singly linked lists are identical to the
-above.  Here is a complete list:
+above. Here is a complete list:
 <tscreen><verb>
-GSList* g_slist_alloc       (void);
+GSList *g_slist_alloc( void );
 
-void    g_slist_free        (GSList   *list);
+void g_slist_free( GSList *list );
 
-void    g_slist_free_1      (GSList   *list);
+void g_slist_free_1( GSList *list );
 
-GSList* g_slist_append      (GSList   *list,
-                             gpointer  data);
+GSList *g_slist_append( GSList   *list,
+                        gpointer  data );
 		
-GSList* g_slist_prepend     (GSList   *list,
-                             gpointer  data);
+GSList *g_slist_prepend( GSList   *list,
+                         gpointer  data );
 			     
-GSList* g_slist_insert      (GSList   *list,
-                             gpointer  data,
-		             gint      position);
+GSList *g_slist_insert( GSList   *list,
+                        gpointer  data,
+		            gint      position );
 			     
-GSList* g_slist_remove      (GSList   *list,
-                             gpointer  data);
+GSList *g_slist_remove( GSList   *list,
+                        gpointer  data );
 			     
-GSList* g_slist_remove_link (GSList   *list,
-                             GSList   *link);
+GSList *g_slist_remove_link( GSList *list,
+                             GSList *link );
 			     
-GSList* g_slist_reverse     (GSList   *list);
+GSList *g_slist_reverse( GSList *list );
 
-GSList* g_slist_nth         (GSList   *list,
-                             gint      n);
+GSList *g_slist_nth( GSList *list,
+                     gint    n );
 			     
-GSList* g_slist_find        (GSList   *list,
-                             gpointer  data);
+GSList *g_slist_find( GSList   *list,
+                      gpointer  data );
 			     
-GSList* g_slist_last        (GSList   *list);
+GSList *g_slist_last( GSList *list );
 
-gint    g_slist_length      (GSList   *list);
+gint g_slist_length( GSList *list );
 
-void    g_slist_foreach     (GSList   *list,
-                             GFunc     func,
-			     gpointer  user_data);
+void g_slist_foreach( GSList   *list,
+                      GFunc     func,
+			    gpointer  user_data );
 	
 </verb></tscreen>
 
@@ -6890,41 +7114,41 @@ void    g_slist_foreach     (GSList   *list,
 <sect1>Memory Management
 <p>
 <tscreen><verb>
-gpointer g_malloc      (gulong    size);
+gpointer g_malloc( gulong size );
 </verb></tscreen>
 
-This is a replacement for malloc().  You do not need to check the return
+This is a replacement for malloc(). You do not need to check the return
 vaule as it is done for you in this function.
 
 <tscreen><verb>
-gpointer g_malloc0     (gulong    size);
+gpointer g_malloc0( gulong size );
 </verb></tscreen>
 
 Same as above, but zeroes the memory before returning a pointer to it.
 
 <tscreen><verb>
-gpointer g_realloc     (gpointer  mem,
-                        gulong    size);
+gpointer g_realloc( gpointer mem,
+                    gulong   size );
 </verb></tscreen>
 
-Relocates "size" bytes of memory starting at "mem".  Obviously, the memory should have been
-previously allocated.
+Relocates "size" bytes of memory starting at "mem".  Obviously, the
+memory should have been previously allocated.
 
 <tscreen><verb>
-void     g_free        (gpointer  mem);
+void g_free( gpointer mem );
 </verb></tscreen>
 
-Frees memory.  Easy one.
+Frees memory. Easy one.
 
 <tscreen><verb>
-void     g_mem_profile (void);
+void g_mem_profile( void );
 </verb></tscreen>
 
 Dumps a profile of used memory, but requries that you add #define
 MEM_PROFILE to the top of glib/gmem.c and re-make and make install.
 
 <tscreen><verb>
-void     g_mem_check   (gpointer  mem);
+void g_mem_check( gpointer mem );
 </verb></tscreen>
 
 Checks that a memory location is valid.  Requires you add #define
@@ -6936,71 +7160,72 @@ MEM_CHECK to the top of gmem.c and re-make and make install.
 Timer functions..
 
 <tscreen><verb>
-GTimer* g_timer_new     (void);
+GTimer *g_timer_new( void );
 
-void    g_timer_destroy (GTimer  *timer);
+void g_timer_destroy( GTimer *timer );
 
-void    g_timer_start   (GTimer  *timer);
+void g_timer_start( GTimer  *timer );
 
-void    g_timer_stop    (GTimer  *timer);
+void g_timer_stop( GTimer  *timer );
 
-void    g_timer_reset   (GTimer  *timer);
+void g_timer_reset( GTimer  *timer );
 
-gdouble g_timer_elapsed (GTimer  *timer,
-                         gulong  *microseconds);
+gdouble g_timer_elapsed( GTimer *timer,
+                         gulong *microseconds );
 </verb></tscreen>			 
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>String Handling
 <p>
-A whole mess of string handling functions.  They all look very interesting, and
+A whole mess of string handling functions. They all look very interesting, and
 probably better for many purposes than the standard C string functions, but
 require documentation.
 
 <tscreen><verb>
-GString* g_string_new       (gchar   *init);
-void     g_string_free      (GString *string,
-                             gint     free_segment);
+GString *g_string_new( gchar *init );
+
+void g_string_free( GString *string,
+                    gint     free_segment );
 			     
-GString* g_string_assign    (GString *lval,
-                             gchar   *rval);
+GString *g_string_assign( GString *lval,
+                          gchar   *rval );
 			     
-GString* g_string_truncate  (GString *string,
-                             gint     len);
+GString *g_string_truncate( GString *string,
+                            gint     len );
 			     
-GString* g_string_append    (GString *string,
-                             gchar   *val);
+GString *g_string_append( GString *string,
+                          gchar   *val );
 			    
-GString* g_string_append_c  (GString *string,
-                             gchar    c);
+GString *g_string_append_c( GString *string,
+                            gchar    c );
 	
-GString* g_string_prepend   (GString *string,
-                             gchar   *val);
+GString *g_string_prepend( GString *string,
+                           gchar   *val );
 			     
-GString* g_string_prepend_c (GString *string,
-                             gchar    c);
+GString *g_string_prepend_c( GString *string,
+                             gchar    c );
 	
-void     g_string_sprintf   (GString *string,
-                             gchar   *fmt,
-			     ...);
+void g_string_sprintf( GString *string,
+                       gchar   *fmt,
+                       ...);
 	
-void     g_string_sprintfa  (GString *string,
-                             gchar   *fmt,
-			     ...);
+void g_string_sprintfa ( GString *string,
+                         gchar   *fmt,
+                         ... );
 </verb></tscreen>							  
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Utility and Error Functions
 <p>
 <tscreen><verb>
-gchar* g_strdup    (const gchar *str);
+gchar *g_strdup( const gchar *str );
 </verb></tscreen>
 
-Replacement strdup function.  Copies the
-original strings contents to newly allocated memory, and returns a pointer to it.
+Replacement strdup function.  Copies the original strings contents to
+newly allocated memory, and returns a pointer to it.
 
 <tscreen><verb>
-gchar* g_strerror  (gint errnum);
+gchar *g_strerror( gint errnum );
 </verb></tscreen>
 
 I recommend using this for all error messages.  It's much nicer, and more
@@ -7017,28 +7242,28 @@ g_print("hello_world:open:%s:%s\n", filename, g_strerror(errno));
 </verb></tscreen>
 
 <tscreen><verb>
-void g_error   (gchar *format, ...);
+void g_error( gchar *format, ... );
 </verb></tscreen>
 
-Prints an error message.  The format is just like printf, but it
+Prints an error message. The format is just like printf, but it
 prepends "** ERROR **: " to your message, and exits the program.  
 Use only for fatal errors.
 
 <tscreen><verb>
-void g_warning (gchar *format, ...);
+void g_warning( gchar *format, ... );
 </verb></tscreen>
 
 Same as above, but prepends "** WARNING **: ", and does not exit the
 program.
 
 <tscreen><verb>
-void g_message (gchar *format, ...);
+void g_message( gchar *format, ... );
 </verb></tscreen>
 
 Prints "message: " prepended to the string you pass in.
 
 <tscreen><verb>
-void g_print   (gchar *format, ...);
+void g_print( gchar *format, ... );
 </verb></tscreen>
 
 Replacement for printf().
@@ -7046,7 +7271,7 @@ Replacement for printf().
 And our last function:
 
 <tscreen><verb>
-gchar* g_strsignal (gint signum);
+gchar *g_strsignal( gint signum );
 </verb></tscreen>
 
 Prints out the name of the Unix system signal given the signal number.
@@ -7058,44 +7283,45 @@ to document any function, just send me an email!
 <!-- ***************************************************************** -->
 <sect>GTK's rc Files
 <!-- ***************************************************************** -->
-
 <p>
 GTK has it's own way of dealing with application defaults, by using rc
-files.  These can be used to set the colors of just about any widget, and
+files. These can be used to set the colors of just about any widget, and
 can also be used to tile pixmaps onto the background of some widgets.  
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Functions For rc Files 
 <p>
 When your application starts, you should include a call to:
+
 <tscreen><verb>
-void gtk_rc_parse (char *filename);
+void gtk_rc_parse( char *filename );
 </verb></tscreen>
-<p>
+
 Passing in the filename of your rc file.  This will cause GTK to parse this
 file, and use the style settings for the widget types defined there.
-<p>
+
 If you wish to have a special set of widgets that can take on a different
 style from others, or any other logical division of widgets, use a call to:
+
 <tscreen><verb>
-void gtk_widget_set_name (GtkWidget *widget,
-                          gchar *name);
+void gtk_widget_set_name( GtkWidget *widget,
+                          gchar     *name );
 </verb></tscreen>
-<p>
+
 Passing your newly created widget as the first argument, and the name
-you wish to give it as the second.  This will allow you to change the
+you wish to give it as the second. This will allow you to change the
 attributes of this widget by name through the rc file.
-<p>
+
 If we use a call something like this:
 
 <tscreen><verb>
 button = gtk_button_new_with_label ("Special Button");
 gtk_widget_set_name (button, "special button");
 </verb></tscreen>
-<p>
+
 Then this button is given the name "special button" and may be addressed by
 name in the rc file as "special button.GtkButton".  [<--- Verify ME!]
-<p>
+
 The example rc file below, sets the properties of the main window, and lets
 all children of that main window inherit the style described by the "main
 button" style.  The code used in the application is:
@@ -7104,37 +7330,39 @@ button" style.  The code used in the application is:
 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
 gtk_widget_set_name (window, "main window");
 </verb></tscreen>
-<p>
+
 And then the style is defined in the rc file using:
 
 <tscreen><verb>
 widget "main window.*GtkButton*" style "main_button"
 </verb></tscreen>
-<p>
+
 Which sets all the GtkButton widgets in the "main window" to the
 "main_buttons" style as defined in the rc file.
-<p>
+
 As you can see, this is a fairly powerful and flexible system.  Use your
 imagination as to how best to take advantage of this.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>GTK's rc File Format
 <p>
-The format of the GTK file is illustrated in the example below.  This is
+The format of the GTK file is illustrated in the example below. This is
 the testgtkrc file from the GTK distribution, but I've added a
-few comments and things.  You may wish to include this explanation
+few comments and things. You may wish to include this explanation
 your application to allow the user to fine tune his application.
-<p>
+
 There are several directives to change the attributes of a widget.
+
 <itemize>
 <item>fg - Sets the foreground color of a widget.
 <item>bg - Sets the background color of a widget.
 <item>bg_pixmap - Sets the background of a widget to a tiled pixmap.
 <item>font - Sets the font to be used with the given widget.
 </itemize>
-<p>
+
 In addition to this, there are several states a widget can be in, and you
-can set different colors, pixmaps and fonts for each state.  These states are:
+can set different colors, pixmaps and fonts for each state. These states are:
+
 <itemize>
 <item>NORMAL - The normal state of a widget, without the mouse over top of
 it, and not being pressed etc.
@@ -7146,52 +7374,51 @@ the attributes assigned by this tag will be in effect.
 activated, it will take these attributes.
 <item>SELECTED - When an object is selected, it takes these attributes.
 </itemize>
-<p>
+
 When using the "fg" and "bg" keywords to set the colors of widgets, the
 format is:
+
 <tscreen><verb>
 fg[<STATE>] = { Red, Green, Blue }
 </verb></tscreen>
-<p>
+
 Where STATE is one of the above states (PRELIGHT, ACTIVE etc), and the Red,
 Green and Blue are values in the range of 0 - 1.0,  { 1.0, 1.0, 1.0 } being
-white.
-They must be in float form, or they will register as 0, so a straight 
-"1" will not work, it must
-be "1.0".  A straight "0" is fine because it doesn't matter if it's not
-recognized.  Unrecognized values are set to 0.
-<p>
+white. They must be in float form, or they will register as 0, so a straight 
+"1" will not work, it must be "1.0".  A straight "0" is fine because it 
+doesn't matter if it's not recognized.  Unrecognized values are set to 0.
+
 bg_pixmap is very similar to the above, except the colors are replaced by a
 filename.
 
 pixmap_path is a list of paths seperated by ":"'s.  These paths will be
 searched for any pixmap you specify.
 
-<p>
 The font directive is simply:
 <tscreen><verb>
 font = "<font name>"
 </verb></tscreen>
-<p>
-Where the only hard part is figuring out the font string.  Using xfontsel or
+
+Where the only hard part is figuring out the font string. Using xfontsel or
 similar utility should help.
-<p>
-The "widget_class" sets the style of a class of widgets.  These classes are
+
+The "widget_class" sets the style of a class of widgets. These classes are
 listed in the widget overview on the class hierarchy.
-<p>
+
 The "widget" directive sets a specificaly named set of widgets to a
 given style, overriding any style set for the given widget class.
 These widgets are registered inside the application using the
-gtk_widget_set_name() call.  This allows you to specify the attributes of a
+gtk_widget_set_name() call. This allows you to specify the attributes of a
 widget on a per widget basis, rather than setting the attributes of an
-entire widget class.  I urge you to document any of these special widgets so
+entire widget class. I urge you to document any of these special widgets so
 users may customize them.
-<p>
-When the keyword "<tt>parent</>" is used as an attribute, the widget will take on
+
+When the keyword <tt>parent</> is used as an attribute, the widget will take on
 the attributes of it's parent in the application.
-<p>
+
 When defining a style, you may assign the attributes of a previously defined
 style to this new one.
+
 <tscreen><verb>
 style "main_button" = "button"
 {
@@ -7199,13 +7426,13 @@ style "main_button" = "button"
   bg[PRELIGHT] = { 0.75, 0, 0 }
 }
 </verb></tscreen>
-<p>
+
 This example takes the "button" style, and creates a new "main_button" style
 simply by changing the font and prelight background color of the "button"
 style.
-<p>
-Of course, many of these attributes don't apply to all widgets.  It's a
-simple matter of common sense really.  Anything that could apply, should.
+
+Of course, many of these attributes don't apply to all widgets. It's a
+simple matter of common sense really. Anything that could apply, should.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Example rc file
@@ -7349,9 +7576,9 @@ widget "main window.*GtkButton*" style "main_button"
 Although the GTK distribution comes with many types of widgets that
 should cover most basic needs, there may come a time when you need to
 create your own new widget type. Since GTK uses widget inheretence
-extensively, and there is already a widget that
-is close to what you want, it is often possible to make a useful new widget type in
-just a few lines of code.  But before starting work on a new widget, check
+extensively, and there is already a widget that is close to what you want,
+it is often possible to make a useful new widget type in
+just a few lines of code. But before starting work on a new widget, check
 around first to make sure that someone has not already written
 it. This will prevent duplication of effort and keep the number of
 GTK widgets out there to a minimum, which will help keep both the code
@@ -7369,13 +7596,11 @@ name="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial">
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> The Anatomy Of A Widget
-
 <p>
 In order to create a new widget, it is important to have an
 understanding of how GTK objects work. This section is just meant as a
 brief overview. See the reference documentation for the details. 
 
-<p>
 GTK widgets are implemented in an object oriented fashion. However,
 they are implemented in standard C. This greatly improves portability
 and stability over using current generation C++ compilers; however,
@@ -7402,12 +7627,10 @@ struct _GtkButtonClass
 };
 </verb></tscreen>
 
-<p>
 When a button is treated as a container (for instance, when it is
 resized), its class structure can be cast to GtkContainerClass, and
 the relevant fields used to handle the signals.
 
-<p>
 There is also a structure for each widget that is created on a
 per-instance basis. This structure has fields to store information that
 is different for each instance of the widget. We'll call this
@@ -7426,7 +7649,6 @@ struct _GtkButton
 };
 </verb></tscreen>
 
-<p>
 Note that, similar to the class structure, the first field is the
 object structure of the parent class, so that this structure can be
 cast to the parent class's object structure as needed.
@@ -7436,7 +7658,6 @@ cast to the parent class's object structure as needed.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> Introduction
-
 <p>
 One type of widget that you may be interested in creating is a
 widget that is merely an aggregate of other GTK widgets. This type of
@@ -7445,7 +7666,6 @@ widgets, but provides a convenient way of packaging user interface
 elements for reuse. The FileSelection and ColorSelection widgets in
 the standard distribution are examples of this type of widget.
 
-<p>
 The example widget that we'll create in this section is the Tictactoe
 widget, a 3x3 array of toggle buttons which triggers a signal when all
 three buttons in a row, column, or on one of the diagonals are
@@ -7453,7 +7673,6 @@ depressed.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> Choosing a parent class
-
 <p>
 The parent class for a composite widget is typically the container
 class that holds all of the elements of the composite widget. For
@@ -7475,7 +7694,6 @@ from GtkVBox instead, and stick our table inside the VBox.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> The header file
-
 <p>
 Each widget class has a header file which declares the object and
 class structures for that widget, along with public functions. 
@@ -7511,7 +7729,6 @@ macros in our header file, <tt/TICTACTOE(obj)/,
 pointer into a pointer to the object or class structure, and check
 if an object is a Tictactoe widget respectively.
 
-<p>
 Here is the complete header file:
 
 <tscreen><verb>
@@ -7563,7 +7780,6 @@ void	       tictactoe_clear           (Tictactoe *ttt);
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> The <tt/_get_type()/ function.
-
 <p>
 We now continue on to the implementation of our widget. A core
 function for every widget is the function
@@ -7597,7 +7813,6 @@ tictactoe_get_type ()
 }
 </verb></tscreen>
 
-<p>
 The GtkTypeInfo structure has the following definition:
 
 <tscreen><verb>
@@ -7613,7 +7828,6 @@ struct _GtkTypeInfo
 };
 </verb></tscreen>
 
-<p>
 The fields of this structure are pretty self-explanatory. We'll ignore
 the <tt/arg_set_func/ and <tt/arg_get_func/ fields here: they have an important, 
 but as yet largely
@@ -7624,7 +7838,6 @@ type.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> The <tt/_class_init()/ function
-
 <p>
 The <tt/WIDGETNAME_class_init()/ function initializes the fields of
 the widget's class structure, and sets up any signals for the
@@ -7659,8 +7872,7 @@ tictactoe_class_init (TictactoeClass *class)
 }
 </verb></tscreen>
 
-<p>
-Our widget has just one signal, the ``tictactoe'' signal that is
+Our widget has just one signal, the <tt/tictactoe/ signal that is
 invoked when a row, column, or diagonal is completely filled in. Not
 every composite widget needs signals, so if you are reading this for
 the first time, you may want to skip to the next section now, as
@@ -7669,14 +7881,14 @@ things are going to get a bit complicated.
 The function:
 
 <tscreen><verb>
-gint   gtk_signal_new (const gchar         *name,
-                       GtkSignalRunType    run_type,
-		       GtkType             object_type,
-		       gint                function_offset,
-		       GtkSignalMarshaller marshaller,
-		       GtkType             return_val,
-		       guint               nparams,
-		       ...);
+gint gtk_signal_new( const gchar         *name,
+                     GtkSignalRunType     run_type,
+                     GtkType              object_type,
+                     gint                 function_offset,
+                     GtkSignalMarshaller  marshaller,
+                     GtkType              return_val,
+                     guint                nparams,
+                     ...);
 </verb></tscreen>
 
 Creates a new signal. The parameters are:
@@ -7734,7 +7946,6 @@ typedef enum
 } GtkFundamentalType;
 </verb></tscreen>
 
-<p>
 <tt/gtk_signal_new()/ returns a unique integer identifier for the
 signal, that we store in the <tt/tictactoe_signals/ array, which we
 index using an enumeration. (Conventionally, the enumeration elements
@@ -7750,9 +7961,7 @@ indicating that there is no default action.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> The <tt/_init()/ function.
-
 <p>
-
 Each widget class also needs a function to initialize the object
 structure. Usually, this function has the fairly limited role of
 setting the fields of the structure to default values. For composite
@@ -7785,9 +7994,7 @@ tictactoe_init (Tictactoe *ttt)
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> And the rest...
-
 <p>
-
 There is one more function that every widget (except for base widget
 types like GtkBin that cannot be instantiated) needs to have - the
 function that the user calls to create an object of that type. This is
@@ -7796,13 +8003,11 @@ widgets, though not for the Tictactoe widgets, this function takes
 arguments, and does some setup based on the arguments. The other two
 functions are specific to the Tictactoe widget. 
 
-<p>
 <tt/tictactoe_clear()/ is a public function that resets all the
 buttons in the widget to the up position. Note the use of
 <tt/gtk_signal_handler_block_by_data()/ to keep our signal handler for
 button toggles from being triggered unnecessarily.
 
-<p>
 <tt/tictactoe_toggle()/ is the signal handler that is invoked when the
 user clicks on a button. It checks to see if there are any winning
 combinations that involve the toggled button, and if so, emits
@@ -7867,8 +8072,6 @@ tictactoe_toggle (GtkWidget *widget, Tictactoe *ttt)
 }
 </verb></tscreen>
 
-<p>
-
 And finally, an example program using our Tictactoe widget:
 
 <tscreen><verb>
@@ -7923,9 +8126,7 @@ main (int argc, char *argv[])
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> Introduction
-
 <p>
-
 In this section, we'll learn more about how widgets display themselves
 on the screen and interact with events. As an example of this, we'll
 create an analog dial widget with a pointer that the user can drag to
@@ -7933,7 +8134,6 @@ set the value.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> Displaying a widget on the screen
-
 <p>
 There are several steps that are involved in displaying on the screen.
 After the widget is created with a call to <tt/WIDGETNAME_new()/,
@@ -7959,7 +8159,6 @@ have their own windows. (If they have their own windows, then X will
 generate the necessary expose events)
 </itemize>
 
-<p>
 You might notice that the last two functions are quite similar - each
 is responsible for drawing the widget on the screen. In fact many
 types of widgets don't really care about the difference between the
@@ -7970,7 +8169,6 @@ functions. For instance, if a widget has multiple X windows, then
 since expose events identify the exposed window, it can redraw only
 the affected window, which is not possible for calls to <tt/draw()/.
 
-<p>
 Container widgets, even if they don't care about the difference for
 themselves, can't simply use the default <tt/draw()/ function because
 their child widgets might care about the difference. However,
@@ -7980,7 +8178,6 @@ functions. The convention is that such widgets have a function called
 widget, that is then called by the <tt/draw()/ and <tt/expose()/
 functions.
 
-<p>
 In our example approach, since the dial widget is not a container
 widget, and only has a single window, we can take the simplest
 approach and use the default <tt/draw()/ function and only implement
@@ -7988,7 +8185,6 @@ an <tt/expose()/ function.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> The origins of the Dial Widget
-
 <p>
 Just as all land animals are just variants on the first amphibian that
 crawled up out of the mud, Gtk widgets tend to start off as variants
@@ -8005,7 +8201,6 @@ would be a good idea to look them over before continuing.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> The Basics
-
 <p>
 Quite a bit of our widget should look pretty familiar from the
 Tictactoe widget. First, we have a header file:
diff --git a/docs/tutorial/gtk_tut.sgml b/docs/tutorial/gtk_tut.sgml
index 82c381d48..a896d66f4 100644
--- a/docs/tutorial/gtk_tut.sgml
+++ b/docs/tutorial/gtk_tut.sgml
@@ -10,7 +10,7 @@
 			      name="&lt;imain@gtk.org&gt;"></tt>,
 Tony Gale <tt><htmlurl url="mailto:gale@gtk.org"
 			      name="&lt;gale@gtk.org&gt;"></tt>
-<date>May 24th, 1998
+<date>May 29th, 1998
 
 <!-- ***************************************************************** -->
 <sect>Introduction
@@ -18,8 +18,8 @@ Tony Gale <tt><htmlurl url="mailto:gale@gtk.org"
 <p>
 GTK (GIMP Toolkit) was originally developed as a toolkit for the GIMP
 (General Image Manipulation Program).  GTK is built on top of GDK (GIMP
-Drawing Kit)  which is basically wrapper around the Xlib functions.  It's
-called the GIMP toolkit because it was original written for developing
+Drawing Kit) which is basically a wrapper around the Xlib functions.  It's
+called the GIMP toolkit because it was originally written for developing
 the GIMP, but has now been used in several free software projects.  The
 authors are
 <itemize>
@@ -31,12 +31,11 @@ authors are
 			   name="jmacd@xcf.berkeley.edu"></tt>
 </itemize>
 
-<p>
 GTK is essentially an object oriented application programmers interface (API).  
 Although written completely in
 C, it is implemented using the idea of classes and callback functions
 (pointers to functions).
-<p>
+
 There is also a third component called glib which contains a few
 replacements for some standard calls, as well as some additional functions
 for handling linked lists etc.  The replacement functions are used to 
@@ -44,7 +43,7 @@ increase GTK's portability, as some of the functions implemented
 here are not available or are nonstandard on other unicies such as 
 g_strerror().   Some also contain enhancements to the libc versions, such as
 g_malloc that has enhanced debugging utilities.
-<p>
+
 This tutorial is an attempt to document as much as possible of GTK, it is by 
 no means complete.  This
 tutorial assumes a good understanding of C, and how to create C programs.
@@ -54,9 +53,9 @@ first widget set, please comment on how you found this tutorial, and what
 you had trouble with.
 Note that there is also a C++ API for GTK (GTK--) in the works, so if you
 prefer to use C++, you should look into this instead.  There's also an
-Objective C wrapper, and guile bindings available, but I don't follow these.
-<p>
-I would very much like to hear any problems you have learning GTK from this
+Objective C wrapper, and Guile bindings available, but I don't follow these.
+
+I would very much like to hear of any problems you have learning GTK from this
 document, and would appreciate input as to how it may be improved.
 
 <!-- ***************************************************************** -->
@@ -70,7 +69,7 @@ You can also view other sources of GTK information on http://www.gtk.org/
 <htmlurl url="http://www.gtk.org/" name="http://www.gtk.org/">.
 GTK uses GNU autoconf for
 configuration.  Once untar'd, type ./configure --help to see a list of options.
-<p>
+
 To begin our introduction to GTK, we'll start with the simplest program 
 possible.  This program will
 create a 200x200 pixel window and has no way of exiting except to be
@@ -94,10 +93,10 @@ int main (int argc, char *argv[])
 }
 </verb></tscreen>
 
-All programs will of course include the gtk/gtk.h which declares the
+All programs will of course include gtk/gtk.h which declares the
 variables, functions, structures etc. that will be used in your GTK 
 application.
-<p>
+
 The next line:
 
 <tscreen><verb>
@@ -119,12 +118,14 @@ of the following:
 <item> <tt/--sync/
 <item> <tt/--show-events/
 <item> <tt/--no-show-events/
+<item> <tt/--name/
+<item> <tt/--class/
 </itemize>
-<p>
+
 It removes these from the argument list, leaving anything it does
-not recognize for your application to parse or ignore.	This creates a set
+not recognize for your application to parse or ignore. This creates a set
 of standard arguments accepted by all GTK applications.
-<p>
+
 The next two lines of code create and display a window.
 
 <tscreen><verb>
@@ -136,10 +137,10 @@ The GTK_WINDOW_TOPLEVEL argument specifies that we want the window to
 undergo window manager decoration and placement. Rather than create a
 window of 0x0 size, a window without children is set to 200x200 by default
 so you can still manipulate it.
-<p>
-The gtk_widget_show() function, lets GTK know that we are done setting the
-attributes of this widget, and it can display it.
-<p>
+
+The gtk_widget_show() function lets GTK know that we are done setting the
+attributes of this widget, and that it can display it.
+
 The last line enters the GTK main processing loop.
 
 <tscreen><verb>
@@ -158,7 +159,7 @@ OK, now for a program with a widget (a button).  It's the classic hello
 world ala GTK.
 
 <tscreen><verb>
-/* helloworld.c */
+/* example-start helloworld/helloworld.c */
 
 #include <gtk/gtk.h>
 
@@ -169,7 +170,7 @@ void hello (GtkWidget *widget, gpointer data)
     g_print ("Hello World\n");
 }
 
-gint delete_event(GtkWidget *widget, gpointer data)
+gint delete_event(GtkWidget *widget, GdkEvent *event, gpointer data)
 {
     g_print ("delete event occured\n");
     /* if you return FALSE in the "delete_event" signal handler,
@@ -204,10 +205,10 @@ int main (int argc, char *argv[])
     window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
     
     /* when the window is given the "delete_event" signal (this is given
-    * by the window manager (usually the 'close' option, or on the
+    * by the window manager, usually by the 'close' option, or on the
     * titlebar), we ask it to call the delete_event () function
     * as defined above.  The data passed to the callback
-    * function is NULL and is ignored in the callback. */
+    * function is NULL and is ignored in the callback function. */
     gtk_signal_connect (GTK_OBJECT (window), "delete_event",
 			GTK_SIGNAL_FUNC (delete_event), NULL);
     
@@ -251,6 +252,7 @@ int main (int argc, char *argv[])
     
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
@@ -262,7 +264,6 @@ To compile use:
 gcc -Wall -g helloworld.c -o hello_world `gtk-config --cflags` \
     `gtk-config --libs`
 </verb></tscreen>
-<p>
 
 This uses the program <tt>gtk-config</>, which comes with gtk. This
 program 'knows' what compiler switches are needed to compile programs
@@ -271,7 +272,6 @@ directories for the compiler to look in, and <tt>gtk-config --libs</>
 will output the list of libraries for the compiler to link with and
 the directories to find them in.
 
-<p>
 The libraries that are usually linked in are:
 <itemize>
 <item>The GTK library (-lgtk), the widget library, based on top of GDK.
@@ -289,65 +289,72 @@ pixmaps and other X extensions.
 <!-- ----------------------------------------------------------------- -->
 <sect1>Theory of Signals and Callbacks
 <p>
-Before we look in detail at hello world, we'll discuss events and callbacks.
+Before we look in detail at hello world, we'll discuss signals and callbacks.
 GTK is an event driven toolkit, which means it will sleep in
 gtk_main until an event occurs and control is passed to the appropriate
 function.
-<p>
+
 This passing of control is done using the idea of "signals".  When an 
 event occurs, such as the press of a mouse button, the
 appropriate signal will be "emitted" by the widget that was pressed.  
-This is how GTK does
-most of its useful work.  To make a button perform an action, 
-we set up a signal handler to catch these
+This is how GTK does most of its useful work. There are a set of signals
+that all widgets inherit, such as "destroy", and there are signals that are
+widget specific, such as "toggled" on a toggle button.
+
+To make a button perform an action, we set up a signal handler to catch these
 signals and call the appropriate function.  This is done by using a 
 function such as:
 
 <tscreen><verb>
-gint gtk_signal_connect (GtkObject *object,
-                         gchar *name,
-			 GtkSignalFunc func,
-			 gpointer func_data);
+gint gtk_signal_connect( GtkObject     *object,
+                         gchar         *name,
+                         GtkSignalFunc  func,
+                         gpointer       func_data );
 </verb></tscreen>
-<p>
+
 Where the first argument is the widget which will be emitting the signal, and
 the second, the name of the signal you wish to catch.  The third is the function
 you wish to be called when it is caught, and the fourth, the data you wish
 to have passed to this function.
-<p>
+
 The function specified in the third argument is called a "callback
-function", and should be of the form:
+function", and should generally be of the form:
 
 <tscreen><verb>
-void callback_func(GtkWidget *widget, gpointer callback_data);
+void callback_func( GtkWidget *widget,
+                    gpointer   callback_data );
 </verb></tscreen>
-<p>
-Where the first argument will be a pointer to the widget that emitted the signal, and
-the second, a pointer to the data given as the last argument to the
-gtk_signal_connect() function as shown above.
-<p>
+
+Where the first argument will be a pointer to the widget that emitted the 
+signal, and the second, a pointer to the data given as the last argument
+to the gtk_signal_connect() function as shown above.
+
+Note that the above form for a signal callback function declaration is
+only a general guide, as some widget specific signals generate different
+calling parameters. For example, the GtkCList "select_row" signal provides
+both row and column parameters.
+
 Another call used in the hello world example, is:
 
 <tscreen><verb>
-gint gtk_signal_connect_object (GtkObject *object,
-                                gchar  *name,
-				GtkSignalFunc func,
-				GtkObject *slot_object);
+gint gtk_signal_connect_object( GtkObject     *object,
+                                gchar         *name,
+                                GtkSignalFunc  func,
+                                GtkObject     *slot_object );
 </verb></tscreen>
-<p>
+
 gtk_signal_connect_object() is the same as gtk_signal_connect() except that
-the callback function only uses one argument, a
-pointer to a GTK 
-object.  So when using this function to connect signals, the callback should be of
-the form:
+the callback function only uses one argument, a pointer to a GTK 
+object.  So when using this function to connect signals, the callback
+should be of the form:
 
 <tscreen><verb>
-void callback_func (GtkObject *object);
+void callback_func( GtkObject *object );
 </verb></tscreen>
-<p>
+
 Where the object is usually a widget.  We usually don't setup callbacks for
 gtk_signal_connect_object however.  They are usually used 
-to call a GTK function that accept a single widget or object as an
+to call a GTK function that accepts a single widget or object as an
 argument, as is the case in our hello world example.
 
 The purpose of having two functions to connect signals is simply to allow
@@ -357,11 +364,133 @@ want to use the gtk_signal_connect_object() for these, whereas for your
 functions, you may need to have additional data supplied to the callbacks.
 
 <!-- ----------------------------------------------------------------- -->
+<sect1>Events
+<p>
+In addition to the signal mechanism described above, there are a set of
+<em>events</em> that reflect the X event mechanism. Callbacks may also be
+attached to these events. These events are:
+
+<itemize>
+<item> event
+<item> button_press_event
+<item> button_release_event
+<item> motion_notify_event
+<item> delete_event
+<item> destroy_event
+<item> expose_event
+<item> key_press_event
+<item> key_release_event
+<item> enter_notify_event
+<item> leave_notify_event
+<item> configure_event
+<item> focus_in_event
+<item> focus_out_event
+<item> map_event
+<item> unmap_event
+<item> property_notify_event
+<item> selection_clear_event
+<item> selection_request_event
+<item> selection_notify_event
+<item> proximity_in_event
+<item> proximity_out_event
+<item> drag_begin_event
+<item> drag_request_event
+<item> drag_end_event
+<item> drop_enter_event
+<item> drop_leave_event
+<item> drop_data_available_event
+<item> other_event
+</itemize>
+
+In order to connect a callback function to one of these events, you use
+the function gtk_signal_connect, as described above, using one of the
+above event names as the <tt/name/ parameter. The callback function for
+events has a slighty different form than that for signals:
+
+<tscreen><verb>
+void callback_func( GtkWidget *widget,
+                    GdkEvent  *event,
+                    gpointer   callback_data );
+</verb></tscreen>
+
+GdkEvent is a C <tt/union/ structure whose type will depend upon which of the
+above events has occured. In order for us to tell which event has been issued
+each of the possible alternatives has a <tt/type/ parameter which reflects the
+event being issued. The other components of the event structure will depend
+upon the type of the event. Possible values for the type are:
+
+<tscreen><verb>
+  GDK_NOTHING
+  GDK_DELETE
+  GDK_DESTROY
+  GDK_EXPOSE
+  GDK_MOTION_NOTIFY
+  GDK_BUTTON_PRESS
+  GDK_2BUTTON_PRESS
+  GDK_3BUTTON_PRESS
+  GDK_BUTTON_RELEASE
+  GDK_KEY_PRESS
+  GDK_KEY_RELEASE
+  GDK_ENTER_NOTIFY
+  GDK_LEAVE_NOTIFY
+  GDK_FOCUS_CHANGE
+  GDK_CONFIGURE
+  GDK_MAP
+  GDK_UNMAP
+  GDK_PROPERTY_NOTIFY
+  GDK_SELECTION_CLEAR
+  GDK_SELECTION_REQUEST
+  GDK_SELECTION_NOTIFY
+  GDK_PROXIMITY_IN
+  GDK_PROXIMITY_OUT
+  GDK_DRAG_BEGIN
+  GDK_DRAG_REQUEST
+  GDK_DROP_ENTER
+  GDK_DROP_LEAVE
+  GDK_DROP_DATA_AVAIL
+  GDK_CLIENT_EVENT
+  GDK_VISIBILITY_NOTIFY
+  GDK_NO_EXPOSE
+  GDK_OTHER_EVENT	/* Deprecated, use filters instead */
+</verb></tscreen>
+
+So, to connect a callback function to one of these events we would use
+something like
+
+<tscreen><verb>
+gtk_signal_connect( GTK_OBJECT(button), "button_press_event",
+                    GTK_SIGNAL_FUNC(button_press_callback), 
+		        NULL);
+</verb></tscreen>
+
+This assumes that <tt/button/ is a GtkButton widget. Now, when the mouse is
+over the button and a mouse button is pressed, the function 
+<tt/button_press_callback/ will be called. This function may be declared as:
+
+<tscreen><verb>
+static gint button_press_event (GtkWidget      *widget, 
+                                GdkEventButton *event,
+                                gpointer        data);
+</verb></tscreen>
+
+Note that we can declare the second argument as type <tt/GdkEventButton/
+as we know what type of event will occur for this function to be called.
+
+<!-- Need an Annex with all the event types in it - TRG -->
+
+<!-- Need to check this - TRG
+The value returned from this function indicates whether the event should
+be processed further by the GTK event handling mechanism. Returning
+TRUE indicates that the event has been handled, and that it should not
+propogate further. Returning FALSE continues the normal event handling.
+-->
+
+<!-- ----------------------------------------------------------------- -->
 <sect1>Stepping Through Hello World
 <p>
 Now that we know the theory behind this, lets clarify by walking through 
 the example hello world program.
-<p>
+
 Here is the callback function that will be called when the button is
 "clicked".  We ignore both the widget and the data in this example, but it 
 is not hard to do things with them.  The next example will use the data 
@@ -374,7 +503,6 @@ void hello (GtkWidget *widget, gpointer data)
 }
 </verb></tscreen>
 
-<p>
 This callback is a bit special.  The "delete_event" occurs when the
 window manager sends this event to the application.  We have a choice here
 as to what to do about these events.  We can ignore them, make some sort of
@@ -387,7 +515,7 @@ ask that "destroy" is emitted, which in turn will call our "destroy"
 signal handler.
 
 <tscreen><verb>
-gint delete_event(GtkWidget *widget, gpointer data)
+gint delete_event(GtkWidget *widget, GdkEvent *event, gpointer data)
 {
     g_print ("delete event occured\n");
 
@@ -395,7 +523,6 @@ gint delete_event(GtkWidget *widget, gpointer data)
 }
 </verb></tscreen>
 
-<p>
 Here is another callback function which causes the program to quit by calling
 gtk_main_quit().  This function tells GTK that it is to exit from gtk_main
 when control is returned to it.
@@ -407,73 +534,79 @@ void destroy (GtkWidget *widget, gpointer data)
 }
 </verb></tscreen>
 
-<p>
 I assume you know about the main() function... yes, as with other
 applications, all GTK applications will also have one of these.
+
 <tscreen><verb>
 int main (int argc, char *argv[])
 {
 </verb></tscreen>
-<p>
+
 This next part, declares a pointer to a structure of type GtkWidget.  These
 are used below to create a window and a button.
+
 <tscreen><verb>
     GtkWidget *window;
     GtkWidget *button;
 </verb></tscreen>
-<p>
-Here is our gtk_init again.  As before, this initializes the toolkit, and
+
+Here is our gtk_init again. As before, this initializes the toolkit, and
 parses the arguments found on the command line.  Any argument it
 recognizes from the command line, it removes from the list, and modifies
 argc and argv to make it look like they never existed, allowing your
 application to parse the remaining arguments.
+
 <tscreen><verb>
     gtk_init (&amp;argc, &amp;argv);
 </verb></tscreen>
-<p>
+
 Create a new window.  This is fairly straight forward.  Memory is allocated
 for the GtkWidget *window structure so it now points to a valid structure.
-It sets up a new window, but it is not displayed until below where we call
+It sets up a new window, but it is not displayed until we call
 gtk_widget_show(window) near the end of our program.
+
 <tscreen><verb>
     window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
 </verb></tscreen>
-<p>
-Here is an example of connecting a signal handler to an object, in this case, the
-window.  Here, the "destroy" signal is caught.  This is emitted when we use
-the window manager to kill the window (and we return TRUE in the
-"delete_event" handler), or when we use the
+
+Here is an example of connecting a signal handler to an object, in
+this case, the window.  Here, the "destroy" signal is caught.  This is
+emitted when we use the window manager to kill the window (and we return
+TRUE in the "delete_event" handler), or when we use the
 gtk_widget_destroy() call passing in the window widget as the object to
-destroy.  By setting this up, we handle both cases with a single call.
+destroy. By setting this up, we handle both cases with a single call.
 Here, it just calls the destroy() function defined above with a NULL
 argument, which quits GTK for us.  
-<p>
-The GTK_OBJECT and GTK_SIGNAL_FUNC are macros that perform type casting and
-checking for us, as well as aid the readability of the code.
+
+The GTK_OBJECT and GTK_SIGNAL_FUNC are macros that perform type 
+casting and checking for us, as well as aid the readability of the code.
+
 <tscreen><verb>
     gtk_signal_connect (GTK_OBJECT (window), "destroy",
-			GTK_SIGNAL_FUNC (destroy), NULL);
+                        GTK_SIGNAL_FUNC (destroy), NULL);
 </verb></tscreen>
-<p>
+
 This next function is used to set an attribute of a container object.  
 This just sets the window
 so it has a blank area along the inside of it 10 pixels wide where no
 widgets will go.  There are other similar functions which we will look at 
 in the section on 
 <ref id="sec_setting_widget_attributes" name="Setting Widget Attributes">
-<p>
+
 And again, GTK_CONTAINER is a macro to perform type casting.
+
 <tscreen><verb>
     gtk_container_border_width (GTK_CONTAINER (window), 10);
 </verb></tscreen>
-<p>
+
 This call creates a new button.  It allocates space for a new GtkWidget
 structure in memory, initializes it, and makes the button pointer point to
-it.  It will have the label "Hello World" on it when displayed.
+it. It will have the label "Hello World" on it when displayed.
+
 <tscreen><verb>
     button = gtk_button_new_with_label ("Hello World");
 </verb></tscreen>
-<p>
+
 Here, we take this button, and make it do something useful.  We attach a
 signal handler to it so when it emits the "clicked" signal, our hello()
 function is called.  The data is ignored, so we simply pass in NULL to the
@@ -482,71 +615,78 @@ we click the button with our mouse pointer.
 
 <tscreen><verb>
     gtk_signal_connect (GTK_OBJECT (button), "clicked",
-			GTK_SIGNAL_FUNC (hello), NULL);
+                        GTK_SIGNAL_FUNC (hello), NULL);
 </verb></tscreen>
-<p>
+
 We are also going to use this button to exit our program.  This will
 illustrate how the "destroy"
 signal may come from either the window manager, or our program.  When the
 button is "clicked", same as above, it calls the first hello() callback function,
 and then this one in the order they are set up.  You may have as many
-callback function as you need, and all will be executed in the order you
+callback functions as you need, and all will be executed in the order you
 connected them.  Because the gtk_widget_destroy() function accepts only a
 GtkWidget *widget as an argument, we use the gtk_signal_connect_object()
 function here instead of straight gtk_signal_connect().
 
 <tscreen><verb>
-    gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
-			       GTK_SIGNAL_FUNC (gtk_widget_destroy),
-			       GTK_OBJECT (window));
+gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
+                           GTK_SIGNAL_FUNC (gtk_widget_destroy),
+                           GTK_OBJECT (window));
 </verb></tscreen>
-<p>
+
 This is a packing call, which will be explained in depth later on.  But it
 is fairly easy to understand.  It simply tells GTK that the button is to be 
-placed in the window where it will be displayed.
+placed in the window where it will be displayed. Note that a GTK container
+can only contain one widget. There are other widgets, that are described later,
+which are designed to layout multiple widgets in various ways.
+ 
 <tscreen><verb>
     gtk_container_add (GTK_CONTAINER (window), button);
 </verb></tscreen>
-<p>
+
 Now that we have everything setup the way we want it to be.  With all the
 signal handlers in place, and the button placed in the window where it
 should be, we ask GTK to "show" the widgets on the screen.  The window
 widget is shown last so the whole window will pop up at once rather than
 seeing the window pop up, and then the button form inside of it.  Although
-with such simple example, you'd never notice.
+with such a simple example, you'd never notice.
+
 <tscreen><verb>
     gtk_widget_show (button);
 
     gtk_widget_show (window);
 </verb></tscreen>
-<p>
+
 And of course, we call gtk_main() which waits for events to come from the X
 server and will call on the widgets to emit signals when these events come.
+
 <tscreen><verb>
     gtk_main ();
 </verb></tscreen>
+
 And the final return.  Control returns here after gtk_quit() is called.
+
 <tscreen><verb>
     return 0;
 </verb></tscreen>
-<p>
+
 Now, when we click the mouse button on a GTK button, the
-widget emits a "clicked" signal.  In order for us to use this information, our
-program sets up a signal handler to catch that signal, which dispatches the function 
-of our choice. In our example, when the button we created is "clicked", the 
-hello() function is called with a NULL
+widget emits a "clicked" signal.  In order for us to use this
+information, our program sets up a signal handler to catch that signal, 
+which dispatches the function of our choice. In our example, when the 
+button we created is "clicked", the hello() function is called with a NULL
 argument, and then the next handler for this signal is called.  This calls
 the gtk_widget_destroy() function, passing it the window widget as it's
 argument, destroying the window widget.  This causes the window to emit the 
-"destroy" signal, which is
-caught, and calls our destroy() callback function, which simply exits GTK.
-<p>
+"destroy" signal, which is caught, and calls our destroy() callback 
+function, which simply exits GTK.
+
 Another course of events, is to use the window manager to kill the window.
 This will cause the "delete_event" to be emitted.  This will call our
 "delete_event" handler.  If we return TRUE here, the window will be left as
 is and nothing will happen.  Returning FALSE will cause GTK to emit the
 "destroy" signal which of course, calls the "destroy" callback, exiting GTK.
-<p>
+
 Note that these signals are not the same as the Unix system
 signals, and are not implemented using them, although the terminology is
 almost identical.
@@ -559,17 +699,17 @@ almost identical.
 <sect1>Data Types
 <p>
 There are a few things you probably noticed in the previous examples that
-need explaining.  The 
-gint, gchar etc. that you see are typedefs to int and char respectively.  This is done
-to get around that nasty dependency on the size of simple data types when doing calculations.
-A good example is "gint32" which will be
-typedef'd to a 32 bit integer for any given platform, whether it be the 64 bit
-alpha, or the 32 bit i386.  The
+need explaining.  The gint, gchar etc. that you see are typedefs to int and 
+char respectively.  This is done to get around that nasty dependency on the 
+size of simple data types when doing calculations.
+
+A good example is "gint32" which will be typedef'd to a 32 bit integer for
+any given platform, whether it be the 64 bit alpha, or the 32 bit i386.  The
 typedefs are very straight forward and intuitive.  They are all defined in
 glib/glib.h (which gets included from gtk.h).
-<p>
-You'll also notice the ability to use GtkWidget when the function calls for a GtkObject.  
-GTK is an object oriented design, and a widget is an object.
+
+You'll also notice the ability to use GtkWidget when the function calls for 
+a GtkObject. GTK is an object oriented design, and a widget is an object.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>More on Signal Handlers
@@ -577,20 +717,24 @@ GTK is an object oriented design, and a widget is an object.
 Lets take another look at the gtk_signal_connect declaration.
 
 <tscreen><verb>
-gint gtk_signal_connect (GtkObject *object, gchar *name,
-			 GtkSignalFunc func, gpointer func_data);
+gint gtk_signal_connect( GtkObject *object,
+                         gchar *name,
+                         GtkSignalFunc func,
+                         gpointer func_data );
 </verb></tscreen>
 
 Notice the gint return value ?  This is a tag that identifies your callback
 function.  As said above, you may have as many callbacks per signal and per
 object as you need, and each will be executed in turn, in the order they 
-were attached.  
+were attached.
 
 This tag allows you to remove this callback from the list by using:
+
 <tscreen><verb>
-void gtk_signal_disconnect (GtkObject *object,
-                            gint id);
+void gtk_signal_disconnect( GtkObject *object,
+                            gint id );
 </verb></tscreen>
+
 So, by passing in the widget you wish to remove the handler from, and the
 tag or id returned by one of the signal_connect functions, you can
 disconnect a signal handler.
@@ -598,7 +742,7 @@ disconnect a signal handler.
 Another function to remove all the signal handers from an object is:
 
 <tscreen><verb>
-gtk_signal_handlers_destroy (GtkObject *object);
+void gtk_signal_handlers_destroy( GtkObject *object );
 </verb></tscreen>
 
 This call is fairly self explanatory.  It simply removes all the current
@@ -612,7 +756,7 @@ of callbacks.  This will also introduce us to our next topic, packing
 widgets.
 
 <tscreen><verb>
-/* helloworld2.c */
+/* example-start helloworld2/helloworld2.c */
 
 #include <gtk/gtk.h>
 
@@ -624,7 +768,7 @@ void callback (GtkWidget *widget, gpointer data)
 }
 
 /* another callback */
-void delete_event (GtkWidget *widget, gpointer data)
+void delete_event (GtkWidget *widget, GdkEvent *event, gpointer data)
 {
     gtk_main_quit ();
 }
@@ -703,6 +847,7 @@ int main (int argc, char *argv[])
 
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 Compile this program using the same linking arguments as our first example.
@@ -720,42 +865,41 @@ differently and should be used for transient windows.
 <!-- ***************************************************************** -->
 <sect>Packing Widgets
 <!-- ***************************************************************** -->
-
 <p>
-When creating an application, you'll want to put more than one button
+When creating an application, you'll want to put more than one widget
 inside a window.  Our first hello world example only used one widget so we
 could simply use a gtk_container_add call to "pack" the widget into the
 window.  But when you want to put more than one widget into a window, how
-do you control where that widget is positioned ?  This is where packing
+do you control where that widget is positioned? This is where packing
 comes in.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Theory of Packing Boxes
 <p>
 Most packing is done by creating boxes as in the example above.  These are
-invisible widget containers that we can pack our widgets into and come in
+invisible widget containers that we can pack our widgets into which come in
 two forms, a horizontal box, and a vertical box.  When packing widgets
 into a horizontal box, the objects are inserted horizontally from left to
 right or right to left depending on the call used. In a vertical box,
 widgets are packed from top to bottom or vice versa.  You may use any
 combination of boxes inside or beside other boxes to create the desired
 effect.
-<p>
+
 To create a new horizontal box, we use a call to gtk_hbox_new(), and for
-vertical boxes, gtk_vbox_new().  The gtk_box_pack_start() and
+vertical boxes, gtk_vbox_new(). The gtk_box_pack_start() and
 gtk_box_pack_end() functions are used to place objects inside of these
 containers.  The gtk_box_pack_start() function will start at the top and
 work its way down in a vbox, and pack left to right in an hbox.
 gtk_box_pack_end() will do the opposite, packing from bottom to top in a
 vbox, and right to left in an hbox.  Using these functions allow us to
 right justify or left justify our widgets and may be mixed in any way to
-achieve the desired effect.  We will use gtk_box_pack_start() in most of
-our examples.  An object may be another container or a widget.	And in
-fact, many widgets are actually containers themselves including the
+achieve the desired effect. We will use gtk_box_pack_start() in most of
+our examples.  An object may be another container or a widget. In
+fact, many widgets are actually containers themselves, including the
 button, but we usually only use a label inside a button.
-<p>
+
 By using these calls, GTK knows where you want to place your widgets so it
-can do automatic resizing and other nifty things.  there's also a number
+can do automatic resizing and other nifty things. There's also a number
 of options as to how your widgets should be packed. As you can imagine,
 this method gives us a quite a bit of flexibility when placing and
 creating widgets.
@@ -766,9 +910,8 @@ creating widgets.
 Because of this flexibility, packing boxes in GTK can be confusing at
 first. There are a lot of options, and it's not immediately obvious how
 they all fit together.	In the end however, there are basically five
-different styles you can get.
+different styles.
 
-<p>
 <? <CENTER> >
 <?
 <IMG SRC="gtk_tut_packbox1.gif" VSPACE="15" HSPACE="10" WIDTH="528" HEIGHT="235"
@@ -779,51 +922,50 @@ ALT="Box Packing Example Image">
 Each line contains one horizontal box (hbox) with several buttons. The
 call to gtk_box_pack is shorthand for the call to pack each of the buttons
 into the hbox. Each of the buttons is packed into the hbox the same way
-(i.e. same arguments to the gtk_box_pack_start () function).
-<p>
+(i.e. same arguments to the gtk_box_pack_start() function).
+
 This is the declaration of the gtk_box_pack_start function.
 
 <tscreen><verb>
-void gtk_box_pack_start (GtkBox    *box,
-			 GtkWidget *child,
-			 gint	    expand,
-			 gint	    fill,
-			 gint	    padding);
+void gtk_box_pack_start( GtkBox    *box,
+                         GtkWidget *child,
+                         gint       expand,
+                         gint       fill,
+                         gint       padding );
 </verb></tscreen>
 
 The first argument is the box you are packing the object into, the second
-is this object.  The objects will all be buttons for now, so we'll be
+is the object. The objects will all be buttons for now, so we'll be
 packing buttons into boxes.
-<p>
-The expand argument to gtk_box_pack_start() or gtk_box_pack_end() controls
+
+The expand argument to gtk_box_pack_start() and gtk_box_pack_end() controls
 whether the widgets are laid out in the box to fill in all the extra space
 in the box so the box is expanded to fill the area alloted to it (TRUE).
-Or the box is shrunk to just fit the widgets (FALSE).  Setting expand to
-FALSE will allow you to do right and left
-justifying of your widgets.  Otherwise, they will all expand to fit in the
-box, and the same effect could be achieved by using only one of
-gtk_box_pack_start or pack_end functions.
-<p>
+Or the box is shrunk to just fit the widgets (FALSE). Setting expand to
+FALSE will allow you to do right and left justification of your widgets.
+Otherwise, they will all expand to fit into the box, and the same effect
+could be achieved by using only one of gtk_box_pack_start or pack_end functions.
+
 The fill argument to the gtk_box_pack functions control whether the extra
 space is allocated to the objects themselves (TRUE), or as extra padding
 in the box around these objects (FALSE). It only has an effect if the
 expand argument is also TRUE.
-<p>
+
 When creating a new box, the function looks like this:
 
 <tscreen><verb>
-GtkWidget * gtk_hbox_new (gint homogeneous,
-			  gint spacing);
+GtkWidget *gtk_hbox_new (gint homogeneous,
+                         gint spacing);
 </verb></tscreen>
 
 The homogeneous argument to gtk_hbox_new (and the same for gtk_vbox_new)
 controls whether each object in the box has the same size (i.e. the same
 width in an hbox, or the same height in a vbox). If it is set, the expand
 argument to the gtk_box_pack routines is always turned on.
-<p>
+
 What's the difference between spacing (set when the box is created) and
 padding (set when elements are packed)? Spacing is added between objects,
-and padding is added on either side of an object.  The following figure
+and padding is added on either side of an object. The following figure
 should make it clearer:
 
 <? <CENTER> >
@@ -834,19 +976,19 @@ VSPACE="15" HSPACE="10" ALT="Box Packing Example Image">
 <? </CENTER> >
 
 Here is the code used to create the above images.  I've commented it fairly
-heavily so hopefully you won't have any problems following it.  Compile it yourself
-and play with it.
+heavily so hopefully you won't have any problems following it.  Compile it 
+yourself and play with it.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Packing Demonstration Program
 <p>
 <tscreen><verb>
-/* packbox.c */
+/* example-start packbox/packbox.c */
 
 #include "gtk/gtk.h"
 
 void
-delete_event (GtkWidget *widget, gpointer data)
+delete_event (GtkWidget *widget, GdkEvent *event, gpointer data)
 {
     gtk_main_quit ();
 }
@@ -1124,6 +1266,7 @@ main (int argc, char *argv[])
     
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
@@ -1132,26 +1275,27 @@ main (int argc, char *argv[])
 Let's take a look at another way of packing - Tables.  These can be
 extremely useful in certain situations.
 
-Using tables, we create a grid that we can place widgets in.  The widgets
+Using tables, we create a grid that we can place widgets in. The widgets
 may take up as many spaces as we specify.
 
 The first thing to look at of course, is the gtk_table_new function:
 
 <tscreen><verb>
-GtkWidget* gtk_table_new (gint rows,
+GtkWidget *gtk_table_new( gint rows,
                           gint columns,
-                          gint homogeneous);
+                          gint homogeneous );
 </verb></tscreen>
-<p>
+
 The first argument is the number of rows to make in the table, while the
-second, obviously, the number of columns.
+second, obviously, is the number of columns.
 
-The homogeneous argument has to do with how the table's boxes are sized.  If homogeneous 
-is TRUE, the table boxes are resized to the size of the largest widget in the table.
-If homogeneous is FALSE, the size of a table boxes is dictated by the tallest widget 
-in its same row, and the widest widget in its column.
+The homogeneous argument has to do with how the table's boxes are sized. If
+homogeneous is TRUE, the table boxes are resized to the size of the largest
+widget in the table. If homogeneous is FALSE, the size of a table boxes is 
+dictated by the tallest widget in its same row, and the widest widget in its
+column.
 
-The rows and columnts are laid out starting with 0 to n, where n was the
+The rows and columnts are laid out from 0 to n, where n was the
 number specified in the call to gtk_table_new.  So, if you specify rows = 2 and 
 columns = 2, the layout would look something like this:
 
@@ -1163,35 +1307,34 @@ columns = 2, the layout would look something like this:
  |          |          |
 2+----------+----------+
 </verb></tscreen>
-<p>
+
 Note that the coordinate system starts in the upper left hand corner.  To place a 
 widget into a box, use the following function:
 
 <tscreen><verb>
-void gtk_table_attach (GtkTable      *table,
-                       GtkWidget     *child,
-		       gint           left_attach,
-		       gint           right_attach,
-		       gint           top_attach,
-		       gint           bottom_attach,
-		       gint           xoptions,
-		       gint           yoptions,
-		       gint           xpadding,
-		       gint           ypadding);
+void gtk_table_attach( GtkTable  *table,
+                       GtkWidget *child,
+                       gint       left_attach,
+                       gint       right_attach,
+                       gint       top_attach,
+                       gint       bottom_attach,
+                       gint       xoptions,
+                       gint       yoptions,
+                       gint       xpadding,
+                       gint       ypadding );
 </verb></tscreen>				       
-<p>
+
 Where the first argument ("table") is the table you've created and the second
 ("child") the widget you wish to place in the table.
 
-The left and right attach 
-arguments specify where to place the widget, and how many boxes to use.  If you want 
-a button in the lower right table entry 
+The left and right attach arguments specify where to place the widget, and how
+many boxes to use. If you want a button in the lower right table entry 
 of our 2x2 table, and want it to fill that entry ONLY.  left_attach would be = 1, 
 right_attach = 2, top_attach = 1, bottom_attach = 2.
 
 Now, if you wanted a widget to take up the whole 
-top row of our 2x2 table, you'd use left_attach = 0, right_attach =2, top_attach = 0, 
-bottom_attach = 1.
+top row of our 2x2 table, you'd use left_attach = 0, right_attach = 2,
+top_attach = 0, bottom_attach = 1.
 
 The xoptions and yoptions are used to specify packing options and may be OR'ed 
 together to allow multiple options.  
@@ -1217,31 +1360,33 @@ specified in pixels.
 gtk_table_attach() has a LOT of options.  So, there's a shortcut:
 
 <tscreen><verb>
-void gtk_table_attach_defaults (GtkTable   *table,
-                                GtkWidget  *widget,
-				gint        left_attach,
-				gint        right_attach,
-				gint        top_attach,
-				gint        bottom_attach);
+void gtk_table_attach_defaults( GtkTable  *table,
+                                GtkWidget *widget,
+                                gint       left_attach,
+                                gint       right_attach,
+                                gint       top_attach,
+                                gint       bottom_attach );
 </verb></tscreen>
 
 The X and Y options default to GTK_FILL | GTK_EXPAND, and X and Y padding
-are set to 0.  The rest of the arguments are identical to the previous
+are set to 0. The rest of the arguments are identical to the previous
 function.
 
-We also have gtk_table_set_row_spacing() and gtk_table_set_col_spacing(). 
+We also have gtk_table_set_row_spacing() and gtk_table_set_col_spacing().
 This places spacing between the rows at the specified row or column.
 
 <tscreen><verb>
-void gtk_table_set_row_spacing (GtkTable      *table,
-                                gint           row,
-				gint           spacing);
+void gtk_table_set_row_spacing( GtkTable *table,
+                                gint      row,
+                                gint      spacing );
 </verb></tscreen>
+
 and
+
 <tscreen><verb>
-void       gtk_table_set_col_spacing  (GtkTable      *table,
-                                       gint           column,
-				       gint           spacing);
+void gtk_table_set_col_spacing ( GtkTable *table,
+                                 gint      column,
+                                 gint      spacing );
 </verb></tscreen>
 
 Note that for columns, the space goes to the right of the column, and for 
@@ -1250,16 +1395,17 @@ rows, the space goes below the row.
 You can also set a consistent spacing of all rows and/or columns with:
 
 <tscreen><verb>
-void gtk_table_set_row_spacings (GtkTable *table,
-                                 gint      spacing);
+void gtk_table_set_row_spacings( GtkTable *table,
+                                 gint      spacing );
 </verb></tscreen>
-<p>
+
 And,
+
 <tscreen><verb>
-void gtk_table_set_col_spacings (GtkTable  *table,
-                                 gint       spacing);
+void gtk_table_set_col_spacings( GtkTable *table,
+                                 gint      spacing );
 </verb></tscreen>
-<p>
+
 Note that with these calls, the last row and last column do not get any 
 spacing.
 
@@ -1270,7 +1416,7 @@ Here we make a window with three buttons in a 2x2 table.
 The first two buttons will be placed in the upper row.
 A third, quit button, is placed in the lower row, spanning both columns.
 Which means it should look something like this:
-<p>
+
 <? <CENTER> >
 <?
 <IMG SRC="gtk_tut_table.gif" VSPACE="15" HSPACE="10" 
@@ -1281,7 +1427,7 @@ ALT="Table Packing Example Image" WIDTH="180" HEIGHT="120">
 Here's the source code:
 
 <tscreen><verb>
-/* table.c */
+/* example-start table/table.c */
 #include <gtk/gtk.h>
 
 /* our callback.
@@ -1292,7 +1438,7 @@ void callback (GtkWidget *widget, gpointer data)
 }
 
 /* this callback quits the program */
-void delete_event (GtkWidget *widget, gpointer data)
+void delete_event (GtkWidget *widget, GdkEvent *event, gpointer data)
 {
     gtk_main_quit ();
 }
@@ -1373,18 +1519,20 @@ int main (int argc, char *argv[])
 
     return 0;
 }
+/* example-end */
 </verb></tscreen>
+
 <!-- ***************************************************************** -->
 <sect>Widget Overview
 <!-- ***************************************************************** -->
-
 <p>
 The general steps to creating a widget in GTK are:
 <enum>
 <item> gtk_*_new - one of various functions to create a new widget.  These
 are all detailed in this section.
 
-<item> Connect all signals we wish to use to the appropriate handlers.
+<item> Connect all signals and events we wish to use to the
+appropriate handlers.
 
 <item> Set the attributes of the widget.
 
@@ -1393,16 +1541,15 @@ gtk_container_add() or gtk_box_pack_start().
 
 <item> gtk_widget_show() the widget.
 </enum>
-<p>
+
 gtk_widget_show() lets GTK know that we are done setting the attributes
 of the widget, and it is ready to be displayed.  You may also use
 gtk_widget_hide to make it disappear again.  The order in which you
 show the widgets is not important, but I suggest showing the window
 last so the whole window pops up at once rather than seeing the individual
 widgets come up on the screen as they're formed.  The children of a widget
-(a window is a widget too)
-will not be displayed until the window itself is shown using the
-gtk_widget_show() function.
+(a window is a widget too) will not be displayed until the window itself
+is shown using the gtk_widget_show() function.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Casting
@@ -1425,23 +1572,23 @@ examples, and can usually tell when to use them simply by looking at the
 function's declaration.
 
 As you can see below in the class hierarchy, all GtkWidgets are derived from
-the GtkObject base class.  This means you can use an widget in any place the 
+the GtkObject base class.  This means you can use a widget in any place the 
 function asks for an object - simply use the GTK_OBJECT() macro.
 
 For example:
 
 <tscreen><verb>
-gtk_signal_connect(GTK_OBJECT(button), "clicked",
-                   GTK_SIGNAL_FUNC(callback_function), callback_data);
+gtk_signal_connect( GTK_OBJECT(button), "clicked",
+                    GTK_SIGNAL_FUNC(callback_function), callback_data);
 </verb></tscreen> 
 
 This casts the button into an object, and provides a cast for the function
 pointer to the callback.
 
 Many widgets are also containers.  If you look in the class hierarchy below,
-you'll notice that many widgets drive from the GtkContainer class.  Any one
-of those widgets may use with the GTK_CONTAINER macro to
-pass them to functions that ask for containers.
+you'll notice that many widgets derive from the GtkContainer class.  Any one
+of these widgets may be used with the GTK_CONTAINER macro to pass them to
+functions that ask for containers.
 
 Unfortunately, these macros are not extensively covered in the tutorial, but I
 recomend taking a look through the GTK header files.  It can be very
@@ -1563,7 +1710,7 @@ GtkHBox
 GtkVSeparator
 GtkHSeparator
 </verb></tscreen>
-<p>
+
 We'll further our exploration of GTK by examining each widget in turn,
 creating a few simple functions to display them.  Another good source is
 the testgtk.c program that comes with GTK.  It can be found in
@@ -1576,20 +1723,20 @@ gtk/testgtk.c.
 <!-- ----------------------------------------------------------------- -->
 <sect1>Normal Buttons
 <p>
-We've almost seen all there is to see of the button widget.  It's pretty
-simple.  There is however two ways to create a button.	You can use the
+We've almost seen all there is to see of the button widget. It's pretty
+simple.  There is however two ways to create a button. You can use the
 gtk_button_new_with_label() to create a button with a label, or use
-gtk_button_new() to create a blank button.  It's then up to you to pack a
-label or pixmap into this new button.  To do this, create a new box, and
+gtk_button_new() to create a blank button. It's then up to you to pack a
+label or pixmap into this new button. To do this, create a new box, and
 then pack your objects into this box using the usual gtk_box_pack_start,
 and then use gtk_container_add to pack the box into the button.
-<p>
+
 Here's an example of using gtk_button_new to create a button with a
 picture and a label in it.  I've broken the code to create a box up from
 the rest so you can use it in your programs.
 
 <tscreen><verb>
-/* buttons.c */
+/* example-start buttons/buttons.c */
 
 #include <gtk/gtk.h>
 
@@ -1693,45 +1840,56 @@ int main (int argc, char *argv[])
 
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 The xpm_label_box function could be used to pack xpm's and labels into any
 widget that can be a container.
 
+The Buton widget has the following signals:
+
+<itemize>
+<item> pressed
+<item> released
+<item> clicked
+<item> enter
+<item> leave
+</itemize>
+
 <!-- ----------------------------------------------------------------- -->
 <sect1> Toggle Buttons
 <p>
-Toggle buttons are very similar to normal buttons, except they will always
-be in one of two states, alternated by a click.  They may be depressed, and
-when you click again, they will pop back up.  Click again, and they will pop
-back down. 
+Toggle buttons are derived from normal buttons and are very similar, except
+they will always be in one of two states, alternated by a click.  They may
+be depressed, and when you click again, they will pop back up. Click again,
+and they will pop back down. 
 
 Toggle buttons are the basis for check buttons and radio buttons, as such,
 many of the calls used for toggle buttons are inherited by radio and check
-buttons.  I will point these out when we come to them.
+buttons. I will point these out when we come to them.
 
 Creating a new toggle button:
 
 <tscreen><verb>
-GtkWidget* gtk_toggle_button_new (void);
+GtkWidget *gtk_toggle_button_new( void );
 
-GtkWidget* gtk_toggle_button_new_with_label (gchar *label);
+GtkWidget *gtk_toggle_button_new_with_label( gchar *label );
 </verb></tscreen>
-<p>
+
 As you can imagine, these work identically to the normal button widget
-calls.  The first creates a blank toggle button, and the second, a button 
+calls. The first creates a blank toggle button, and the second, a button 
 with a label widget already packed into it.
-<p>
+
 To retrieve the state of the toggle widget, including radio and check
 buttons, we use a macro as shown in our example below.  This tests the state
-of the toggle in a callback.  The signal of interest emitted to us by toggle
+of the toggle in a callback. The signal of interest emitted to us by toggle
 buttons (the toggle button, check button, and radio button widgets), is the
 "toggled" signal.  To check the state of these buttons, set up a signal
 handler to catch the toggled signal, and use the macro to determine it's
-state.  The callback will look something like:
+state. The callback will look something like:
 
 <tscreen><verb>
-void toggle_button_callback (GtkWidget *widget, gpointer   data)
+void toggle_button_callback (GtkWidget *widget, gpointer data)
 {
     if (GTK_TOGGLE_BUTTON (widget)->active) 
     {
@@ -1744,61 +1902,41 @@ void toggle_button_callback (GtkWidget *widget, gpointer   data)
 }
 </verb></tscreen>
 
-<!--
-
-COMMENTED!
-
-<tscreen><verb>
-guint gtk_toggle_button_get_type (void);
-</verb></tscreen>
-<p>
-No idea... they all have this, but I dunno what it is :)
-
-
 <tscreen><verb>
-void gtk_toggle_button_set_mode (GtkToggleButton *toggle_button,
-                                 gint draw_indicator);
+void gtk_toggle_button_set_state( GtkToggleButton *toggle_button,
+                                  gint             state );
 </verb></tscreen>
-<p>
-No idea.
--->
 
-<tscreen><verb>
-void gtk_toggle_button_set_state (GtkToggleButton *toggle_button,
-                                  gint state);
-</verb></tscreen>
-<p>
 The above call can be used to set the state of the toggle button, and it's
-children the radio and check buttons.  Passing
-in your created button as the first argument, and a TRUE or FALSE
-for the second state argument to specify whether it should be up (released) or
-down (depressed).  Default is up, or FALSE.
+children the radio and check buttons. Passing in your created button as
+the first argument, and a TRUE or FALSE for the second state argument to
+specify whether it should be up (released) or down (depressed).  Default
+is up, or FALSE.
 
 Note that when you use the gtk_toggle_button_set_state() function, and the
-state is actually changed, it causes
-the "clicked" signal to be emitted from the button.
+state is actually changed, it causes the "clicked" signal to be emitted 
+from the button.
 
 <tscreen><verb>
-void       gtk_toggle_button_toggled        (GtkToggleButton *toggle_button);
+void gtk_toggle_button_toggled (GtkToggleButton *toggle_button);
 </verb></tscreen>
-<p>
+
 This simply toggles the button, and emits the "toggled" signal.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Check Buttons
 <p>
-Check buttons inherent many properties and functions from the the toggle buttons above, 
-but look a little
-different.  Rather than being buttons with text inside them, they are small
-squares with the text to the right of them.  These are often seen for
-toggling options on and off in applications.
+Check buttons inherent many properties and functions from the the toggle
+buttons above, but look a little different. Rather than being buttons with
+text inside them, they are small squares with the text to the right of 
+them. These are often used for toggling options on and off in applications.
 
-The two creation functions are the same as for the normal button.
+The two creation functions are similar to those of the normal button.
 
 <tscreen><verb>
-GtkWidget* gtk_check_button_new (void);
+GtkWidget *gtk_check_button_new( void );
 
-GtkWidget* gtk_check_button_new_with_label (gchar *label);
+GtkWidget *gtk_check_button_new_with_label ( gchar *label );
 </verb></tscreen>
 
 The new_with_label function creates a check button with a label beside it.
@@ -1810,27 +1948,26 @@ button.
 <sect1> Radio Buttons
 <p>
 Radio buttons are similar to check buttons except they are grouped so that
-only one may be selected/depressed at a time.  This is good for places in
+only one may be selected/depressed at a time. This is good for places in
 your application where you need to select from a short list of options.
 
 Creating a new radio button is done with one of these calls:
 
 <tscreen><verb>
-GtkWidget* gtk_radio_button_new (GSList *group);
+GtkWidget *gtk_radio_button_new( GSList *group );
 
-GtkWidget* gtk_radio_button_new_with_label (GSList *group,
-                                            gchar *label);
+GtkWidget *gtk_radio_button_new_with_label( GSList *group,
+                                            gchar  *label );
 </verb></tscreen>
-<p>
+
 You'll notice the extra argument to these calls.  They require a group to
-perform they're duty properly.  The first call should pass NULL as the first
-argument.  Then create a group using:
+perform they're duty properly. The first call should pass NULL as the first
+argument. Then create a group using:
 
 <tscreen><verb>
-GSList* gtk_radio_button_group (GtkRadioButton *radio_button);
+GSList *gtk_radio_button_group( GtkRadioButton *radio_button );
 </verb></tscreen>
 
-<p>
 The important thing to remember is that gtk_radio_button_group must be
 called for each new button added to the group, with the previous button
 passed in as an argument. The result is then passed into the call to
@@ -1842,22 +1979,22 @@ It is also a good idea to explicitly set which button should be the
 default depressed button with:
 
 <tscreen><verb>
-void gtk_toggle_button_set_state (GtkToggleButton *toggle_button,
-                                  gint state);
+void gtk_toggle_button_set_state( GtkToggleButton *toggle_button,
+                                  gint             state );
 </verb></tscreen>
-<p>
+
 This is described in the section on toggle buttons, and works in exactly the
 same way.
-<p>
+
 The following example creates a radio button group with three buttons.
 
 <tscreen><verb>
-/* radiobuttons.c */
+/* example-start radiobuttons/radiobuttons.c */
 
 #include <gtk/gtk.h>
 #include <glib.h>
 
-void close_application( GtkWidget *widget, gpointer data ) {
+void close_application( GtkWidget *widget, GdkEvent *event, gpointer data ) {
   gtk_main_quit();
 }
 
@@ -1937,6 +2074,8 @@ removes the need for a variable to hold the list of buttons:
                  "button2");
 </verb></tscreen>
 
+<!-- TODO: checout out gtk_radio_button_new_from_widget function - TRG -->
+
 <!-- ***************************************************************** -->
 <sect> Miscallaneous Widgets
 <!-- ***************************************************************** -->
@@ -1944,14 +2083,14 @@ removes the need for a variable to hold the list of buttons:
 <!-- ----------------------------------------------------------------- -->
 <sect1> Labels
 <p>
-Labels are used a lot in GTK, and are relatively simple.  Labels emit no
-signals as they do not have an associated X window.  If you need to catch
+Labels are used a lot in GTK, and are relatively simple. Labels emit no
+signals as they do not have an associated X window. If you need to catch
 signals, or do clipping, use the EventBox widget.
 
 To create a new label, use:
 
 <tscreen><verb>
-GtkWidget* gtk_label_new (char *str);
+GtkWidget *gtk_label_new( char *str );
 </verb></tscreen>
 
 Where the sole argument is the string you wish the label to display.
@@ -1959,11 +2098,11 @@ Where the sole argument is the string you wish the label to display.
 To change the label's text after creation, use the function:
 
 <tscreen><verb>
-void gtk_label_set (GtkLabel  *label,
-		    char      *str);
+void gtk_label_set( GtkLabel *label,
+                    char     *str );
 </verb></tscreen>
-<p>
-Where the first argument is the label you created previously (casted using
+
+Where the first argument is the label you created previously (cast using
 the GTK_LABEL() macro), and the second is the new string.
 
 The space needed for the new string will be automatically adjusted if needed.
@@ -1971,8 +2110,8 @@ The space needed for the new string will be automatically adjusted if needed.
 To retrieve the current string, use:
 
 <tscreen><verb>
-void gtk_label_get (GtkLabel  *label,
-		    char     **str);
+void gtk_label_get( GtkLabel  *label,
+                    char     **str );
 </verb></tscreen>
 
 Where the first arguement is the label you've created, and the second, the
@@ -1982,34 +2121,37 @@ return for the string.
 <sect1>The Tooltips Widget
 <p>
 These are the little text strings that pop up when you leave your pointer
-over a button or other widget for a few seconds.  They are easy to use, so I
-will just explain them without giving an example.  If you want to see some
+over a button or other widget for a few seconds. They are easy to use, so I
+will just explain them without giving an example. If you want to see some
 code, take a look at the testgtk.c program distributed with GDK.
-<p>
+
 Some widgets (such as the label) will not work with tooltips.
-<p>
-The first call you will use to create a new tooltip.  You only need to do
-this once in a given function.	The <tt/GtkTooltip/ this function 
+
+The first call you will use to create a new tooltip. You only need to do
+this once in a given function. The <tt/GtkTooltip/ object this function 
 returns can be used to create multiple tooltips.
 
 <tscreen><verb>
-GtkTooltips *gtk_tooltips_new (void);
+GtkTooltips *gtk_tooltips_new( void );
 </verb></tscreen>
 
 Once you have created a new tooltip, and the widget you wish to use it on,
-simply use this call to set it.
+simply use this call to set it:
 
 <tscreen><verb>
-void gtk_tooltips_set_tip (GtkTooltips *tooltips,
+void gtk_tooltips_set_tip( GtkTooltips *tooltips,
                            GtkWidget   *widget,
                            const gchar *tip_text,
-                           const gchar *tip_private);
+                           const gchar *tip_private );
 </verb></tscreen>
 
 The first argument is the tooltip you've already created, followed by the
 widget you wish to have this tooltip pop up for, and the text you wish it to
-say. The last argument can be set to NULL.
-<p>
+say. The last argument is a text string that can be used as an identifier when using
+GtkTipsQuery to implement context sensitive help. For now, you can set
+it to NULL.
+<!-- TODO: sort out what how to do the context sensitive help -->
+
 Here's a short example:
 
 <tscreen><verb>
@@ -2022,53 +2164,41 @@ button = gtk_button_new_with_label ("button 1");
 gtk_tooltips_set_tip (tooltips, button, "This is button 1", NULL);
 </verb></tscreen>
 
-There are other calls used with tooltips.  I will just list them with a
-brief description of what they do.
-
-<tscreen><verb>
-void gtk_tooltips_destroy    (GtkTooltips *tooltips);
-</verb></tscreen>
-
-Destroy the created tooltips.
+There are other calls that can be used with tooltips.  I will just
+list them with a brief description of what they do.
 
 <tscreen><verb>
-void gtk_tooltips_enable     (GtkTooltips *tooltips);
+void gtk_tooltips_enable( GtkTooltips *tooltips );
 </verb></tscreen>
 
 Enable a disabled set of tooltips.
 
 <tscreen><verb>
-void gtk_tooltips_disable    (GtkTooltips *tooltips);
+void gtk_tooltips_disable( GtkTooltips *tooltips );
 </verb></tscreen>
 
 Disable an enabled set of tooltips.
 
 <tscreen><verb>
-void gtk_tooltips_set_delay  (GtkTooltips *tooltips,
-			      gint	   delay);
+void gtk_tooltips_set_delay( GtkTooltips *tooltips,
+                             gint         delay );
 
 </verb></tscreen>
-Sets how many milliseconds you have to hold you pointer over the widget before the
-tooltip will pop up.  The default is 1000 milliseconds or 1 second.
 
-<tscreen><verb>
-void	  gtk_tooltips_set_tips (GtkTooltips *tooltips,
-			         GtkWidget   *widget,
-			         gchar	  *tips_text);
-</verb></tscreen>
-
-Change the tooltip text of an already created tooltip.
+Sets how many milliseconds you have to hold your pointer over the 
+widget before the tooltip will pop up.  The default is 1000 milliseconds
+or 1 second.
 
 <tscreen><verb>
-void gtk_tooltips_set_colors (GtkTooltips *tooltips,
-			      GdkColor	  *background,
-			      GdkColor	  *foreground);
+void gtk_tooltips_set_colors( GtkTooltips *tooltips,
+                              GdkColor    *background,
+                              GdkColor    *foreground );
 </verb></tscreen>
 
-Set the foreground and background color of the tooltips.  Again, I have no
+Set the foreground and background color of the tooltips. Again, I have no
 idea how to specify the colors.
-<p>
-And that's all the functions associated with tooltips.  More than you'll
+
+And that's all the functions associated with tooltips. More than you'll
 ever want to know :)
 
 <!-- ----------------------------------------------------------------- -->
@@ -2079,18 +2209,20 @@ easy to use, as you will see with the code below. But first lets start out
 with the call to create a new progress bar.
 
 <tscreen><verb>
-GtkWidget *gtk_progress_bar_new (void);
+GtkWidget *gtk_progress_bar_new( void );
 </verb></tscreen>
 
 Now that the progress bar has been created we can use it.
 
 <tscreen><verb>
-void gtk_progress_bar_update (GtkProgressBar *pbar, gfloat percentage);
+void gtk_progress_bar_update( GtkProgressBar *pbar,
+                              gfloat          percentage );
 </verb></tscreen>
 
 The first argument is the progress bar you wish to operate on, and the second 
 argument is the amount 'completed', meaning the amount the progress bar has 
-been filled from 0-100% (a real number between 0 and 1).
+been filled from 0-100%. This is passed to the function as a real number
+ranging from 0 to 1.
 
 Progress Bars are usually used with timeouts or other such functions (see
 section on <ref id="sec_timeouts" name="Timeouts, I/O and Idle Functions">) 
@@ -2101,7 +2233,7 @@ Here is an example of the progress bar, updated using timeouts.  This
 code also shows you how to reset the Progress Bar.
 
 <tscreen><verb>
-/* progressbar.c */
+/* example-start progressbar/progressbar.c */
 
 #include <gtk/gtk.h>
 
@@ -2134,7 +2266,7 @@ void progress_r (void)
     pstat = FALSE;  
 }
 
-void destroy (GtkWidget *widget, gpointer data)
+void destroy (GtkWidget *widget, GdkEvent *event, gpointer data)
 {
     gtk_main_quit ();
 }
@@ -2192,32 +2324,33 @@ int main (int argc, char *argv[])
     
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 In this small program there are four areas that concern the general operation
 of Progress Bars, we will look at them in the order they are called.
 
 <tscreen><verb>
-pbar = gtk_progress_bar_new ();
+    pbar = gtk_progress_bar_new ();
 </verb></tscreen>
 
 This code creates a new progress bar, called pbar.
 
 <tscreen><verb>
-ptimer = gtk_timeout_add (100, progress, pbar);
+    ptimer = gtk_timeout_add (100, progress, pbar);
 </verb></tscreen>
 
-This code, uses timeouts to enable a constant time interval, timeouts are 
+This code uses timeouts to enable a constant time interval, timeouts are 
 not necessary in the use of Progress Bars. 
 
 <tscreen><verb>
-pvalue = GTK_PROGRESS_BAR (data)->percentage;
+    pvalue = GTK_PROGRESS_BAR (data)->percentage;
 </verb></tscreen>
 
 This code assigns the current value of the percentage bar to pvalue.
 
 <tscreen><verb>
-gtk_progress_bar_update (GTK_PROGRESS_BAR (data), pvalue);
+    gtk_progress_bar_update (GTK_PROGRESS_BAR (data), pvalue);
 </verb></tscreen>
 
 Finally, this code updates the progress bar with the value of pvalue
@@ -2227,9 +2360,8 @@ And that is all there is to know about Progress Bars, enjoy.
 <!-- ----------------------------------------------------------------- -->
 <sect1> Dialogs
 <p>
-
 The Dialog widget is very simple, and is actually just a window with a few
-things pre-packed into it for you.  The structure for a Dialog is:
+things pre-packed into it for you. The structure for a Dialog is:
 
 <tscreen><verb>
 struct GtkDialog
@@ -2241,7 +2373,7 @@ struct GtkDialog
 };
 </verb></tscreen>
 
-So you see, it simple creates a window, and then packs a vbox into the top,
+So you see, it simply creates a window, and then packs a vbox into the top,
 then a seperator, and then an hbox for the "action_area".
 
 The Dialog widget can be used for pop-up messages to the user, and 
@@ -2249,7 +2381,7 @@ other similar tasks.  It is really basic, and there is only one
 function for the dialog box, which is:
 
 <tscreen><verb>
-GtkWidget* gtk_dialog_new (void);
+GtkWidget *gtk_dialog_new( void );
 </verb></tscreen>
 
 So to create a new dialog box, use,
@@ -2260,7 +2392,7 @@ window = gtk_dialog_new ();
 </verb></tscreen>
 
 This will create the dialog box, and it is now up to you to use it.
-you could pack a button in the action_area by doing something like so:
+you could pack a button in the action_area by doing something like this:
 
 <tscreen><verb>
 button = ...
@@ -2285,64 +2417,69 @@ area, asking the user a question or giving an error etc.  Then you could
 attach a different signal to each of the buttons and perform the 
 operation the user selects.
 
+If the simple functionality provided by the default vertical and
+horizontal boxes in the two areas don't give you enough control for your
+application, then you can simply pack another layout widget into the boxes
+provided. For example, you could pack a table into the vertical box.
+
 <!-- ----------------------------------------------------------------- -->
 <sect1> Pixmaps
 <p>
-Pixmaps are data structures that contain pictures.  These pictures can be
+Pixmaps are data structures that contain pictures. These pictures can be
 used in various places, but most visibly as icons on the X-Windows desktop,
-or as cursors.  A bitmap is a 2-color pixmap.
+or as cursors. A bitmap is a 2-color pixmap.
 
 To use pixmaps in GTK, we must first build a GdkPixmap structure using
-routines from the GDK layer.  Pixmaps can either be created from in-memory
-data, or from data read from a file.  We'll go through each of the calls
+routines from the GDK layer. Pixmaps can either be created from in-memory
+data, or from data read from a file. We'll go through each of the calls
 to create a pixmap.
 
 <tscreen><verb>
 GdkPixmap *gdk_bitmap_create_from_data( GdkWindow *window,
                                         gchar     *data,
-                                        gint      width,
-                                        gint      height );
+                                        gint       width,
+                                        gint       height );
 </verb></tscreen>
-<p>
+
 This routine is used to create a single-plane pixmap (2 colors) from data in
-memory.  Each bit of the data represents whether that pixel is off or on.
-Width and height are in pixels.  The GdkWindow pointer is to the current
+memory. Each bit of the data represents whether that pixel is off or on.
+Width and height are in pixels. The GdkWindow pointer is to the current
 window, since a pixmap resources are meaningful only in the context of the
 screen where it is to be displayed.
 
 <tscreen><verb>
-GdkPixmap* gdk_pixmap_create_from_data( GdkWindow  *window,
-                                        gchar      *data,
-                                        gint        width,
-                                        gint        height,
-                                        gint        depth,
-                                        GdkColor   *fg,
-                                        GdkColor   *bg );
+GdkPixmap *gdk_pixmap_create_from_data( GdkWindow *window,
+                                        gchar     *data,
+                                        gint       width,
+                                        gint       height,
+                                        gint       depth,
+                                        GdkColor  *fg,
+                                        GdkColor  *bg );
 </verb></tscreen>
 
 This is used to create a pixmap of the given depth (number of colors) from
-the bitmap data specified.  fg and bg are the foreground and background
-color to use.
+the bitmap data specified. <tt/fg/ and <tt/bg/ are the foreground and
+background color to use.
 
 <tscreen><verb>
-GdkPixmap* gdk_pixmap_create_from_xpm( GdkWindow  *window,
-                                       GdkBitmap **mask,
-                                       GdkColor   *transparent_color,
+GdkPixmap *gdk_pixmap_create_from_xpm( GdkWindow   *window,
+                                       GdkBitmap  **mask,
+                                       GdkColor    *transparent_color,
                                        const gchar *filename );
 </verb></tscreen>
 
 XPM format is a readable pixmap representation for the X Window System.  It
 is widely used and many different utilities are available for creating image
 files in this format.  The file specified by filename must contain an image
-in that format and it is loaded into the pixmap structure.  The mask specifies
-what bits of the pixmap are opaque.  All other bits are colored using the
-color specified by transparent_color.  An example using this follows below.  
+in that format and it is loaded into the pixmap structure. The mask specifies
+which bits of the pixmap are opaque. All other bits are colored using the
+color specified by transparent_color. An example using this follows below.  
 
 <tscreen><verb>
-GdkPixmap* gdk_pixmap_create_from_xpm_d (GdkWindow  *window,
+GdkPixmap *gdk_pixmap_create_from_xpm_d( GdkWindow  *window,
                                          GdkBitmap **mask,
                                          GdkColor   *transparent_color,
-                                         gchar     **data);
+                                         gchar     **data );
 </verb></tscreen>
 
 Small images can be incorporated into a program as data in the XPM format.
@@ -2374,42 +2511,39 @@ static const char * xpm_data[] = {
 "                "};
 </verb></tscreen>
 
-<tscreen><verb>
-void gdk_pixmap_destroy( GdkPixmap  *pixmap );
-</verb></tscreen>
-<p>
 When we're done using a pixmap and not likely to reuse it again soon,
-it is a good idea to release the resource using gdk_pixmap_destroy.  Pixmaps
+it is a good idea to release the resource using gdk_pixmap_unref(). Pixmaps
 should be considered a precious resource.
 
-
-Once we've created a pixmap, we can display it as a GTK widget.  We must
-create a pixmap widget to contain the GDK pixmap.  This is done using
+Once we've created a pixmap, we can display it as a GTK widget. We must
+create a pixmap widget to contain the GDK pixmap. This is done using
 
 <tscreen><verb>
-GtkWidget* gtk_pixmap_new( GdkPixmap  *pixmap,
-                           GdkBitmap  *mask );
+GtkWidget *gtk_pixmap_new( GdkPixmap *pixmap,
+                           GdkBitmap *mask );
 </verb></tscreen>
-<p>
+
 The other pixmap widget calls are
 
 <tscreen><verb>
 guint gtk_pixmap_get_type( void );
+
 void  gtk_pixmap_set( GtkPixmap  *pixmap,
                       GdkPixmap  *val,
-                      GdkBitmap  *mask);
+                      GdkBitmap  *mask );
+
 void  gtk_pixmap_get( GtkPixmap  *pixmap,
                       GdkPixmap **val,
                       GdkBitmap **mask);
 </verb></tscreen>
-<p>
+
 gtk_pixmap_set is used to change the pixmap that the widget is currently
-managing.  Val is the pixmap created using GDK.
+managing. Val is the pixmap created using GDK.
 
 The following is an example of using a pixmap in a button.
 
 <tscreen><verb>
-/* pixmap.c */
+/* example-start pixmap/pixmap.c */
 
 #include <gtk/gtk.h>
 
@@ -2440,7 +2574,7 @@ static const char * xpm_data[] = {
 
 /* when invoked (via signal delete_event), terminates the application.
  */
-void close_application( GtkWidget *widget, gpointer data ) {
+void close_application( GtkWidget *widget, GdkEvent *event, gpointer data ) {
     gtk_main_quit();
 }
 
@@ -2492,9 +2626,9 @@ int main( int argc, char *argv[] )
           
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
-
 To load a file from an XPM data file called icon0.xpm in the current
 directory, we would have created the pixmap thus
 
@@ -2508,24 +2642,20 @@ directory, we would have created the pixmap thus
     gtk_container_add( GTK_CONTAINER(window), pixmapwid );
 </verb></tscreen>
 
-
-
-Using Shapes
-<p>
 A disadvantage of using pixmaps is that the displayed object is always
-rectangular, regardless of the image.  We would like to create desktops
-and applications with icons that have more natural shapes.  For example,
-for a game interface, we would like to have round buttons to push.  The
+rectangular, regardless of the image. We would like to create desktops
+and applications with icons that have more natural shapes. For example,
+for a game interface, we would like to have round buttons to push. The
 way to do this is using shaped windows.
 
 A shaped window is simply a pixmap where the background pixels are
-transparent.  This way, when the background image is multi-colored, we
+transparent. This way, when the background image is multi-colored, we
 don't overwrite it with a rectangular, non-matching border around our
-icon.  The following example displays a full wheelbarrow image on the
+icon. The following example displays a full wheelbarrow image on the
 desktop.
 
 <tscreen><verb>
-/* wheelbarrow.c */
+/* example-start wheelbarrow/wheelbarrow.c */
 
 #include <gtk/gtk.h>
 
@@ -2648,7 +2778,7 @@ static char * WheelbarrowFull_xpm[] = {
 
 /* when invoked (via signal delete_event), terminates the application.
  */
-void close_application( GtkWidget *widget, gpointer data ) {
+void close_application( GtkWidget *widget, GdkEvent *event, gpointer data ) {
     gtk_main_quit();
 }
 
@@ -2697,7 +2827,7 @@ int main (int argc, char *argv[])
     return 0;
 }
 </verb></tscreen>
-<p>
+
 To make the wheelbarrow image sensitive, we could attach the button press
 event signal to make it do something.  The following few lines would make
 the picture sensitive to a mouse button being pressed which makes the
@@ -2706,7 +2836,7 @@ application terminate.
 <tscreen><verb>
 gtk_widget_set_events( window,
                        gtk_widget_get_events( window ) |
-		       GDK_BUTTON_PRESS_MASK );
+                       GDK_BUTTON_PRESS_MASK );
 
 gtk_signal_connect( GTK_OBJECT(window), "button_press_event",
                     GTK_SIGNAL_FUNC(close_application), NULL );
@@ -2716,26 +2846,26 @@ gtk_signal_connect( GTK_OBJECT(window), "button_press_event",
 <sect1>Rulers
 <p>
 Ruler widgets are used to indicate the location of the mouse pointer
-in a given window.  A window can have a vertical ruler spanning across
+in a given window. A window can have a vertical ruler spanning across
 the width and a horizontal ruler spanning down the height.  A small
 triangular indicator on the ruler shows the exact location of the
 pointer relative to the ruler.
 
-A ruler must first be created.  Horizontal and vertical rulers are
+A ruler must first be created. Horizontal and vertical rulers are
 created using
 
 <tscreen><verb>
-GtkWidget *gtk_hruler_new(void);    /* horizontal ruler */
-GtkWidget *gtk_vruler_new(void);    /* vertical ruler   */
+GtkWidget *gtk_hruler_new( void );    /* horizontal ruler */
+GtkWidget *gtk_vruler_new( void );    /* vertical ruler   */
 </verb></tscreen>
 
-Once a ruler is created, we can define the unit of measurement.  Units
+Once a ruler is created, we can define the unit of measurement. Units
 of measure for rulers can be GTK_PIXELS, GTK_INCHES or
-GTK_CENTIMETERS.  This is set using
+GTK_CENTIMETERS. This is set using
 
 <tscreen><verb>
-void gtk_ruler_set_metric( GtkRuler        *ruler,
-                           GtkMetricType   metric );
+void gtk_ruler_set_metric( GtkRuler      *ruler,
+                           GtkMetricType  metric );
 </verb></tscreen>
 
 The default measure is GTK_PIXELS.
@@ -2745,18 +2875,18 @@ gtk_ruler_set_metric( GTK_RULER(ruler), GTK_PIXELS );
 </verb></tscreen>
 
 Other important characteristics of a ruler are how to mark the units
-of scale and where the position indicator is initially placed.  These
+of scale and where the position indicator is initially placed. These
 are set for a ruler using
 
 <tscreen><verb>
-void  gtk_ruler_set_range  (GtkRuler       *ruler,
-                            gfloat          lower,
-                            gfloat          upper,
-                            gfloat          position,
-                            gfloat          max_size);
+void gtk_ruler_set_range( GtkRuler *ruler,
+                          gfloat    lower,
+                          gfloat    upper,
+                          gfloat    position,
+                          gfloat    max_size );
 </verb></tscreen>
 
-The lower and upper arguments define the extents of the ruler, and
+The lower and upper arguments define the extent of the ruler, and
 max_size is the largest possible number that will be displayed.
 Position defines the initial position of the pointer indicator within
 the ruler.
@@ -2768,7 +2898,7 @@ gtk_ruler_set_range( GTK_RULER(vruler), 0, 800, 0, 800);
 </verb></tscreen>
 
 The markings displayed on the ruler will be from 0 to 800, with
-a number for every 100 pixels.  If instead we wanted the ruler to
+a number for every 100 pixels. If instead we wanted the ruler to
 range from 7 to 16, we would code
 
 <tscreen><verb>
@@ -2776,7 +2906,7 @@ gtk_ruler_set_range( GTK_RULER(vruler), 7, 16, 0, 20);
 </verb></tscreen>
 
 The indicator on the ruler is a small triangular mark that indicates
-the position of the pointer relative to the ruler.  If the ruler is
+the position of the pointer relative to the ruler. If the ruler is
 used to follow the mouse pointer, the motion_notify_event signal
 should be connected to the motion_notify_event method of the ruler.
 To follow all mouse movements within a window area, we would use
@@ -2791,13 +2921,13 @@ gtk_signal_connect_object( GTK_OBJECT(area), "motion_notify_event",
 
 The following example creates a drawing area with a horizontal ruler
 above it and a vertical ruler to the left of it.  The size of the
-drawing area is 600 pixels wide by 400 pixels high.  The horizontal
+drawing area is 600 pixels wide by 400 pixels high. The horizontal
 ruler spans from 7 to 13 with a mark every 100 pixels, while the
 vertical ruler spans from 0 to 400 with a mark every 100 pixels.
 Placement of the drawing area and the rulers are done using a table.
 
 <tscreen><verb>
-/* rulers.c */
+/* example-start rulers/rulers.c */
 
 #include <gtk/gtk.h>
 
@@ -2808,7 +2938,7 @@ Placement of the drawing area and the rulers are done using a table.
 
 /* this routine gets control when the close button is clicked
  */
-void close_application( GtkWidget *widget, gpointer data ) {
+void close_application( GtkWidget *widget, GdkEvent *event, gpointer data ) {
     gtk_main_quit();
 }
 
@@ -2870,57 +3000,64 @@ int main( int argc, char *argv[] ) {
 
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Statusbars
 <p>
-Statusbars are simple widgets used to display a text message. They keep a stack 
-of the messages pushed onto them, so that popping the current message 
-will re-display the previous text message.
+Statusbars are simple widgets used to display a text message. They keep
+a stack  of the messages pushed onto them, so that popping the current
+message will re-display the previous text message.
 
-In order to allow different parts of an application to use the same statusbar to display
-messages, the statusbar widget issues Context Identifiers which are used to identify
-different 'users'. The message on top of the stack is the one displayed, no matter what context
-it is in. Messages are stacked in last-in-first-out order, not context identifier order.
+In order to allow different parts of an application to use the same
+statusbar to display messages, the statusbar widget issues Context
+Identifiers which are used to identify different 'users'. The message on
+top of the stack is the one displayed, no matter what context it is in.
+Messages are stacked in last-in-first-out order, not context identifier order.
 
 A statusbar is created with a call to:
+
 <tscreen><verb>
-GtkWidget* gtk_statusbar_new (void);
+GtkWidget *gtk_statusbar_new( void );
 </verb></tscreen>
 
-A new Context Identifier is requested using a call to the following function with a short
-textual description of the context:
+A new Context Identifier is requested using a call to the following 
+function with a short textual description of the context:
+
 <tscreen><verb>
-guint gtk_statusbar_get_context_id (GtkStatusbar *statusbar,
-                                    const gchar  *context_description);
+guint gtk_statusbar_get_context_id( GtkStatusbar *statusbar,
+                                    const gchar  *context_description );
 </verb></tscreen>
 
-There are three functions that can operate on statusbars.
+There are three functions that can operate on statusbars:
+
 <tscreen><verb>
-guint       gtk_statusbar_push           (GtkStatusbar *statusbar,
-                                         guint          context_id,
-                                         gchar         *text);
+guint gtk_statusbar_push( GtkStatusbar *statusbar,
+                          guint         context_id,
+                          gchar        *text );
+
+void gtk_statusbar_pop( GtkStatusbar *statusbar)
+                        guint         context_id );
 
-void       gtk_statusbar_pop            (GtkStatusbar *statusbar)
-                                         guint         context_id);
-void       gtk_statusbar_remove         (GtkStatusbar *statusbar,
-                                         guint         context_id,
-                                         guint         message_id); 
+void gtk_statusbar_remove( GtkStatusbar *statusbar,
+                           guint         context_id,
+                           guint         message_id ); 
 </verb></tscreen>
 
 The first, gtk_statusbar_push, is used to add a new message to the statusbar. 
-It returns a Message Identifier, which can be passed later to the function gtk_statusbar_remove
-to remove the message with the given Message and Context Identifiers from the statusbar's stack.
+It returns a Message Identifier, which can be passed later to the function
+gtk_statusbar_remove to remove the message with the given Message and Context
+Identifiers from the statusbar's stack.
 
-The function gtk_statusbar_pop removes the message highest in the stack with the given
-Context Identifier.
+The function gtk_statusbar_pop removes the message highest in the stack with
+the given Context Identifier.
 
 The following example creates a statusbar and two buttons, one for pushing items
 onto the statusbar, and one for popping the last item back off.
 
 <tscreen><verb>
-/* statusbar.c */
+/* example-start statusbar/statusbar.c */
 
 #include <gtk/gtk.h>
 #include <glib.h>
@@ -2992,86 +3129,99 @@ int main (int argc, char *argv[])
 
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Text Entries
 <p>
-The Entry widget allows text to be typed and displayed in a single line text box. 
-The text may be set with functions calls that allow new text to replace, 
-prepend or append the current contents of the Entry widget.
+The Entry widget allows text to be typed and displayed in a single line
+text box. The text may be set with function calls that allow new text
+to replace, prepend or append the current contents of the Entry widget.
 
 There are two functions for creating Entry widgets:
+
 <tscreen><verb>
-GtkWidget* gtk_entry_new (void);
+GtkWidget *gtk_entry_new( void );
 
-GtkWidget* gtk_entry_new_with_max_length (guint16 max);
+GtkWidget *gtk_entry_new_with_max_length( guint16 max );
 </verb></tscreen>
 
-The first just creates a new Entry widget, whilst the second creates a new Entry and 
-sets a limit on the length of the text within the Entry..
+The first just creates a new Entry widget, whilst the second creates a
+new Entry and sets a limit on the length of the text within the Entry.
+
+There are several functions for altering the text which is currently
+within the Entry widget.
 
-There are several functions for altering the text which is currently within the Entry widget.
 <tscreen><verb>
-void gtk_entry_set_text       (GtkEntry    *entry,
-                               const gchar *text);
-void gtk_entry_append_text    (GtkEntry    *entry,
-                               const gchar *text);
-void gtk_entry_prepend_text   (GtkEntry    *entry,
-                               const gchar *text);
+void gtk_entry_set_text( GtkEntry    *entry,
+                         const gchar *text );
+
+void gtk_entry_append_text( GtkEntry    *entry,
+                            const gchar *text );
+
+void gtk_entry_prepend_text( GtkEntry    *entry,
+                             const gchar *text );
 </verb></tscreen>
 
-The function gtk_entry_set_text sets the contents of the Entry widget, replacing the
-current contents. The functions gtk_entry_append_text and gtk_entry_prepend_text allow
-the current contents to be appended and prepended to.
+The function gtk_entry_set_text sets the contents of the Entry widget,
+replacing the current contents. The functions gtk_entry_append_text and
+gtk_entry_prepend_text allow the current contents to be appended and
+prepended to.
 
 The next function allows the current insertion point to be set.
+
 <tscreen><verb>
-void gtk_entry_set_position   (GtkEntry *entry,
-                               gint     position);
+void gtk_entry_set_position( GtkEntry *entry,
+                             gint      position );
 </verb></tscreen>
 
-The contents of the Entry can be retrieved by using a call to the following function. This
-is useful in the callback functions described below.
+The contents of the Entry can be retrieved by using a call to the
+following function. This is useful in the callback functions described below.
+
 <tscreen><verb>
-gchar* gtk_entry_get_text (GtkEntry *entry);
+gchar *gtk_entry_get_text( GtkEntry *entry );
 </verb></tscreen>
 
-If we don't want the contents of the Entry to be changed by someone typing into it, we
-can change it's edittable state.
+If we don't want the contents of the Entry to be changed by someone typing
+into it, we can change it's editable state.
+
 <tscreen><verb>
-void gtk_entry_set_editable (GtkEntry *entry,
-                             gboolean editable);
+void gtk_entry_set_editable( GtkEntry *entry,
+                             gboolean  editable );
 </verb></tscreen>
 
-This function allows us to toggle the edittable state of the Entry widget by passing in
-TRUE or FALSE values for the editable argument.
+This function allows us to toggle the edittable state of the Entry widget 
+by passing in a TRUE or FALSE value for the <tt/editable/ argument.
+
+If we are using the Entry where we don't want the text entered to be visible,
+for example when a password is being entered, we can use the following
+function, which also takes a boolean flag.
 
-If we are using the Entry where we don't want the text entered to be visible, for
-example when a password is being entered, we can use the following function, which
-also takes a boolean flag.
 <tscreen><verb>
-void gtk_entry_set_visibility (GtkEntry *entry,
-                               gboolean visible);
+void gtk_entry_set_visibility( GtkEntry *entry,
+                               gboolean  visible );
 </verb></tscreen>
 
-A region of the text may be set as selected by using the following function. This would
-most often be used after setting some default text in an Entry, making it easy for the user
-to remove it.
+A region of the text may be set as selected by using the following 
+function. This would most often be used after setting some default text 
+in an Entry, making it easy for the user to remove it.
+
 <tscreen><verb>
-void gtk_entry_select_region (GtkEntry *entry,
-                              gint     start,
-                              gint     end);
+void gtk_entry_select_region( GtkEntry *entry,
+                              gint      start,
+                              gint      end );
 </verb></tscreen>
 
 If we want to catch when the user has entered text, we can connect to the
 <tt/activate/ or <tt/changed/ signal. Activate is raised when the user hits 
-the enter key within the Entry widget. Changed is raised when the text changes at all, 
-e.g. for every character entered or removed.
+the enter key within the Entry widget. Changed is raised when the text
+changes at all, e.g. for every character entered or removed.
 
 The following code is an example of using an Entry widget.
+
 <tscreen><verb>
-/* entry.c */
+/* example-start entry/entry.c */
 
 #include <gtk/gtk.h>
 
@@ -3161,80 +3311,90 @@ int main (int argc, char *argv[])
     gtk_main();
     return(0);
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Color Selection
-<P>
+<p>
 The color selection widget is, not surprisingly, a widget for interactive
-selection of colors. This composite widget lets the user select a color by manipulating
-RGB (Red, Green, Blue) and HSV (Hue, Saturation, Value) triples. This is done
-either by adjusting single values with sliders or entries, or by picking the desired
-color from a hue-saturation wheel/value bar. Optionally, the opacity of the color can also
-be set.
+selection of colors. This composite widget lets the user select a color by
+manipulating RGB (Red, Green, Blue) and HSV (Hue, Saturation, Value) triples.
+This is done either by adjusting single values with sliders or entries, or
+by picking the desired color from a hue-saturation wheel/value bar.
+Optionally, the opacity of the color can also be set.
 
-The color selection widget currently emits only one signal, "color_changed", which is emitted
-whenever the current color in the widget changes, either when the user changes it or if
-it's set explicitly through gtk_color_selection_set_color().
+The color selection widget currently emits only one signal,
+"color_changed", which is emitted whenever the current color in the widget
+changes, either when the user changes it or if it's set explicitly through
+gtk_color_selection_set_color().
 
-Lets have a look at what the color selection widget has to offer us. The widget comes
-in two flavours; gtk_color_selection and gtk_color_selection_dialog:
+Lets have a look at what the color selection widget has to offer us. The
+widget comes in two flavours; gtk_color_selection and
+gtk_color_selection_dialog:
 
 <tscreen><verb>
-GtkWidget *gtk_color_selection_new(void);
+GtkWidget *gtk_color_selection_new( void );
 </verb></tscreen>
 	
 You'll probably not be using this constructor directly. It creates an orphan
-GtkColorSelection widget which you'll have to parent yourself. The GtkColorSelection widget
-inherits from the GtkVBox widget.
+GtkColorSelection widget which you'll have to parent yourself. The
+GtkColorSelection widget inherits from the GtkVBox widget.
 
 <tscreen><verb> 
-GtkWidget *gtk_color_selection_dialog_new(const gchar *title);
+GtkWidget *gtk_color_selection_dialog_new( const gchar *title );
 </verb></tscreen>
 
-This is the most common color selection constructor. It creates a GtkColorSelectionDialog, which
-inherits from a GtkDialog. It consists of a GtkFrame containing a GtkColorSelection widget, a
-GtkHSeparator and a GtkHBox with three buttons, "Ok", "Cancel" and "Help". You can reach these
-buttons by accessing the "ok_button", "cancel_button" and "help_button" widgets in the
-GtkColorSelectionDialog structure, (i.e. GTK_COLOR_SELECTION_DIALOG(colorseldialog)->ok_button).
+This is the most common color selection constructor. It creates a 
+GtkColorSelectionDialog, which inherits from a GtkDialog. It consists
+of a GtkFrame containing a GtkColorSelection widget, a GtkHSeparator and a
+GtkHBox with three buttons, "Ok", "Cancel" and "Help". You can reach these
+buttons by accessing the "ok_button", "cancel_button" and "help_button"
+widgets in the GtkColorSelectionDialog structure, 
+(i.e. GTK_COLOR_SELECTION_DIALOG(colorseldialog)->ok_button).
 
 <tscreen><verb>
-void gtk_color_selection_set_update_policy(GtkColorSelection *colorsel, 
-                                           GtkUpdateType policy);
+void gtk_color_selection_set_update_policy( GtkColorSelection *colorsel, 
+                                            GtkUpdateType      policy );
 </verb></tscreen>
 
-This function sets the update policy. The default policy is GTK_UPDATE_CONTINOUS which means that
-the current color is updated continously when the user drags the sliders or presses the mouse and drags
-in the hue-saturation wheel or value bar. If you experience performance problems, you may
-want to set the policy to GTK_UPDATE_DISCONTINOUS or GTK_UPDATE_DELAYED.
+This function sets the update policy. The default policy is
+GTK_UPDATE_CONTINOUS which means that the current color is updated 
+continously when the user drags the sliders or presses the mouse and drags
+in the hue-saturation wheel or value bar. If you experience performance
+problems, you may want to set the policy to GTK_UPDATE_DISCONTINOUS or 
+GTK_UPDATE_DELAYED.
 
 <tscreen><verb>
-void gtk_color_selection_set_opacity(GtkColorSelection *colorsel,
-                                     gint use_opacity);
+void gtk_color_selection_set_opacity( GtkColorSelection *colorsel,
+                                      gint               use_opacity );
 </verb></tscreen>
 
-The color selection widget supports adjusting the opacity of a color (also known as the alpha channel).
-This is disabled by default. Calling this function with use_opacity set to TRUE enables opacity.
-Likewise, use_opacity set to FALSE will disable opacity.
+The color selection widget supports adjusting the opacity of a color
+(also known as the alpha channel). This is disabled by default. Calling
+this function with use_opacity set to TRUE enables opacity. Likewise,
+use_opacity set to FALSE will disable opacity.
 
 <tscreen><verb>
-void gtk_color_selection_set_color(GtkColorSelection *colorsel,
-                                   gdouble *color);
+void gtk_color_selection_set_color( GtkColorSelection *colorsel,
+                                    gdouble           *color );
 </verb></tscreen>
 
-You can set the current color explicitly by calling this function with a pointer to an array
-of colors (gdouble). The length of the array depends on whether opacity is enabled or not.
-Position 0 contains the red component, 1 is green, 2 is blue and opacity is at position 3 (only if
-opacity is enabled, see gtk_color_selection_set_opacity()). All values are between 0.0 and 1.0.
+You can set the current color explicitly by calling this function with
+a pointer to an array of colors (gdouble). The length of the array depends
+on whether opacity is enabled or not. Position 0 contains the red component,
+1 is green, 2 is blue and opacity is at position 3 (only if opacity is enabled,
+see gtk_color_selection_set_opacity()). All values are between 0.0 and 1.0.
 
 <tscreen><verb>
-void gtk_color_selection_get_color(GtkColorSelection *colorsel,
-                                   gdouble *color);
+void gtk_color_selection_get_color( GtkColorSelection *colorsel,
+                                    gdouble           *color );
 </verb></tscreen>
 
-When you need to query the current color, typically when you've received a "color_changed" signal,
-you use this function. Color is a pointer to the array of colors to fill in. See the
-gtk_color_selection_set_color() function for the description of this array.
+When you need to query the current color, typically when you've received a
+"color_changed" signal, you use this function. Color is a pointer to the
+array of colors to fill in. See the gtk_color_selection_set_color() function
+for the description of this array.
 
 <!-- Need to do a whole section on DnD - TRG
 Drag and drop
@@ -3247,11 +3407,14 @@ on) or 1.0 (opacity off) followed by the red, green and blue values at positions
 If opacity is enabled, the opacity is passed in the value at position 4.
 -->
 
-Here's a simple example demonstrating the use of the GtkColorSelectionDialog. The program displays a window
-containing a drawing area. Clicking on it opens a color selection dialog, and changing the color in the
-color selection dialog changes the background color.
+Here's a simple example demonstrating the use of the GtkColorSelectionDialog.
+The program displays a window containing a drawing area. Clicking on it opens
+a color selection dialog, and changing the color in the color selection dialog
+changes the background color.
 
 <tscreen><verb>
+/* example-start colorsel/colorsel.c */
+
 #include <glib.h>
 #include <gdk/gdk.h>
 #include <gtk/gtk.h>
@@ -3387,7 +3550,9 @@ gint main (gint argc, gchar *argv[])
 
   return 0;
 }
+/* example-end */
 </verb></tscreen>
+
 <!-- ----------------------------------------------------------------- -->
 <sect1> File Selections
 <p>
@@ -3398,21 +3563,22 @@ to cut down on programming time.
 To create a new file selection box use:
 
 <tscreen><verb>
-GtkWidget* gtk_file_selection_new (gchar *title);
+GtkWidget *gtk_file_selection_new( gchar *title );
 </verb></tscreen>
 
 To set the filename, for example to bring up a specific directory, or
 give a default filename, use this function: 
 
 <tscreen><verb>
-void gtk_file_selection_set_filename (GtkFileSelection *filesel, gchar *filename);
+void gtk_file_selection_set_filename( GtkFileSelection *filesel,
+                                      gchar            *filename );
 </verb></tscreen>
 
 To grab the text that the user has entered or clicked on, use this 
 function:
 
 <tscreen><verb>
-gchar* gtk_file_selection_get_filename (GtkFileSelection *filesel);
+gchar *gtk_file_selection_get_filename( GtkFileSelection *filesel );
 </verb></tscreen>
 
 There are also pointers to the widgets contained within the file 
@@ -3434,11 +3600,11 @@ help_button pointers in signaling their use.
 
 Included here is an example stolen from testgtk.c, modified to run
 on it's own.  As you will see, there is nothing much to creating a file 
-selection widget.  While, in this example, the Help button appears on the 
+selection widget.  While in this example the Help button appears on the 
 screen, it does nothing as there is not a signal attached to it. 
 
 <tscreen><verb>
-/* filesel.c */
+/* example-start filesel/filesel.c */
 
 #include <gtk/gtk.h>
 
@@ -3482,6 +3648,7 @@ int main (int argc, char *argv[])
     gtk_main ();
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ***************************************************************** -->
@@ -3500,21 +3667,22 @@ The first function call you will need to know, as you can probably
 guess by now, is used to create a new notebook widget.
 
 <tscreen><verb>
-GtkWidget* gtk_notebook_new (void);
+GtkWidget *gtk_notebook_new( void );
 </verb></tscreen>
 
 Once the notebook has been created, there are 12 functions that 
-operate on the notebook widget.  Let's look at them individually.
+operate on the notebook widget. Let's look at them individually.
 
 The first one we will look at is how to position the page indicators.
 These page indicators or 'tabs' as they are referred to, can be positioned
-in four ways; top, bottom, left, or right.
+in four ways: top, bottom, left, or right.
 
 <tscreen><verb>
-void gtk_notebook_set_tab_pos (GtkNotebook *notebook, GtkPositionType pos);
+void gtk_notebook_set_tab_pos( GtkNotebook     *notebook,
+                               GtkPositionType  pos );
 </verb></tscreen>
 
-GtkPostionType will be one of the following, and they are pretty self explanatory.
+GtkPostionType will be one of the following, and they are pretty self explanatory:
 <itemize>
 <item> GTK_POS_LEFT
 <item> GTK_POS_RIGHT
@@ -3524,89 +3692,102 @@ GtkPostionType will be one of the following, and they are pretty self explanator
 
 GTK_POS_TOP is the default.
 
-Next we will look at how to add pages to the notebook.  There are three
+Next we will look at how to add pages to the notebook. There are three
 ways to add pages to the NoteBook.  Let's look at the first two together as 
 they are quite similar.
 
 <tscreen><verb>
-void gtk_notebook_append_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label);
+void gtk_notebook_append_page( GtkNotebook *notebook,
+                               GtkWidget   *child,
+                               GtkWidget   *tab_label );
 
-void gtk_notebook_prepend_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label);
+void gtk_notebook_prepend_page( GtkNotebook *notebook,
+                                GtkWidget   *child,
+                                GtkWidget   *tab_label );
 </verb></tscreen>
 
 These functions add pages to the notebook by inserting them from the 
 back of the notebook (append), or the front of the notebook (prepend).  
-*child is the widget that is placed within the notebook page, and *tab_label is
-the label for the page being added.
+<tt/child/ is the widget that is placed within the notebook page, and
+<tt/tab_label/ is the label for the page being added.
 
 The final function for adding a page to the notebook contains all of 
 the properties of the previous two, but it allows you to specify what position
 you want the page to be in the notebook.
 
 <tscreen><verb>
-void gtk_notebook_insert_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label, gint position);
+void gtk_notebook_insert_page( GtkNotebook *notebook,
+                               GtkWidget   *child,
+                               GtkWidget   *tab_label,
+                               gint         position );
 </verb></tscreen>
 
 The parameters are the same as _append_ and _prepend_ except it 
-contains an extra parameter, position.  This parameter is used to specify what
-place this page will inserted to.
+contains an extra parameter, <tt/position/.  This parameter is used to
+specify what place this page will be inserted into.
 
 Now that we know how to add a page, lets see how we can remove a page 
 from the notebook.
 
 <tscreen><verb>
-void gtk_notebook_remove_page (GtkNotebook *notebook, gint page_num);
+void gtk_notebook_remove_page( GtkNotebook *notebook,
+                               gint         page_num );
 </verb></tscreen>
 
 This function takes the page specified by page_num and removes it from 
-the widget *notebook.
+the widget pointed to by <tt/notebook/.
 
 To find out what the current page is in a notebook use the function:
 
 <tscreen><verb>
-gint gtk_notebook_current_page (GtkNotebook *notebook);
+gint gtk_notebook_current_page( GtkNotebook *notebook );
 </verb></tscreen>
 
 These next two functions are simple calls to move the notebook page 
-forward or backward.  Simply provide the respective function call with the
-notebook widget you wish to operate on.  Note:  When the NoteBook is currently
+forward or backward. Simply provide the respective function call with the
+notebook widget you wish to operate on.  Note: when the NoteBook is currently
 on the last page, and gtk_notebook_next_page is called, the notebook will 
-wrap back to the first page.  Likewise, if the NoteBook is on the first page, 
+wrap back to the first page. Likewise, if the NoteBook is on the first page, 
 and gtk_notebook_prev_page is called, the notebook will wrap to the last page.
 
 <tscreen><verb>
-void gtk_notebook_next_page (GtkNoteBook *notebook);
-void gtk_notebook_prev_page (GtkNoteBook *notebook);
+void gtk_notebook_next_page( GtkNoteBook *notebook );
+
+void gtk_notebook_prev_page( GtkNoteBook *notebook );
 </verb></tscreen>
 
-This next function sets the 'active' page.  If you wish the
+This next function sets the 'active' page. If you wish the
 notebook to be opened to page 5 for example, you would use this function.  
 Without using this function, the notebook defaults to the first page.
 
 <tscreen><verb>
-void gtk_notebook_set_page (GtkNotebook *notebook, gint page_num);
+void gtk_notebook_set_page( GtkNotebook *notebook,
+                            gint         page_num );
 </verb></tscreen>
 
 The next two functions add or remove the notebook page tabs and the 
 notebook border respectively.
 
 <tscreen><verb>
-void gtk_notebook_set_show_tabs (GtkNotebook *notebook, gint show_tabs);
-void gtk_notebook_set_show_border (GtkNotebook *notebook, gint show_border);
+void gtk_notebook_set_show_tabs( GtkNotebook *notebook,
+                                 gint         show_tabs);
+
+void gtk_notebook_set_show_border( GtkNotebook *notebook,
+                                   gint         show_border );
 </verb></tscreen>
 
-show_tabs and show_border can both be either TRUE or FALSE (0 or 1).
+show_tabs and show_border can be either TRUE or FALSE.
 
 Now lets look at an example, it is expanded from the testgtk.c code 
 that comes with the GTK distribution, and it shows all 13 functions. This 
-small program, creates a window with a notebook and six buttons.  The notebook 
+small program creates a window with a notebook and six buttons. The notebook 
 contains 11 pages, added in three different ways, appended, inserted, and 
-prepended.  The buttons allow you rotate the tab positions, add/remove the tabs
+prepended. The buttons allow you rotate the tab positions, add/remove the tabs
 and border, remove a page, change pages in both a forward and backward manner,
 and exit the program. 
 
 <tscreen><verb>
-/* notebook.c */
+/* example-start notebooknotebook.c */
 
 #include <gtk/gtk.h>
 
@@ -3642,7 +3823,7 @@ void remove_book (GtkButton *button, GtkNotebook *notebook)
     gtk_widget_draw(GTK_WIDGET(notebook), NULL);
 }
 
-void delete (GtkWidget *widget, gpointer data)
+void delete (GtkWidget *widget, GtkWidget *event, gpointer data)
 {
     gtk_main_quit ();
 }
@@ -3778,39 +3959,40 @@ int main (int argc, char *argv[])
     
     return 0;
 }
+/* example-end */
 </verb></tscreen>
-<p>
+
 Hopefully this helps you on your way with creating notebooks for your
 GTK applications.
 
 <!-- ----------------------------------------------------------------- -->
-<sect1> Scrolled Windows
+<sect1>Scrolled Windows
 <p>
 Scrolled windows are used to create a scrollable area inside a real window.  
-You may insert any types of widgets to these scrolled windows, and they will
-all be accessable regardless of the size by using the scrollbars.
+You may insert any type of widget into a scrolled window, and it will
+be accessable regardless of the size by using the scrollbars.
 
 The following function is used to create a new scolled window.
 
 <tscreen><verb>
-GtkWidget* gtk_scrolled_window_new (GtkAdjustment *hadjustment,
-                                    GtkAdjustment *vadjustment);
+GtkWidget *gtk_scrolled_window_new( GtkAdjustment *hadjustment,
+                                    GtkAdjustment *vadjustment );
 </verb></tscreen>
-<p>
+
 Where the first argument is the adjustment for the horizontal
 direction, and the second, the adjustment for the vertical direction.
 These are almost always set to NULL.
 
 <tscreen><verb>
-void gtk_scrolled_window_set_policy (GtkScrolledWindow *scrolled_window,
+void gtk_scrolled_window_set_policy( GtkScrolledWindow *scrolled_window,
                                      GtkPolicyType      hscrollbar_policy,
-				     GtkPolicyType      vscrollbar_policy);
+                                     GtkPolicyType      vscrollbar_policy );
 </verb></tscreen>
 
 This sets the policy to be used with respect to the scrollbars.
 The first arguement is the scrolled window you wish to change. The second
-sets the policiy for the horizontal scrollbar, and the third, 
-the vertical scrollbar.  
+sets the policiy for the horizontal scrollbar, and the third the policy for 
+the vertical scrollbar.
 
 The policy may be one of GTK_POLICY AUTOMATIC, or GTK_POLICY_ALWAYS.
 GTK_POLICY_AUTOMATIC will automatically decide whether you need
@@ -3821,7 +4003,7 @@ Here is a simple example that packs 100 toggle buttons into a scrolled window.
 I've only commented on the parts that may be new to you.
 
 <tscreen><verb>
-/* scrolledwin.c */
+/* example-start scrolledwin/scrolledwin.c */
 
 #include <gtk/gtk.h>
 
@@ -3913,11 +4095,12 @@ int main (int argc, char *argv[])
     
     return(0);
 }
+/* example-end */
 </verb></tscreen>
-<p>
-Try playing with resizing the window.  You'll notice how the scrollbars
-react.  You may also wish to use the gtk_widget_set_usize() call to set the default
-size of the window or other widgets.
+
+Try playing with resizing the window. You'll notice how the scrollbars
+react. You may also wish to use the gtk_widget_set_usize() call to set
+the default size of the window or other widgets.
 
 <!-- ----------------------------------------------------------------- -->   
 <sect1> Paned Window Widgets
@@ -3931,16 +4114,18 @@ be horizontal (HPaned) or vertical (VPaned).
 To create a new paned window, call one of:
    
 <tscreen><verb>
-GtkWidget* gtk_hpaned_new (void)
-GtkWidget* gtk_vpaned_new (void)
+GtkWidget *gtk_hpaned_new (void);
+
+GtkWidget *gtk_vpaned_new (void);
 </verb></tscreen>
 
 After creating the paned window widget, you need to add child widgets
 to its two halves. To do this, use the functions:
    
 <tscreen><verb>
-void gtk_paned_add1 (GtkPaned *paned, GtkWidget *child)
-void gtk_paned_add2 (GtkPaned *paned, GtkWidget *child)
+void gtk_paned_add1 (GtkPaned *paned, GtkWidget *child);
+
+void gtk_paned_add2 (GtkPaned *paned, GtkWidget *child);
 </verb></tscreen>
    
 <tt/gtk_paned_add1()/ adds the child widget to the left or top half of
@@ -3951,7 +4136,7 @@ As an example, we will create part of the user interface of an
 imaginary email program. A window is divided into two portions
 vertically, with the top portion being a list of email messages and
 the bottom portion the text of the email message. Most of the program
-is pretty straightforward. A couple of points to note are: Text can't
+is pretty straightforward. A couple of points to note: text can't
 be added to a Text widget until it is realized. This could be done by
 calling <tt/gtk_widget_realize()/, but as a demonstration of an alternate
 technique, we connect a handler to the "realize" signal to add the
@@ -3961,7 +4146,7 @@ that when the bottom portion is made smaller, the correct portions
 shrink instead of being pushed off the bottom of the window.
 
 <tscreen><verb>
-/* paned.c */
+/* example-start paned/paned.c */
 
 #include <gtk/gtk.h>
    
@@ -4097,7 +4282,7 @@ main (int argc, char *argv[])
     gtk_main ();
     return 0;
 }
-
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->   
@@ -4111,14 +4296,14 @@ preview a larger image. The size of the preview should vary when
 the user resizes the window, but the aspect ratio needs to always match
 the original image.
    
-To create a new aspect frame, use:
+To create a new aspect frame use:
    
 <tscreen><verb>
-GtkWidget* gtk_aspect_frame_new	 (const gchar *label,
-   					gfloat xalign,
-   					gfloat yalign,
-   					gfloat ratio,
-   					gint obey_child)
+GtkWidget *gtk_aspect_frame_new( const gchar *label,
+                                 gfloat       xalign,
+                                 gfloat       yalign,
+                                 gfloat       ratio,
+                                 gint         obey_child);
 </verb></tscreen>
    
 <tt/xalign/ and <tt/yalign/ specifiy alignment as with Alignment
@@ -4129,20 +4314,19 @@ Otherwise, it is given by <tt/ratio/.
 To change the options of an existing aspect frame, you can use:
    
 <tscreen><verb>
-void gtk_aspect_frame_set (GtkAspectFrame *aspect_frame,
-			   gfloat xalign,
-			   gfloat yalign,
-			   gfloat ratio,
-			   gint obey_child)
+void gtk_aspect_frame_set( GtkAspectFrame *aspect_frame,
+                           gfloat          xalign,
+                           gfloat          yalign,
+                           gfloat          ratio,
+                           gint            obey_child);
 </verb></tscreen>
    
-<p>
 As an example, the following program uses an AspectFrame to
 present a drawing area whose aspect ratio will always be 2:1, no
 matter how the user resizes the top-level window.
    
 <tscreen><verb>
-/* aspectframe.c */
+/* example-start aspectframe/aspectframe.c */
 
 #include <gtk/gtk.h>
    
@@ -4157,7 +4341,7 @@ main (int argc, char *argv[])
     window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
     gtk_window_set_title (GTK_WINDOW (window), "Aspect Frame");
     gtk_signal_connect (GTK_OBJECT (window), "destroy",
-    GTK_SIGNAL_FUNC (gtk_main_quit), NULL);
+                        GTK_SIGNAL_FUNC (gtk_main_quit), NULL);
     gtk_container_border_width (GTK_CONTAINER (window), 10);
    
     /* Create an aspect_frame and add it to our toplevel window */
@@ -4184,14 +4368,16 @@ main (int argc, char *argv[])
     gtk_widget_show (window);
     gtk_main ();
     return 0;
-}  
+}
+/* example-end */
 </verb></tscreen>
                               
 <!-- ***************************************************************** -->
 <sect> List Widgets
 <!-- ***************************************************************** -->
-
 <p>
+NOTE: The GtkList widget has been superseded by the GtkCList widget.
+
 The GtkList widget is designed to act as a vertical container for widgets
 that should be of the type GtkListItem.
 
@@ -4201,7 +4387,7 @@ GtkContainer it can be treated as such by using the GTK_CONTAINER(List)
 macro, see the GtkContainer widget for more on this.
 One should already be familar whith the usage of a GList and its
 related functions g_list_*() to be able to use the GtkList widget to
-its fully extends.
+it full extent.
 
 There is one field inside the structure definition of the GtkList widget
 that will be of greater interest to us, this is:
@@ -4217,53 +4403,53 @@ struct _GtkList
 </verb></tscreen>
 
 The selection field of a GtkList points to a linked list of all items
-that are cureently selected, or `NULL' if the selection is empty.
+that are curently selected, or NULL if the selection is empty.
 So to learn about the current selection we read the GTK_LIST()->selection
 field, but do not modify it since the internal fields are maintained by
 the gtk_list_*() functions.
 
 The selection_mode of the GtkList determines the selection facilities
 of a GtkList and therefore the contents of the GTK_LIST()->selection
-field:
+field. The selection_mode may be one of the following:
 
-The selection_mode may be one of the following:
 <itemize>
-<item> GTK_SELECTION_SINGLE -   The selection is either `NULL'
-                        or contains a GList* pointer
+<item> GTK_SELECTION_SINGLE - The selection is either NULL
+                        or contains a GList pointer
                         for a single selected item.
 
-<item> GTK_SELECTION_BROWSE -  The selection is `NULL' if the list
+<item> GTK_SELECTION_BROWSE -  The selection is NULL if the list
                         contains no widgets or insensitive
                         ones only, otherwise it contains
                         a GList pointer for one GList
                         structure, and therefore exactly
                         one list item.
 
-<item> GTK_SELECTION_MULTIPLE -  The selection is `NULL' if no list
+<item> GTK_SELECTION_MULTIPLE -  The selection is NULL if no list
                         items are selected or a GList pointer
                         for the first selected item. That
                         in turn points to a GList structure
                         for the second selected item and so
                         on.
 
-<item> GTK_SELECTION_EXTENDED - The selection is always `NULL'.
+<item> GTK_SELECTION_EXTENDED - The selection is always NULL.
 </itemize>
-<p>
+
 The default is GTK_SELECTION_MULTIPLE.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Signals
 <p>
 <tscreen><verb>
-void selection_changed (GtkList *LIST)
+void selection_changed( GtkList *list );
 </verb></tscreen>
 
-This signal will be invoked whenever a the selection field
+This signal will be invoked whenever the selection field
 of a GtkList has changed. This happens when a child of
-the GtkList got selected or unselected.
+the GtkList got selected or deselected.
 
 <tscreen><verb>
-void select_child (GtkList *LIST, GtkWidget *CHILD)
+void select_child( GtkList   *list,
+                   GtkWidget *child);
 </verb></tscreen>
 
 This signal is invoked when a child of the GtkList is about
@@ -4273,11 +4459,12 @@ and sometimes indirectly triggered on some else occasions where
 children get added to or removed from the GtkList.
 
 <tscreen><verb>
-void unselect_child (GtkList *LIST, GtkWidget *CHILD)
+void unselect_child( GtkList   *list,
+                     GtkWidget *child );
 </verb></tscreen>
 
 This signal is invoked when a child of the GtkList is about
-to get unselected. This happens mainly on calls to
+to get deselected. This happens mainly on calls to
 gtk_list_unselect_item(), gtk_list_unselect_child(), button presses
 and sometimes indirectly triggered on some else occasions where
 children get added to or removed from the GtkList.
@@ -4286,116 +4473,128 @@ children get added to or removed from the GtkList.
 <sect1> Functions
 <p>
 <tscreen><verb>
-guint gtk_list_get_type (void)
+guint gtk_list_get_type( void );
 </verb></tscreen>
 
 Returns the `GtkList' type identifier.
 
 <tscreen><verb>
-GtkWidget* gtk_list_new (void)
+GtkWidget *gtk_list_new( void );
 </verb></tscreen>
 
-Create a new `GtkList' object. The new widget is
-returned as a pointer to a `GtkWidget' object.
-`NULL' is returned on failure.
+Create a new GtkList object. The new widget is returned as a pointer to a
+GtkWidget object. NULL is returned on failure.
 
 <tscreen><verb>
-void gtk_list_insert_items (GtkList *LIST, GList *ITEMS, gint POSITION)
+void gtk_list_insert_items( GtkList *list,
+                            GList   *items,
+                            gint     position );
 </verb></tscreen>
 
-Insert list items into the LIST, starting at POSITION.
-ITEMS is a doubly linked list where each nodes data
+Insert list items into the list, starting at <tt/position/.
+<tt/items/ is a doubly linked list where each nodes data
 pointer is expected to point to a newly created GtkListItem.
-The GList nodes of ITEMS are taken over by the LIST.
+The GList nodes of <tt/items/ are taken over by the list.
 
 <tscreen><verb>
-void gtk_list_append_items (GtkList *LIST, GList *ITEMS)
+void gtk_list_append_items( GtkList *list,
+                            GList   *items);
 </verb></tscreen>
 
 Insert list items just like gtk_list_insert_items() at the end
-of the LIST. The GList nodes of ITEMS are taken over by the LIST.
+of the list. The GList nodes of <tt/items/ are taken over by the list.
 
 <tscreen><verb>
-void gtk_list_prepend_items (GtkList *LIST, GList *ITEMS)
+void gtk_list_prepend_items( GtkList *list,
+                             GList   *items);
 </verb></tscreen>
 
 Insert list items just like gtk_list_insert_items() at the very
-beginning of the LIST. The GList nodes of ITEMS are taken over
-by the LIST.
+beginning of the list. The GList nodes of <tt/items/ are taken over
+by the list.
 
 <tscreen><verb>
-void gtk_list_remove_items (GtkList *LIST, GList *ITEMS)
+void gtk_list_remove_items( GtkList *list,
+                            GList   *items);
 </verb></tscreen>
 
-Remove list items from the LIST. ITEMS is a doubly linked
+Remove list items from the list. <tt/items/ is a doubly linked
 list where each nodes data pointer is expected to point to a
-direct child of LIST. It is the callers responsibility to make a
-call to g_list_free(ITEMS) afterwards. Also the caller has to
+direct child of list. It is the callers responsibility to make a
+call to g_list_free(items) afterwards. Also the caller has to
 destroy the list items himself.
 
 <tscreen><verb>
-void gtk_list_clear_items (GtkList *LIST, gint START, gint END)
+void gtk_list_clear_items( GtkList *list,
+                           gint start,
+                           gint end );
 </verb></tscreen>
 
-Remove and destroy list items from the LIST. a widget is affected if
-its current position within LIST is in the range specified by START
-and END.
+Remove and destroy list items from the list. A widget is affected if
+its current position within the list is in the range specified by
+<tt/start/ and <tt/end/.
 
 <tscreen><verb>
-void gtk_list_select_item (GtkList *LIST, gint ITEM)
+void gtk_list_select_item( GtkList *list,
+                           gint     item );
 </verb></tscreen>
 
 Invoke the select_child signal for a list item
-specified through its current position within LIST.
+specified through its current position within the list.
 
 <tscreen><verb>
-void gtk_list_unselect_item (GtkList *LIST, gint ITEM)
+void gtk_list_unselect_item( GtkList *list,
+                             gint     item);
 </verb></tscreen>
 
 Invoke the unselect_child signal for a list item
-specified through its current position within LIST.
+specified through its current position within the list.
 
 <tscreen><verb>
-void gtk_list_select_child (GtkList *LIST, GtkWidget *CHILD)
+void gtk_list_select_child( GtkList *list,
+                            GtkWidget *child);
 </verb></tscreen>
 
-Invoke the select_child signal for the specified CHILD.
+Invoke the select_child signal for the specified child.
 
 <tscreen><verb>
-void gtk_list_unselect_child (GtkList *LIST, GtkWidget *CHILD)
+void gtk_list_unselect_child( GtkList   *list,
+                              GtkWidget *child);
 </verb></tscreen>
 
-Invoke the unselect_child signal for the specified CHILD.
+Invoke the unselect_child signal for the specified child.
 
 <tscreen><verb>
-gint gtk_list_child_position (GtkList *LIST, GtkWidget *CHILD)
+gint gtk_list_child_position( GtkList *list,
+                              GtkWidget *child);
 </verb></tscreen>
 
-Return the position of CHILD within LIST. `-1' is returned on failure.
+Return the position of <tt/child/ within the list. "-1" is returned on failure.
 
 <tscreen><verb>
-void gtk_list_set_selection_mode (GtkList *LIST, GtkSelectionMode MODE)
+void gtk_list_set_selection_mode( GtkList         *list,
+                                  GtkSelectionMode mode );
 </verb></tscreen>
 
-Set LIST to the selection mode MODE wich can be of GTK_SELECTION_SINGLE,
+Set the selection mode MODE which can be of GTK_SELECTION_SINGLE,
 GTK_SELECTION_BROWSE, GTK_SELECTION_MULTIPLE or GTK_SELECTION_EXTENDED.
 
 <tscreen><verb>
-GtkList* GTK_LIST (gpointer OBJ)
+GtkList *GTK_LIST( gpointer obj );
 </verb></tscreen>
 
-Cast a generic pointer to `GtkList*'. *Note Standard Macros::, for
+Cast a generic pointer to `GtkList *'. *Note Standard Macros::, for
 more info.
 
 <tscreen><verb>
-GtkListClass* GTK_LIST_CLASS (gpointer CLASS)
+GtkListClass *GTK_LIST_CLASS( gpointer class);
 </verb></tscreen>
 
 Cast a generic pointer to `GtkListClass*'. *Note Standard Macros::,
 for more info.
 
 <tscreen><verb>
-gint GTK_IS_LIST (gpointer OBJ)
+gint GTK_IS_LIST( gpointer obj);
 </verb></tscreen>
 
 Determine if a generic pointer refers to a `GtkList' object. *Note
@@ -4406,10 +4605,10 @@ Standard Macros::, for more info.
 <p>
 Following is an example program that will print out the changes
 of the selection of a GtkList, and lets you "arrest" list items
-into a prison by selecting them with the rightmost mouse button:
+into a prison by selecting them with the rightmost mouse button.
 
 <tscreen><verb>
-/* list.c */
+/* example-start list/list.c */
 
 /* include the gtk+ header files
  * include stdio.h, we need that for the printf() function
@@ -4691,6 +4890,7 @@ sigh_print_selection    (GtkWidget      *gtklist,
     }
     g_print("\n");
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
@@ -4707,7 +4907,7 @@ As it is directly derived from a
 GtkItem it can be treated as such by using the GTK_ITEM(ListItem)
 macro, see the GtkItem widget for more on this.
 Usualy a GtkListItem just holds a label to identify e.g. a filename
-within a GtkList -- therefore the convenient function
+within a GtkList -- therefore the convenience function
 gtk_list_item_new_with_label() is provided.  The same effect can be
 achieved by creating a GtkLabel on its own, setting its alignment
 to xalign=0 and yalign=0.5 with a subsequent container addition
@@ -4725,32 +4925,29 @@ the signals of a GtkItem. *Note GtkItem::, for more info.
 <!-- ----------------------------------------------------------------- -->
 <sect1> Functions
 <p>
-
 <tscreen><verb>
-guint gtk_list_item_get_type (void)
+guint gtk_list_item_get_type( void );
 </verb></tscreen>
 
 Returns the `GtkListItem' type identifier.
 
 <tscreen><verb>
-GtkWidget* gtk_list_item_new (void)
+GtkWidget *gtk_list_item_new( void );
 </verb></tscreen>
 
-Create a new `GtkListItem' object. The new widget is
-returned as a pointer to a `GtkWidget' object.
-`NULL' is returned on failure.
+Create a new GtkListItem object. The new widget is returned as a pointer
+to a GtkWidget object. NULL is returned on failure.
 
 <tscreen><verb>
-GtkWidget* gtk_list_item_new_with_label (gchar *LABEL)
+GtkWidget *gtk_list_item_new_with_label( gchar *label );
 </verb></tscreen>
 
-Create a new `GtkListItem' object, having a single GtkLabel as
+Create a new GtkListItem object, having a single GtkLabel as
 the sole child. The new widget is returned as a pointer to a
-`GtkWidget' object.
-`NULL' is returned on failure.
+GtkWidget object. NULL is returned on failure.
 
 <tscreen><verb>
-void gtk_list_item_select (GtkListItem *LIST_ITEM)
+void gtk_list_item_select( GtkListItem *list_item );
 </verb></tscreen>
 
 This function is basicaly a wrapper around a call to
@@ -4759,7 +4956,7 @@ select signal.
 *Note GtkItem::, for more info.
 
 <tscreen><verb>
-void gtk_list_item_deselect (GtkListItem *LIST_ITEM)
+void gtk_list_item_deselect( GtkListItem *list_item );
 </verb></tscreen>
 
 This function is basicaly a wrapper around a call to
@@ -4768,21 +4965,21 @@ deselect signal.
 *Note GtkItem::, for more info.
 
 <tscreen><verb>
-GtkListItem* GTK_LIST_ITEM (gpointer OBJ)
+GtkListItem *GTK_LIST_ITEM( gpointer obj );
 </verb></tscreen>
 
 Cast a generic pointer to `GtkListItem*'. *Note Standard Macros::,
 for more info.
 
 <tscreen><verb>
-GtkListItemClass* GTK_LIST_ITEM_CLASS (gpointer CLASS)
+GtkListItemClass *GTK_LIST_ITEM_CLASS( gpointer class );
 </verb></tscreen>
 
-Cast a generic pointer to `GtkListItemClass*'. *Note Standard
+Cast a generic pointer to GtkListItemClass*. *Note Standard
 Macros::, for more info.
 
 <tscreen><verb>
-gint GTK_IS_LIST_ITEM (gpointer OBJ)
+gint GTK_IS_LIST_ITEM( gpointer obj );
 </verb></tscreen>
 
 Determine if a generic pointer refers to a `GtkListItem' object.
@@ -4797,17 +4994,16 @@ GtkListItem as well.
 <!-- ***************************************************************** -->
 <sect>Menu Widgets
 <!-- ***************************************************************** -->
-
 <p>
 There are two ways to create menus, there's the easy way, and there's the
-hard way.  Both have their uses, but you can usually use the menufactory
-(the easy way).  The "hard" way is to create all the menus using the calls
-directly.  The easy way is to use the gtk_menu_factory calls.  This is
+hard way. Both have their uses, but you can usually use the menufactory
+(the easy way). The "hard" way is to create all the menus using the calls
+directly. The easy way is to use the gtk_menu_factory calls. This is
 much simpler, but there are advantages and disadvantages to each approach.
 
 The menufactory is much easier to use, and to add new menus to, although
 writing a few wrapper functions to create menus using the manual method 
-could go a long way towards usability.  With the menufactory, it is not 
+could go a long way towards usability. With the menufactory, it is not 
 possible to add images or the character '/' to the menus.
 
 <!-- ----------------------------------------------------------------- -->
@@ -4815,7 +5011,7 @@ possible to add images or the character '/' to the menus.
 <p>
 In the true tradition of teaching, we'll show you the hard
 way first. <tt>:)</>
-<p>
+
 There are three widgets that go into making a menubar and submenus:
 <itemize>
 <item>a menu item, which is what the user wants to select, e.g. 'Save'
@@ -4823,15 +5019,16 @@ There are three widgets that go into making a menubar and submenus:
 <item>a menubar, which is a container for each of the individual menus,
 </itemize>
 
-This is slightly complicated by the fact that menu item widgets are used for two different things. They are
-both the widets that are packed into the menu, and the widget that is packed into the menubar, which,
+This is slightly complicated by the fact that menu item widgets are used
+for two different things. They are both the widets that are packed into
+the menu, and the widget that is packed into the menubar, which,
 when selected, activiates the menu.
 
 Let's look at the functions that are used to create menus and menubars.
 This first function is used to create a new menubar.
 
 <tscreen><verb>
-GtkWidget *gtk_menu_bar_new(void);
+GtkWidget *gtk_menu_bar_new( void );
 </verb></tscreen>
 
 This rather self explanatory function creates a new menubar.  You use
@@ -4839,41 +5036,41 @@ gtk_container_add to pack this into a window, or the box_pack functions to
 pack it into a box - the same as buttons.
 
 <tscreen><verb>
-GtkWidget *gtk_menu_new();
+GtkWidget *gtk_menu_new( void );
 </verb></tscreen>
 
 This function returns a pointer to a new menu, it is never actually shown
 (with gtk_widget_show), it is just a container for the menu items.  Hopefully this will
 become more clear when you look at the example below.
-<p>
+
 The next two calls are used to create menu items that are packed into
 the menu (and menubar).
 
 <tscreen><verb>
-GtkWidget *gtk_menu_item_new();
+GtkWidget *gtk_menu_item_new( void );
 </verb></tscreen>
 
 and
 
 <tscreen><verb>
-GtkWidget *gtk_menu_item_new_with_label(const char *label);
+GtkWidget *gtk_menu_item_new_with_label( const char *label );
 </verb></tscreen>
 
 These calls are used to create the menu items that are to be displayed.
 Remember to differentiate between a "menu" as created with gtk_menu_new
-and a "menu item" as created by the gtk_menu_item_new functions.  The
+and a "menu item" as created by the gtk_menu_item_new functions. The
 menu item will be an actual button with an associated action,
 whereas a menu will be a container holding menu items.
 
 The gtk_menu_new_with_label and gtk_menu_new functions are just as you'd expect after
-reading about the buttons.  One creates a new menu item with a label
+reading about the buttons. One creates a new menu item with a label
 already packed into it, and the other just creates a blank menu item.
 
-Once you've created a menu item you have to put it into a menu. This is done using the function
-gtk_menu_append. In order to capture when the item is selected by the user, we need to connect
-to the <tt/activate/ signal in the usual way.
-So, if we wanted to create a standard <tt/File/ menu, with the options <tt/Open/, 
-<tt/Save/ and <tt/Quit/ the code would look something like
+Once you've created a menu item you have to put it into a menu. This is 
+done using the function gtk_menu_append. In order to capture when the item
+is selected by the user, we need to connect to the <tt/activate/ signal in
+the usual way. So, if we wanted to create a standard <tt/File/ menu, with
+the options <tt/Open/, <tt/Save/ and <tt/Quit/ the code would look something like
 
 <tscreen><verb>
 file_menu = gtk_menu_new();    /* Don't need to show menus */
@@ -4904,8 +5101,8 @@ gtk_widget_show( save_item );
 gtk_widget_show( quit_item );
 </verb></tscreen>
 
-At this point we have our menu. Now we need to create a menubar and a menu item for the <tt/File/ entry,
-to which we add our menu. The code looks like this 
+At this point we have our menu. Now we need to create a menubar and a menu
+item for the <tt/File/ entry, to which we add our menu. The code looks like this 
 
 <tscreen><verb>
 menu_bar = gtk_menu_bar_new();
@@ -4916,20 +5113,22 @@ file_item = gtk_menu_item_new_with_label("File");
 gtk_widget_show(file_item);
 </verb></tscreen>
 
-Now we need to associate the menu with <tt/file_item/. This is done with the function
+Now we need to associate the menu with <tt/file_item/. This is done with the
+function
 
 <tscreen>
 void gtk_menu_item_set_submenu( GtkMenuItem *menu_item,
-                                GtkWidget *submenu);
+                                GtkWidget   *submenu );
 </tscreen>
 
 So, our example would continue with
 
 <tscreen><verb>
-gtk_menu_item_set_submenu( GTK_MENU_ITEM(file_item), file_menu);
+gtk_menu_item_set_submenu( GTK_MENU_ITEM(file_item), file_menu );
 </verb></tscreen>
 
-All that is left to do is to add the menu to the menubar, which is accomplished using the function
+All that is left to do is to add the menu to the menubar, which is accomplished
+using the function
 
 <tscreen>
 void gtk_menu_bar_append( GtkMenuBar *menu_bar, GtkWidget *menu_item);
@@ -4941,39 +5140,43 @@ which in our case looks like this:
 gtk_menu_bar_append( GTK_MENU_BAR (menu_bar), file_item );
 </verb></tscreen>
 
-If we wanted the menu right justified on the menubar, such as help menus often are, we can
-use the following function (again on <tt/file_item/ in the current example) before attaching 
-it to the menubar.
+If we wanted the menu right justified on the menubar, such as help menus
+often are, we can use the following function (again on <tt/file_item/
+in the current example) before attaching it to the menubar.
+
 <tscreen><verb>
-void gtk_menu_item_right_justify (GtkMenuItem *menu_item);
+void gtk_menu_item_right_justify( GtkMenuItem *menu_item );
 </verb></tscreen>
 
 Here is a summary of the steps needed to create a menu bar with menus attached:
+
 <itemize>
-<item>	Create a new menu using gtk_menu_new()
-<item>	Use multiple calls to gtk_menu_item_new() for each item you wish to have on
-  your menu.  And use gtk_menu_append() to put each of these new items on
-  to the menu.
-<item>	Create a menu item using gtk_menu_item_new().  This will be the root of
-  the menu, the text appearing here will be on the menubar itself.
-<item>	Use gtk_menu_item_set_submenu() to attach the menu to
-  the root menu item (The one created in the above step).
-<item>	Create a new menubar using gtk_menu_bar_new.  This step only needs
-  to be done once when creating a series of menus on one menu bar.
+<item> Create a new menu using gtk_menu_new()
+<item> Use multiple calls to gtk_menu_item_new() for each item you wish to have
+on your menu. And use gtk_menu_append() to put each of these new items on 
+to the menu.
+<item> Create a menu item using gtk_menu_item_new(). This will be the root of
+the menu, the text appearing here will be on the menubar itself.
+<item>Use gtk_menu_item_set_submenu() to attach the menu to the root menu 
+item (the one created in the above step).
+<item> Create a new menubar using gtk_menu_bar_new. This step only needs
+to be done once when creating a series of menus on one menu bar.
 <item> Use gtk_menu_bar_append to put the root menu onto the menubar.
 </itemize>
-<p>
-Creating a popup menu is nearly the same.  The difference is that the
-menu is not posted `automatically' by a menubar, but explicitly
-by calling the function gtk_menu_popup() from a button-press event, for example.
+
+Creating a popup menu is nearly the same. The difference is that the
+menu is not posted `automatically' by a menubar, but explicitly by calling
+the function gtk_menu_popup() from a button-press event, for example.
 Take these steps:
+
 <itemize>
-<item>Create an event handling function.  It needs to have the prototype
+<item>Create an event handling function. It needs to have the prototype
 <tscreen>
-static gint handler(GtkWidget *widget, GdkEvent *event);
+static gint handler( GtkWidget *widget,
+                     GdkEvent  *event );
 </tscreen>
 and it will use the event to find out where to pop up the menu.
-<item>In the event handler, if event is a mouse button press, treat
+<item>In the event handler, if the event is a mouse button press, treat
 <tt>event</tt> as a button event (which it is) and use it as
 shown in the sample code to pass information to gtk_menu_popup().
 <item>Bind that event handler to a widget with
@@ -4993,7 +5196,7 @@ as shown in the sample code.
 That should about do it.  Let's take a look at an example to help clarify.
 
 <tscreen><verb>
-/* menu.c */
+/* example-start menu/menu.c */
 
 #include <gtk/gtk.h>
 
@@ -5094,8 +5297,6 @@ int main (int argc, char *argv[])
     return 0;
 }
 
-
-
 /* Respond to a button-press by posting a menu passed in as widget.
  *
  * Note that the "widget" argument is the menu being posted, NOT
@@ -5125,6 +5326,7 @@ static void menuitem_response (gchar *string)
 {
     printf("%s\n", string);
 }
+/* example-end */
 </verb></tscreen>
 
 You may also set a menu item to be insensitive and, using an accelerator
@@ -5140,11 +5342,11 @@ gtk_menu_factory calls.
 <sect1>Menu Factory Example
 <p>
 Here is an example using the GTK menu factory.  This is the first file,
-menufactory.h.  We keep a separate menufactory.c and mfmain.c because of the global variables used
-in the menufactory.c file.  
+menufactory.h.  We keep a separate menufactory.c and mfmain.c because
+of the global variables used in the menufactory.c file.  
 
 <tscreen><verb>
-/* menufactory.h */
+/* example-start menu/menufactory.h */
 
 #ifndef __MENUFACTORY_H__
 #define __MENUFACTORY_H__
@@ -5161,12 +5363,13 @@ void menus_create(GtkMenuEntry *entries, int nmenu_entries);
 #endif /* __cplusplus */
 
 #endif /* __MENUFACTORY_H__ */
+/* example-end */
 </verb></tscreen>
-<p>
+
 And here is the menufactory.c file.
 
 <tscreen><verb>
-/* menufactory.c */
+/* example-start menu/menufactory.c */
 
 #include <gtk/gtk.h>
 #include <strings.h>
@@ -5315,13 +5518,13 @@ void menus_set_sensitive(char *path, int sensitive)
     else
 	    g_warning("Unable to set sensitivity for menu which doesn't exist: %s", path);
 }
-
+/* example-end */
 </verb></tscreen>
-<p>
+
 And here's the mfmain.h
 
 <tscreen><verb>
-/* mfmain.h */
+/* example-start menu/mfmain.h */
 
 #ifndef __MFMAIN_H__
 #define __MFMAIN_H__
@@ -5338,12 +5541,13 @@ void file_quit_cmd_callback(GtkWidget *widget, gpointer data);
 #endif /* __cplusplus */
 
 #endif /* __MFMAIN_H__ */
+/* example-end */
 </verb></tscreen>
-<p>
+
 And mfmain.c
 
 <tscreen><verb>
-/* mfmain.c */
+/* example-start menu/mfmain.c */
 
 #include <gtk/gtk.h>
 
@@ -5393,8 +5597,9 @@ void file_quit_cmd_callback (GtkWidget *widget, gpointer data)
     g_print ("%s\n", (char *) data);
     gtk_exit(0);
 }
+/* example-end */
 </verb></tscreen>
-<p>
+
 And a makefile so it'll be easier to compile it.
 
 <tscreen><verb>
@@ -5421,7 +5626,7 @@ clean:
 distclean: clean 
 	rm -f *~
 </verb></tscreen>
-<p>
+
 For now, there's only this example.  An explanation and lots 'o' comments
 will follow later.
 
@@ -5429,38 +5634,40 @@ will follow later.
 <sect> Text Widget
 <!-- ***************************************************************** -->
 <p>
-The Text widget allows multiple lines of text to be displayed and edited. It supports both
-multi-colored and multi-font text, allowing them to be mixed in any way we wish. It also has
-a wide set of key based text editing commands, which are compatible with Emacs.
+The Text widget allows multiple lines of text to be displayed and edited.
+It supports both multi-colored and multi-font text, allowing them to be
+mixed in any way we wish. It also has a wide set of key based text editing
+commands, which are compatible with Emacs.
 
-The text widget supports full cut-and-paste facilities, including the use of double- and
-triple-click to select a word and a whole line, respectively.
+The text widget supports full cut-and-paste facilities, including the use
+of double- and triple-click to select a word and a whole line, respectively.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Creating and Configuring a Text box
 <p>
 There is only one function for creating a new Text widget.
 <tscreen><verb>
-GtkWidget* gtk_text_new (GtkAdjustment *hadj,
-                         GtkAdjustment *vadj);
+GtkWidget *gtk_text_new( GtkAdjustment *hadj,
+                         GtkAdjustment *vadj );
 </verb></tscreen>
 
-The arguments allow us to give the Text widget pointers to Adjustments that can be used 
-to track the viewing position of the widget. Passing NULL values to either or both of
-these arguments will cause the gtk_text_new function to create it's own.
+The arguments allow us to give the Text widget pointers to Adjustments
+that can be used to track the viewing position of the widget. Passing NULL
+values to either or both of these arguments will cause the gtk_text_new
+function to create it's own.
 
 <tscreen><verb>
-void gtk_text_set_adjustments (GtkText       *text,
+void gtk_text_set_adjustments( GtkText       *text,
                                GtkAdjustment *hadj,
-                               GtkAdjustment *vadj);
+                               GtkAdjustment *vadj );
 </verb></tscreen>
 
-The above function allows the horizontal and vertical adjustments of a Text widget to be
-changed at any time.
+The above function allows the horizontal and vertical adjustments of a
+Text widget to be changed at any time.
 
-The text widget will not automatically create it's own scrollbars when the amount of text
-to be displayed is too long for the display window. We therefore have to create and add
-them to the display layout ourselves.
+The text widget will not automatically create it's own scrollbars when
+the amount of text to be displayed is too long for the display window. We
+therefore have to create and add them to the display layout ourselves.
 
 <tscreen><verb>
   vscrollbar = gtk_vscrollbar_new (GTK_TEXT(text)->vadj);
@@ -5468,111 +5675,129 @@ them to the display layout ourselves.
   gtk_widget_show (vscrollbar);
 </verb></tscreen>
 
-The above code snippet creates a new vertical scrollbar, and attaches it to the vertical
-adjustment of the text widget, <tt/text/. It then packs it into a box in the normal way.
+The above code snippet creates a new vertical scrollbar, and attaches
+it to the vertical adjustment of the text widget, <tt/text/. It then packs
+it into a box in the normal way.
 
-There are two main ways in which a Text widget can be used: to allow the user to edit a
-body of text, or to allow us to display multiple lines of text to the user. In order for
-us to switch between these modes of operation, the text widget has the following function:
+Note, currently the GtkText widget does not support horizontal scrollbars.
+
+There are two main ways in which a Text widget can be used: to allow the
+user to edit a body of text, or to allow us to display multiple lines of
+text to the user. In order for us to switch between these modes of
+operation, the text widget has the following function:
 
 <tscreen><verb>
-void gtk_text_set_editable    (GtkText *text,
-                               gint    editable);
+void gtk_text_set_editable( GtkText *text,
+                            gint     editable );
 </verb></tscreen>
 
-The <tt/editable/ argument is a TRUE or FALSE value that specifies whether the user is
-permitted to edit the contents of the Text widget. When the text widget is editable, it
-will display a cursor at the current insertion point.
+The <tt/editable/ argument is a TRUE or FALSE value that specifies whether
+the user is permitted to edit the contents of the Text widget. When the
+text widget is editable, it will display a cursor at the current insertion
+point.
 
-You are not, however, restricted to just using the text widget in these two modes. You can
-toggle the editable state of the text widget at any time, and can insert text at any time.
+You are not, however, restricted to just using the text widget in these
+two modes. You can toggle the editable state of the text widget at any
+time, and can insert text at any time.
 
-The text widget is capable of wrapping lines of text that are too long to fit onto a single
-line of the display window. It's default behaviour is to break words across line breaks. This
-can be changed using the next function:
+The text widget wraps lines of text that are too long to
+fit onto a single line of the display window. It's default behaviour is
+to break words across line breaks. This can be changed using the next
+function:
 
 <tscreen><verb>
-void gtk_text_set_word_wrap (GtkText *text,
-                             gint    word_wrap);
+void gtk_text_set_word_wrap( GtkText *text,
+                             gint     word_wrap );
 </verb></tscreen>
 
-Using this function allows us to specify that the text widget should wrap long lines on word
-boundaries. The <tt/word_wrap/ argument is a TRUE or FALSE value.
+Using this function allows us to specify that the text widget should
+wrap long lines on word boundaries. The <tt/word_wrap/ argument is a
+TRUE or FALSE value.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Text Manipulation
 <P>
 The current insertion point of a Text widget can be set using
 <tscreen><verb>
-void gtk_text_set_point (GtkText *text,
-                         guint   index);
+void gtk_text_set_point( GtkText *text,
+                         guint    index );
 </verb></tscreen>
+
 where <tt/index/ is the position to set the insertion point.
 
 Analogous to this is the function for getting the current insertion point:
+
 <tscreen><verb>
-guint gtk_text_get_point (GtkText *text);
+guint gtk_text_get_point( GtkText *text );
 </verb></tscreen>
 
 A function that is useful in combination with the above two functions is
+
 <tscreen><verb>
-guint gtk_text_get_length (GtkText *text);
+guint gtk_text_get_length( GtkText *text );
 </verb></tscreen>
-which returns the current length of the Text widget. The length is the number of characters
-that are within the text block of the widget, including characters such as carriage-return,
-which marks the end of lines.
 
-In order to insert text at the current insertion point of a Text widget, the function
-gtk_text_insert is used, which also allows us to specify background and foreground colors and a 
-font for the text.
+which returns the current length of the Text widget. The length is the
+number of characters that are within the text block of the widget,
+including characters such as carriage-return, which marks the end of lines.
+
+In order to insert text at the current insertion point of a Text
+widget, the function gtk_text_insert is used, which also allows us to
+specify background and foreground colors and a font for the text.
 
 <tscreen><verb>
-void gtk_text_insert (GtkText    *text,
+void gtk_text_insert( GtkText    *text,
                       GdkFont    *font,
                       GdkColor   *fore,
                       GdkColor   *back,
                       const char *chars,
-                      gint       length);
+                      gint        length );
 </verb></tscreen>
 
-Passing a value of <tt/NULL/ in as the value for the foreground color, background colour or
-font will result in the values set within the widget style to be used. Using a value of <tt/-1/ for
-the length parameter will result in the whole of the text string given being inserted.
+Passing a value of <tt/NULL/ in as the value for the foreground color,
+background colour or font will result in the values set within the widget
+style to be used. Using a value of <tt/-1/ for the length parameter will
+result in the whole of the text string given being inserted.
 
-The text widget is one of the few within GTK that redraws itself dynamically, outside of the gtk_main
-function. This means that all changes to the contents of the text widget take effect immediately. This
-may be undesirable when performing multiple changes to the text widget. In order to allow us to perform
-multiple updates to the text widget without it continuously redrawing, we can freeze the widget, which
-temporarily stops it from automatically redrawing itself every time it is changed. We can then thaw the
-widget after our updates are complete.
+The text widget is one of the few within GTK that redraws itself
+dynamically, outside of the gtk_main function. This means that all changes
+to the contents of the text widget take effect immediately. This may be
+undesirable when performing multiple changes to the text widget. In order
+to allow us to perform multiple updates to the text widget without it
+continuously redrawing, we can freeze the widget, which temporarily stops
+it from automatically redrawing itself every time it is changed. We can
+then thaw the widget after our updates are complete.
 
 The following two functions perform this freeze and thaw action:
 
 <tscreen><verb>
-void gtk_text_freeze (GtkText *text);
-void gtk_text_thaw   (GtkText *text);         
+void gtk_text_freeze( GtkText *text );
+
+void gtk_text_thaw( GtkText *text );         
 </verb></tscreen>
 
-Text is deleted from the text widget relative to the current insertion point by the following
-two functions:
+Text is deleted from the text widget relative to the current insertion
+point by the following two functions. The return value is a TRUE or
+FALSE indicator of whether the operation was successful.
 
 <tscreen><verb>
-gint gtk_text_backward_delete (GtkText *text,
-                               guint   nchars);
-gint gtk_text_forward_delete  (GtkText *text,
-                               guint   nchars);
+gint gtk_text_backward_delete( GtkText *text,
+                               guint    nchars );
+
+gint gtk_text_forward_delete ( GtkText *text,
+                               guint    nchars );
 </verb></tscreen>
 
 If you want to retrieve the contents of the text widget, then the macro 
-<tt/GTK_TEXT_INDEX(t, index)/ allows you to retrieve the character at position
-<tt/index/ within the text widget <tt/t/.
+<tt/GTK_TEXT_INDEX(t, index)/ allows you to retrieve the character at
+position <tt/index/ within the text widget <tt/t/.
 
 To retrieve larger blocks of text, we can use the function
 
 <tscreen><verb>
-gchar *gtk_editable_get_chars (GtkEditable *editable,
-                               gint        start_pos,
-                               gint        end_pos);   
+gchar *gtk_editable_get_chars( GtkEditable *editable,
+                               gint         start_pos,
+                               gint         end_pos );   
 </verb></tscreen>
 
 This is a function of the parent class of the text widget. A value of -1 as
@@ -5585,24 +5810,24 @@ to free it with a call to g_free when you have finished with it.
 <sect1>Keyboard Shortcuts
 <p>
 The text widget has a number of pre-installed keyboard shotcuts for common
-editing, motion and selection functions. These are accessed using Control and Alt
-key combinations.
+editing, motion and selection functions. These are accessed using Control
+and Alt key combinations.
 
-In addition to these, holding down the Control key whilst using cursor key movement
-will move the cursor by words rather than characters. Holding down Shift whilst using
-cursor movement will extend the selection.
+In addition to these, holding down the Control key whilst using cursor key
+movement will move the cursor by words rather than characters. Holding down
+Shift whilst using cursor movement will extend the selection.
 
 <sect2>Motion Shotcuts
 <p>
 <itemize>
 <item> Ctrl-A   Beginning of line
-<item> Ctrl-E	End of line
+<item> Ctrl-E   End of line
 <item> Ctrl-N   Next Line
-<item> Ctrl-P	Previous Line
+<item> Ctrl-P   Previous Line
 <item> Ctrl-B   Backward one character
 <item> Ctrl-F   Forward one character
 <item> Alt-B    Backward one word
-<item> Alt-F	Forward one word
+<item> Alt-F    Forward one word
 </itemize>
 
 <sect2>Editing Shortcuts
@@ -5610,10 +5835,10 @@ cursor movement will extend the selection.
 <itemize>
 <item> Ctrl-H   Delete Backward Character (Backspace)
 <item> Ctrl-D   Delete Forward Character (Delete)
-<item> Ctrl-W	Delete Backward Word
+<item> Ctrl-W   Delete Backward Word
 <item> Alt-D    Delete Forward Word
-<item> Ctrl-K	Delete to end of line
-<item> Ctrl-U	Delete line
+<item> Ctrl-K   Delete to end of line
+<item> Ctrl-U   Delete line
 </itemize>
 
 <sect2>Selection Shortcuts
@@ -5621,30 +5846,44 @@ cursor movement will extend the selection.
 <itemize>
 <item> Ctrl-X   Cut to clipboard
 <item> Ctrl-C   Copy to clipboard
-<item> Ctrl-V	Paste from clipboard
+<item> Ctrl-V   Paste from clipboard
 </itemize>
 
 <!-- ***************************************************************** -->
 <sect> Undocumented Widgets
 <!-- ***************************************************************** -->
-
 <p>
 These all require authors! :)  Please consider contributing to our tutorial.
 
 If you must use one of these widgets that are undocumented, I strongly
-suggest you take a look at their respective header files in the GTK distro.
-GTK's function names are very descriptive.  Once you have an understanding
-of how things work, it's not difficult to figure out how to use a widget simply
-by looking at it's function declarations.  This, along with a few examples
-from others' code, and it should be no problem.
+suggest you take a look at their respective header files in the GTK
+distribution. GTK's function names are very descriptive.  Once you have an
+understanding of how things work, it's not difficult to figure out how to
+use a widget simply by looking at it's function declarations.  This, along
+with a few examples from others' code, and it should be no problem.
 
 When you do come to understand all the functions of a new undocumented
-widget, please consider writing a tutorial on it so others may benifit from
-your time.
+widget, please consider writing a tutorial on it so others may benifit
+from your time.
 
 <!-- ----------------------------------------------------------------- -->
+<sect1> Adjustments
+<p>
+<!-- ----------------------------------------------------------------- -->
+<sect1> Toolbar
+<p>
+<!-- ----------------------------------------------------------------- -->
+<sect1> Fixed Container
+<p>
+<!-- ----------------------------------------------------------------- -->
+<sect1> CList
+<p>
+<!-- ----------------------------------------------------------------- -->
 <sect1> Range Controls
-
+<p>
+<!-- ----------------------------------------------------------------- -->
+<sect1> Curves
+<p>
 <!-- ----------------------------------------------------------------- -->
 <sect1> Previews
 <p>
@@ -6088,53 +6327,45 @@ That's all, folks!
 
 </verb></tscreen>
 
-<!-- ----------------------------------------------------------------- -->
-<sect1> Curves
-<p>
-
 <!-- ***************************************************************** -->
 <sect>The EventBox Widget<label id="sec_The_EventBox_Widget">
 <!-- ***************************************************************** -->
-
 <p> 
 Some gtk widgets don't have associated X windows, so they just draw on 
-thier parents.  Because of this, they cannot recieve events
+their parents. Because of this, they cannot recieve events
 and if they are incorrectly sized, they don't clip so you can get
-messy overwritting etc.  If you require more from these widgets, the
+messy overwritting etc. If you require more from these widgets, the
 EventBox is for you.
 
 At first glance, the EventBox widget might appear to be totally
 useless. It draws nothing on the screen and responds to no
-events.  However, it does serve a function - it provides an X window for
+events. However, it does serve a function - it provides an X window for
 its child widget. This is important as many GTK widgets do not
-have an associated X window.  Not having an X window saves memory and
+have an associated X window. Not having an X window saves memory and
 improves performance, but also has some drawbacks. A widget without an
 X window cannot receive events, and does not perform any clipping on
-it's contents. Although the name ``EventBox'' emphasizes the
-event-handling function, the widget also can be used for clipping. 
+it's contents. Although the name <em/EventBox/ emphasizes the
+event-handling function, the widget can also be used for clipping. 
 (And more ... see the example below.)
 
-<p>
 To create a new EventBox widget, use:
 
 <tscreen><verb>
-GtkWidget* gtk_event_box_new (void);
+GtkWidget *gtk_event_box_new( void );
 </verb></tscreen>
 
-<p>
 A child widget can then be added to this EventBox:
 
 <tscreen><verb>
-gtk_container_add (GTK_CONTAINER(event_box), widget);
+gtk_container_add( GTK_CONTAINER(event_box), widget );
 </verb></tscreen>
 
-<p>
 The following example demonstrates both uses of an EventBox - a label
-is created that clipped to a small box, and set up so that a
+is created that is clipped to a small box, and set up so that a
 mouse-click on the label causes the program to exit.
 
 <tscreen><verb>
-/* eventbox.c */
+/* example-start eventbox/eventbox.c */
 
 #include <gtk/gtk.h>
 
@@ -6187,12 +6418,12 @@ main (int argc, char *argv[])
     
     return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ***************************************************************** -->
 <sect>Setting Widget Attributes<label id="sec_setting_widget_attributes">
 <!-- ***************************************************************** -->
-
 <p>
 This describes the functions used to operate on widgets.  These can be used
 to set style, padding, size etc.
@@ -6200,44 +6431,46 @@ to set style, padding, size etc.
 (Maybe I should make a whole section on accelerators.)
 
 <tscreen><verb>
-void       gtk_widget_install_accelerator (GtkWidget           *widget,
-					   GtkAcceleratorTable *table,
-					   gchar               *signal_name,
-					   gchar                key,
-					   guint8               modifiers);
+void gtk_widget_install_accelerator( GtkWidget           *widget,
+                                     GtkAcceleratorTable *table,
+                                     gchar               *signal_name,
+                                     gchar                key,
+                                     guint8               modifiers );
 
-void       gtk_widget_remove_accelerator  (GtkWidget           *widget,
-					   GtkAcceleratorTable *table,
-					   gchar               *signal_name);
+void gtk_widget_remove_accelerator ( GtkWidget           *widget,
+                                     GtkAcceleratorTable *table,
+                                     gchar               *signal_name);
 
-void       gtk_widget_activate            (GtkWidget           *widget);
+void gtk_widget_activate( GtkWidget *widget );
 
-void       gtk_widget_set_name            (GtkWidget           *widget,
-					   gchar               *name);
-gchar*     gtk_widget_get_name            (GtkWidget           *widget);
+void gtk_widget_set_name( GtkWidget *widget,
+                          gchar     *name );
 
-void       gtk_widget_set_sensitive       (GtkWidget           *widget,
-					   gint                 sensitive);
+gchar *gtk_widget_get_name( GtkWidget *widget );
 
-void       gtk_widget_set_style           (GtkWidget           *widget,
-					   GtkStyle            *style);
+void gtk_widget_set_sensitive( GtkWidget *widget,
+                               gint       sensitive );
+
+void gtk_widget_set_style( GtkWidget *widget,
+                           GtkStyle  *style );
 					   
-GtkStyle*    gtk_widget_get_style     (GtkWidget *widget);
+GtkStyle *gtk_widget_get_style( GtkWidget *widget );
+
+GtkStyle *gtk_widget_get_default_style( void );
 
-GtkStyle*    gtk_widget_get_default_style    (void);
+void gtk_widget_set_uposition( GtkWidget *widget,
+                               gint       x,
+                               gint       y );
 
-void       gtk_widget_set_uposition       (GtkWidget           *widget,
-					   gint                 x,
-					   gint                 y);
-void       gtk_widget_set_usize           (GtkWidget           *widget,
-					   gint                 width,
-					   gint                 height);
+void gtk_widget_set_usize( GtkWidget *widget,
+                           gint       width,
+                           gint       height );
 
-void       gtk_widget_grab_focus          (GtkWidget           *widget);
+void gtk_widget_grab_focus( GtkWidget *widget );
 
-void       gtk_widget_show                (GtkWidget           *widget);
+void gtk_widget_show( GtkWidget *widget );
 
-void       gtk_widget_hide                (GtkWidget           *widget);
+void gtk_widget_hide( GtkWidget *widget );
 </verb></tscreen>
 
 <!-- ***************************************************************** -->
@@ -6248,33 +6481,33 @@ void       gtk_widget_hide                (GtkWidget           *widget);
 <sect1>Timeouts
 <p>
 You may be wondering how you make GTK do useful work when in gtk_main.
-Well, you have several options.  Using the following functions you can
-create a timeout function that will be called every "interval" milliseconds.
+Well, you have several options. Using the following functions you can
+create a timeout function that will be called every "interval"
+milliseconds.
 
 <tscreen><verb>
-gint gtk_timeout_add (guint32 interval,
-		      GtkFunction function,
-		      gpointer data);
+gint gtk_timeout_add( guint32     interval,
+                      GtkFunction function,
+                      gpointer    data );
 </verb></tscreen>
 
-The first argument is the number of milliseconds
-between calls to your function.  The second argument is the function
-you wish to have called, and
-the third, the data passed to this callback function.  The return value is
+The first argument is the number of milliseconds between calls to your
+function.  The second argument is the function you wish to have called, and
+the third, the data passed to this callback function. The return value is
 an integer "tag" which may be used to stop the timeout by calling:
 
 <tscreen><verb>
-void gtk_timeout_remove (gint tag);
+void gtk_timeout_remove( gint tag );
 </verb></tscreen>
 
 You may also stop the timeout function by returning zero or FALSE from
-your callback function.  Obviously this means if you want your function to
+your callback function. Obviously this means if you want your function to
 continue to be called, it should return a non-zero value, ie TRUE.
 
 The declaration of your callback should look something like this:
 
 <tscreen><verb>
-gint timeout_callback (gpointer data);
+gint timeout_callback( gpointer data );
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
@@ -6285,61 +6518,64 @@ file descriptor for you (as returned by open(2) or socket(2)).	This is
 especially useful for networking applications.	The function:
 
 <tscreen><verb>
-gint gdk_input_add (gint source,
-		    GdkInputCondition condition,
-		    GdkInputFunction  function,
-		    gpointer data);
+gint gdk_input_add( gint              source,
+                    GdkInputCondition condition,
+                    GdkInputFunction  function,
+                    gpointer          data );
 </verb></tscreen>
 
 Where the first argument is the file descriptor you wish to have watched,
 and the second specifies what you want GDK to look for.  This may be one of:
-<p>
-GDK_INPUT_READ - Call your function when there is data ready for reading on
-your file descriptor.
-<p>
-GDK_INPUT_WRITE - Call your function when the file descriptor is ready for
-writing.
-<p>
+
+<itemize>
+<item>GDK_INPUT_READ - Call your function when there is data ready for
+reading on your file descriptor.
+
+<item>GDK_INPUT_WRITE - Call your function when the file descriptor is
+ready for writing.
+</itemize>
+
 As I'm sure you've figured out already, the third argument is the function
 you wish to have called when the above conditions are satisfied, and the
 fourth is the data to pass to this function.
-<p>
+
 The return value is a tag that may be used to stop GDK from monitoring this
 file descriptor using the following function.
-<p>
+
 <tscreen><verb>
-void gdk_input_remove (gint tag);
+void gdk_input_remove( gint tag );
 </verb></tscreen>
-<p>
-The callback function should be declared:
-<p>
+
+The callback function should be declared as:
+
 <tscreen><verb>
-void input_callback (gpointer data, gint source, 
-                     GdkInputCondition condition);
+void input_callback( gpointer          data,
+                     gint              source, 
+                     GdkInputCondition condition );
 </verb></tscreen>
-<p>
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Idle Functions
 <p>
+<!-- Need to check on idle priorities - TRG -->
 What if you have a function you want called when nothing else is
 happening ?
 
 <tscreen><verb>
-gint gtk_idle_add (GtkFunction function,
-		   gpointer data);
+gint gtk_idle_add( GtkFunction function,
+                   gpointer    data );
 </verb></tscreen>
 
 This causes GTK to call the specified function whenever nothing else is
 happening.
 
 <tscreen><verb>
-void gtk_idle_remove (gint tag);
+void gtk_idle_remove( gint tag );
 </verb></tscreen>
-<p>
+
 I won't explain the meaning of the arguments as they follow very much like
-the ones above.  The function pointed to by the first argument to
-gtk_idle_add will be called whenever the opportunity arises.  As with the
+the ones above. The function pointed to by the first argument to
+gtk_idle_add will be called whenever the opportunity arises. As with the
 others, returning FALSE will stop the idle function from being called.
 
 <!-- ***************************************************************** -->
@@ -6348,22 +6584,19 @@ others, returning FALSE will stop the idle function from being called.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Overview
-
 <p>
-
 One type of interprocess communication supported by GTK is
 <em>selections</em>. A selection identifies a chunk of data, for
 instance, a portion of text, selected by the user in some fashion, for
 instance, by dragging with the mouse. Only one application on a
-display, (he <em>owner</em>_ can own a particular selection at one
+display, (the <em>owner</em> can own a particular selection at one
 time, so when a selection is claimed by one application, the previous
 owner must indicate to the user that selection has been
 relinquished. Other applications can request the contents of a
-selection in different forms, called <em>targets</em>.  There can be
+selection in different forms, called <em>targets</em>. There can be
 any number of selections, but most X applications only handle one, the
 <em>primary selection</em>.
 
-<p>
 In most cases, it isn't necessary for a GTK application to deal with
 selections itself. The standard widgets, such as the Entry widget,
 already have the capability to claim the selection when appropriate
@@ -6374,11 +6607,10 @@ cases in which you want to give other widgets the ability to supply
 the selection, or you wish to retrieve targets not supported by
 default.
 
-<p>
 A fundamental concept needed to understand selection handling is that
 of the <em>atom</em>. An atom is an integer that uniquely identifies a
 string (on a certain display). Certain atoms are predefined by the X
-server, and in some cases there are constants in in <tt>gtk.h</tt>
+server, and in some cases there are constants in <tt>gtk.h</tt>
 corresponding to these atoms. For instance the constant
 <tt>GDK_PRIMARY_SELECTION</tt> corresponds to the string "PRIMARY".
 In other cases, you should use the functions
@@ -6388,28 +6620,25 @@ selections and targets are identifed by atoms.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Retrieving the selection
-
 <p>
-
 Retrieving the selection is an asynchronous process. To start the
 process, you call:
 
 <tscreen><verb>
-gint gtk_selection_convert   (GtkWidget 	  *widget, 
-			      GdkAtom    	   selection, 
-			      GdkAtom    	   target,
-			      guint32    	   time)
+gint gtk_selection_convert( GtkWidget *widget, 
+                            GdkAtom    selection, 
+                            GdkAtom    target,
+                            guint32    time );
 </verb</tscreen>
 
 This <em>converts</em> the selection into the form specified by
-<tt/target/. If it all possible, the time field should be the time
+<tt/target/. If at all possible, the time field should be the time
 from the event that triggered the selection. This helps make sure that
-events occur in the order that the user requested them.
- However, if it is not available (for instance, if the conversion was
-triggered by a "clicked" signal), then you can use the constant
+events occur in the order that the user requested them. However, if it
+is not available (for instance, if the conversion was triggered by
+a "clicked" signal), then you can use the constant
 <tt>GDK_CURRENT_TIME</tt>.
 
-<p>
 When the selection owner responds to the request, a
 "selection_received" signal is sent to your application. The handler
 for this signal receives a pointer to a <tt>GtkSelectionData</tt>
@@ -6434,7 +6663,7 @@ possible values are "STRING", a string of latin-1 characters, "ATOM",
 a series of atoms, "INTEGER", an integer, etc. Most targets can only
 return one type. <tt/format/ gives the length of the units (for
 instance characters) in bits. Usually, you don't care about this when
-receiving data.  <tt>data</tt> is a pointer to the returned data, and
+receiving data. <tt>data</tt> is a pointer to the returned data, and
 <tt>length</tt> gives the length of the returned data, in bytes. If
 <tt>length</tt> is negative, then an error occurred and the selection
 could not be retrieved. This might happen if no application owned the
@@ -6443,13 +6672,12 @@ support. The buffer is actually guaranteed to be one byte longer than
 <tt>length</tt>; the extra byte will always be zero, so it isn't
 necessary to make a copy of strings just to null terminate them.
 
-<p>
 In the following example, we retrieve the special target "TARGETS",
 which is a list of all targets into which the selection can be
 converted.
 
 <tscreen><verb>
-/* gettargets.c */
+/* example-start selection/gettargets.c */
 
 #include <gtk/gtk.h>
 
@@ -6545,39 +6773,37 @@ main (int argc, char *argv[])
   
   return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> Supplying the selection 
-
 <p>
-
 Supplying the selection is a bit more complicated. You must register 
 handlers that will be called when your selection is requested. For
 each selection/target pair you will handle, you make a call to:
 
 <tscreen><verb>
-void gtk_selection_add_handler (GtkWidget           *widget, 
-				GdkAtom              selection,
-				GdkAtom              target,
-				GtkSelectionFunction function,
-				GtkRemoveFunction    remove_func,
-				gpointer             data);
+void gtk_selection_add_handler( GtkWidget            *widget, 
+                                GdkAtom               selection,
+                                GdkAtom               target,
+                                GtkSelectionFunction  function,
+                                GtkRemoveFunction     remove_func,
+                                gpointer              data );
 </verb></tscreen>
 
 <tt/widget/, <tt/selection/, and <tt/target/ identify the requests
-this handler will manage.  <tt/remove_func/ if not
+this handler will manage.  <tt/remove_func/, if not
 NULL, will be called when the signal handler is removed. This is
 useful, for instance, for interpreted languages which need to
 keep track of a reference count for <tt/data/.
 
-<p>
 The callback function has the signature:
 
 <tscreen><verb>
-typedef void (*GtkSelectionFunction) (GtkWidget *widget, 
+typedef void (*GtkSelectionFunction)( GtkWidget        *widget, 
                                       GtkSelectionData *selection_data,
-				      gpointer data);
+                                      gpointer          data );
 
 </verb></tscreen>
 
@@ -6590,25 +6816,24 @@ character - or 32 - <em/i.e./ a. integer.) This is done by calling the
 function:
 
 <tscreen><verb>
-void gtk_selection_data_set (GtkSelectionData *selection_data,
-			     GdkAtom           type,
-			     gint              format,
-			     guchar           *data,
-			     gint              length);
+void gtk_selection_data_set( GtkSelectionData *selection_data,
+                             GdkAtom           type,
+                             gint              format,
+                             guchar           *data,
+                             gint              length );
 </verb></tscreen>
 
 This function takes care of properly making a copy of the data so that
 you don't have to worry about keeping it around. (You should not fill
 in the fields of the GtkSelectionData structure by hand.)
 
-<p>
 When prompted by the user, you claim ownership of the selection by
 calling:
 
 <tscreen><verb>
-gint gtk_selection_owner_set (GtkWidget 	  *widget,
-			      GdkAtom    	   selection,
-			      guint32    	   time);
+gint gtk_selection_owner_set( GtkWidget *widget,
+                              GdkAtom    selection,
+                              guint32    time );
 </verb></tscreen>
 
 If another application claims ownership of the selection, you will
@@ -6622,7 +6847,7 @@ itself), is the "STRING" target. When this target is requested, a
 string representation of the time is returned.
 
 <tscreen><verb>
-/* setselection.c */
+/* example-start selection/setselection.c */
 
 #include <gtk/gtk.h>
 #include <time.h>
@@ -6726,20 +6951,19 @@ main (int argc, char *argv[])
   
   return 0;
 }
+/* example-end */
 </verb></tscreen>
 
 
 <!-- ***************************************************************** -->
 <sect>glib<label id="sec_glib">
 <!-- ***************************************************************** -->
-
 <p>
-glib provides many useful functions and definitions available for use 
-when creating GDK
-and GTK applications.  I will list them all here with a brief explanation.
-Many are duplicates of standard libc functions so I won't go into
-detail on those.  This is mostly to be used as a reference, so you know what is
-available for use.
+glib provides many useful functions and definitions available for use
+when creating GDK and GTK applications. I will list them all here with
+a brief explanation. Many are duplicates of standard libc functions so
+I won't go into detail on those. This is mostly to be used as a reference,
+so you know what is available for use.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Definitions
@@ -6759,9 +6983,9 @@ G_MINLONG
 G_MAXLONG
 </verb></tscreen>
 
-Also, the following typedefs.  The ones left unspecified are dynamically set
-depending on the architecture.  Remember to avoid counting on the size of a
-pointer if you want to be portable!  Eg, a pointer on an Alpha is 8 bytes, but 4
+Also, the following typedefs. The ones left unspecified are dynamically set
+depending on the architecture. Remember to avoid counting on the size of a
+pointer if you want to be portable! Eg, a pointer on an Alpha is 8 bytes, but 4
 on Intel.
 
 <tscreen><verb>
@@ -6799,90 +7023,90 @@ of this document to explain them.  Of course, it's not required that you
 know these for general use of GTK, but they are nice to know.
 
 <tscreen><verb>
-GList* g_list_alloc       (void);
+GList *g_list_alloc( void );
 
-void   g_list_free        (GList     *list);
+void g_list_free( GList *list );
 
-void   g_list_free_1      (GList     *list);
+void g_list_free_1( GList *list );
 
-GList* g_list_append      (GList     *list,
-                           gpointer   data);
+GList *g_list_append( GList     *list,
+                      gpointer   data );
 			   
-GList* g_list_prepend     (GList     *list,
-                           gpointer   data);
+GList *g_list_prepend( GList    *list,
+                       gpointer  data );
 			
-GList* g_list_insert      (GList     *list,
-                           gpointer   data,
-			   gint       position);
+GList *g_list_insert( GList    *list,
+                      gpointer  data,
+			    gint      position );
 
-GList* g_list_remove      (GList     *list,
-                           gpointer   data);
+GList *g_list_remove( GList    *list,
+                      gpointer  data );
 			   
-GList* g_list_remove_link (GList     *list,
-                           GList     *link);
+GList *g_list_remove_link( GList *list,
+                           GList *link );
 
-GList* g_list_reverse     (GList     *list);
+GList *g_list_reverse( GList *list );
 
-GList* g_list_nth         (GList     *list,
-                           gint       n);
+GList *g_list_nth( GList *list,
+                   gint   n );
 			   
-GList* g_list_find        (GList     *list,
-                           gpointer   data);
+GList *g_list_find( GList    *list,
+                    gpointer  data );
 
-GList* g_list_last        (GList     *list);
+GList *g_list_last( GList *list );
 
-GList* g_list_first       (GList     *list);
+GList *g_list_first( GList *list );
 
-gint   g_list_length      (GList     *list);
+gint g_list_length( GList *list );
 
-void   g_list_foreach     (GList     *list,
-                           GFunc      func,
-			   gpointer   user_data);
+void g_list_foreach( GList    *list,
+                     GFunc     func,
+                     gpointer  user_data );
 </verb></tscreen>					      
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Singly Linked Lists
 <p>
 Many of the above functions for singly linked lists are identical to the
-above.  Here is a complete list:
+above. Here is a complete list:
 <tscreen><verb>
-GSList* g_slist_alloc       (void);
+GSList *g_slist_alloc( void );
 
-void    g_slist_free        (GSList   *list);
+void g_slist_free( GSList *list );
 
-void    g_slist_free_1      (GSList   *list);
+void g_slist_free_1( GSList *list );
 
-GSList* g_slist_append      (GSList   *list,
-                             gpointer  data);
+GSList *g_slist_append( GSList   *list,
+                        gpointer  data );
 		
-GSList* g_slist_prepend     (GSList   *list,
-                             gpointer  data);
+GSList *g_slist_prepend( GSList   *list,
+                         gpointer  data );
 			     
-GSList* g_slist_insert      (GSList   *list,
-                             gpointer  data,
-		             gint      position);
+GSList *g_slist_insert( GSList   *list,
+                        gpointer  data,
+		            gint      position );
 			     
-GSList* g_slist_remove      (GSList   *list,
-                             gpointer  data);
+GSList *g_slist_remove( GSList   *list,
+                        gpointer  data );
 			     
-GSList* g_slist_remove_link (GSList   *list,
-                             GSList   *link);
+GSList *g_slist_remove_link( GSList *list,
+                             GSList *link );
 			     
-GSList* g_slist_reverse     (GSList   *list);
+GSList *g_slist_reverse( GSList *list );
 
-GSList* g_slist_nth         (GSList   *list,
-                             gint      n);
+GSList *g_slist_nth( GSList *list,
+                     gint    n );
 			     
-GSList* g_slist_find        (GSList   *list,
-                             gpointer  data);
+GSList *g_slist_find( GSList   *list,
+                      gpointer  data );
 			     
-GSList* g_slist_last        (GSList   *list);
+GSList *g_slist_last( GSList *list );
 
-gint    g_slist_length      (GSList   *list);
+gint g_slist_length( GSList *list );
 
-void    g_slist_foreach     (GSList   *list,
-                             GFunc     func,
-			     gpointer  user_data);
+void g_slist_foreach( GSList   *list,
+                      GFunc     func,
+			    gpointer  user_data );
 	
 </verb></tscreen>
 
@@ -6890,41 +7114,41 @@ void    g_slist_foreach     (GSList   *list,
 <sect1>Memory Management
 <p>
 <tscreen><verb>
-gpointer g_malloc      (gulong    size);
+gpointer g_malloc( gulong size );
 </verb></tscreen>
 
-This is a replacement for malloc().  You do not need to check the return
+This is a replacement for malloc(). You do not need to check the return
 vaule as it is done for you in this function.
 
 <tscreen><verb>
-gpointer g_malloc0     (gulong    size);
+gpointer g_malloc0( gulong size );
 </verb></tscreen>
 
 Same as above, but zeroes the memory before returning a pointer to it.
 
 <tscreen><verb>
-gpointer g_realloc     (gpointer  mem,
-                        gulong    size);
+gpointer g_realloc( gpointer mem,
+                    gulong   size );
 </verb></tscreen>
 
-Relocates "size" bytes of memory starting at "mem".  Obviously, the memory should have been
-previously allocated.
+Relocates "size" bytes of memory starting at "mem".  Obviously, the
+memory should have been previously allocated.
 
 <tscreen><verb>
-void     g_free        (gpointer  mem);
+void g_free( gpointer mem );
 </verb></tscreen>
 
-Frees memory.  Easy one.
+Frees memory. Easy one.
 
 <tscreen><verb>
-void     g_mem_profile (void);
+void g_mem_profile( void );
 </verb></tscreen>
 
 Dumps a profile of used memory, but requries that you add #define
 MEM_PROFILE to the top of glib/gmem.c and re-make and make install.
 
 <tscreen><verb>
-void     g_mem_check   (gpointer  mem);
+void g_mem_check( gpointer mem );
 </verb></tscreen>
 
 Checks that a memory location is valid.  Requires you add #define
@@ -6936,71 +7160,72 @@ MEM_CHECK to the top of gmem.c and re-make and make install.
 Timer functions..
 
 <tscreen><verb>
-GTimer* g_timer_new     (void);
+GTimer *g_timer_new( void );
 
-void    g_timer_destroy (GTimer  *timer);
+void g_timer_destroy( GTimer *timer );
 
-void    g_timer_start   (GTimer  *timer);
+void g_timer_start( GTimer  *timer );
 
-void    g_timer_stop    (GTimer  *timer);
+void g_timer_stop( GTimer  *timer );
 
-void    g_timer_reset   (GTimer  *timer);
+void g_timer_reset( GTimer  *timer );
 
-gdouble g_timer_elapsed (GTimer  *timer,
-                         gulong  *microseconds);
+gdouble g_timer_elapsed( GTimer *timer,
+                         gulong *microseconds );
 </verb></tscreen>			 
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>String Handling
 <p>
-A whole mess of string handling functions.  They all look very interesting, and
+A whole mess of string handling functions. They all look very interesting, and
 probably better for many purposes than the standard C string functions, but
 require documentation.
 
 <tscreen><verb>
-GString* g_string_new       (gchar   *init);
-void     g_string_free      (GString *string,
-                             gint     free_segment);
+GString *g_string_new( gchar *init );
+
+void g_string_free( GString *string,
+                    gint     free_segment );
 			     
-GString* g_string_assign    (GString *lval,
-                             gchar   *rval);
+GString *g_string_assign( GString *lval,
+                          gchar   *rval );
 			     
-GString* g_string_truncate  (GString *string,
-                             gint     len);
+GString *g_string_truncate( GString *string,
+                            gint     len );
 			     
-GString* g_string_append    (GString *string,
-                             gchar   *val);
+GString *g_string_append( GString *string,
+                          gchar   *val );
 			    
-GString* g_string_append_c  (GString *string,
-                             gchar    c);
+GString *g_string_append_c( GString *string,
+                            gchar    c );
 	
-GString* g_string_prepend   (GString *string,
-                             gchar   *val);
+GString *g_string_prepend( GString *string,
+                           gchar   *val );
 			     
-GString* g_string_prepend_c (GString *string,
-                             gchar    c);
+GString *g_string_prepend_c( GString *string,
+                             gchar    c );
 	
-void     g_string_sprintf   (GString *string,
-                             gchar   *fmt,
-			     ...);
+void g_string_sprintf( GString *string,
+                       gchar   *fmt,
+                       ...);
 	
-void     g_string_sprintfa  (GString *string,
-                             gchar   *fmt,
-			     ...);
+void g_string_sprintfa ( GString *string,
+                         gchar   *fmt,
+                         ... );
 </verb></tscreen>							  
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Utility and Error Functions
 <p>
 <tscreen><verb>
-gchar* g_strdup    (const gchar *str);
+gchar *g_strdup( const gchar *str );
 </verb></tscreen>
 
-Replacement strdup function.  Copies the
-original strings contents to newly allocated memory, and returns a pointer to it.
+Replacement strdup function.  Copies the original strings contents to
+newly allocated memory, and returns a pointer to it.
 
 <tscreen><verb>
-gchar* g_strerror  (gint errnum);
+gchar *g_strerror( gint errnum );
 </verb></tscreen>
 
 I recommend using this for all error messages.  It's much nicer, and more
@@ -7017,28 +7242,28 @@ g_print("hello_world:open:%s:%s\n", filename, g_strerror(errno));
 </verb></tscreen>
 
 <tscreen><verb>
-void g_error   (gchar *format, ...);
+void g_error( gchar *format, ... );
 </verb></tscreen>
 
-Prints an error message.  The format is just like printf, but it
+Prints an error message. The format is just like printf, but it
 prepends "** ERROR **: " to your message, and exits the program.  
 Use only for fatal errors.
 
 <tscreen><verb>
-void g_warning (gchar *format, ...);
+void g_warning( gchar *format, ... );
 </verb></tscreen>
 
 Same as above, but prepends "** WARNING **: ", and does not exit the
 program.
 
 <tscreen><verb>
-void g_message (gchar *format, ...);
+void g_message( gchar *format, ... );
 </verb></tscreen>
 
 Prints "message: " prepended to the string you pass in.
 
 <tscreen><verb>
-void g_print   (gchar *format, ...);
+void g_print( gchar *format, ... );
 </verb></tscreen>
 
 Replacement for printf().
@@ -7046,7 +7271,7 @@ Replacement for printf().
 And our last function:
 
 <tscreen><verb>
-gchar* g_strsignal (gint signum);
+gchar *g_strsignal( gint signum );
 </verb></tscreen>
 
 Prints out the name of the Unix system signal given the signal number.
@@ -7058,44 +7283,45 @@ to document any function, just send me an email!
 <!-- ***************************************************************** -->
 <sect>GTK's rc Files
 <!-- ***************************************************************** -->
-
 <p>
 GTK has it's own way of dealing with application defaults, by using rc
-files.  These can be used to set the colors of just about any widget, and
+files. These can be used to set the colors of just about any widget, and
 can also be used to tile pixmaps onto the background of some widgets.  
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Functions For rc Files 
 <p>
 When your application starts, you should include a call to:
+
 <tscreen><verb>
-void gtk_rc_parse (char *filename);
+void gtk_rc_parse( char *filename );
 </verb></tscreen>
-<p>
+
 Passing in the filename of your rc file.  This will cause GTK to parse this
 file, and use the style settings for the widget types defined there.
-<p>
+
 If you wish to have a special set of widgets that can take on a different
 style from others, or any other logical division of widgets, use a call to:
+
 <tscreen><verb>
-void gtk_widget_set_name (GtkWidget *widget,
-                          gchar *name);
+void gtk_widget_set_name( GtkWidget *widget,
+                          gchar     *name );
 </verb></tscreen>
-<p>
+
 Passing your newly created widget as the first argument, and the name
-you wish to give it as the second.  This will allow you to change the
+you wish to give it as the second. This will allow you to change the
 attributes of this widget by name through the rc file.
-<p>
+
 If we use a call something like this:
 
 <tscreen><verb>
 button = gtk_button_new_with_label ("Special Button");
 gtk_widget_set_name (button, "special button");
 </verb></tscreen>
-<p>
+
 Then this button is given the name "special button" and may be addressed by
 name in the rc file as "special button.GtkButton".  [<--- Verify ME!]
-<p>
+
 The example rc file below, sets the properties of the main window, and lets
 all children of that main window inherit the style described by the "main
 button" style.  The code used in the application is:
@@ -7104,37 +7330,39 @@ button" style.  The code used in the application is:
 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
 gtk_widget_set_name (window, "main window");
 </verb></tscreen>
-<p>
+
 And then the style is defined in the rc file using:
 
 <tscreen><verb>
 widget "main window.*GtkButton*" style "main_button"
 </verb></tscreen>
-<p>
+
 Which sets all the GtkButton widgets in the "main window" to the
 "main_buttons" style as defined in the rc file.
-<p>
+
 As you can see, this is a fairly powerful and flexible system.  Use your
 imagination as to how best to take advantage of this.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>GTK's rc File Format
 <p>
-The format of the GTK file is illustrated in the example below.  This is
+The format of the GTK file is illustrated in the example below. This is
 the testgtkrc file from the GTK distribution, but I've added a
-few comments and things.  You may wish to include this explanation
+few comments and things. You may wish to include this explanation
 your application to allow the user to fine tune his application.
-<p>
+
 There are several directives to change the attributes of a widget.
+
 <itemize>
 <item>fg - Sets the foreground color of a widget.
 <item>bg - Sets the background color of a widget.
 <item>bg_pixmap - Sets the background of a widget to a tiled pixmap.
 <item>font - Sets the font to be used with the given widget.
 </itemize>
-<p>
+
 In addition to this, there are several states a widget can be in, and you
-can set different colors, pixmaps and fonts for each state.  These states are:
+can set different colors, pixmaps and fonts for each state. These states are:
+
 <itemize>
 <item>NORMAL - The normal state of a widget, without the mouse over top of
 it, and not being pressed etc.
@@ -7146,52 +7374,51 @@ the attributes assigned by this tag will be in effect.
 activated, it will take these attributes.
 <item>SELECTED - When an object is selected, it takes these attributes.
 </itemize>
-<p>
+
 When using the "fg" and "bg" keywords to set the colors of widgets, the
 format is:
+
 <tscreen><verb>
 fg[<STATE>] = { Red, Green, Blue }
 </verb></tscreen>
-<p>
+
 Where STATE is one of the above states (PRELIGHT, ACTIVE etc), and the Red,
 Green and Blue are values in the range of 0 - 1.0,  { 1.0, 1.0, 1.0 } being
-white.
-They must be in float form, or they will register as 0, so a straight 
-"1" will not work, it must
-be "1.0".  A straight "0" is fine because it doesn't matter if it's not
-recognized.  Unrecognized values are set to 0.
-<p>
+white. They must be in float form, or they will register as 0, so a straight 
+"1" will not work, it must be "1.0".  A straight "0" is fine because it 
+doesn't matter if it's not recognized.  Unrecognized values are set to 0.
+
 bg_pixmap is very similar to the above, except the colors are replaced by a
 filename.
 
 pixmap_path is a list of paths seperated by ":"'s.  These paths will be
 searched for any pixmap you specify.
 
-<p>
 The font directive is simply:
 <tscreen><verb>
 font = "<font name>"
 </verb></tscreen>
-<p>
-Where the only hard part is figuring out the font string.  Using xfontsel or
+
+Where the only hard part is figuring out the font string. Using xfontsel or
 similar utility should help.
-<p>
-The "widget_class" sets the style of a class of widgets.  These classes are
+
+The "widget_class" sets the style of a class of widgets. These classes are
 listed in the widget overview on the class hierarchy.
-<p>
+
 The "widget" directive sets a specificaly named set of widgets to a
 given style, overriding any style set for the given widget class.
 These widgets are registered inside the application using the
-gtk_widget_set_name() call.  This allows you to specify the attributes of a
+gtk_widget_set_name() call. This allows you to specify the attributes of a
 widget on a per widget basis, rather than setting the attributes of an
-entire widget class.  I urge you to document any of these special widgets so
+entire widget class. I urge you to document any of these special widgets so
 users may customize them.
-<p>
-When the keyword "<tt>parent</>" is used as an attribute, the widget will take on
+
+When the keyword <tt>parent</> is used as an attribute, the widget will take on
 the attributes of it's parent in the application.
-<p>
+
 When defining a style, you may assign the attributes of a previously defined
 style to this new one.
+
 <tscreen><verb>
 style "main_button" = "button"
 {
@@ -7199,13 +7426,13 @@ style "main_button" = "button"
   bg[PRELIGHT] = { 0.75, 0, 0 }
 }
 </verb></tscreen>
-<p>
+
 This example takes the "button" style, and creates a new "main_button" style
 simply by changing the font and prelight background color of the "button"
 style.
-<p>
-Of course, many of these attributes don't apply to all widgets.  It's a
-simple matter of common sense really.  Anything that could apply, should.
+
+Of course, many of these attributes don't apply to all widgets. It's a
+simple matter of common sense really. Anything that could apply, should.
 
 <!-- ----------------------------------------------------------------- -->
 <sect1>Example rc file
@@ -7349,9 +7576,9 @@ widget "main window.*GtkButton*" style "main_button"
 Although the GTK distribution comes with many types of widgets that
 should cover most basic needs, there may come a time when you need to
 create your own new widget type. Since GTK uses widget inheretence
-extensively, and there is already a widget that
-is close to what you want, it is often possible to make a useful new widget type in
-just a few lines of code.  But before starting work on a new widget, check
+extensively, and there is already a widget that is close to what you want,
+it is often possible to make a useful new widget type in
+just a few lines of code. But before starting work on a new widget, check
 around first to make sure that someone has not already written
 it. This will prevent duplication of effort and keep the number of
 GTK widgets out there to a minimum, which will help keep both the code
@@ -7369,13 +7596,11 @@ name="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial">
 
 <!-- ----------------------------------------------------------------- -->
 <sect1> The Anatomy Of A Widget
-
 <p>
 In order to create a new widget, it is important to have an
 understanding of how GTK objects work. This section is just meant as a
 brief overview. See the reference documentation for the details. 
 
-<p>
 GTK widgets are implemented in an object oriented fashion. However,
 they are implemented in standard C. This greatly improves portability
 and stability over using current generation C++ compilers; however,
@@ -7402,12 +7627,10 @@ struct _GtkButtonClass
 };
 </verb></tscreen>
 
-<p>
 When a button is treated as a container (for instance, when it is
 resized), its class structure can be cast to GtkContainerClass, and
 the relevant fields used to handle the signals.
 
-<p>
 There is also a structure for each widget that is created on a
 per-instance basis. This structure has fields to store information that
 is different for each instance of the widget. We'll call this
@@ -7426,7 +7649,6 @@ struct _GtkButton
 };
 </verb></tscreen>
 
-<p>
 Note that, similar to the class structure, the first field is the
 object structure of the parent class, so that this structure can be
 cast to the parent class's object structure as needed.
@@ -7436,7 +7658,6 @@ cast to the parent class's object structure as needed.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> Introduction
-
 <p>
 One type of widget that you may be interested in creating is a
 widget that is merely an aggregate of other GTK widgets. This type of
@@ -7445,7 +7666,6 @@ widgets, but provides a convenient way of packaging user interface
 elements for reuse. The FileSelection and ColorSelection widgets in
 the standard distribution are examples of this type of widget.
 
-<p>
 The example widget that we'll create in this section is the Tictactoe
 widget, a 3x3 array of toggle buttons which triggers a signal when all
 three buttons in a row, column, or on one of the diagonals are
@@ -7453,7 +7673,6 @@ depressed.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> Choosing a parent class
-
 <p>
 The parent class for a composite widget is typically the container
 class that holds all of the elements of the composite widget. For
@@ -7475,7 +7694,6 @@ from GtkVBox instead, and stick our table inside the VBox.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> The header file
-
 <p>
 Each widget class has a header file which declares the object and
 class structures for that widget, along with public functions. 
@@ -7511,7 +7729,6 @@ macros in our header file, <tt/TICTACTOE(obj)/,
 pointer into a pointer to the object or class structure, and check
 if an object is a Tictactoe widget respectively.
 
-<p>
 Here is the complete header file:
 
 <tscreen><verb>
@@ -7563,7 +7780,6 @@ void	       tictactoe_clear           (Tictactoe *ttt);
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> The <tt/_get_type()/ function.
-
 <p>
 We now continue on to the implementation of our widget. A core
 function for every widget is the function
@@ -7597,7 +7813,6 @@ tictactoe_get_type ()
 }
 </verb></tscreen>
 
-<p>
 The GtkTypeInfo structure has the following definition:
 
 <tscreen><verb>
@@ -7613,7 +7828,6 @@ struct _GtkTypeInfo
 };
 </verb></tscreen>
 
-<p>
 The fields of this structure are pretty self-explanatory. We'll ignore
 the <tt/arg_set_func/ and <tt/arg_get_func/ fields here: they have an important, 
 but as yet largely
@@ -7624,7 +7838,6 @@ type.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> The <tt/_class_init()/ function
-
 <p>
 The <tt/WIDGETNAME_class_init()/ function initializes the fields of
 the widget's class structure, and sets up any signals for the
@@ -7659,8 +7872,7 @@ tictactoe_class_init (TictactoeClass *class)
 }
 </verb></tscreen>
 
-<p>
-Our widget has just one signal, the ``tictactoe'' signal that is
+Our widget has just one signal, the <tt/tictactoe/ signal that is
 invoked when a row, column, or diagonal is completely filled in. Not
 every composite widget needs signals, so if you are reading this for
 the first time, you may want to skip to the next section now, as
@@ -7669,14 +7881,14 @@ things are going to get a bit complicated.
 The function:
 
 <tscreen><verb>
-gint   gtk_signal_new (const gchar         *name,
-                       GtkSignalRunType    run_type,
-		       GtkType             object_type,
-		       gint                function_offset,
-		       GtkSignalMarshaller marshaller,
-		       GtkType             return_val,
-		       guint               nparams,
-		       ...);
+gint gtk_signal_new( const gchar         *name,
+                     GtkSignalRunType     run_type,
+                     GtkType              object_type,
+                     gint                 function_offset,
+                     GtkSignalMarshaller  marshaller,
+                     GtkType              return_val,
+                     guint                nparams,
+                     ...);
 </verb></tscreen>
 
 Creates a new signal. The parameters are:
@@ -7734,7 +7946,6 @@ typedef enum
 } GtkFundamentalType;
 </verb></tscreen>
 
-<p>
 <tt/gtk_signal_new()/ returns a unique integer identifier for the
 signal, that we store in the <tt/tictactoe_signals/ array, which we
 index using an enumeration. (Conventionally, the enumeration elements
@@ -7750,9 +7961,7 @@ indicating that there is no default action.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> The <tt/_init()/ function.
-
 <p>
-
 Each widget class also needs a function to initialize the object
 structure. Usually, this function has the fairly limited role of
 setting the fields of the structure to default values. For composite
@@ -7785,9 +7994,7 @@ tictactoe_init (Tictactoe *ttt)
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> And the rest...
-
 <p>
-
 There is one more function that every widget (except for base widget
 types like GtkBin that cannot be instantiated) needs to have - the
 function that the user calls to create an object of that type. This is
@@ -7796,13 +8003,11 @@ widgets, though not for the Tictactoe widgets, this function takes
 arguments, and does some setup based on the arguments. The other two
 functions are specific to the Tictactoe widget. 
 
-<p>
 <tt/tictactoe_clear()/ is a public function that resets all the
 buttons in the widget to the up position. Note the use of
 <tt/gtk_signal_handler_block_by_data()/ to keep our signal handler for
 button toggles from being triggered unnecessarily.
 
-<p>
 <tt/tictactoe_toggle()/ is the signal handler that is invoked when the
 user clicks on a button. It checks to see if there are any winning
 combinations that involve the toggled button, and if so, emits
@@ -7867,8 +8072,6 @@ tictactoe_toggle (GtkWidget *widget, Tictactoe *ttt)
 }
 </verb></tscreen>
 
-<p>
-
 And finally, an example program using our Tictactoe widget:
 
 <tscreen><verb>
@@ -7923,9 +8126,7 @@ main (int argc, char *argv[])
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> Introduction
-
 <p>
-
 In this section, we'll learn more about how widgets display themselves
 on the screen and interact with events. As an example of this, we'll
 create an analog dial widget with a pointer that the user can drag to
@@ -7933,7 +8134,6 @@ set the value.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> Displaying a widget on the screen
-
 <p>
 There are several steps that are involved in displaying on the screen.
 After the widget is created with a call to <tt/WIDGETNAME_new()/,
@@ -7959,7 +8159,6 @@ have their own windows. (If they have their own windows, then X will
 generate the necessary expose events)
 </itemize>
 
-<p>
 You might notice that the last two functions are quite similar - each
 is responsible for drawing the widget on the screen. In fact many
 types of widgets don't really care about the difference between the
@@ -7970,7 +8169,6 @@ functions. For instance, if a widget has multiple X windows, then
 since expose events identify the exposed window, it can redraw only
 the affected window, which is not possible for calls to <tt/draw()/.
 
-<p>
 Container widgets, even if they don't care about the difference for
 themselves, can't simply use the default <tt/draw()/ function because
 their child widgets might care about the difference. However,
@@ -7980,7 +8178,6 @@ functions. The convention is that such widgets have a function called
 widget, that is then called by the <tt/draw()/ and <tt/expose()/
 functions.
 
-<p>
 In our example approach, since the dial widget is not a container
 widget, and only has a single window, we can take the simplest
 approach and use the default <tt/draw()/ function and only implement
@@ -7988,7 +8185,6 @@ an <tt/expose()/ function.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> The origins of the Dial Widget
-
 <p>
 Just as all land animals are just variants on the first amphibian that
 crawled up out of the mud, Gtk widgets tend to start off as variants
@@ -8005,7 +8201,6 @@ would be a good idea to look them over before continuing.
 
 <!-- ----------------------------------------------------------------- -->
 <sect2> The Basics
-
 <p>
 Quite a bit of our widget should look pretty familiar from the
 Tictactoe widget. First, we have a header file: