ran make templates, to fix problems with structs.

1999-09-22 Damon Chaplin <damon@karuna.freeserve.co.uk> * gtk/tmpl/*.sgml: ran make templates, to fix problems with structs. * gtk/gtk-sections.txt: rearranged GtkCombo section. * gtk/tmpl/gtkvseparator.sgml: * gtk/tmpl/gtkhseparator.sgml: * gtk/tmpl/gtkgc.sgml: * gtk/tmpl/gtkfeatures.sgml: * gtk/tmpl/gtktipsquery.sgml: * gtk/tmpl/gtkitem.sgml: * gtk/tmpl/gtkinvisible.sgml: * gtk/tmpl/gtkgamma.sgml: * gtk/tmpl/gtkdata.sgml: * gtk/tmpl/gtkcurve.sgml: * gtk/tmpl/gtkcombo.sgml: * gtk/tmpl/gtkaccellabel.sgml: documented.
author: Damon Chaplin <damon@karuna.freeserve.co.uk> 1999-09-22 21:30:57 +0000
committer: Damon Chaplin <damon@src.gnome.org> 1999-09-22 21:30:57 +0000
commit: 372c4d2627e4cb15a3bec51d051f4cc30afc5138 (patch)
tree: 47494baccbd01d820fd39a00182bc7502d3f646e /docs/reference
parent: 9e7433487be556e130e8c14c6317eb6f04697330 (diff)
download: gdk-pixbuf-372c4d2627e4cb15a3bec51d051f4cc30afc5138.tar.gz
105 files changed, 2165 insertions, 1788 deletions
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 7f56930c8..a474648f9 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,55 @@
+1999-09-22  Damon Chaplin  <damon@karuna.freeserve.co.uk>
+
+	* gtk/tmpl/*.sgml: ran make templates, to fix problems with structs.
+
+	* gtk/gtk-sections.txt: rearranged GtkCombo section.
+
+	* gtk/tmpl/gtkvseparator.sgml: 
+	* gtk/tmpl/gtkhseparator.sgml: 
+	* gtk/tmpl/gtkgc.sgml: 
+	* gtk/tmpl/gtkfeatures.sgml: 
+	* gtk/tmpl/gtktipsquery.sgml: 
+	* gtk/tmpl/gtkitem.sgml: 
+	* gtk/tmpl/gtkinvisible.sgml: 
+	* gtk/tmpl/gtkgamma.sgml: 
+	* gtk/tmpl/gtkdata.sgml: 
+	* gtk/tmpl/gtkcurve.sgml: 
+	* gtk/tmpl/gtkcombo.sgml: 
+	* gtk/tmpl/gtkaccellabel.sgml: documented.
+
+1999-09-20  Damon Chaplin  <damon@karuna.freeserve.co.uk>
+
+	* gtk/gtk-docs.sgml: added role="no-toc" to the GTK+ Widgets & Objects
+	chapter since we've created our own special contents page.
+
+1999-09-19  Damon Chaplin  <damon@karuna.freeserve.co.uk>
+
+	* gtk/tmpl/gtkmarshal.sgml: 
+	* gtk/tmpl/gtksignal.sgml: new sections from 
+         David Benson <daveb@idealab.com>.
+
+	* gtk/gtk-sections.txt: rearranged signal sections, and made most
+	marshallers private. Moved GtkSignalRunType to signals section.
+
+	* gtk/tmpl/gtkradiobutton.sgml: new section from Lee Mallabone.
+
+1999-09-17  Damon Chaplin  <damon@karuna.freeserve.co.uk>
+
+	* gtk/gtk-docs.sgml: removed menu factory and debugging sections.
+
+	* gtk/gtk-sections.txt: made menu factory stuff private since it is
+	deprecated. Also made debugging stuff private since it is only useful
+	within GTK+.
+
+1999-09-14  Damon Chaplin  <damon@karuna.freeserve.co.uk>
+
+	* gtk/tmpl/gtkfilesel.sgml: fixed mismatched parentheses.
+
+1999-09-02  Damon Chaplin  <damon@karuna.freeserve.co.uk>
+
+	* gdk/tmpl/event_structs.sgml: 
+	* gdk/tmpl/drawing.sgml: minor fixes.
+
 1999-09-20  David C. Mason  <dcm@redhat.com>
 
 	* gtk/tmpl/gtkimage.sgml: first pass at gtkimage... not complete
diff --git a/docs/reference/gdk/tmpl/drawing.sgml b/docs/reference/gdk/tmpl/drawing.sgml
index d57db7b25..83ab876aa 100644
--- a/docs/reference/gdk/tmpl/drawing.sgml
+++ b/docs/reference/gdk/tmpl/drawing.sgml
@@ -160,7 +160,7 @@ the ellipse to be drawn.
 @height: the height of the bounding rectangle.
 @angle1: the start angle of the arc, relative to the 3 o'clock position,
 counter-clockwise, in 1/64ths of a degree.
-@angle2: the end angle of the arc, similar to @angle1.
+@angle2: the end angle of the arc, in the same units as @angle1.
 
 
 <!-- ##### FUNCTION gdk_draw_polygon ##### -->
@@ -184,7 +184,7 @@ Draws a string of characters in the given font or fontset.
 
 @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 @font: a #GdkFont.
-q@gc: a #GdkGC.
+@gc: a #GdkGC.
 @x: the x coordinate of the left edge of the text.
 @y: the y coordinate of the baseline of the text.
 @string: the string of characters to draw.
diff --git a/docs/reference/gdk/tmpl/event_structs.sgml b/docs/reference/gdk/tmpl/event_structs.sgml
index 5a4370bc1..ce5ba37aa 100644
--- a/docs/reference/gdk/tmpl/event_structs.sgml
+++ b/docs/reference/gdk/tmpl/event_structs.sgml
@@ -94,7 +94,7 @@ Any event can safely be cast to a #GdkEventAny to access these fields.
 <para>
 Used for button press and button release events. The
 <structfield>type</structfield> field will be one of %GDK_BUTTON_PRESS,
-%GDK_2BUTTON_PRESS, GDK_3BUTTON_PRESS, and GDK_BUTTON_RELEASE.
+%GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, and %GDK_BUTTON_RELEASE.
 </para>
 <para>
 Double and treble-clicks result in a sequence of events being received.
@@ -128,7 +128,8 @@ is inserted after the third click. The order of the events is:
 @type: the type of the event.
 @window: the window which received the event.
 @send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
-@time: the time of the event in milliseconds. This wraps around every 50 days.
+@time: the time of the event in milliseconds. This wraps around roughly every
+50 days.
 @x: the x coordinate of the mouse relative to the window.
 @y: the y coordinate of the mouse relative to the window.
 @pressure: the pressure of the button press, intended for input devices such
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 97afce312..6042de191 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -102,14 +102,12 @@
 <!entity gtk-Keyboard-Accelerators SYSTEM "sgml/gtkaccelgroup.sgml">
 <!entity gtk-Selections SYSTEM "sgml/gtkselection.sgml">
 <!entity gtk-Drag-and-Drop SYSTEM "sgml/gtkdnd.sgml">
-<!entity gtk-Menu-Factory SYSTEM "sgml/gtkmenufactory.sgml">
 <!entity gtk-Signals SYSTEM "sgml/gtksignal.sgml">
 <!entity gtk-Signal-Marshallers SYSTEM "sgml/gtkmarshal.sgml">
 <!entity gtk-Object-Properties SYSTEM "sgml/gtkarg.sgml">
 <!entity gtk-Types SYSTEM "sgml/gtktypeutils.sgml">
 <!entity gtk-Bindings SYSTEM "sgml/gtkbindings.sgml">
 <!entity gtk-Standard-Enumerations SYSTEM "sgml/gtkenums.sgml">
-<!entity gtk-Debugging SYSTEM "sgml/gtkdebug.sgml">
 <!entity gtk-Private-Information SYSTEM "sgml/gtkprivate.sgml">
 
 <!entity index-Object-Tree SYSTEM "sgml/tree_index.sgml">
@@ -168,7 +166,6 @@ An advanced widget set.
 </varlistentry>
 </variablelist>
     </para>
-
     &gtk-General;
     &gtk-Feature-Test-Macros;
     &gtk-Graphics-Contexts;
@@ -178,18 +175,16 @@ An advanced widget set.
     &gtk-Keyboard-Accelerators;
     &gtk-Selections;
     &gtk-Drag-and-Drop;
-    &gtk-Menu-Factory;
     &gtk-Signals;
     &gtk-Signal-Marshallers;
     &gtk-Object-Properties;
     &gtk-Types;
     &gtk-Bindings;
     &gtk-Standard-Enumerations;
-    &gtk-Debugging;
     &gtk-Private-Information;
   </chapter>
 
-  <chapter id="gtkobjects">
+  <chapter id="gtkobjects" role="no-toc">
     <title>GTK+ Widgets and Objects</title>
     &index-Objects-Grouped;
 
diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt
index 492488536..fe99b4d45 100644
--- a/docs/reference/gtk/gtk-sections.txt
+++ b/docs/reference/gtk/gtk-sections.txt
@@ -378,12 +378,12 @@ GTK_COLOR_SELECTION_DIALOG_CLASS
 GtkCombo
 <TITLE>GtkCombo</TITLE>
 gtk_combo_new
+gtk_combo_set_popdown_strings
 gtk_combo_set_value_in_list
 gtk_combo_set_use_arrows
 gtk_combo_set_use_arrows_always
 gtk_combo_set_case_sensitive
 gtk_combo_set_item_string
-gtk_combo_set_popdown_strings
 gtk_combo_disable_activate
 <SUBSECTION Standard>
 GTK_COMBO
@@ -2505,23 +2505,6 @@ gtk_drag_dest_handle_event
 
 
 <SECTION>
-<FILE>gtkmenufactory</FILE>
-<TITLE>Menu Factory</TITLE>
-GtkMenuCallback
-GtkMenuEntry
-GtkMenuPath
-GtkMenuFactory
-gtk_menu_factory_new
-gtk_menu_factory_destroy
-gtk_menu_factory_add_entries
-gtk_menu_factory_add_subfactory
-gtk_menu_factory_remove_paths
-gtk_menu_factory_remove_entries
-gtk_menu_factory_remove_subfactory
-gtk_menu_factory_find
-</SECTION>
-
-<SECTION>
 <FILE>gtksignal</FILE>
 <TITLE>Signals</TITLE>
 GTK_SIGNAL_OFFSET
@@ -2529,6 +2512,7 @@ GtkSignalMarshal
 GtkSignalDestroy
 GtkEmissionHook
 GtkSignalQuery
+GtkSignalRunType
 gtk_signal_init
 gtk_signal_new
 gtk_signal_newv
@@ -2547,8 +2531,8 @@ gtk_signal_connect_after
 gtk_signal_connect_object
 gtk_signal_connect_object_after
 gtk_signal_connect_full
-gtk_signal_connect_object_while_alive
 gtk_signal_connect_while_alive
+gtk_signal_connect_object_while_alive
 gtk_signal_disconnect
 gtk_signal_disconnect_by_func
 gtk_signal_disconnect_by_data
@@ -2573,6 +2557,8 @@ gtk_signal_remove_emission_hook
 <FILE>gtkmarshal</FILE>
 <TITLE>Signal Marshallers</TITLE>
 gtk_signal_default_marshaller
+
+<SUBSECTION Private>
 gtk_marshal_BOOL__POINTER_INT_INT_UINT
 gtk_marshal_BOOL__POINTER_STRING_STRING_POINTER
 gtk_marshal_ENUM__ENUM
@@ -2902,7 +2888,6 @@ GtkCurveType
 GtkDirectionType
 GtkJustification
 GtkMatchType
-GtkMenuFactoryType
 GtkMetricType
 GtkOrientation
 GtkPackType
@@ -2913,7 +2898,6 @@ GtkPositionType
 GtkPreviewType
 GtkReliefStyle
 GtkResizeMode
-GtkSignalRunType
 GtkScrollType
 GtkSelectionMode
 GtkShadowType
@@ -2930,14 +2914,6 @@ GtkSortType
 </SECTION>
 
 <SECTION>
-<FILE>gtkdebug</FILE>
-<TITLE>Debugging</TITLE>
-GtkDebugFlag
-gtk_debug_flags
-GTK_NOTE
-</SECTION>
-
-<SECTION>
 <FILE>gtkprivate</FILE>
 <TITLE>Private Information</TITLE>
 GtkPrivateFlags
@@ -2952,5 +2928,24 @@ GTK_WIDGET_IN_REPARENT
 GTK_WIDGET_IS_OFFSCREEN
 GTK_PRIVATE_SET_FLAG
 GTK_PRIVATE_UNSET_FLAG
+
+<SUBSECTION Private>
+GtkMenuCallback
+GtkMenuEntry
+GtkMenuPath
+GtkMenuFactory
+GtkMenuFactoryType
+gtk_menu_factory_new
+gtk_menu_factory_destroy
+gtk_menu_factory_add_entries
+gtk_menu_factory_add_subfactory
+gtk_menu_factory_remove_paths
+gtk_menu_factory_remove_entries
+gtk_menu_factory_remove_subfactory
+gtk_menu_factory_find
+
+GtkDebugFlag
+gtk_debug_flags
+GTK_NOTE
 </SECTION>
 
diff --git a/docs/reference/gtk/objects_grouped.sgml b/docs/reference/gtk/objects_grouped.sgml
index da6e073e0..3b546dc9c 100644
--- a/docs/reference/gtk/objects_grouped.sgml
+++ b/docs/reference/gtk/objects_grouped.sgml
@@ -30,7 +30,6 @@
     <link linkend="GtkViewport">GtkViewport</link>
     <link linkend="GtkEventBox">GtkEventBox</link>
     <link linkend="GtkAlignment">GtkAlignment</link>
-    <link linkend="GtkInvisible">GtkInvisible</link>
     <link linkend="GtkHButtonBox">GtkHButtonBox</link>
     <link linkend="GtkVButtonBox">GtkVButtonBox</link>
     <link linkend="GtkHPaned">GtkHPaned</link>
@@ -125,6 +124,7 @@
 <emphasis>Misc. Objects</emphasis>
     <link linkend="GtkAdjustment">GtkAdjustment</link>
     <link linkend="GtkItemFactory">GtkItemFactory</link>
+    <link linkend="GtkInvisible">GtkInvisible</link>
 </literallayout></entry>
 </row>
 </tbody></tgroup></informaltable>
diff --git a/docs/reference/gtk/tmpl/gtk-unused.sgml b/docs/reference/gtk/tmpl/gtk-unused.sgml
index 3e32cdde9..8cd00ccc2 100644
--- a/docs/reference/gtk/tmpl/gtk-unused.sgml
+++ b/docs/reference/gtk/tmpl/gtk-unused.sgml
@@ -1,3 +1,209 @@
+<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:Title ##### -->
+Menu Factory
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### STRUCT GtkMenuFactory ##### -->
+<para>
+
+</para>
+
+@path: 
+@type: 
+@accel_group: 
+@widget: 
+@subfactories: 
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### MACRO gtk_marshal_NONE__UINT_STRING ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_FLOAT ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_POINTER ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_INT__POINTER ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_menu_factory_find ##### -->
+<para>
+
+</para>
+
+@factory: 
+@path: 
+@Returns: 
+
+<!-- ##### MACRO gtk_marshal_NONE__ENUM_FLOAT_BOOL ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_STRING_STRING ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER_INT_INT_INT_POINTER ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### MACRO gtk_marshal_NONE__UINT_POINTER_UINT_ENUM_ENUM_POINTER ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ENUM GtkMenuFactoryType ##### -->
+<para>
+
+</para>
+
+@GTK_MENU_FACTORY_MENU: 
+@GTK_MENU_FACTORY_MENU_BAR: 
+@GTK_MENU_FACTORY_OPTION_MENU: 
+
+<!-- ##### FUNCTION gtk_marshal_INT__POINTER_CHAR_CHAR ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_INT_POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_FLOAT_BOOL ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### MACRO gtk_marshal_NONE__BOXED ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_menu_factory_add_entries ##### -->
+<para>
+
+</para>
+
+@factory: 
+@entries: 
+@nentries: 
+
+<!-- ##### STRUCT GtkMenuPath ##### -->
+<para>
+
+</para>
+
+@path: 
+@widget: 
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### MACRO gtk_marshal_NONE__UINT_POINTER_UINT_UINT_ENUM ##### -->
+<para>
+
+</para>
+
+
 <!-- ##### ARG GtkPreview:expand ##### -->
 <para>
 Determines the way that the the preview widget behaves
@@ -6,6 +212,215 @@ size. See gtk_preview_set_expand().
 </para>
 
 
+<!-- ##### MACRO gtk_marshal_NONE__STRING_INT_POINTER ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_INT_INT_POINTER_UINT_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_INT_INT_INT ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### MACRO gtk_marshal_BOOL__POINTER_STRING_STRING_POINTER ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__ENUM_FLOAT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_INT ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_POINTER_UINT_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_menu_factory_remove_paths ##### -->
+<para>
+
+</para>
+
+@factory: 
+@paths: 
+@npaths: 
+
+<!-- ##### FUNCTION gtk_menu_factory_destroy ##### -->
+<para>
+
+</para>
+
+@factory: 
+
+<!-- ##### MACRO gtk_marshal_BOOL__POINTER_INT_INT_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_INT__INT ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### MACRO gtk_marshal_ENUM__ENUM ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER_INT_INT_INT ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### MACRO GTK_NOTE ##### -->
+<para>
+
+</para>
+
+@type: 
+@action: 
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER_POINTER ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__BOOL ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_POINTER_POINTER_POINTER ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### MACRO gtk_marshal_NONE__OBJECT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ENUM GtkDebugFlag ##### -->
+<para>
+
+</para>
+
+@GTK_DEBUG_OBJECTS: 
+@GTK_DEBUG_MISC: 
+@GTK_DEBUG_SIGNALS: 
+@GTK_DEBUG_DND: 
+@GTK_DEBUG_PLUGSOCKET: 
+
 <!-- ##### ARG GtkHandleBox:snap_edge ##### -->
 <para>
 Determines the snap edge of a handlebox. The snap edge is
@@ -22,3 +437,193 @@ Determines the side of the handlebox where the handle is drawn.
 </para>
 
 
+<!-- ##### MACRO gtk_marshal_NONE__STRING ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__ENUM ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__C_CALLBACK_C_CALLBACK ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_menu_factory_new ##### -->
+<para>
+
+</para>
+
+@type: 
+@Returns: 
+
+<!-- ##### SECTION ./tmpl/gtkdebug.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__INT_INT_POINTER ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_NONE__C_CALLBACK ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_POINTER_INT_INT ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_menu_factory_remove_entries ##### -->
+<para>
+
+</para>
+
+@factory: 
+@entries: 
+@nentries: 
+
+<!-- ##### SECTION ./tmpl/gtkdebug.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### USER_FUNCTION GtkMenuCallback ##### -->
+<para>
+
+</para>
+
+@widget: 
+@user_data: 
+
+<!-- ##### VARIABLE gtk_debug_flags ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_menu_factory_remove_subfactory ##### -->
+<para>
+
+</para>
+
+@factory: 
+@subfactory: 
+@path: 
+
+<!-- ##### SECTION ./tmpl/gtkdebug.sgml:Title ##### -->
+Debugging
+
+
+<!-- ##### FUNCTION gtk_ruler_draw_pos ##### -->
+<para>
+
+</para>
+
+@ruler: the gtkruler
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_UINT ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gtkdebug.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_ENUM ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gtk_marshal_NONE__NONE ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_marshal_BOOL__NONE ##### -->
+<para>
+
+</para>
+
+@object: 
+@func: 
+@func_data: 
+@args: 
+
+<!-- ##### FUNCTION gtk_menu_factory_add_subfactory ##### -->
+<para>
+
+</para>
+
+@factory: 
+@subfactory: 
+@path: 
+
+<!-- ##### STRUCT GtkMenuEntry ##### -->
+<para>
+
+</para>
+
+@path: 
+@accelerator: 
+@callback: 
+@callback_data: 
+@widget: 
+
+<!-- ##### FUNCTION gtk_ruler_draw_ticks ##### -->
+<para>
+
+</para>
+
+@ruler: the gtkruler
+
+<!-- ##### SECTION ./tmpl/gtkmenufactory.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
diff --git a/docs/reference/gtk/tmpl/gtkaccellabel.sgml b/docs/reference/gtk/tmpl/gtkaccellabel.sgml
index bd1c8c05a..7676b5c70 100644
--- a/docs/reference/gtk/tmpl/gtkaccellabel.sgml
+++ b/docs/reference/gtk/tmpl/gtkaccellabel.sgml
@@ -2,68 +2,131 @@
 GtkAccelLabel
 
 <!-- ##### SECTION Short_Description ##### -->
-
+a label which displays an accelerator key on the right of the text.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The #GtkAccelLabel widget is a subclass of #GtkLabel that also displays an
+accelerator key on the right of the label text, e.g. 'Ctl+S'.
+It is commonly used in menus to show the keyboard short-cuts for commands.
+</para>
+<para>
+The accelerator key to display is not set explicitly.
+Instead, the #GtkAccelLabel displays the accelerators which have been added to
+a particular widget. This widget is set by calling
+gtk_accel_label_set_accel_widget().
+</para>
+<para>
+For example, a #GtkMenuItem widget may have an accelerator added to emit the
+"activate" signal when the 'Ctl+S' key combination is pressed.
+A #GtkAccelLabel is created and added to the #GtkMenuItem, and
+gtk_accel_label_set_accel_widget() is called with the #GtkMenuItem as the
+second argument. The #GtkAccelLabel will now display 'Ctl+S' after its label.
 </para>
+<para>
+Note that creating a #GtkMenuItem with gtk_menu_item_new_with_label() (or
+one of the similar functions for #GtkCheckMenuItem and #GtkRadioMenuItem)
+automatically adds a #GtkAccelLabel to the #GtkMenuItem and calls
+gtk_accel_label_set_accel_widget() to set it up for you.
+</para>
+<para>
+A #GtkAccelLabel will only display accelerators which have GTK_ACCEL_VISIBLE
+set (see #GtkAccelFlags).
+A #GtkAccelLabel can display multiple accelerators and even signal names,
+though it is almost always used to display just one accelerator key.
+</para>
+
+<example>
+<title>Creating a simple menu item with an accelerator key.</title>
+<programlisting>
+  GtkWidget *save_item;
+  GtkAccelGroup *accel_group;
+
+  /* Create a #GtkAccelGroup and add it to the window. */
+  accel_group = gtk_accel_group_new ();
+  gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);
+
+  /* Create the menu item using the convenience function. */
+  save_item = gtk_menu_item_new_with_label ("Save");
+  gtk_widget_show (save_item);
+  gtk_container_add (GTK_CONTAINER (menu), save_item);
+
+  /* Now add the accelerator to the #GtkMenuItem. Note that since we called
+     gtk_menu_item_new_with_label() to create the #GtkMenuItem the
+     #GtkAccelLabel is automatically set up to display the #GtkMenuItem
+     accelerators. We just need to make sure we use GTK_ACCEL_VISIBLE here. */
+  gtk_widget_add_accelerator (save_item, "activate", accel_group,
+                              GDK_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
+</programlisting>
+</example>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
+<variablelist>
 
+<varlistentry>
+<term><link linkend="gtk-keyboard-accelerators">Keyboard Accelerators</link>
+</term>
+<listitem><para>installing and using keyboard short-cuts.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>#GtkItemFactory</term>
+<listitem><para>an easier way to create menus.</para></listitem>
+</varlistentry>
+
+</variablelist>
 </para>
 
 <!-- ##### STRUCT GtkAccelLabel ##### -->
 <para>
-
+The #GtkAccelLabel-struct struct contains private data only, and
+should be accessed using the functions below.
 </para>
 
-@label: 
-@queue_id: 
-@accel_padding: 
-@accel_widget: 
-@accel_string: 
-@accel_string_width: 
 
 <!-- ##### FUNCTION gtk_accel_label_new ##### -->
 <para>
-
+Creates a new #GtkAccelLabel.
 </para>
 
-@string: 
-@Returns: 
+@string: the label string.
+@Returns: a new #GtkAccelLabel.
 
 
 <!-- ##### FUNCTION gtk_accel_label_set_accel_widget ##### -->
 <para>
-
+Sets the widget whose accelerators are to be shown.
 </para>
 
-@accel_label: 
-@accel_widget: 
+@accel_label: a #GtkAccelLabel.
+@accel_widget: the widget whose accelerators are to be displayed.
 
 
 <!-- ##### FUNCTION gtk_accel_label_get_accel_width ##### -->
 <para>
-
+Returns the width needed to display the accelerator key(s).
+This is used by menus to align all of the #GtkMenuItem widgets, and shouldn't
+be needed by applications.
 </para>
 
-@accel_label: 
+@accel_label: a #GtkAccelLabel.
 @Returns: 
 
 
 <!-- ##### FUNCTION gtk_accel_label_refetch ##### -->
 <para>
-
+Recreates the string representing the accelerator keys.
+This should not be needed since the string is automatically updated whenever
+accelerators are added or removed from the associated widget.
 </para>
 
-@accel_label: 
-@Returns: 
+@accel_label: a #GtkAccelLabel.
+@Returns: always returns FALSE.
 
 
 <!-- ##### ARG GtkAccelLabel:accel_widget ##### -->
 <para>
-
+The widget whose accelerators are to be shown by the #GtkAccelLabel.
 </para>
 
diff --git a/docs/reference/gtk/tmpl/gtkadjustment.sgml b/docs/reference/gtk/tmpl/gtkadjustment.sgml
index 4d8540ad4..bef714965 100644
--- a/docs/reference/gtk/tmpl/gtkadjustment.sgml
+++ b/docs/reference/gtk/tmpl/gtkadjustment.sgml
@@ -78,13 +78,6 @@ In a #GtkScrollbar this is the size of the area which is currently visible.
 
 </para>
 
-@data: 
-@lower: 
-@upper: 
-@value: 
-@step_increment: 
-@page_increment: 
-@page_size: 
 
 <!-- ##### FUNCTION gtk_adjustment_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkalignment.sgml b/docs/reference/gtk/tmpl/gtkalignment.sgml
index 5a2b5b51a..39338e9bb 100644
--- a/docs/reference/gtk/tmpl/gtkalignment.sgml
+++ b/docs/reference/gtk/tmpl/gtkalignment.sgml
@@ -33,11 +33,6 @@ The #GtkAlignment-struct struct contains private data only, and should
 be accessed using the functions below.
 </para>
 
-@bin: 
-@xalign: 
-@yalign: 
-@xscale: 
-@yscale: 
 
 <!-- ##### FUNCTION gtk_alignment_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkarrow.sgml b/docs/reference/gtk/tmpl/gtkarrow.sgml
index 4aef9526a..dd3eaf25b 100644
--- a/docs/reference/gtk/tmpl/gtkarrow.sgml
+++ b/docs/reference/gtk/tmpl/gtkarrow.sgml
@@ -56,9 +56,6 @@ an application.)
 </tbody></tgroup></informaltable>
 </para>
 
-@misc: 
-@arrow_type: 
-@shadow_type: 
 
 <!-- ##### FUNCTION gtk_arrow_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkaspectframe.sgml b/docs/reference/gtk/tmpl/gtkaspectframe.sgml
index 868a48868..4abe32b7c 100644
--- a/docs/reference/gtk/tmpl/gtkaspectframe.sgml
+++ b/docs/reference/gtk/tmpl/gtkaspectframe.sgml
@@ -25,12 +25,6 @@ a frame around the child. The frame will be
 
 </para>
 
-@frame: 
-@xalign: 
-@yalign: 
-@ratio: 
-@obey_child: 
-@center_allocation: 
 
 <!-- ##### FUNCTION gtk_aspect_frame_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkbbox.sgml b/docs/reference/gtk/tmpl/gtkbbox.sgml
index 4d77c5b25..a73be1256 100644
--- a/docs/reference/gtk/tmpl/gtkbbox.sgml
+++ b/docs/reference/gtk/tmpl/gtkbbox.sgml
@@ -1,10 +1,10 @@
-<!-- ##### SECTION Title ##### -->
-GtkButtonBox
-
-<!-- ##### SECTION Short_Description ##### -->
-Base class for #GtkHButtonBox and #GtkVButtonBox
-
-<!-- ##### SECTION Long_Description ##### -->
+<!-- ##### SECTION Title ##### -->
+GtkButtonBox
+
+<!-- ##### SECTION Short_Description ##### -->
+Base class for #GtkHButtonBox and #GtkVButtonBox
+
+<!-- ##### SECTION Long_Description ##### -->
 <para>
 The primary purpose of this class is to keep track of the various properties
 of #GtkHButtonBox and #GtkVButtonBox widgets.
@@ -41,9 +41,9 @@ used to spread the buttons in a button box across the container, respectively.
 
 <para>
 
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
 <para>
 <variablelist>
 <varlistentry>
@@ -55,141 +55,148 @@ used to spread the buttons in a button box across the container, respectively.
 <listitem><para>Horizontal sub-class of #GtkButtonBox.</para></listitem>
 </varlistentry>
 </variablelist>
-</para>
-
-<!-- ##### STRUCT GtkButtonBox ##### -->
+</para>
+
+<!-- ##### STRUCT GtkButtonBox ##### -->
 <para>
 This is a read-only struct; no members should be modified directly.
-</para>
-
-
-<!-- ##### MACRO GTK_BUTTONBOX_DEFAULT ##### -->
+</para>
+
+
+<!-- ##### MACRO GTK_BUTTONBOX_DEFAULT ##### -->
 <para>
 Used internally only.
-</para>
-
-
-
-<!-- ##### FUNCTION gtk_button_box_get_child_size_default ##### -->
+</para>
+
+
+
+<!-- ##### FUNCTION gtk_button_box_get_child_size_default ##### -->
 <para>
 Retrieves the default minimum width and height for all button boxes, and
 places the values in @min_width and @min_height, respectively.
-</para>
-
-@min_width: the default minimum width of a child widget.
-@min_height: the default minimum height of a child widget.
-
-
-<!-- ##### FUNCTION gtk_button_box_get_child_ipadding_default ##### -->
+</para>
+
+@min_width: the default minimum width of a child widget.
+@min_height: the default minimum height of a child widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_get_child_ipadding_default ##### -->
 <para>
 The internal padding of a button is the amount of space between the outside
 of the button and the widget it contains. This function gets the default
 amount of horizontal and vertical padding, placing the results in @ipad_x
 and @ipad_y, respectively.
-</para>
-
-@ipad_x: the default horizontal internal button padding.
-@ipad_y: the default vertical internal button padding.
-
-
-<!-- ##### FUNCTION gtk_button_box_set_child_size_default ##### -->
+</para>
+
+@ipad_x: the default horizontal internal button padding.
+@ipad_y: the default vertical internal button padding.
+
+
+<!-- ##### FUNCTION gtk_button_box_set_child_size_default ##### -->
 <para>
 Sets the default size of child buttons.
-</para>
-
-@min_width: minimum default width for child buttons.
-@min_height: minimum default height for child buttons.
-
-
-<!-- ##### FUNCTION gtk_button_box_set_child_ipadding_default ##### -->
+</para>
+
+@min_width: minimum default width for child buttons.
+@min_height: minimum default height for child buttons.
+
+
+<!-- ##### FUNCTION gtk_button_box_set_child_ipadding_default ##### -->
 <para>
 Sets the default number of pixels that pad each button in every button box.
-</para>
-
-@ipad_x: new default horizontal padding.
-@ipad_y: new default vertical padding.
-
-
-<!-- ##### FUNCTION gtk_button_box_get_spacing ##### -->
+</para>
+
+@ipad_x: new default horizontal padding.
+@ipad_y: new default vertical padding.
+
+
+<!-- ##### FUNCTION gtk_button_box_get_spacing ##### -->
 <para>
 Retrieves how much space a button box is placing between each child button.
-</para>
-
-@widget: a #GtkButtonBox.
-@Returns: the current spacing applied to the buttons in @widget.
-
-
-<!-- ##### FUNCTION gtk_button_box_get_layout ##### -->
+</para>
+
+@widget: a #GtkButtonBox.
+@Returns: the current spacing applied to the buttons in @widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_get_layout ##### -->
 <para>
 Retrieves the method being used to arrange the buttons in a button box.
-</para>
-
-@widget: a #GtkButtonBox.
-@Returns: the method used to layout buttons in @widget.
-
-
-<!-- ##### FUNCTION gtk_button_box_get_child_size ##### -->
+</para>
+
+@widget: a #GtkButtonBox.
+@Returns: the method used to layout buttons in @widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_get_child_size ##### -->
 <para>
 Retrieves the current width and height of all child widgets in a button box.
 @min_width and @min_height are filled with those values, respectively.
-</para>
-
-@widget: a #GtkButtonBox.
-@min_width: the width of the buttons contained by @widget.
-@min_height: the height of the buttons contained by @widget.
-
-
-<!-- ##### FUNCTION gtk_button_box_get_child_ipadding ##### -->
+</para>
+
+@widget: a #GtkButtonBox.
+@min_width: the width of the buttons contained by @widget.
+@min_height: the height of the buttons contained by @widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_get_child_ipadding ##### -->
 <para>
 Gets the default number of pixels that pad the buttons in a given button box.
-</para>
-
-@widget: a #GtkButtonBox.
-@ipad_x: the horizontal padding used by buttons in @widget.
-@ipad_y: the vertical padding used by buttons in @widget.
-
-
-<!-- ##### FUNCTION gtk_button_box_set_spacing ##### -->
+</para>
+
+@widget: a #GtkButtonBox.
+@ipad_x: the horizontal padding used by buttons in @widget.
+@ipad_y: the vertical padding used by buttons in @widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_set_spacing ##### -->
 <para>
 Sets the amount of spacing between buttons in a given button box.
-</para>
-
-@widget: a #GtkButtonBox.
-@spacing: the number of pixels of spacing.
-
-
-<!-- ##### FUNCTION gtk_button_box_set_layout ##### -->
+</para>
+
+@widget: a #GtkButtonBox.
+@spacing: the number of pixels of spacing.
+
+
+<!-- ##### FUNCTION gtk_button_box_set_layout ##### -->
 <para>
 Changes the way buttons are arranged in their container.
-</para>
-
-@widget: a #GtkButtonBox.
-@layout_style: the new layout style.
-
-
-<!-- ##### FUNCTION gtk_button_box_set_child_size ##### -->
+</para>
+
+@widget: a #GtkButtonBox.
+@layout_style: the new layout style.
+
+
+<!-- ##### FUNCTION gtk_button_box_set_child_size ##### -->
 <para>
 Sets a new default size for the children of a given button box.
-</para>
-
-@widget: a #GtkButtonBox.
-@min_width: a default width for buttons in @widget.
-@min_height: a default height for buttons in @widget.
-
-
-<!-- ##### FUNCTION gtk_button_box_set_child_ipadding ##### -->
+</para>
+
+@widget: a #GtkButtonBox.
+@min_width: a default width for buttons in @widget.
+@min_height: a default height for buttons in @widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_set_child_ipadding ##### -->
 <para>
 Changes the amount of internal padding used by all buttons in a given button
 box.
-</para>
-
-@widget: a #GtkButtonBox.
-@ipad_x: the horizontal padding that should be used by each button in @widget.
-@ipad_y: the vertical padding that should be used by each button in @widget.
-
-
-<!-- ##### FUNCTION gtk_button_box_child_requisition ##### -->
+</para>
+
+@widget: a #GtkButtonBox.
+@ipad_x: the horizontal padding that should be used by each button in @widget.
+@ipad_y: the vertical padding that should be used by each button in @widget.
+
+
+<!-- ##### FUNCTION gtk_button_box_child_requisition ##### -->
 <para>
 This is an internally used function and should never be called from an
 application.
-</para>
+</para>
+
+@widget: 
+@nvis_children: 
+@width: 
+@height: 
+
+
diff --git a/docs/reference/gtk/tmpl/gtkbin.sgml b/docs/reference/gtk/tmpl/gtkbin.sgml
index 1aa48ce5a..400fc8e2b 100644
--- a/docs/reference/gtk/tmpl/gtkbin.sgml
+++ b/docs/reference/gtk/tmpl/gtkbin.sgml
@@ -39,6 +39,4 @@ an application.)
 
 </para>
 
-@container: 
-@child: 
 
diff --git a/docs/reference/gtk/tmpl/gtkbox.sgml b/docs/reference/gtk/tmpl/gtkbox.sgml
index 191b7a963..442da3120 100644
--- a/docs/reference/gtk/tmpl/gtkbox.sgml
+++ b/docs/reference/gtk/tmpl/gtkbox.sgml
@@ -131,10 +131,6 @@ field.</entry>
 </tbody></tgroup></informaltable>
 </para>
 
-@container: 
-@children: 
-@spacing: 
-@homogeneous: 
 
 <!-- ##### STRUCT GtkBoxChild ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkbutton.sgml b/docs/reference/gtk/tmpl/gtkbutton.sgml
index 32a88b5c4..7438cf40c 100644
--- a/docs/reference/gtk/tmpl/gtkbutton.sgml
+++ b/docs/reference/gtk/tmpl/gtkbutton.sgml
@@ -26,11 +26,6 @@ the #GtkLabel.
 This should not be accessed directly.  Use the accessor functions below.
 </para>
 
-@bin: 
-@child: 
-@in_button: 
-@button_down: 
-@relief: 
 
 <!-- ##### FUNCTION gtk_button_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkcalendar.sgml b/docs/reference/gtk/tmpl/gtkcalendar.sgml
index 4ca84c283..b7bc32649 100644
--- a/docs/reference/gtk/tmpl/gtkcalendar.sgml
+++ b/docs/reference/gtk/tmpl/gtkcalendar.sgml
@@ -57,26 +57,6 @@ All of these fields should be considered read only, and everything in this
 struct should only be modified using the functions provided below.
 </para>
 
-@widget: 
-@header_style: 
-@label_style: 
-@month: 
-@year: 
-@selected_day: 
-@day_month: 
-@day: 
-@num_marked_dates: 
-@marked_date: 
-@display_flags: 
-@marked_date_color: 
-@gc: 
-@xor_gc: 
-@focus_row: 
-@focus_col: 
-@highlight_row: 
-@highlight_col: 
-@private_data: 
-@grow_space: 
 
 <!-- ##### ENUM GtkCalendarDisplayOptions ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkcheckbutton.sgml b/docs/reference/gtk/tmpl/gtkcheckbutton.sgml
index bdbbbf7ab..cf2929b1d 100644
--- a/docs/reference/gtk/tmpl/gtkcheckbutton.sgml
+++ b/docs/reference/gtk/tmpl/gtkcheckbutton.sgml
@@ -39,7 +39,6 @@ The important signal ('toggled') is also inherited from #GtkToggleButton.
 <structfield>toggle_button</structfield> is a #GtkToggleButton representing the actual toggle button that composes the check button.
 </para>
 
-@toggle_button: 
 
 <!-- ##### FUNCTION gtk_check_button_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkcheckmenuitem.sgml b/docs/reference/gtk/tmpl/gtkcheckmenuitem.sgml
index 451e0cf7a..0cbac1879 100644
--- a/docs/reference/gtk/tmpl/gtkcheckmenuitem.sgml
+++ b/docs/reference/gtk/tmpl/gtkcheckmenuitem.sgml
@@ -40,9 +40,6 @@ an application.)
 </tbody></tgroup></informaltable>
 </para>
 
-@menu_item: 
-@active: 
-@always_show_toggle: 
 
 <!-- ##### FUNCTION gtk_check_menu_item_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkclist.sgml b/docs/reference/gtk/tmpl/gtkclist.sgml
index 6c6d8a4a2..0c5263ce8 100644
--- a/docs/reference/gtk/tmpl/gtkclist.sgml
+++ b/docs/reference/gtk/tmpl/gtkclist.sgml
@@ -19,52 +19,6 @@ GtkCList
 
 </para>
 
-@container: 
-@flags: 
-@row_mem_chunk: 
-@cell_mem_chunk: 
-@freeze_count: 
-@internal_allocation: 
-@rows: 
-@row_center_offset: 
-@row_height: 
-@row_list: 
-@row_list_end: 
-@columns: 
-@column_title_area: 
-@title_window: 
-@column: 
-@clist_window: 
-@clist_window_width: 
-@clist_window_height: 
-@hoffset: 
-@voffset: 
-@shadow_type: 
-@selection_mode: 
-@selection: 
-@selection_end: 
-@undo_selection: 
-@undo_unselection: 
-@undo_anchor: 
-@button_actions: 
-@drag_button: 
-@click_cell: 
-@hadjustment: 
-@vadjustment: 
-@xor_gc: 
-@fg_gc: 
-@bg_gc: 
-@cursor_drag: 
-@x_drag: 
-@focus_row: 
-@anchor: 
-@anchor_state: 
-@drag_pos: 
-@htimer: 
-@vtimer: 
-@sort_type: 
-@compare: 
-@sort_column: 
 
 <!-- ##### ENUM GtkCellType ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkcolorsel.sgml b/docs/reference/gtk/tmpl/gtkcolorsel.sgml
index 819a072de..e6e059f91 100644
--- a/docs/reference/gtk/tmpl/gtkcolorsel.sgml
+++ b/docs/reference/gtk/tmpl/gtkcolorsel.sgml
@@ -19,26 +19,6 @@ GtkColorSelection
 
 </para>
 
-@vbox: 
-@wheel_area: 
-@value_area: 
-@sample_area: 
-@sample_area_eb: 
-@scales: 
-@entries: 
-@opacity_label: 
-@wheel_gc: 
-@value_gc: 
-@sample_gc: 
-@policy: 
-@use_opacity: 
-@timer_active: 
-@timer_tag: 
-@values: 
-@old_values: 
-@wheel_buf: 
-@value_buf: 
-@sample_buf: 
 
 <!-- ##### FUNCTION gtk_color_selection_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkcolorseldlg.sgml b/docs/reference/gtk/tmpl/gtkcolorseldlg.sgml
index 2dc847a65..8a2f81963 100644
--- a/docs/reference/gtk/tmpl/gtkcolorseldlg.sgml
+++ b/docs/reference/gtk/tmpl/gtkcolorseldlg.sgml
@@ -19,13 +19,6 @@ GtkColorSelectionDialog
 
 </para>
 
-@window: 
-@colorsel: 
-@main_vbox: 
-@ok_button: 
-@reset_button: 
-@cancel_button: 
-@help_button: 
 
 <!-- ##### FUNCTION gtk_color_selection_dialog_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkcombo.sgml b/docs/reference/gtk/tmpl/gtkcombo.sgml
index ce8e542db..7113bbe6e 100644
--- a/docs/reference/gtk/tmpl/gtkcombo.sgml
+++ b/docs/reference/gtk/tmpl/gtkcombo.sgml
@@ -2,12 +2,86 @@
 GtkCombo
 
 <!-- ##### SECTION Short_Description ##### -->
-
+a text entry field with a dropdown list.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The #GtkCombo widget consists of a single-line text entry field and a drop-down
+list. The drop-down list is displayed when the user clicks on a small arrow
+button to the right of the entry field.
+</para>
+<para>
+The drop-down list is a #GtkList widget and can be accessed using the
+<structfield>list</structfield> member of the #GtkCombo-struct.
+List elements can contain arbitrary widgets, but if an element is not a
+plain label, then you must use the gtk_list_set_item_string() function.
+This sets the string which will be placed in the text entry field when the
+item is selected.
+</para>
+<para>
+By default, the user can step through the items in the list using the
+arrow (cursor) keys, though this behaviour can be turned off with
+gtk_combo_set_use_arrows().
 </para>
+<para>
+Normally the arrow keys are only active when the contents of the text entry
+field matches one of the items in the list. If the contents of the entry field
+do not match any of the list items, then pressing the arrow keys does nothing.
+However, by calling gtk_combo_set_use_arrows_always() you can specify that the
+arrow keys are always active. If the contents of the entry field does not match
+any of the items in the list, then pressing the up or down arrow key will set
+the entry field to the last or first item in the list, respectively.
+</para>
+
+<example id="gtkcombo-simple-example">
+<title>Creating a #GtkCombo widget with simple text items.</title>
+<programlisting>
+  GtkWidget *combo;
+  GList *items = NULL;
+
+  items = g_list_append (items, "First Item");
+  items = g_list_append (items, "Second Item");
+  items = g_list_append (items, "Third Item");
+  items = g_list_append (items, "Fourth Item");
+  items = g_list_append (items, "Fifth Item");
+
+  combo = gtk_combo_new ();
+  gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);
+</programlisting>
+</example>
+
+<example>
+<title>Creating a #GtkCombo widget with a complex item.</title>
+<programlisting>
+  GtkWidget *combo, *item, *hbox, *arrow, *label;
+
+  combo = gtk_combo_new ();
+
+  item = gtk_list_item_new ();
+  gtk_widget_show (item);
+
+  /* You can put almost anything into the GtkListItem widget. Here we will use
+     a horizontal box with an arrow and a label in it. */
+  hbox = gtk_hbox_new (FALSE, 3);
+  gtk_container_add (GTK_CONTAINER (item), hbox);
+  gtk_widget_show (hbox);
+
+  arrow = gtk_arrow_new (GTK_ARROW_RIGHT, GTK_SHADOW_OUT);
+  gtk_widget_show (arrow);
+  gtk_box_pack_start (GTK_BOX (hbox), pixmap, FALSE, FALSE, 0);
+
+  label = gtk_label_new ("First Item");
+  gtk_widget_show (label);
+  gtk_box_pack_start (GTK_BOX (hbox), label, FALSE, FALSE, 0);
+
+  /* You must set the string to display in the entry field when the item is
+     selected. */
+  gtk_combo_set_item_string (GTK_COMBO (combo), GTK_ITEM (item), "1st Item");
+
+  /* Now we simply add the item to the combo's list. */
+  gtk_container_add (GTK_CONTAINER (GTK_COMBO (combo)->list), item);
+</programlisting>
+</example>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
@@ -16,94 +90,115 @@ GtkCombo
 
 <!-- ##### STRUCT GtkCombo ##### -->
 <para>
+The #GtkFixedChild-struct struct contains the following fields.
+(These fields should be considered read-only. They should never be set by
+an application.)
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#GtkWidget *entry;</entry>
+<entry>the text entry field.</entry>
+</row>
 
+<row>
+<entry>#GtkWidget *list;</entry>
+<entry>the list shown in the drop-down window.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
 </para>
 
-@hbox: 
-@entry: 
-@button: 
-@popup: 
-@popwin: 
-@list: 
-@entry_change_id: 
-@list_change_id: 
-@value_in_list: 
-@ok_if_empty: 
-@case_sensitive: 
-@use_arrows: 
-@use_arrows_always: 
-@current_button: 
-@activate_id: 
 
 <!-- ##### FUNCTION gtk_combo_new ##### -->
 <para>
+Creates a new #GtkCombo.
+</para>
 
+@Returns: a new #GtkCombo.
+
+
+<!-- ##### FUNCTION gtk_combo_set_popdown_strings ##### -->
+<para>
+Convenience function to set all of the items in the popup list.
+(See the <link linkend="gtkcombo-simple-example">example</link> above.)
 </para>
 
-@Returns: 
+@combo: a #GtkCombo.
+@strings: a list of strings.
 
 
 <!-- ##### FUNCTION gtk_combo_set_value_in_list ##### -->
 <para>
-
+Specifies whether the value entered in the text entry field must match one of
+the values in the list. If this is set then the user will not be able to
+perform any other action until a valid value has been entered.
+</para>
+<para>
+If an empty field is acceptable, the @ok_if_empty parameter should be TRUE.
 </para>
 
-@combo: 
-@val: 
-@ok_if_empty: 
+@combo: a #GtkCombo.
+@val: TRUE if the value entered must match one of the values in the list.
+@ok_if_empty: TRUE if an empty value is considered valid.
 
 
 <!-- ##### FUNCTION gtk_combo_set_use_arrows ##### -->
 <para>
-
+Specifies if the arrow (cursor) keys can be used to step through the items in
+the list. This is on by default.
 </para>
 
-@combo: 
-@val: 
+@combo: a #GtkCombo.
+@val: TRUE if the arrow keys can be used to step through the items in the list.
 
 
 <!-- ##### FUNCTION gtk_combo_set_use_arrows_always ##### -->
 <para>
-
+Specifies if the arrow keys will still work even if the current contents of the
+#GtkEntry field do not match any of the list items. 
 </para>
 
-@combo: 
+@combo: a #GtkCombo.
 @val: 
 
 
 <!-- ##### FUNCTION gtk_combo_set_case_sensitive ##### -->
 <para>
-
+Specifies whether the text entered into the #GtkEntry field and the text in
+the list items is case sensitive.
 </para>
-
-@combo: 
-@val: 
-
-
-<!-- ##### FUNCTION gtk_combo_set_item_string ##### -->
 <para>
-
+This may be useful, for example, when you have called
+gtk_combo_set_value_in_list() to limit the values entered, but you are not
+worried about differences in case.
 </para>
 
-@combo: 
-@item: 
-@item_value: 
+@combo: a #GtkCombo.
+@val: 
 
 
-<!-- ##### FUNCTION gtk_combo_set_popdown_strings ##### -->
+<!-- ##### FUNCTION gtk_combo_set_item_string ##### -->
 <para>
-
+Sets the string to place in the #GtkEntry field when a particular list item is
+selected. This is needed if the list item is not a simple label.
 </para>
 
-@combo: 
-@strings: 
+@combo: a #GtkCombo.
+@item: a #GtkItem which
+@item_value: the string to place in the #GtkEntry when @item is selected.
 
 
 <!-- ##### FUNCTION gtk_combo_disable_activate ##### -->
 <para>
-
+Stops the #GtkCombo widget from showing the popup list when the #GtkEntry
+emits the "activate" signal, i.e. when the Return key is pressed.
+This may be useful if, for example. you want the Return key to close a dialog
+instead.
 </para>
 
-@combo: 
+@combo: a #GtkCombo.
 
 
diff --git a/docs/reference/gtk/tmpl/gtkcontainer.sgml b/docs/reference/gtk/tmpl/gtkcontainer.sgml
index 3786dce30..d6782383c 100644
--- a/docs/reference/gtk/tmpl/gtkcontainer.sgml
+++ b/docs/reference/gtk/tmpl/gtkcontainer.sgml
@@ -19,12 +19,6 @@ GtkContainer
 
 </para>
 
-@widget: 
-@focus_child: 
-@border_width: 
-@need_resize: 
-@resize_mode: 
-@resize_widgets: 
 
 <!-- ##### MACRO GTK_IS_RESIZE_CONTAINER ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkctree.sgml b/docs/reference/gtk/tmpl/gtkctree.sgml
index 32de3679e..1979f30d3 100644
--- a/docs/reference/gtk/tmpl/gtkctree.sgml
+++ b/docs/reference/gtk/tmpl/gtkctree.sgml
@@ -74,15 +74,6 @@ node.</entry>
 </tbody></tgroup></informaltable>
 </para>
 
-@clist: 
-@lines_gc: 
-@tree_indent: 
-@tree_spacing: 
-@tree_column: 
-@line_style: 
-@expander_style: 
-@show_stub: 
-@drag_compare: 
 
 <!-- ##### MACRO GTK_CTREE_ROW ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkcurve.sgml b/docs/reference/gtk/tmpl/gtkcurve.sgml
index b8119415b..a056d270d 100644
--- a/docs/reference/gtk/tmpl/gtkcurve.sgml
+++ b/docs/reference/gtk/tmpl/gtkcurve.sgml
@@ -2,107 +2,123 @@
 GtkCurve
 
 <!-- ##### SECTION Short_Description ##### -->
-
+allows direct editing of a curve.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The #GtkCurve widget allows the user to edit a curve covering a range of
+values. It is typically used to fine-tune color balances in graphics
+applications like the Gimp.
+</para>
+<para>
+The #GtkCurve widget has 3 modes of operation - spline, linear and free.
+In spline mode the user places points on the curve which are automatically
+connected together into a smooth curve. In linear mode the user places points
+on the curve which are connected by straight lines. In free mode the user can
+draw the points of the curve freely, and they are not connected at all.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
+<variablelist>
+<varlistentry>
+<term>#GtkGammaCurve</term>
+<listitem><para>a subclass for editing gamma curves.
+</listitem>
+</varlistentry>
+</variablelist>
 
 </para>
 
 <!-- ##### STRUCT GtkCurve ##### -->
 <para>
-
+The #GtkCurve-struct struct contains private data only, and
+should be accessed using the functions below.
 </para>
 
-@graph: 
-@cursor_type: 
-@min_x: 
-@max_x: 
-@min_y: 
-@max_y: 
-@pixmap: 
-@curve_type: 
-@height: 
-@grab_point: 
-@last: 
-@num_points: 
-@point: 
-@num_ctlpoints: 
 
 <!-- ##### FUNCTION gtk_curve_new ##### -->
 <para>
-
+Creates a new #GtkCurve.
 </para>
 
-@Returns: 
+@Returns: a new #GtkCurve.
 
 
 <!-- ##### FUNCTION gtk_curve_reset ##### -->
 <para>
-
+Resets the curve to a straight line from the minimum x & y values to the
+maximum x & y values (i.e. from the bottom-left to the top-right corners).
+The curve type is not changed.
 </para>
 
-@curve: 
+@curve: a #GtkCurve.
 
 
 <!-- ##### FUNCTION gtk_curve_set_gamma ##### -->
 <para>
-
+Recomputes the entire curve using the given gamma value.
+A gamma value of 1 results in a straight line. Values greater than 1 result
+in a curve above the straight line. Values less than 1 result in a curve
+below the straight line. The curve type is changed to %GTK_CURVE_TYPE_FREE.
+FIXME: Needs a more precise definition of gamma.
 </para>
 
-@curve: 
-@gamma: 
+@curve: a #GtkCurve.
+@gamma: the gamma value.
 
 
 <!-- ##### FUNCTION gtk_curve_set_range ##### -->
 <para>
-
+Sets the minimum and maximum x & y values of the curve.
+The curve is also reset with a call to gtk_curve_reset().
 </para>
 
-@curve: 
-@min_x: 
-@max_x: 
-@min_y: 
-@max_y: 
+@curve: a #GtkCurve.
+@min_x: the minimum x value.
+@max_x: the maximum x value.
+@min_y: the minimum y value.
+@max_y: the maximum y value.
 
 
 <!-- ##### FUNCTION gtk_curve_get_vector ##### -->
 <para>
-
+Returns a vector of points representing the curve.
 </para>
 
-@curve: 
-@veclen: 
-@vector: 
+@curve: a #GtkCurve.
+@veclen: the number of points to calculate.
+@vector: returns the points.
 
 
 <!-- ##### FUNCTION gtk_curve_set_vector ##### -->
 <para>
-
+Sets the vector of points on the curve.
+The curve type is set to %GTK_CURVE_TYPE_FREE.
 </para>
 
-@curve: 
-@veclen: 
-@vector: 
+@curve: a #GtkCurve.
+@veclen: the number of points.
+@vector: the points on the curve.
 
 
 <!-- ##### FUNCTION gtk_curve_set_curve_type ##### -->
 <para>
-
+Sets the type of the curve. The curve will remain unchanged except when
+changing from a free curve to a linear or spline curve, in which case the
+curve will be changed as little as possible.
 </para>
 
-@curve: 
-@type: 
+@curve: a #GtkCurve.
+@type: the type of the curve.
 
 
 <!-- ##### SIGNAL GtkCurve::curve-type-changed ##### -->
 <para>
-
+Emitted when the curve type has been changed.
+The curve type can be changed explicitly with a call to
+gtk_curve_set_curve_type(). It is also changed as a side-effect of
+calling gtk_curve_reset() or gtk_curve_set_gamma().
 </para>
 
 @curve: the object which received the signal.
diff --git a/docs/reference/gtk/tmpl/gtkdata.sgml b/docs/reference/gtk/tmpl/gtkdata.sgml
index 2da64638d..e24459d5d 100644
--- a/docs/reference/gtk/tmpl/gtkdata.sgml
+++ b/docs/reference/gtk/tmpl/gtkdata.sgml
@@ -2,11 +2,19 @@
 GtkData
 
 <!-- ##### SECTION Short_Description ##### -->
-
+abstract base class for objects containing data.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The #GtkData object is a very simple object intended to be used as a base
+class for objects which contain data (i.e. the 'Model' in the object-oriented
+Model/View/Controller framework).
+</para>
+<para>
+Currently it is not very useful since all it provides is a "disconnect" signal.
+This signal could be emitted by a #GtkData subclass to notify any 'Views'
+that they should disconnect from the #GtkData (the 'Model'), possibly just
+before the #GtkData is destroyed.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,14 +24,14 @@ GtkData
 
 <!-- ##### STRUCT GtkData ##### -->
 <para>
-
+The #GtkData-struct struct contains no public fields.
 </para>
 
-@object: 
 
 <!-- ##### SIGNAL GtkData::disconnect ##### -->
 <para>
-
+Emitted to notify any views on the #GtkData object to disconnect from it,
+possibly because the #GtkData object is about to be destroyed.
 </para>
 
 @data: the object which received the signal.
diff --git a/docs/reference/gtk/tmpl/gtkdialog.sgml b/docs/reference/gtk/tmpl/gtkdialog.sgml
index 2ce535540..9c0b70947 100644
--- a/docs/reference/gtk/tmpl/gtkdialog.sgml
+++ b/docs/reference/gtk/tmpl/gtkdialog.sgml
@@ -101,9 +101,6 @@ gtk_window_set_title(). See the #GtkWindow section for more).
 <structfield>action_area</structfield> is a #GtkHBox packed below the dividing #GtkHSeparator in the dialog. It is treated exactly the same as any other #GtkHBox.
 </para>
 
-@window: 
-@vbox: 
-@action_area: 
 
 <!-- ##### STRUCT GtkDialogButton ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkdrawingarea.sgml b/docs/reference/gtk/tmpl/gtkdrawingarea.sgml
index cc9800dec..94cf07e04 100644
--- a/docs/reference/gtk/tmpl/gtkdrawingarea.sgml
+++ b/docs/reference/gtk/tmpl/gtkdrawingarea.sgml
@@ -85,8 +85,6 @@ The #GtkDrawingArea-struct struct contains private data only, and
 should be accessed using the functions below.
 </para>
 
-@widget: 
-@draw_data: 
 
 <!-- ##### FUNCTION gtk_drawing_area_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkeditable.sgml b/docs/reference/gtk/tmpl/gtkeditable.sgml
index f822b3bfe..0d292c9e5 100644
--- a/docs/reference/gtk/tmpl/gtkeditable.sgml
+++ b/docs/reference/gtk/tmpl/gtkeditable.sgml
@@ -91,16 +91,10 @@ editable by the user.</entry>
 </tbody></tgroup></informaltable>
 </para>
 
-@widget: 
 @current_pos: 
 @selection_start_pos: 
 @selection_end_pos: 
 @has_selection: 
-@editable: 
-@visible: 
-@ic: 
-@ic_attr: 
-@clipboard_text: 
 
 <!-- ##### USER_FUNCTION GtkTextFunction ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkentry.sgml b/docs/reference/gtk/tmpl/gtkentry.sgml
index 0552539a3..73d3b2273 100644
--- a/docs/reference/gtk/tmpl/gtkentry.sgml
+++ b/docs/reference/gtk/tmpl/gtkentry.sgml
@@ -30,22 +30,6 @@ position is visible.
 The #GtkEntry-struct struct contains only private data.
 </para>
 
-@editable: 
-@text_area: 
-@backing_pixmap: 
-@cursor: 
-@text: 
-@text_size: 
-@text_length: 
-@text_max_length: 
-@scroll_offset: 
-@visible: 
-@timer: 
-@button: 
-@char_offset: 
-@text_mb: 
-@text_mb_dirty: 
-@use_wchar: 
 
 <!-- ##### FUNCTION gtk_entry_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkenums.sgml b/docs/reference/gtk/tmpl/gtkenums.sgml
index 5b8b1ede8..33ffe7f81 100644
--- a/docs/reference/gtk/tmpl/gtkenums.sgml
+++ b/docs/reference/gtk/tmpl/gtkenums.sgml
@@ -107,15 +107,6 @@ Standard Enumerations
 @GTK_MATCH_EXACT: 
 @GTK_MATCH_LAST: 
 
-<!-- ##### ENUM GtkMenuFactoryType ##### -->
-<para>
-
-</para>
-
-@GTK_MENU_FACTORY_MENU: 
-@GTK_MENU_FACTORY_MENU_BAR: 
-@GTK_MENU_FACTORY_OPTION_MENU: 
-
 <!-- ##### ENUM GtkMetricType ##### -->
 <para>
 
@@ -224,18 +215,6 @@ contains grayscale or red-green-blue data.
 @GTK_RESIZE_QUEUE: 
 @GTK_RESIZE_IMMEDIATE: 
 
-<!-- ##### ENUM GtkSignalRunType ##### -->
-<para>
-
-</para>
-
-@GTK_RUN_FIRST: 
-@GTK_RUN_LAST: 
-@GTK_RUN_BOTH: 
-@GTK_RUN_NO_RECURSE: 
-@GTK_RUN_ACTION: 
-@GTK_RUN_NO_HOOKS: 
-
 <!-- ##### ENUM GtkScrollType ##### -->
 <para>
 
diff --git a/docs/reference/gtk/tmpl/gtkeventbox.sgml b/docs/reference/gtk/tmpl/gtkeventbox.sgml
index 463a9f996..8dc8fbcd9 100644
--- a/docs/reference/gtk/tmpl/gtkeventbox.sgml
+++ b/docs/reference/gtk/tmpl/gtkeventbox.sgml
@@ -22,7 +22,6 @@ The #GtkEventBox-struct struct contains private data only, and
 should be accessed using the functions below.
 </para>
 
-@bin: 
 
 <!-- ##### FUNCTION gtk_event_box_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkfeatures.sgml b/docs/reference/gtk/tmpl/gtkfeatures.sgml
index bf8520788..b1d62c477 100644
--- a/docs/reference/gtk/tmpl/gtkfeatures.sgml
+++ b/docs/reference/gtk/tmpl/gtkfeatures.sgml
@@ -1,12 +1,14 @@
 <!-- ##### SECTION Title ##### -->
-Feature Test Macros
+Version Information
 
 <!-- ##### SECTION Short_Description ##### -->
-
+variables and functions to check the GTK+ version.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+This section describes the variables and functions available to test the
+version of the GTK+ library in use.
+FIXME: probably merge with other general stuff.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,19 +18,22 @@ Feature Test Macros
 
 <!-- ##### VARIABLE gtk_major_version ##### -->
 <para>
-
+The major version number of the GTK+ library.
+(e.g. in GTK+ version 1.2.5 this is 1.)
 </para>
 
 
 <!-- ##### VARIABLE gtk_minor_version ##### -->
 <para>
-
+The minor version number of the GTK+ library.
+(e.g. in GTK+ version 1.2.5 this is 2.)
 </para>
 
 
 <!-- ##### VARIABLE gtk_micro_version ##### -->
 <para>
-
+The micro version number of the GTK+ library.
+(e.g. in GTK+ version 1.2.5 this is 5.)
 </para>
 
 
@@ -46,12 +51,13 @@ Feature Test Macros
 
 <!-- ##### FUNCTION gtk_check_version ##### -->
 <para>
-
+Checks that the GTK+ library in use is compatable with the given version.
 </para>
 
-@required_major: 
-@required_minor: 
-@required_micro: 
-@Returns: 
+@required_major: the required major version.
+@required_minor: the required major version.
+@required_micro: the required major version.
+@Returns: NULL if the GTK+ library is compatable with the given version, or
+a string describing the version mismatch.
 
 
diff --git a/docs/reference/gtk/tmpl/gtkfilesel.sgml b/docs/reference/gtk/tmpl/gtkfilesel.sgml
index 6a36d803b..9ac71c75c 100644
--- a/docs/reference/gtk/tmpl/gtkfilesel.sgml
+++ b/docs/reference/gtk/tmpl/gtkfilesel.sgml
@@ -40,16 +40,16 @@ void create_file_selection(void) {
    
    file_selector = gtk_file_selection_new("Please select a file for editing.");
    
-   gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->ok_button)),
+   gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->ok_button),
    			   "clicked", GTK_SIGNAL_FUNC (store_filename), NULL);
    			   
    /* Ensure that the dialog box is destroyed when the user clicks a button. */
    
-   gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->ok_button)),
+   gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->ok_button),
    					  "clicked", GTK_SIGNAL_FUNC (gtk_widget_destroy),
    					  (gpointer) file_selector);
 
-   gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->cancel_button)),
+   gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->cancel_button),
    					  "clicked", GTK_SIGNAL_FUNC (gtk_widget_destroy),
    					  (gpointer) file_selector);
    
@@ -110,27 +110,6 @@ The #GtkFileSelection struct contains the following #GtkWidget fields:
 
 </para>
 
-@window: 
-@dir_list: 
-@file_list: 
-@selection_entry: 
-@selection_text: 
-@main_vbox: 
-@ok_button: 
-@cancel_button: 
-@help_button: 
-@history_pulldown: 
-@history_menu: 
-@history_list: 
-@fileop_dialog: 
-@fileop_entry: 
-@fileop_file: 
-@cmpl_state: 
-@fileop_c_dir: 
-@fileop_del_file: 
-@fileop_ren_file: 
-@button_area: 
-@action_area: 
 
 <!-- ##### FUNCTION gtk_file_selection_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkfixed.sgml b/docs/reference/gtk/tmpl/gtkfixed.sgml
index 20f6c085a..c72b4e743 100644
--- a/docs/reference/gtk/tmpl/gtkfixed.sgml
+++ b/docs/reference/gtk/tmpl/gtkfixed.sgml
@@ -35,8 +35,6 @@ their positions.</entry>
 </tbody></tgroup></informaltable>
 </para>
 
-@container: 
-@children: 
 
 <!-- ##### STRUCT GtkFixedChild ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkfontsel.sgml b/docs/reference/gtk/tmpl/gtkfontsel.sgml
index caf3f8847..d888b18f1 100644
--- a/docs/reference/gtk/tmpl/gtkfontsel.sgml
+++ b/docs/reference/gtk/tmpl/gtkfontsel.sgml
@@ -51,37 +51,6 @@ The #GtkFontSelection struct contains private data only, and should
 only be accessed using the functions below.
 </para>
 
-@notebook: 
-@main_vbox: 
-@font_label: 
-@font_entry: 
-@font_clist: 
-@font_style_entry: 
-@font_style_clist: 
-@size_entry: 
-@size_clist: 
-@pixels_button: 
-@points_button: 
-@filter_button: 
-@preview_entry: 
-@message_label: 
-@info_vbox: 
-@info_clist: 
-@requested_font_name: 
-@actual_font_name: 
-@filter_vbox: 
-@type_bitmaps_button: 
-@type_scalable_button: 
-@type_scaled_bitmaps_button: 
-@filter_clists: 
-@font: 
-@font_index: 
-@style: 
-@metric: 
-@size: 
-@selected_size: 
-@property_values: 
-@filters: 
 
 <!-- ##### FUNCTION gtk_font_selection_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkfontseldlg.sgml b/docs/reference/gtk/tmpl/gtkfontseldlg.sgml
index 8c32d89a2..03d6b7b1f 100644
--- a/docs/reference/gtk/tmpl/gtkfontseldlg.sgml
+++ b/docs/reference/gtk/tmpl/gtkfontseldlg.sgml
@@ -71,15 +71,6 @@ The #GtkFontSelectionDialog struct contains private data only, and should
 only be accessed using the functions below.
 </para>
 
-@window: 
-@fontsel: 
-@main_vbox: 
-@action_area: 
-@ok_button: 
-@apply_button: 
-@cancel_button: 
-@dialog_width: 
-@auto_resize: 
 
 <!-- ##### FUNCTION gtk_font_selection_dialog_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkframe.sgml b/docs/reference/gtk/tmpl/gtkframe.sgml
index 492ceefc3..a675fc909 100644
--- a/docs/reference/gtk/tmpl/gtkframe.sgml
+++ b/docs/reference/gtk/tmpl/gtkframe.sgml
@@ -23,13 +23,6 @@ label can be controlled with gtk_frame_set_label_align().
 
 </para>
 
-@bin: 
-@label: 
-@shadow_type: 
-@label_width: 
-@label_height: 
-@label_xalign: 
-@label_yalign: 
 
 <!-- ##### FUNCTION gtk_frame_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkgamma.sgml b/docs/reference/gtk/tmpl/gtkgamma.sgml
index 114c74548..28f392d5c 100644
--- a/docs/reference/gtk/tmpl/gtkgamma.sgml
+++ b/docs/reference/gtk/tmpl/gtkgamma.sgml
@@ -2,11 +2,20 @@
 GtkGammaCurve
 
 <!-- ##### SECTION Short_Description ##### -->
-
+a subclass of #GtkCurve for editing gamma curves.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The #GtkGammaCurve widget is a subclass of #GtkCurve specifically for
+editing gamma curves, which are used in graphics applications such as the
+Gimp.
+</para>
+<para>
+The #GammaCurve widget shows a curve which the user can edit with the mouse
+just like a #GtkCurve widget. On the right of the curve it also displays
+5 buttons, 3 of which change between the 3 curve modes (spline, linear and
+free), and the other 2 set the curve to a particular gamma value, or reset it
+to a straight line.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,22 +25,16 @@ GtkGammaCurve
 
 <!-- ##### STRUCT GtkGammaCurve ##### -->
 <para>
-
+The #GtkGammaCurve-struct struct contains private data only, and
+should be accessed using the functions below.
 </para>
 
-@vbox: 
-@table: 
-@curve: 
-@button: 
-@gamma: 
-@gamma_dialog: 
-@gamma_text: 
 
 <!-- ##### FUNCTION gtk_gamma_curve_new ##### -->
 <para>
-
+Creates a new #GtkGammaCurve.
 </para>
 
-@Returns: 
+@Returns: a new #GtkGammaCurve.
 
 
diff --git a/docs/reference/gtk/tmpl/gtkgc.sgml b/docs/reference/gtk/tmpl/gtkgc.sgml
index e1cd99b42..7304c4912 100644
--- a/docs/reference/gtk/tmpl/gtkgc.sgml
+++ b/docs/reference/gtk/tmpl/gtkgc.sgml
@@ -2,11 +2,15 @@
 Graphics Contexts
 
 <!-- ##### SECTION Short_Description ##### -->
-
+provides access to a shared pool of #GdkGC objects.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+These functions provide access to a shared pool of #GdkGC objects.
+When a new #GdkGC is needed, gtk_gc_get() is called with the required depth,
+colormap and #GdkGCValues. If a #GdkGC with the required properties already
+exists then that is returned. If not, a new #GdkGC is created.
+When the #GdkGC is no longer needed, gtk_gc_release() is called.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,21 +20,26 @@ Graphics Contexts
 
 <!-- ##### FUNCTION gtk_gc_get ##### -->
 <para>
-
+Gets a #GdkGC with the given depth, colormap and #GdkGCValues.
+If a #GdkGC with the given properties already exists then it is returned,
+otherwise a new #GdkGC is created.
+The returned #GdkGC should be released with gtk_gc_release() when it is no
+longer needed.
 </para>
 
-@depth: 
-@colormap: 
-@values: 
-@values_mask: 
-@Returns: 
+@depth: the depth of the #GdkGC to create.
+@colormap: the #GdkColormap (FIXME: I don't know why this is needed).
+@values: a #GdkGCValues struct containing settings for the #GdkGC.
+@values_mask: a set of flags indicating which of the fields in @values has
+been set.
+@Returns: a #GdkGC.
 
 
 <!-- ##### FUNCTION gtk_gc_release ##### -->
 <para>
-
+Releases a #GdkGC allocated using gtk_gc_get().
 </para>
 
-@gc: 
+@gc: a #GdkGC.
 
 
diff --git a/docs/reference/gtk/tmpl/gtkhandlebox.sgml b/docs/reference/gtk/tmpl/gtkhandlebox.sgml
index 4257f5876..e823a7a56 100644
--- a/docs/reference/gtk/tmpl/gtkhandlebox.sgml
+++ b/docs/reference/gtk/tmpl/gtkhandlebox.sgml
@@ -76,20 +76,6 @@ child is attached or detached.</entry>
 
 </para>
 
-@bin: 
-@bin_window: 
-@float_window: 
-@shadow_type: 
-@handle_position: 
-@float_window_mapped: 
-@child_detached: 
-@in_drag: 
-@shrink_on_detach: 
-@snap_edge: 
-@deskoff_x: 
-@deskoff_y: 
-@attach_allocation: 
-@float_allocation: 
 
 <!-- ##### FUNCTION gtk_handle_box_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkhbbox.sgml b/docs/reference/gtk/tmpl/gtkhbbox.sgml
index 0a67e4445..889f2cf03 100644
--- a/docs/reference/gtk/tmpl/gtkhbbox.sgml
+++ b/docs/reference/gtk/tmpl/gtkhbbox.sgml
@@ -53,7 +53,6 @@ gtk_hbutton_box_get_layout_default().
 should not be modified directly.
 </para>
 
-@button_box: 
 
 <!-- ##### FUNCTION gtk_hbutton_box_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkhbox.sgml b/docs/reference/gtk/tmpl/gtkhbox.sgml
index 0fd5acff2..2259380f1 100644
--- a/docs/reference/gtk/tmpl/gtkhbox.sgml
+++ b/docs/reference/gtk/tmpl/gtkhbox.sgml
@@ -33,7 +33,6 @@ All children are allocated the same height.
 <!-- ##### STRUCT GtkHBox ##### -->
 
 
-@box: 
 
 <!-- ##### FUNCTION gtk_hbox_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkhpaned.sgml b/docs/reference/gtk/tmpl/gtkhpaned.sgml
index 369a0beaf..19f42a410 100644
--- a/docs/reference/gtk/tmpl/gtkhpaned.sgml
+++ b/docs/reference/gtk/tmpl/gtkhpaned.sgml
@@ -21,7 +21,6 @@ a handle. See #GtkPaned for details.
 <para>
 </para>
 
-@paned: 
 
 <!-- ##### FUNCTION gtk_hpaned_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkhruler.sgml b/docs/reference/gtk/tmpl/gtkhruler.sgml
index 21658d405..e6ceadc29 100644
--- a/docs/reference/gtk/tmpl/gtkhruler.sgml
+++ b/docs/reference/gtk/tmpl/gtkhruler.sgml
@@ -19,14 +19,12 @@ rulers.
 
 </para>
 
-
 <!-- ##### STRUCT GtkHRuler ##### -->
 <para>
 The #GtkHRuler struct contains private data and should be accessed
 with the functions below.
 </para>
 
-@ruler: 
 
 <!-- ##### FUNCTION gtk_hruler_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkhscale.sgml b/docs/reference/gtk/tmpl/gtkhscale.sgml
index 9c9803d84..e23b09583 100644
--- a/docs/reference/gtk/tmpl/gtkhscale.sgml
+++ b/docs/reference/gtk/tmpl/gtkhscale.sgml
@@ -27,7 +27,6 @@ The #GtkHScale-struct struct contains private data only, and
 should be accessed using the functions below.
 </para>
 
-@scale: 
 
 <!-- ##### FUNCTION gtk_hscale_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkhscrollbar.sgml b/docs/reference/gtk/tmpl/gtkhscrollbar.sgml
index fa0a60b6a..5317f3eae 100644
--- a/docs/reference/gtk/tmpl/gtkhscrollbar.sgml
+++ b/docs/reference/gtk/tmpl/gtkhscrollbar.sgml
@@ -17,14 +17,12 @@ case one will be created you. See #GtkAdjustment for details.
 
 </para>
 
-
 <!-- ##### STRUCT GtkHScrollbar ##### -->
 <para>
 The #GtkHScrollbar struct contains private data and should be accessed
 unsing the functions below.
 </para>
 
-@scrollbar: 
 
 <!-- ##### FUNCTION gtk_hscrollbar_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkhseparator.sgml b/docs/reference/gtk/tmpl/gtkhseparator.sgml
index 4c3dc810d..6eaa96a74 100644
--- a/docs/reference/gtk/tmpl/gtkhseparator.sgml
+++ b/docs/reference/gtk/tmpl/gtkhseparator.sgml
@@ -2,30 +2,44 @@
 GtkHSeparator
 
 <!-- ##### SECTION Short_Description ##### -->
-
+a horizontal separator.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The #GtkHSeparator widget is a horizontal separator, used to group the
+widgets within a window. It displays a horizontal line with a shadow to
+make it appear sunken into the interface.
+</para>
+<note>
+<para>
+The #GtkHSeparator widget is not used as a separator within menus.
+To create a separator in a menu create an empty #GtkMenuItem widget using
+gtk_menu_item_new() and add it to the menu with gtk_menu_append().
 </para>
+</note>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+<variablelist>
+<varlistentry>
+<term>#GtkVSeparator</term>
+<listitem><para>a vertical separator.</para></listitem>
+</varlistentry>
+</variablelist>
 </para>
 
 <!-- ##### STRUCT GtkHSeparator ##### -->
 <para>
-
+The #GtkHSeparator-struct struct contains private data only, and
+should be accessed using the functions below.
 </para>
 
-@separator: 
 
 <!-- ##### FUNCTION gtk_hseparator_new ##### -->
 <para>
-
+Creates a new #GtkHSeparator.
 </para>
 
-@Returns: 
+@Returns: a new #GtkHSeparator.
 
 
diff --git a/docs/reference/gtk/tmpl/gtkimage.sgml b/docs/reference/gtk/tmpl/gtkimage.sgml
index 1934acf48..c9ba6f1a3 100644
--- a/docs/reference/gtk/tmpl/gtkimage.sgml
+++ b/docs/reference/gtk/tmpl/gtkimage.sgml
@@ -27,9 +27,6 @@ This struct contain private data only and should be accessed by the functions
 below.
 </para>
 
-@misc: 
-@image: 
-@mask: 
 
 <!-- ##### FUNCTION gtk_image_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkinputdialog.sgml b/docs/reference/gtk/tmpl/gtkinputdialog.sgml
index 065889214..691cd1e5a 100644
--- a/docs/reference/gtk/tmpl/gtkinputdialog.sgml
+++ b/docs/reference/gtk/tmpl/gtkinputdialog.sgml
@@ -32,16 +32,6 @@ immediately.
 <para>
 </para>
 
-@dialog: 
-@axis_list: 
-@axis_listbox: 
-@mode_optionmenu: 
-@close_button: 
-@save_button: 
-@axis_items: 
-@current_device: 
-@keys_list: 
-@keys_listbox: 
 
 <!-- ##### FUNCTION gtk_input_dialog_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkinvisible.sgml b/docs/reference/gtk/tmpl/gtkinvisible.sgml
index 692e4138c..50d2f76aa 100644
--- a/docs/reference/gtk/tmpl/gtkinvisible.sgml
+++ b/docs/reference/gtk/tmpl/gtkinvisible.sgml
@@ -2,11 +2,16 @@
 GtkInvisible
 
 <!-- ##### SECTION Short_Description ##### -->
-
+internally-used widget which is not displayed.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The #GtkInvisible widget is used internally in GTK+, and is probably not useful
+for application developers.
+</para>
+<para>
+It is used for reliable pointer grabs and selection handling in the code
+for drag-and-drop.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,16 +21,15 @@ GtkInvisible
 
 <!-- ##### STRUCT GtkInvisible ##### -->
 <para>
-
+The #GtkInvisible-struct struct contains no public fields.
 </para>
 
-@bin: 
 
 <!-- ##### FUNCTION gtk_invisible_new ##### -->
 <para>
-
+Creates a new #GtkInvisible.
 </para>
 
-@Returns: 
+@Returns: a new #GtkInvisible.
 
 
diff --git a/docs/reference/gtk/tmpl/gtkitem.sgml b/docs/reference/gtk/tmpl/gtkitem.sgml
index 42461654d..eec61acc5 100644
--- a/docs/reference/gtk/tmpl/gtkitem.sgml
+++ b/docs/reference/gtk/tmpl/gtkitem.sgml
@@ -2,11 +2,12 @@
 GtkItem
 
 <!-- ##### SECTION Short_Description ##### -->
-
+abstract base class for #GtkMenuItem, #GtkListItem and #GtkTreeItem.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The #GtkItem widget is an abstract base class for #GtkMenuItem, #GtkListItem
+and #GtkTreeItem.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,52 +17,52 @@ GtkItem
 
 <!-- ##### STRUCT GtkItem ##### -->
 <para>
-
+The #GtkItem-struct struct contains private data only, and
+should be accessed using the functions below.
 </para>
 
-@bin: 
 
 <!-- ##### FUNCTION gtk_item_select ##### -->
 <para>
-
+Emits the "select" signal on the given item.
 </para>
 
-@item: 
+@item: a #GtkItem.
 
 
 <!-- ##### FUNCTION gtk_item_deselect ##### -->
 <para>
-
+Emits the "deselect" signal on the given item.
 </para>
 
-@item: 
+@item: a #GtkItem.
 
 
 <!-- ##### FUNCTION gtk_item_toggle ##### -->
 <para>
-
+Emits the "toggle" signal on the given item.
 </para>
 
-@item: 
+@item: a #GtkItem.
 
 
 <!-- ##### SIGNAL GtkItem::select ##### -->
 <para>
-
+Emitted when the item is selected.
 </para>
 
 @item: the object which received the signal.
 
 <!-- ##### SIGNAL GtkItem::deselect ##### -->
 <para>
-
+Emitted when the item is deselected.
 </para>
 
 @item: the object which received the signal.
 
 <!-- ##### SIGNAL GtkItem::toggle ##### -->
 <para>
-
+Emitted when the item is toggled.
 </para>
 
 @item: the object which received the signal.
diff --git a/docs/reference/gtk/tmpl/gtkitemfactory.sgml b/docs/reference/gtk/tmpl/gtkitemfactory.sgml
index 9eb4b7a36..bbe4ac0fe 100644
--- a/docs/reference/gtk/tmpl/gtkitemfactory.sgml
+++ b/docs/reference/gtk/tmpl/gtkitemfactory.sgml
@@ -19,14 +19,6 @@ GtkItemFactory
 
 </para>
 
-@object: 
-@path: 
-@accel_group: 
-@widget: 
-@items: 
-@translate_func: 
-@translate_data: 
-@translate_notify: 
 
 <!-- ##### USER_FUNCTION GtkPrintFunc ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtklabel.sgml b/docs/reference/gtk/tmpl/gtklabel.sgml
index 6d5c30835..5511322ca 100644
--- a/docs/reference/gtk/tmpl/gtklabel.sgml
+++ b/docs/reference/gtk/tmpl/gtklabel.sgml
@@ -23,14 +23,6 @@ This should not be accessed directly.  Use the accessor functions as
 described below.
 </para>
 
-@misc: 
-@label: 
-@label_wc: 
-@pattern: 
-@words: 
-@max_width: 
-@jtype: 
-@wrap: 
 
 <!-- ##### STRUCT GtkLabelWord ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtklayout.sgml b/docs/reference/gtk/tmpl/gtklayout.sgml
index dc058a3e6..ded7a594c 100644
--- a/docs/reference/gtk/tmpl/gtklayout.sgml
+++ b/docs/reference/gtk/tmpl/gtklayout.sgml
@@ -19,20 +19,6 @@ GtkLayout
 
 </para>
 
-@container: 
-@children: 
-@width: 
-@height: 
-@xoffset: 
-@yoffset: 
-@hadjustment: 
-@vadjustment: 
-@bin_window: 
-@visibility: 
-@configure_serial: 
-@scroll_x: 
-@scroll_y: 
-@freeze_count: 
 
 <!-- ##### FUNCTION gtk_layout_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtklist.sgml b/docs/reference/gtk/tmpl/gtklist.sgml
index a640713ca..5b50f0de6 100644
--- a/docs/reference/gtk/tmpl/gtklist.sgml
+++ b/docs/reference/gtk/tmpl/gtklist.sgml
@@ -19,21 +19,6 @@ GtkList
 
 </para>
 
-@container: 
-@children: 
-@selection: 
-@undo_selection: 
-@undo_unselection: 
-@last_focus_child: 
-@undo_focus_child: 
-@htimer: 
-@vtimer: 
-@anchor: 
-@drag_pos: 
-@anchor_state: 
-@selection_mode: 
-@drag_selection: 
-@add_mode: 
 
 <!-- ##### FUNCTION gtk_list_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtklistitem.sgml b/docs/reference/gtk/tmpl/gtklistitem.sgml
index f4b758556..f2e778412 100644
--- a/docs/reference/gtk/tmpl/gtklistitem.sgml
+++ b/docs/reference/gtk/tmpl/gtklistitem.sgml
@@ -19,7 +19,6 @@ GtkListItem
 
 </para>
 
-@item: 
 
 <!-- ##### FUNCTION gtk_list_item_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkmarshal.sgml b/docs/reference/gtk/tmpl/gtkmarshal.sgml
index 288a5cb45..92d29caf1 100644
--- a/docs/reference/gtk/tmpl/gtkmarshal.sgml
+++ b/docs/reference/gtk/tmpl/gtkmarshal.sgml
@@ -2,481 +2,89 @@
 Signal Marshallers
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Functions to adapt C structures to native calling convention.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
-
+<refsect2>
+<title>What are Signal Marshallers?</title>
+<para>
+Marshals are functions which all have the same prototype:
+they take a #GtkObject, a #GtkSignalFunc, a #gpointer,
+and an array of argument values.
+The functions are names gtk_marshall_RETURNTYPE__PARAMTYPE1_PARAMTYPE2....
+</para>
+<para>
+They then call a native function:  the GtkObject is the first
+parameter passed in.  The arguments are passed in the native
+calling convention:  chars, shorts, ints, longs may be packed
+on the stack, or tucked in registers:  it doesn't matter
+because the same calling convention will be generated
+inside the gtkmarshal code as is expected where you define
+your handlers.
+</para>
+<para>
+So the function named:
+<programlisting>
+gtk_marshal_BOOL__POINTER_INT_INT_UINT(GtkObject*, GtkSignalFunc, gpointer, GtkArg*);
+</programlisting>
+will call the #GtkSignalFunc assuming it was a function with signature:
+<programlisting>
+gboolean sigfunc(gpointer,gint,gint,guint);
+</programlisting>
+</para>
+</refsect2>
+<refsect2>
+<title>Writing Custom Marshals</title>
+<para>
+Marshals are primarily used as arguments to gtk_signal_new().
+Sometimes, you may find that a marshaller you need isn't available
+in the standard list.  Then you have to write your own.
+</para>
+<para>
+If you wish to define a signal with a new type of argument list.
+Suppose you want 2 pointers and 2 integers.
+You would write:
+<programlisting>
+typedef int (*GtkSignal_INT__POINTER_POINTER_INT_INT)(
+			gpointer, gpointer, gint, gint
+);
+
+void marshal_INT__POINTER_POINTER_INT_INT(GtkObject*    object,
+					   GtkSignalFunc func,
+					   gpointer      func_data,
+                                           GtkArg*       args)
+{
+	GtkSignal_NONE__POINTER_POINTER_INT_INT rfunc;
+	gint* return_val;
+	return_val = GTK_RETLOC_INT(args[4]);
+	rfunc = (GtkSignal_INT__POINTER_POINTER_INT_INT)func;
+	*return_val = (*rfunc)(object,
+                               GTK_VALUE_POINTER(args[0]),
+                               GTK_VALUE_POINTER(args[1]),
+                               GTK_VALUE_INT(args[2]),
+                               GTK_VALUE_INT(args[3]),
+                               func_data);
+}
+</programlisting>
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
+<variablelist>
 
-</para>
-
-<!-- ##### MACRO gtk_signal_default_marshaller ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_BOOL__POINTER_INT_INT_UINT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_BOOL__POINTER_STRING_STRING_POINTER ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_ENUM__ENUM ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__BOXED ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__ENUM ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__ENUM_FLOAT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__ENUM_FLOAT_BOOL ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__OBJECT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_STRING_STRING ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_ENUM ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_POINTER_UINT_UINT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_INT_INT_POINTER_UINT_UINT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__POINTER_UINT_UINT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__STRING ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__STRING_INT_POINTER ##### -->
-<para>
+<varlistentry>
+<term>#GtkSignal</term>
+<listitem><para>The signal handling functions (of which marshallers are 
+really an implementation detail).</para></listitem>
+</varlistentry>
 
+</variablelist>
 </para>
 
-
-
-<!-- ##### MACRO gtk_marshal_NONE__UINT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__UINT_POINTER_UINT_ENUM_ENUM_POINTER ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__UINT_POINTER_UINT_UINT_ENUM ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO gtk_marshal_NONE__UINT_STRING ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### FUNCTION gtk_marshal_BOOL__NONE ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_INT_INT ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_INT_INT_INT ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_POINTER_INT_INT ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_BOOL__POINTER_POINTER_POINTER_POINTER ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_INT__INT ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_INT__POINTER ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_INT__POINTER_CHAR_CHAR ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__BOOL ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__C_CALLBACK ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__C_CALLBACK_C_CALLBACK ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_FLOAT ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_FLOAT_BOOL ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_INT ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_INT_POINTER ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER_INT_INT_INT ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__INT_POINTER_INT_INT_INT_POINTER ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__NONE ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_INT ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_INT_POINTER_INT_INT ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_INT_POINTER ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER_INT_INT ##### -->
-<para>
-
-</para>
-
-@object: 
-@func: 
-@func_data: 
-@args: 
-
-
-<!-- ##### FUNCTION gtk_marshal_NONE__POINTER_POINTER_POINTER ##### -->
+<!-- ##### MACRO gtk_signal_default_marshaller ##### -->
 <para>
-
+A marshaller that returns void and takes no extra parameters.
 </para>
 
-@object: 
-@func: 
-@func_data: 
-@args: 
 
 
diff --git a/docs/reference/gtk/tmpl/gtkmenu.sgml b/docs/reference/gtk/tmpl/gtkmenu.sgml
index 7411912cb..8e3a4a48a 100644
--- a/docs/reference/gtk/tmpl/gtkmenu.sgml
+++ b/docs/reference/gtk/tmpl/gtkmenu.sgml
@@ -82,15 +82,6 @@ The #GtkMenu-struct struct contains private data only, and
 should be accessed using the functions below.
 </para>
 
-@menu_shell: 
-@parent_menu_item: 
-@old_active_menu_item: 
-@accel_group: 
-@position_func: 
-@position_func_data: 
-@toplevel: 
-@tearoff_window: 
-@torn_off: 
 
 <!-- ##### FUNCTION gtk_menu_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkmenubar.sgml b/docs/reference/gtk/tmpl/gtkmenubar.sgml
index 384affdc5..c1c63280e 100644
--- a/docs/reference/gtk/tmpl/gtkmenubar.sgml
+++ b/docs/reference/gtk/tmpl/gtkmenubar.sgml
@@ -19,9 +19,6 @@ The #GtkMenuBar is a subclass of #GtkMenuShell which contains one to many #GtkMe
 The #GtkMenuBar struct contains the following fields. (These fields should be considered read-only.  They should never be set by an application.)
 </para>
 
-@menu_shell: the #GtkMenuShell container
-@shadow_type: the GtkShadowType to use
-
 <!-- ##### FUNCTION gtk_menu_bar_new ##### -->
 <para>
 Creates the new #GtkMenuBar
diff --git a/docs/reference/gtk/tmpl/gtkmenuitem.sgml b/docs/reference/gtk/tmpl/gtkmenuitem.sgml
index 2eed9a243..e75da30f7 100644
--- a/docs/reference/gtk/tmpl/gtkmenuitem.sgml
+++ b/docs/reference/gtk/tmpl/gtkmenuitem.sgml
@@ -19,17 +19,6 @@ GtkMenuItem
 
 </para>
 
-@item: 
-@submenu: 
-@accelerator_signal: 
-@toggle_size: 
-@accelerator_width: 
-@show_toggle_indicator: 
-@show_submenu_indicator: 
-@submenu_placement: 
-@submenu_direction: 
-@right_justify: 
-@timer: 
 
 <!-- ##### FUNCTION gtk_menu_item_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkmenushell.sgml b/docs/reference/gtk/tmpl/gtkmenushell.sgml
index cad3bdefe..4c00a7a7a 100644
--- a/docs/reference/gtk/tmpl/gtkmenushell.sgml
+++ b/docs/reference/gtk/tmpl/gtkmenushell.sgml
@@ -40,18 +40,6 @@ an application.)
 </tbody></tgroup></informaltable>
 </para>
 
-@container: 
-@children: 
-@active_menu_item: 
-@parent_menu_shell: 
-@active: 
-@have_grab: 
-@have_xgrab: 
-@button: 
-@ignore_leave: 
-@menu_flag: 
-@ignore_enter: 
-@activate_time: 
 
 <!-- ##### FUNCTION gtk_menu_shell_append ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkmisc.sgml b/docs/reference/gtk/tmpl/gtkmisc.sgml
index 8052c8712..861f36332 100644
--- a/docs/reference/gtk/tmpl/gtkmisc.sgml
+++ b/docs/reference/gtk/tmpl/gtkmisc.sgml
@@ -59,11 +59,6 @@ in pixels.</entry>
 </tbody></tgroup></informaltable>
 </para>
 
-@widget: 
-@xalign: 
-@yalign: 
-@xpad: 
-@ypad: 
 
 <!-- ##### FUNCTION gtk_misc_set_alignment ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtknotebook.sgml b/docs/reference/gtk/tmpl/gtknotebook.sgml
index dc6014b07..e4930dbb8 100644
--- a/docs/reference/gtk/tmpl/gtknotebook.sgml
+++ b/docs/reference/gtk/tmpl/gtknotebook.sgml
@@ -19,27 +19,6 @@ GtkNotebook
 
 </para>
 
-@container: 
-@cur_page: 
-@children: 
-@first_tab: 
-@focus_tab: 
-@menu: 
-@panel: 
-@timer: 
-@tab_hborder: 
-@tab_vborder: 
-@show_tabs: 
-@homogeneous: 
-@show_border: 
-@tab_pos: 
-@scrollable: 
-@in_child: 
-@click_child: 
-@button: 
-@need_timer: 
-@child_has_focus: 
-@have_visible_child: 
 
 <!-- ##### MACRO GTK_NOTEBOOK_PAGE ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkobject.sgml b/docs/reference/gtk/tmpl/gtkobject.sgml
index c4d5a576e..ff77d7881 100644
--- a/docs/reference/gtk/tmpl/gtkobject.sgml
+++ b/docs/reference/gtk/tmpl/gtkobject.sgml
@@ -19,10 +19,6 @@ GtkObject
 
 </para>
 
-@klass: 
-@flags: 
-@ref_count: 
-@object_data: 
 
 <!-- ##### MACRO GTK_OBJECT_TYPE ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkoptionmenu.sgml b/docs/reference/gtk/tmpl/gtkoptionmenu.sgml
index 429a319f4..9bc5aab88 100644
--- a/docs/reference/gtk/tmpl/gtkoptionmenu.sgml
+++ b/docs/reference/gtk/tmpl/gtkoptionmenu.sgml
@@ -21,11 +21,6 @@ The #GtkOptionMenu-struct struct contains private data only, and
 should be accessed using the functions below.
 </para>
 
-@button: 
-@menu: 
-@menu_item: 
-@width: 
-@height: 
 
 <!-- ##### FUNCTION gtk_option_menu_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkpacker.sgml b/docs/reference/gtk/tmpl/gtkpacker.sgml
index d9a0fdde0..3302b5d06 100644
--- a/docs/reference/gtk/tmpl/gtkpacker.sgml
+++ b/docs/reference/gtk/tmpl/gtkpacker.sgml
@@ -19,14 +19,6 @@ GtkPacker
 
 </para>
 
-@parent: 
-@children: 
-@spacing: 
-@default_border_width: 
-@default_pad_x: 
-@default_pad_y: 
-@default_i_pad_x: 
-@default_i_pad_y: 
 
 <!-- ##### ENUM GtkPackerOptions ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkpaned.sgml b/docs/reference/gtk/tmpl/gtkpaned.sgml
index 7d3fabda3..db7f80bd3 100644
--- a/docs/reference/gtk/tmpl/gtkpaned.sgml
+++ b/docs/reference/gtk/tmpl/gtkpaned.sgml
@@ -72,26 +72,8 @@ gtk_widget_set_usize (frame1, 50, -1);
 <para>
 </para>
 
-@container: 
-@child1: 
-@child2: 
-@handle: 
-@groove_rectangle: 
-@xor_gc: 
 @handle_size: 
 @gutter_size: 
-@child1_size: 
-@last_allocation: 
-@min_position: 
-@max_position: 
-@position_set: 
-@in_drag: 
-@child1_shrink: 
-@child1_resize: 
-@child2_shrink: 
-@child2_resize: 
-@handle_xpos: 
-@handle_ypos: 
 
 <!-- ##### FUNCTION gtk_paned_add1 ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkpixmap.sgml b/docs/reference/gtk/tmpl/gtkpixmap.sgml
index 57444d827..6a3fca54a 100644
--- a/docs/reference/gtk/tmpl/gtkpixmap.sgml
+++ b/docs/reference/gtk/tmpl/gtkpixmap.sgml
@@ -29,11 +29,6 @@ The #GtkPixmap-struct struct contains private data only, and
 should be accessed using the functions below.
 </para>
 
-@misc: 
-@pixmap: 
-@mask: 
-@pixmap_insensitive: 
-@build_insensitive: 
 
 <!-- ##### FUNCTION gtk_pixmap_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkplug.sgml b/docs/reference/gtk/tmpl/gtkplug.sgml
index 1f71fb5dc..74fa49ee2 100644
--- a/docs/reference/gtk/tmpl/gtkplug.sgml
+++ b/docs/reference/gtk/tmpl/gtkplug.sgml
@@ -33,9 +33,6 @@ inside the first applications window.
 
 </para>
 
-@window: 
-@socket_window: 
-@same_app: 
 
 <!-- ##### FUNCTION gtk_plug_construct ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkpreview.sgml b/docs/reference/gtk/tmpl/gtkpreview.sgml
index d5448de0b..8ab4dbb3d 100644
--- a/docs/reference/gtk/tmpl/gtkpreview.sgml
+++ b/docs/reference/gtk/tmpl/gtkpreview.sgml
@@ -28,15 +28,6 @@ The #GtkPreview-struct struct contains private data only, and
 should be accessed using the functions below.
 </para>
 
-@widget: 
-@buffer: 
-@buffer_width: 
-@buffer_height: 
-@bpp: 
-@rowstride: 
-@dither: 
-@type: 
-@expand: 
 
 <!-- ##### STRUCT GtkPreviewInfo ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkprogress.sgml b/docs/reference/gtk/tmpl/gtkprogress.sgml
index f977ff991..35a02d40d 100644
--- a/docs/reference/gtk/tmpl/gtkprogress.sgml
+++ b/docs/reference/gtk/tmpl/gtkprogress.sgml
@@ -19,14 +19,6 @@ GtkProgress
 
 </para>
 
-@widget: 
-@adjustment: 
-@offscreen_pixmap: 
-@format: 
-@x_align: 
-@y_align: 
-@show_text: 
-@activity_mode: 
 
 <!-- ##### FUNCTION gtk_progress_set_show_text ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkprogressbar.sgml b/docs/reference/gtk/tmpl/gtkprogressbar.sgml
index 5838aba50..2e59e2dc9 100644
--- a/docs/reference/gtk/tmpl/gtkprogressbar.sgml
+++ b/docs/reference/gtk/tmpl/gtkprogressbar.sgml
@@ -19,15 +19,6 @@ GtkProgressBar
 
 </para>
 
-@progress: 
-@bar_style: 
-@orientation: 
-@blocks: 
-@in_block: 
-@activity_pos: 
-@activity_step: 
-@activity_blocks: 
-@activity_dir: 
 
 <!-- ##### ENUM GtkProgressBarStyle ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkradiobutton.sgml b/docs/reference/gtk/tmpl/gtkradiobutton.sgml
index 681ceec23..2419f64d9 100644
--- a/docs/reference/gtk/tmpl/gtkradiobutton.sgml
+++ b/docs/reference/gtk/tmpl/gtkradiobutton.sgml
@@ -2,84 +2,158 @@
 GtkRadioButton
 
 <!-- ##### SECTION Short_Description ##### -->
-
+A choice from multiple check buttons.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+A single radio button performs the same basic function as a #GtkCheckButton,
+as it's position in the object hierarchy reflects. It is only when multiple
+radio buttons are grouped together that they become a different user
+interface component in their own right.</para>
+<para>
+Every radio button is a member of some group of radio buttons. When one is selected, all other
+radio buttons in the same group are deselected. A #GtkRadioButton is one way
+of giving the user a choice from many options.
+</para>
+<para>
+Radio button widgets are created with gtk_radio_button_new(), passing NULL
+as the argument if this is the first radio button in a group. In subsequent
+calls, the group you wish to add this button to should be passed as an
+argument. Optionally, gtk_radio_button_new_with_label() can be used if you
+want a text label on the radio button.
+</para>
+<para>
+Alternatively, when adding widgets to an existing group of radio buttons,
+use gtk_radio_button_new_from_widget() with a #GtkRadioButton that already
+has a group assigned to it. The convenience function
+gtk_radio_button_new_with_label_from_widget() is also provided.
+</para>
+<para>
+To retrieve the group a #GtkRadioButton is assigned to, use
+gtk_radio_button_group().
+</para>
+<para>
+To remove a #GtkRadioButton from one group and make it part of a new one, use gtk_radio_button_set_group().
+</para>
+<para>
+<example>
+<title>How to create a group of two radio buttons.</title>
+<programlisting>
+
+void create_radio_buttons(void) {
+
+   GtkWidget *window, *radio1, *radio2, *box, *entry;
+   window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
+   box = gtk_vbox_new(TRUE, 2);
+   
+   /* Create a radio button with a #GtkEntry widget */
+   radio1 = gtk_radio_button_new(NULL);
+   entry = gtk_entry_new();
+   gtk_container_add(GTK_CONTAINER(radio1), entry);
+   
+   
+   /* Create a radio button with a label */
+   radio2 = gtk_radio_button_new_with_label_from_widget (GTK_RADIO_BUTTON(radio1),
+							"I'm the second radio button.");
+   
+   /* Pack them into a box, then show all the widgets */
+   gtk_box_pack_start (GTK_BOX (box), radio1, TRUE, TRUE, 2);
+   gtk_box_pack_start(GTK_BOX(box), radio2, TRUE, TRUE, 2);
+   gtk_container_add(GTK_CONTAINER(window), box);
+   gtk_widget_show_all (window);
+   return;
+}
+
+</programlisting>
+</example>
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
+<variablelist>
+<varlistentry>
+<term>#GtkOptionMenu</term>
+<listitem><para>Another way of offering the user a single choice from
+many.</para></listitem>
+</varlistentry>
+</variablelist>
 
 </para>
 
 <!-- ##### STRUCT GtkRadioButton ##### -->
 <para>
-
+Contains only private data that should be read and manipulated using the
+functions below.
 </para>
 
-@check_button: 
-@group: 
 
 <!-- ##### FUNCTION gtk_radio_button_new ##### -->
 <para>
-
+Creates a new #GtkRadioButton. To be of any practical value, a widget should
+then be packed into the radio button.
 </para>
 
-@group: 
-@Returns: 
+@group: an existing radio button group, or NULL if you are creating a new group.
+@Returns: a new radio button.
 
 
 <!-- ##### FUNCTION gtk_radio_button_new_from_widget ##### -->
 <para>
-
+Creates a new #GtkRadioButton, adding it to the same group as @group. As
+with gtk_radio_button_new(), a widget should be packed into the radio button.
 </para>
 
-@group: 
-@Returns: 
+@group: an existing #GtkRadioButton.
+@Returns: a new radio button.
 
 
 <!-- ##### FUNCTION gtk_radio_button_new_with_label ##### -->
 <para>
-
+Creates a new #GtkRadioButton with a text label.
 </para>
 
-@group: 
-@label: 
-@Returns: 
+@group: an existing radio button group, or NULL if you are creating a new
+group.
+@label: the text label to display next to the radio button.
+@Returns: a new radio button.
 
 
 <!-- ##### FUNCTION gtk_radio_button_new_with_label_from_widget ##### -->
 <para>
-
+Creates a new #GtkRadioButton with a text label, adding it to the same group
+as @group.
 </para>
 
-@group: 
-@label: 
-@Returns: 
+@group: an existing #GtkRadioButton.
+@label: a text string to display next to the radio button.
+@Returns: a new radio button.
 
 
 <!-- ##### FUNCTION gtk_radio_button_group ##### -->
 <para>
-
+Retrieves the group assigned to a radio button.
 </para>
 
-@radio_button: 
-@Returns: 
+@radio_button: a #GtkRadioButton.
+@Returns: a linked list containing all the radio buttons in the same group
+as @radio_button.
 
 
 <!-- ##### FUNCTION gtk_radio_button_set_group ##### -->
 <para>
-
+Sets a #GtkRadioButton's group. It should be noted that this does not change
+the layout of your interface in any way, so if you are changing the group,
+it is likely you will need to re-arrange the user interface to reflect these
+changes.
 </para>
 
-@radio_button: 
-@group: 
+@radio_button: a #GtkRadioButton.
+@group: an existing radio button group, such as one returned from
+gtk_radio_button_group().
 
 
 <!-- ##### ARG GtkRadioButton:group ##### -->
 <para>
-
+Sets a new group for a radio button.
 </para>
 
diff --git a/docs/reference/gtk/tmpl/gtkradiomenuitem.sgml b/docs/reference/gtk/tmpl/gtkradiomenuitem.sgml
index 58d7fa5af..3d6ed3fe9 100644
--- a/docs/reference/gtk/tmpl/gtkradiomenuitem.sgml
+++ b/docs/reference/gtk/tmpl/gtkradiomenuitem.sgml
@@ -19,8 +19,6 @@ GtkRadioMenuItem
 
 </para>
 
-@check_menu_item: 
-@group: 
 
 <!-- ##### FUNCTION gtk_radio_menu_item_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkrange.sgml b/docs/reference/gtk/tmpl/gtkrange.sgml
index 2908bce5a..fcf22cdc6 100644
--- a/docs/reference/gtk/tmpl/gtkrange.sgml
+++ b/docs/reference/gtk/tmpl/gtkrange.sgml
@@ -19,26 +19,6 @@ GtkRange
 
 </para>
 
-@widget: 
-@trough: 
-@slider: 
-@step_forw: 
-@step_back: 
-@x_click_point: 
-@y_click_point: 
-@button: 
-@digits: 
-@policy: 
-@scroll_type: 
-@in_child: 
-@click_child: 
-@need_timer: 
-@timer: 
-@old_value: 
-@old_lower: 
-@old_upper: 
-@old_page_size: 
-@adjustment: 
 
 <!-- ##### FUNCTION gtk_range_get_adjustment ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkruler.sgml b/docs/reference/gtk/tmpl/gtkruler.sgml
index 3f32ee75e..7f9330de3 100644
--- a/docs/reference/gtk/tmpl/gtkruler.sgml
+++ b/docs/reference/gtk/tmpl/gtkruler.sgml
@@ -25,17 +25,6 @@ All distances are in 1/72nd's of an inch. (According to Adobe thats a point, but
 points are really 1/72.27 in.)
 </para>
 
-@widget:
-@backing_store: 
-@non_gr_exp_gc: 
-@metric: 
-@xsrc: 
-@ysrc: 
-@slider_size: 
-@lower: 
-@upper: 
-@position: 
-@max_size: 
 
 <!-- ##### STRUCT GtkRulerMetric ##### -->
 <para>
@@ -65,25 +54,9 @@ This sets the range of the ruler using gfloat lower, gfloat upper, gfloat positi
 </para>
 
 @ruler: the gtkruler
-@lower:the upper limit of the ruler
-@upper:the lower limit of the ruler
-@position:the mark on the ruler 
-@max_size:the maximum size of the ruler 
-
-
-<!-- ##### FUNCTION gtk_ruler_draw_ticks ##### -->
-<para>
-
-</para>
-
-@ruler: the gtkruler
-
-
-<!-- ##### FUNCTION gtk_ruler_draw_pos ##### -->
-<para>
-
-</para>
-
-@ruler: the gtkruler
+@lower: the upper limit of the ruler
+@upper: the lower limit of the ruler
+@position: the mark on the ruler
+@max_size: the maximum size of the ruler
 
 
diff --git a/docs/reference/gtk/tmpl/gtkscale.sgml b/docs/reference/gtk/tmpl/gtkscale.sgml
index 8eaf20100..e34f3e25e 100644
--- a/docs/reference/gtk/tmpl/gtkscale.sgml
+++ b/docs/reference/gtk/tmpl/gtkscale.sgml
@@ -40,9 +40,6 @@ slider.</entry>
 </tbody></tgroup></informaltable>
 </para>
 
-@range: 
-@draw_value: 
-@value_pos: 
 
 <!-- ##### FUNCTION gtk_scale_set_digits ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkscrollbar.sgml b/docs/reference/gtk/tmpl/gtkscrollbar.sgml
index a459493b0..1996709c7 100644
--- a/docs/reference/gtk/tmpl/gtkscrollbar.sgml
+++ b/docs/reference/gtk/tmpl/gtkscrollbar.sgml
@@ -19,5 +19,4 @@ GtkScrollbar
 
 </para>
 
-@range: 
 
diff --git a/docs/reference/gtk/tmpl/gtkscrolledwindow.sgml b/docs/reference/gtk/tmpl/gtkscrolledwindow.sgml
index 02163acd9..92c6db77f 100644
--- a/docs/reference/gtk/tmpl/gtkscrolledwindow.sgml
+++ b/docs/reference/gtk/tmpl/gtkscrolledwindow.sgml
@@ -49,14 +49,6 @@ There are no public fields in the #GtkScrolledWindow struct; it should
 only be accessed using the functions below.
 </para>
 
-@container: 
-@hscrollbar: 
-@vscrollbar: 
-@hscrollbar_policy: 
-@vscrollbar_policy: 
-@hscrollbar_visible: 
-@vscrollbar_visible: 
-@window_placement: 
 
 <!-- ##### FUNCTION gtk_scrolled_window_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkseparator.sgml b/docs/reference/gtk/tmpl/gtkseparator.sgml
index 1f116c1d4..997fd31fe 100644
--- a/docs/reference/gtk/tmpl/gtkseparator.sgml
+++ b/docs/reference/gtk/tmpl/gtkseparator.sgml
@@ -20,5 +20,4 @@ subclasses #GtkHSeparator and #GtkVSeparator.
 The #GtkSeparator-struct struct contains private data only.
 </para>
 
-@widget: 
 
diff --git a/docs/reference/gtk/tmpl/gtksignal.sgml b/docs/reference/gtk/tmpl/gtksignal.sgml
index 3a450f324..de67e84bf 100644
--- a/docs/reference/gtk/tmpl/gtksignal.sgml
+++ b/docs/reference/gtk/tmpl/gtksignal.sgml
@@ -2,16 +2,149 @@
 Signals
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Object methods and callbacks.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
+<refsect2>
+<title>What are signals?</title>
+<para>
+Signals are a way to get notification when something happens
+and to customize object behavior according to the
+user's needs.
+Every <WordAsWord>signal</WordAsWord> is uniquely identified by a name,
+"class_name::signal_name", where signal_name might be something like
+"clicked" and class_name might be "GtkButton".  Note that some other class
+may also define a "clicked" callback, so long as it doesn't derive from
+#GtkButton.
+</para>
+<para>
+When they are created, they are also assigned a unique positive integer,
+the signal id (1 is the first signal id- 0 is used to flag an error).
+Each is also tied to an array of types that describes
+the prototype of the function pointer(s) (handlers) you may
+connect to the signal.  Finally, every signal has
+a default handler that is given by a function pointer
+in its class structure:  it is run by default whenever the
+signal is emitted.  (It is possible that a signal will
+be emitted and a user-defined handler will prevent the default handler
+from being run.)
+</para>
+<para>
+Signals are used by everyone, but they are only
+created on a per class basis-- so you should call
+call gtk_signal_new() unless you are writing
+a new #GtkObject type.  However, if you want to make a new signal
+for an existing type, you may use gtk_object_class_user_signal_new()
+to create a signal that doesn't correspond to a class's builtin
+methods.
+</para>
+</refsect2>
+<refsect2>
+<title>How are signals used?</title>
+<para>
+There are two basic actions in the signal handling game.
+If you want notification of an event, you must <Emphasis>connect</Emphasis>
+a function pointer and a data pointer to that signal;  the data pointer
+will be passed as the last argument to the function (so long as you
+are using the default marshalling functions).
+You will receive a connection id, a unique positive integer
+corresponding to that attachment.
+</para>
+<para>
+Functions that want to notify the user of certain actions,
+<Emphasis>emit</Emphasis> signals.
+</para>
+</refsect2>
+<refsect2>
+<title>Basic Terminology</title>
+<variablelist>
+
+<varlistentry>
+<term>signal</term>
+<listitem><para>A class method, e.g. GtkButton::clicked.
+More precisely it is a unique class-branch/signal-name pair.
+This means you may not define a signal handler for a class which
+derives from GtkButton that is called clicked,
+but it is okay to share signals names if they are separate in
+the class tree.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>default handler</term>
+<listitem><para>The object's internal method which is invoked
+when the signal is emitted.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>user-defined handler</term>
+<listitem><para>A function pointer and data connected
+to a signal (for a particular object).</para>
+<para>There are really two types: those which are connected
+normally, and those which are connected by one 
+of the connect_after functions.  The connect_after handlers
+are always run after the default handler.</para>
+<para>Many toolkits refer to these as <wordasword>callbacks</wordasword>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>emission</term>
+<listitem><para>the whole process of emitting a signal,
+including the invocation of all
+the different handler types mentioned above.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>signal id</term>
+<listitem><para>The unique positive (nonzero) integer
+used to identify a signal.  It can be used instead of 
+a name to many functions for a slight performance
+improvement.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>connection id</term>
+<listitem><para>The unique positive (nonzero) integer
+used to identify the connection of a user-defined handler
+to a signal.  Notice that it is allowed to connect the
+same function-pointer/user-data pair twice, so
+there is no guarantee that a function-pointer/user-data
+maps to a unique connection id.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</refsect2>
+
+<refsect2><title>A brief note on how they work.</title>
+<para>
+The functions responsible for translating an array of #GtkArgs
+to your C compiler's normal semantics are called Marshallers.
+They are identified by
+gtk_marshal_return_value__parameter_list()
+for example a C function returning a gboolean and taking a gint
+can be invoked by using gtk_marshal_BOOL__INT().
+Not all possibly combinations of return/params are available,
+of course, so if you are writing a #GtkObject with parameters
+you might have to write a marshaller.
+</para>
+</refsect2>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
-
+<para>
+<variablelist>
+
+<varlistentry>
+<term>#GtkObject</term>
+<listitem><para>The base class for things which emit signals.</para></listitem>
+</varlistentry>
+
+</variablelist>
 </para>
 
 <!-- ##### MACRO GTK_SIGNAL_OFFSET ##### -->
@@ -24,42 +157,69 @@ Signals
 
 
 <!-- ##### USER_FUNCTION GtkSignalMarshal ##### -->
-<para>
-
+<para>
+This is currently a hack left in for a scheme wrapper library.
+It may be removed.
+</para>
+<para>
+Don't use it.
 </para>
 
-@object: 
-@data: 
-@nparams: 
-@args: 
-@arg_types: 
-@return_type: 
+@object: The object which emits the signal.
+@data: The user data associated with the hook.
+@nparams: The number of parameters to the function.
+@args: The actual values of the arguments.
+@arg_types: The types of the arguments.
+@return_type: The type of the return value from the function
+or #GTK_TYPE_NONE for no return value.
 
 
 <!-- ##### USER_FUNCTION GtkSignalDestroy ##### -->
-<para>
-
+<para>
+A function which you can use to clean up when the
+signal handler is destroyed.
+</para>
+<para>
+For example, if your handler requires a few variables
+that you made into a struct and allocated (using g_new()
+or something), then you will probably want to free
+it as soon as the hook is destroyed.  This will
+allow you to do that. (For this in particular
+it is convenient to pass g_free() as a #GtkSignalDestroy
+function).
 </para>
 
-@data: 
+@data: The user data associated with the hook that is being
+destroyed.
 
 
 <!-- ##### USER_FUNCTION GtkEmissionHook ##### -->
-<para>
-
-</para>
-
-@object: 
-@signal_id: 
-@n_params: 
-@params: 
-@data: 
-@Returns: 
+<para>
+A simple function pointer to get invoked when the
+signal is emitted.  This allows you tie a hook to the signal type,
+so that it will trap all emissions of that signal, from any object.
+</para>
+<para>
+You may not attach these to signals created with the
+#GTK_RUN_NO_HOOKS flag.
+</para>
+
+@object: the object which emits the signal.
+@signal_id: the unique integer identify the signal type.
+@n_params: the number of parameters to the function,
+not including return value.
+@params: the parameters to the function.  A pointer to
+the return value is passed as a last element.
+@data: the user data associated with the hook.
+@Returns: whether it wished to be removed.  If it returns
+TRUE, the signal hook is disconnected (and destroyed).
 
 
 <!-- ##### STRUCT GtkSignalQuery ##### -->
-<para>
-
+<para>
+This structure contains all the information about a particular
+signal:  its name, the type it affects, the signature of the handlers,
+and its unique identifying integer.
 </para>
 
 @object_type: 
@@ -71,6 +231,81 @@ Signals
 @nparams: 
 @params: 
 
+<!-- ##### ENUM GtkSignalRunType ##### -->
+<para>
+These configure the signal's emission.  They control
+whether the signal can be emitted recursively on an object
+and
+whether to run the default method before or after the user-defined handlers.
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term>GTK_RUN_FIRST</term>
+<listitem><para>Run the default handler before the connected user-defined
+handlers.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>GTK_RUN_LAST</term>
+<listitem><para>Run the default handler after the connected
+user-defined handlers.
+(Handlers registered as "after" always run after the default handler though)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>GTK_RUN_BOTH</term>
+<listitem><para>Run the default handler twice,
+once before the user-defined handlers,
+and
+once after.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>GTK_RUN_NO_RECURSE</term>
+<listitem><para>Whether to prevent a handler or hook
+from reemitting the signal from within itself.
+Attempts to
+emit the signal while it is running will result in the signal
+emission being restarted once it is done with the current processing.
+</para><para>
+You must be
+careful to avoid having two handlers endlessly reemitting signals,
+gtk_signal_n_emissions() can be helpful.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>GTK_RUN_ACTION</term>
+<listitem><para>The signal is an action you can 
+invoke without any particular setup or cleanup.
+The signal is treated no differently, but some
+other code can determine if the signal is appropriate to
+delegate to user control.  For example, key binding sets
+only allow bindings of ACTION signals to keystrokes.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>GTK_RUN_NO_HOOKS</term>
+<listitem><para>This prevents the connection of emission hooks
+to the signal.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+@GTK_RUN_FIRST: 
+@GTK_RUN_LAST: 
+@GTK_RUN_BOTH: 
+@GTK_RUN_NO_RECURSE: 
+@GTK_RUN_ACTION: 
+@GTK_RUN_NO_HOOKS: 
+
 <!-- ##### FUNCTION gtk_signal_init ##### -->
 <para>
 
@@ -79,395 +314,613 @@ Signals
 
 
 <!-- ##### FUNCTION gtk_signal_new ##### -->
-<para>
-
-</para>
-
-@name: 
-@signal_flags: 
-@object_type: 
-@function_offset: 
-@marshaller: 
-@return_val: 
-@nparams: 
-@Varargs: 
-@Returns: 
+<para>
+Create a new signal type.  (This is usually done in the
+class initializer.)
+</para>
+
+@name: the event name for the signal, e.g. "clicked".
+@signal_flags: a combination of GTK_RUN flags
+specifying detail of when the default handler is to be invoked.
+You should at least specify #GTK_RUN_FIRST
+or #GTK_RUN_LAST.
+@object_type: the type of object this signal pertains to.
+It will also pertain to derivers of this type automatically.
+@function_offset: How many bytes the function pointer is in
+the class structure for this type.  Used to invoke a class
+method generically.
+@marshaller: the function to translate between an array
+of GtkArgs and the native calling convention.  Usually they
+are identified just by the type of arguments they take:
+for example, gtk_marshal_BOOL__STRING() describes a marshaller
+which takes a string and returns a boolean value.
+@return_val: the type of return value, or GTK_TYPE_NONE for a signal
+without a return value.
+@nparams: the number of parameter the handlers may take.
+@Varargs: a list of GTK_TYPE_*, one for each parameter.
+@Returns: the signal id.
 
 
 <!-- ##### FUNCTION gtk_signal_newv ##### -->
-<para>
-
-</para>
-
-@name: 
-@signal_flags: 
-@object_type: 
-@function_offset: 
+<para>
+Create a new signal type.  (This is usually done in a
+class initializer.)
+</para>
+<para>
+This function take the types as an array, instead of a list
+following the arguments.  Otherwise the same as gtk_signal_new().
+</para>
+
+@name: the name of the signal to create.
+@signal_flags: see gtk_signal_new().
+@object_type: the type of GtkObject to associate the signal with.
+@function_offset: how many bytes the function pointer is in
+the class structure for this type.
 @marshaller: 
-@return_val: 
-@nparams: 
-@params: 
-@Returns: 
+@return_val: the type of the return value, or GTK_TYPE_NONE if
+you don't want a return value.
+@nparams: the number of parameters to the user-defined handlers.
+@params: an array of GtkTypes, describing the prototype to
+the callbacks.
+@Returns: the signal id.
 
 
 <!-- ##### FUNCTION gtk_signal_lookup ##### -->
-<para>
-
+<para>
+Given the name of the signal and the type of object it connects
+to, get the signal's identifying integer.  Emitting the signal
+by number is somewhat faster than using the name each time.
+</para>
+<para>
+It also tries the ancestors of the given type.
 </para>
 
-@name: 
-@object_type: 
-@Returns: 
+@name: the signal's name, e.g. clicked.
+@object_type: the type that the signal operates on, e.g. #GTK_TYPE_BUTTON.
+@Returns: the signal's identifying number, or 0 if no signal was found.
 
 
 <!-- ##### FUNCTION gtk_signal_name ##### -->
-<para>
-
+<para>
+Given the signal's identifier, find its name.
+</para>
+<para>
+Two different signals may have the same name, if they have differing types.
 </para>
 
-@signal_id: 
-@Returns: 
+@signal_id: the signal's identifying number.
+@Returns: the signal name, or NULL if the signal number was invalid.
 
 
 <!-- ##### FUNCTION gtk_signal_emit ##### -->
-<para>
-
-</para>
-
-@object: 
-@signal_id: 
-@Varargs: 
+<para>
+Emit a signal.  This causes the default handler and user-defined
+handlers to be run.
+</para>
+<para>
+Here is what gtk_signal_emit() does:
+</para>
+<para>
+1.  Calls the default handler and the user-connected handlers.
+The default handler will be called first if
+GTK_RUN_FIRST is set, and last if GTK_RUN_LAST is set.
+</para>
+<para>
+2.  Calls all handlers connected with the "after" flag set.
+</para>
+
+@object: the object that emits the signal.
+@signal_id: the signal identifier.
+@Varargs: the parameters to the function, followed
+by a pointer to the return type, if any.
 
 
 <!-- ##### FUNCTION gtk_signal_emit_by_name ##### -->
-<para>
-
+<para>
+Emit a signal.  This causes the default handler and user-connected
+handlers to be run.
 </para>
 
-@object: 
-@name: 
-@Varargs: 
+@object: the object that emits the signal.
+@name: the name of the signal.
+@Varargs: the parameters to the function, followed
+by a pointer to the return type, if any.
 
 
 <!-- ##### FUNCTION gtk_signal_emitv ##### -->
-<para>
-
+<para>
+Emit a signal.  This causes the default handler and user-connected
+handlers to be run.  This differs from gtk_signal_emit() by taking
+an array of GtkArgs instead of using C's varargs mechanism.
 </para>
 
-@object: 
-@signal_id: 
-@params: 
+@object: the object to emit the signal to.
+@signal_id: the signal identifier.
+@params: an array of GtkArgs, one for each parameter,
+followed by one which is a pointer to the return type.
 
 
 <!-- ##### FUNCTION gtk_signal_emitv_by_name ##### -->
-<para>
-
+<para>
+Emit a signal by name.  This causes the default handler and user-connected
+handlers to be run.  This differs from gtk_signal_emit() by taking
+an array of GtkArgs instead of using C's varargs mechanism.
 </para>
 
-@object: 
-@name: 
-@params: 
+@object: the object to emit the signal to.
+@name: the name of the signal.
+@params: an array of GtkArgs, one for each parameter,
+followed by one which is a pointer to the return type.
 
 
 <!-- ##### FUNCTION gtk_signal_n_emissions ##### -->
-<para>
-
+<para>
+Find out the recursion depth of emissions for a particular type
+of signal and object.  (So it will
+always return 0 or 1 if #GTK_RUN_NO_RECURSE is specified)
+This is a way to avoid recursion:  you can see if
+you are currently running in that signal handler and emit it only
+if you are.
+</para>
+<para>Another way to look at it is that this number increases
+by one when #gtk_signal_emit(), et al, are called,
+and decreases by one when #gtk_signal_emit() returns.
 </para>
 
-@object: 
-@signal_id: 
-@Returns: 
+@object: the object with the signal handler.
+@signal_id: the signal id.
+@Returns: the recursion depth of emissions of this signal for this
+object.
 
 
 <!-- ##### FUNCTION gtk_signal_n_emissions_by_name ##### -->
-<para>
-
+<para>
+Find out the recursion depth of emissions for a particular type
+of signal and object.  Just like gtk_signal_n_emissions()
+except it will lookup the signal id for you.
 </para>
 
-@object: 
-@name: 
-@Returns: 
+@object: the object with the signal handler.
+@name: the signal name.
+@Returns: the recursion depth of emissions of this signal for this
+object.
 
 
 <!-- ##### FUNCTION gtk_signal_emit_stop ##### -->
-<para>
-
+<para>
+This function aborts a signal's current emission.
+</para>
+<para>
+It will prevent the default method from running,
+if the signal was #GTK_RUN_LAST and you connected
+normally (i.e. without the "after" flag).
+<para>
+It will print a warning if used on a signal which
+isn't being emitted.
 </para>
 
-@object: 
-@signal_id: 
+@object: the object whose signal handlers you wish to stop.
+@signal_id: the signal identifier, as returned by gtk_signal_lookup().
 
 
 <!-- ##### FUNCTION gtk_signal_emit_stop_by_name ##### -->
-<para>
-
+<para>
+This function aborts a signal's current emission.
+</para>
+<para>It is just like
+gtk_signal_emit_stop()
+except it will lookup the signal id for you.
 </para>
 
-@object: 
-@name: 
+@object: the object whose signal handlers you wish to stop.
+@name: the name of the signal you wish to stop.
 
 
 <!-- ##### FUNCTION gtk_signal_connect ##### -->
-<para>
-
-</para>
-
-@object: 
-@name: 
-@func: 
-@func_data: 
-@Returns: 
+<para>
+Attach a function pointer and user data to a signal for
+a particular object.
+</para>
+<para>
+The GtkSignalFunction takes a <StructName>GtkObject</StructName> as its first parameter.
+It will be the same object as the one you're connecting
+the hook to.  The func_data will be passed as the last parameter
+to the hook.
+</para>
+<para>
+All else being equal, signal handlers are invoked in the order 
+connected (see gtk_signal_emit() for the other details of
+which order things are called in).
+</para>
+<para>
+Here is how one passes an integer as user data,
+for when you just want to specify a constant int
+as parameter to your function:
+<informalexample>
+<programlisting>
+static void button_clicked_int(GtkButton* button, gpointer func_data)
+{
+	g_print("button pressed: %d\n", GPOINTER_TO_INT(func_data));
+}
+
+/* By calling this function, you will make the g_print above
+ * execute, printing the number passed as `to_print'. */
+static void attach_print_signal(GtkButton* button, gint to_print)
+{
+	gtk_signal_connect(GTK_OBJECT(button), "clicked",
+		GTK_SIGNAL_FUNC(button_clicked_int),
+		GINT_TO_POINTER(to_print));
+}
+</programlisting>
+</informalexample>
+
+@object: the object associated with the signal, e.g. if a button
+is getting pressed, this is that button.
+@name: name of the signal.
+@func: function pointer to attach to the signal.
+@func_data: value to pass as to your function (through the marshaller).
+@Returns: the connection id.
 
 
 <!-- ##### FUNCTION gtk_signal_connect_after ##### -->
-<para>
-
+<para>
+Attach a function pointer and user data to a signal
+so that this handler will be called after the other handlers.
 </para>
 
-@object: 
-@name: 
-@func: 
-@func_data: 
-@Returns: 
+@object: the object associated with the signal.
+@name: name of the signal.
+@func: function pointer to attach to the signal.
+@func_data: value to pass as to your function (through the marshaller).
+@Returns: the unique identifier for this attachment:  the connection id.
 
 
 <!-- ##### FUNCTION gtk_signal_connect_object ##### -->
-<para>
-
-</para>
-
-@object: 
-@name: 
-@func: 
-@slot_object: 
-@Returns: 
+<para>
+This function is for registering a callback that will
+call another object's callback.  That is,
+instead of passing the object which is responsible
+for the event as the first parameter of the callback,
+it is switched with the user data (so the object which emits
+the signal will be the last parameter, which is where the
+user data usually is).
+</para>
+<para>
+This is useful for passing a standard function in as a callback.
+For example, if you wanted a button's press to gtk_widget_show()
+some widget, you could write:
+</para>
+<informalexample>
+<programlisting>
+gtk_signal_connect_object(button, "clicked", gtk_widget_show, window);
+</programlisting>
+</informalexample>
+
+@object: the object which emits the signal.
+@name: the name of the signal.
+@func: the function to callback.
+@slot_object: the object to pass as the first parameter to func.
+(Though it pretends to take an object, you can
+really pass any gpointer as the #slot_object .)
+@Returns: the connection id.
 
 
 <!-- ##### FUNCTION gtk_signal_connect_object_after ##### -->
-<para>
-
+<para>
+Attach a signal hook to a signal, passing in an alternate
+object as the first parameter, and guaranteeing 
+that the default handler and all normal
+handlers are called first.
 </para>
 
-@object: 
-@name: 
-@func: 
-@slot_object: 
-@Returns: 
+@object: the object associated with the signal.
+@name: name of the signal.
+@func: function pointer to attach to the signal.
+@slot_object: the object to pass as the first parameter to #func.
+@Returns: the connection id.
 
 
 <!-- ##### FUNCTION gtk_signal_connect_full ##### -->
-<para>
-
-</para>
-
-@object: 
-@name: 
-@func: 
-@marshal: 
-@data: 
-@destroy_func: 
-@object_signal: 
-@after: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_signal_connect_object_while_alive ##### -->
-<para>
-
-</para>
-
-@object: 
-@signal: 
-@func: 
-@alive_object: 
+<para>
+Attach a function pointer and user data to a signal with
+more control.
+</para>
+
+@object: the object which emits the signal.  For example, a button
+in the button press signal.
+@name: the name of the signal.
+@func: function pointer to attach to the signal.
+@marshal: the function marshal, see the gtkmarshall documentation for
+more details, but briefly: the marshaller is a function which takes
+the #GtkObject which emits the signal, the user data, the number of the
+arguments, and the array of arguments.  It is responsible for
+calling the function in the appropriate calling convention.
+gtk_signal_default_marshaller is usually fine.
+(This shows up, for example, when worrying about matching
+c++ or other languages' calling conventions.)
+@data: the user data associated with the function.
+@destroy_func: function to call when this particular hook is 
+disconnected.
+@object_signal: whether this is an object signal-- basically an "object
+signal" is one that wants its user_data and object fields switched,
+which is useful for calling functions which operate on another
+object primarily.
+@after: whether to invoke the user-defined handler after the signal, or to let 
+the signal's default behavior preside (i.e. depending on #GTK_RUN_FIRST
+and #GTK_RUN_LAST).
+@Returns: the connection id.
 
 
 <!-- ##### FUNCTION gtk_signal_connect_while_alive ##### -->
-<para>
+<para>
+Attach a function pointer and another GtkObject to a signal.
+</para>
+<para>
+This function takes an object whose "destroy" signal
+should be trapped.
+That way, you don't have to clean up the
+signal handler when you destroy the object.
+It is a little less efficient though.
+</para>
+<para>
+(Instead you may call gtk_signal_disconnect_by_data(), if you want
+to explicitly delete all attachments to this object.  This
+is perhaps not recommended since it could be confused
+with an integer masquerading as a pointer (through GINT_AS_POINTER).)
+</para>
+
+@object: the object that emits the signal.
+@signal: 
+@func: function pointer to attach to the signal.
+@func_data: pointer to pass to func.
+@alive_object: object whose death should cause the handler connection
+to be destroyed.
+<!-- # Unused Parameters # -->
+@name: name of the signal.
 
-</para>
 
-@object: 
+<!-- ##### FUNCTION gtk_signal_connect_object_while_alive ##### -->
+<para>
+These signal connectors are for signals which refer to objects,
+so they must not be called after the object is deleted.
+</para>
+<para>
+Unlike gtk_signal_connect_while_alive(),
+this swaps the object and user data, making it suitable for
+use with functions which primarily operate on the user data.
+</para>
+<para>
+This function acts just like gtk_signal_connect_object() except
+it traps the "destroy" signal to prevent you from having to
+clean up the handler.
+</para>
+
+@object: the object associated with the signal.
 @signal: 
-@func: 
-@func_data: 
-@alive_object: 
+@func: function pointer to attach to the signal.
+@alive_object: the user data, which must be an object, whose destruction
+should signal the removal of this signal.
+<!-- # Unused Parameters # -->
+@name: name of the signal.
 
 
 <!-- ##### FUNCTION gtk_signal_disconnect ##### -->
-<para>
-
+<para>
+Destroy a user-defined handler connection.
 </para>
 
-@object: 
-@handler_id: 
+@object: the object which the handler pertains to.
+@handler_id: the connection id.
 
 
 <!-- ##### FUNCTION gtk_signal_disconnect_by_func ##### -->
-<para>
-
+<para>
+Destroy all connections for a particular object, with
+the given function-pointer and user-data.
 </para>
 
-@object: 
-@func: 
-@data: 
+@object: the object which emits the signal.
+@func: the function pointer to search for.
+@data: the user data to search for.
 
 
 <!-- ##### FUNCTION gtk_signal_disconnect_by_data ##### -->
-<para>
-
+<para>
+Destroy all connections for a particular object, with
+the given user-data.
 </para>
 
-@object: 
-@data: 
+@object: the object which emits the signal.
+@data: the user data to search for.
 
 
 <!-- ##### FUNCTION gtk_signal_handler_block ##### -->
-<para>
-
+<para>
+Prevent an user-defined handler from being invoked.  All other
+signal processing will go on as normal, but this particular
+handler will ignore it.
 </para>
 
-@object: 
-@handler_id: 
+@object: the object which emits the signal to block.
+@handler_id: the connection id.
 
 
 <!-- ##### FUNCTION gtk_signal_handler_block_by_func ##### -->
-<para>
-
+<para>
+Prevent a user-defined handler from being invoked, by reference to
+the user-defined handler's function pointer and user data.  (It may result in
+multiple hooks being blocked, if you've called connect multiple times.)
 </para>
 
-@object: 
-@func: 
-@data: 
+@object: the object which emits the signal to block.
+@func: the function pointer of the handler to block.
+@data: the user data of the handler to block.
 
 
 <!-- ##### FUNCTION gtk_signal_handler_block_by_data ##### -->
-<para>
-
+<para>
+Prevent all user-defined handlers with a certain user data from being invoked.
 </para>
 
-@object: 
-@data: 
+@object: the object which emits the signal we want to block.
+@data: the user data of the handlers to block.
 
 
 <!-- ##### FUNCTION gtk_signal_handler_unblock ##### -->
-<para>
-
+<para>
+Undo a block, by connection id.  Note that undoing a block doesn't
+necessarily make the hook callable, because if you block a
+hook twice, you must unblock it twice.
 </para>
 
-@object: 
-@handler_id: 
+@object: the object which emits the signal we want to unblock.
+@handler_id: the emission handler identifier, as returned by
+gtk_signal_connect(), etc.
 
 
 <!-- ##### FUNCTION gtk_signal_handler_unblock_by_func ##### -->
-<para>
-
+<para>
+Undo a block, by function pointer and data.
+Note that undoing a block doesn't
+necessarily make the hook callable, because if you block a
+hook twice, you must unblock it twice.
 </para>
 
-@object: 
-@func: 
-@data: 
+@object: the object which emits the signal we want to unblock.
+@func: the function pointer to search for.
+@data: the user data to search for.
 
 
 <!-- ##### FUNCTION gtk_signal_handler_unblock_by_data ##### -->
-<para>
-
+<para>
+Undo block(s), to all signals for a particular object
+with a particular user-data pointer
 </para>
 
-@object: 
-@data: 
+@object: the object which emits the signal we want to unblock.
+@data: the user data to search for.
 
 
 <!-- ##### FUNCTION gtk_signal_handler_pending ##### -->
-<para>
-
+<para>
+Returns a connection id corresponding to a given signal id and object.
+</para>
+<para>
+One example of when you might use this is when the arguments
+to the signal are difficult to compute.  A class implementor
+may opt to not emit the signal if no one is attached anyway,
+thus saving the cost of building the arguments.
 </para>
 
-@object: 
-@signal_id: 
-@may_be_blocked: 
-@Returns: 
+@object: the object to search for the desired user-defined handler.
+@signal_id: the number of the signal to search for.
+@may_be_blocked: whether it is acceptable to return a blocked
+handler.
+@Returns: the connection id, if a connection was found.  0 otherwise.
 
 
 <!-- ##### FUNCTION gtk_signal_handler_pending_by_func ##### -->
-<para>
-
+<para>
+Returns a connection id corresponding to a given signal id, object, function
+pointer and user data.
 </para>
 
-@object: 
-@signal_id: 
-@may_be_blocked: 
-@func: 
-@data: 
-@Returns: 
+@object: the object to search for the desired handler.
+@signal_id: the number of the signal to search for.
+@may_be_blocked: whether it is acceptable to return a blocked
+handler.
+@func: the function pointer to search for.
+@data: the user data to search for.
+@Returns: the connection id, if a handler was found.  0 otherwise.
 
 
 <!-- ##### FUNCTION gtk_signal_handler_pending_by_id ##### -->
-<para>
-
+<para>
+Returns whether a connection id is valid (and optionally not blocked).
 </para>
 
-@object: 
-@handler_id: 
-@may_be_blocked: 
-@Returns: 
+@object: the object to search for the desired handler.
+@handler_id: the connection id.
+@may_be_blocked: whether it is acceptable to return a blocked
+handler.
+@Returns: TRUE if the signal exists and wasn't blocked,
+unless #may_be_blocked was specified.  FALSE otherwise.
 
 
 <!-- ##### FUNCTION gtk_signal_handlers_destroy ##### -->
-<para>
-
+<para>
+Destroy all the signal handlers connected to an object.
+This is done automatically when the object is destroyed.
+</para>
+<para>
+This function is labeled private.
 </para>
 
-@object: 
+@object: the object whose signal handlers should be destroyed.
 
 
 <!-- ##### FUNCTION gtk_signal_set_funcs ##### -->
-<para>
-
+<para>
+These set default functions to call when the user didn't
+supply a function when connecting.  (These are rarely
+used, and probably only for language bindings)
+</para>
+<para>
+By default, there are no such functions.
 </para>
 
-@marshal_func: 
-@destroy_func: 
+@marshal_func: the function to invoke on every handlers for which there
+isn't a function pointer.  May be NULL.
+@destroy_func: the function to invoke when each hook is destroyed.
+May be NULL.
 
 
 <!-- ##### FUNCTION gtk_signal_query ##### -->
-<para>
-
+<para>
+Obtain information about a signal.
 </para>
 
-@signal_id: 
-@Returns: 
+@signal_id: the signal type identifier.
+@Returns: a pointer to a GtkSignalQuery structure
+which contains all the information, or NULL.
+The pointer is allocated just for you:  you must g_free() it.
 
 
 <!-- ##### FUNCTION gtk_signal_add_emission_hook ##### -->
-<para>
-
+<para>
+Add an emission hook for a type of signal, for any object.
 </para>
 
-@signal_id: 
-@hook_func: 
-@data: 
-@Returns: 
+@signal_id: the type of signal to hook for.
+@hook_func: the function to invoke to handle the emission hook.
+@data: the user data passed in to hook_func.
+@Returns: the id (that you may pass as a parameter
+to gtk_signal_remove_emission_hook()).
 
 
 <!-- ##### FUNCTION gtk_signal_add_emission_hook_full ##### -->
-<para>
-
+<para>
+Add an emission hook for a type of signal, for any object.
+(with control of what happens when the hook is
+destroyed).
 </para>
 
-@signal_id: 
-@hook_func: 
-@data: 
-@destroy: 
-@Returns: 
+@signal_id: the type of signal add the hook for.
+@hook_func: the function to invoke to handle the hook.
+@data: the user data passed in to hook_func.
+@destroy: a function to invoke when the hook is destroyed,
+to clean up any allocation done just for this
+signal handler.
+@Returns: the id (that you may pass as a parameter
+to gtk_signal_remove_emission_hook()).
 
 
 <!-- ##### FUNCTION gtk_signal_remove_emission_hook ##### -->
-<para>
-
+<para>
+Delete an emission hook. (see gtk_signal_add_emission_hook())
 </para>
 
-@signal_id: 
-@hook_id: 
+@signal_id: the id of the signal type.
+@hook_id: the id of the emission handler, returned by add_emission_hook().
 
 
diff --git a/docs/reference/gtk/tmpl/gtksocket.sgml b/docs/reference/gtk/tmpl/gtksocket.sgml
index ae9ea670f..6023b1044 100644
--- a/docs/reference/gtk/tmpl/gtksocket.sgml
+++ b/docs/reference/gtk/tmpl/gtksocket.sgml
@@ -101,16 +101,6 @@ never be set by an application.)
 </tbody></tgroup></informaltable>
 </para>
 
-@container: 
-@request_width: 
-@request_height: 
-@current_width: 
-@current_height: 
-@plug_window: 
-@same_app: 
-@focus_in: 
-@have_size: 
-@need_map: 
 
 <!-- ##### FUNCTION gtk_socket_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkspinbutton.sgml b/docs/reference/gtk/tmpl/gtkspinbutton.sgml
index 661ea26e1..6bed4c17f 100644
--- a/docs/reference/gtk/tmpl/gtkspinbutton.sgml
+++ b/docs/reference/gtk/tmpl/gtkspinbutton.sgml
@@ -127,24 +127,6 @@ void create_floating_spin_button(void) {
 <structfield>entry</structfield> is the #GtkEntry part of the #GtkSpinButton widget, and can be used accordingly. All other fields contain private data and should only be modified using the functions below.
 </para>
 
-@entry: 
-@adjustment: 
-@panel: 
-@shadow_type: 
-@timer: 
-@ev_time: 
-@climb_rate: 
-@timer_step: 
-@update_policy: 
-@in_child: 
-@click_child: 
-@button: 
-@need_timer: 
-@timer_calls: 
-@digits: 
-@numeric: 
-@wrap: 
-@snap_to_ticks: 
 
 <!-- ##### ENUM GtkSpinButtonUpdatePolicy ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkstatusbar.sgml b/docs/reference/gtk/tmpl/gtkstatusbar.sgml
index 13fa228c7..f751cd051 100644
--- a/docs/reference/gtk/tmpl/gtkstatusbar.sgml
+++ b/docs/reference/gtk/tmpl/gtkstatusbar.sgml
@@ -49,13 +49,6 @@ The message at the top of the stack can be removed using gtk_statusbar_pop(). A
 Contains private data that should be modified with the functions described below.
 </para>
 
-@parent_widget: 
-@frame: 
-@label: 
-@messages: 
-@keys: 
-@seq_context_id: 
-@seq_message_id: 
 
 <!-- ##### STRUCT GtkStatusbarMsg ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtktable.sgml b/docs/reference/gtk/tmpl/gtktable.sgml
index 0ba1ce02e..74fe50b42 100644
--- a/docs/reference/gtk/tmpl/gtktable.sgml
+++ b/docs/reference/gtk/tmpl/gtktable.sgml
@@ -54,15 +54,6 @@ The GtkTable structure holds the data for the actual table itself.
 <structfield>nrows</structfield> and <structfield>ncols</structfield> are 16bit integers storing the number of rows and columns the table has. 
 </para>
 
-@container: 
-@children: 
-@rows: 
-@cols: 
-@nrows: 
-@ncols: 
-@column_spacing: 
-@row_spacing: 
-@homogeneous: 
 
 <!-- ##### STRUCT GtkTableChild ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtktearoffmenuitem.sgml b/docs/reference/gtk/tmpl/gtktearoffmenuitem.sgml
index a065298e8..b155db59c 100644
--- a/docs/reference/gtk/tmpl/gtktearoffmenuitem.sgml
+++ b/docs/reference/gtk/tmpl/gtktearoffmenuitem.sgml
@@ -42,8 +42,6 @@ The #GtkTearoffMenuItem-struct struct contains private data only, and
 should be accessed using the functions below.
 </para>
 
-@menu_item: 
-@torn_off: 
 
 <!-- ##### FUNCTION gtk_tearoff_menu_item_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtktext.sgml b/docs/reference/gtk/tmpl/gtktext.sgml
index 73cd8f003..968a3e286 100644
--- a/docs/reference/gtk/tmpl/gtktext.sgml
+++ b/docs/reference/gtk/tmpl/gtktext.sgml
@@ -42,13 +42,6 @@ at widget creation.</entry>
 
 </para>
 
-@editable: 
-@text_area: 
-@hadj: 
-@vadj: 
-@gc: 
-@line_wrap_bitmap: 
-@line_arrow_bitmap: 
 
 <!-- ##### STRUCT GtkTextFont ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtktipsquery.sgml b/docs/reference/gtk/tmpl/gtktipsquery.sgml
index 0bc6abfaa..7f7949a1d 100644
--- a/docs/reference/gtk/tmpl/gtktipsquery.sgml
+++ b/docs/reference/gtk/tmpl/gtktipsquery.sgml
@@ -2,128 +2,159 @@
 GtkTipsQuery
 
 <!-- ##### SECTION Short_Description ##### -->
-
+displays help about widgets in the user interface.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The #GtkTipsQuery widget is a subclass of #GtkLabel which is used to display
+help about widgets in a user interface.
+</para>
+<para>
+A query is started with a call to gtk_tips_query_start_query(), usually
+when some kind of 'Help' button is pressed. The #GtkTipsQuery then grabs all
+events, stopping the user interface from functioning normally.
+Then as the user moves the mouse over the widgets, the #GtkTipsQuery displays
+each widget's tooltip text.
+</para>
+<para>
+By connecting to the "widget-entered" or "widget-selected" signals, it is
+possible to customize the #GtkTipsQuery to perform other actions when widgets
+are entered or selected. For example, a help browser could be opened with
+documentation on the widget selected.
+</para>
+<para>
+At some point a call to gtk_tips_query_stop_query() must be made in order to
+stop the query and return the interface to its normal state.
+The gtk_tips_query_set_caller() function can be used to specify a widget
+which the user can select to stop the query (often the same button used to
+start the query).
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+<variablelist>
+<varlistentry>
+<term>#GtkTooltips</term>
+<listitem><para>the object which handles tooltips.</para></listitem>
+</varlistentry>
+</variablelist>
 </para>
 
 <!-- ##### STRUCT GtkTipsQuery ##### -->
 <para>
-
+The #GtkTipsQuery-struct struct contains private data only, and
+should be accessed using the functions below.
 </para>
 
-@label: 
-@emit_always: 
-@in_query: 
-@label_inactive: 
-@label_no_tip: 
-@caller: 
-@last_crossed: 
-@query_cursor: 
 
 <!-- ##### FUNCTION gtk_tips_query_new ##### -->
 <para>
-
+Creates a new #GtkTipsQuery.
 </para>
 
-@Returns: 
+@Returns: a new #GtkTipsQuery.
 
 
 <!-- ##### FUNCTION gtk_tips_query_start_query ##### -->
 <para>
-
+Starts a query.
+The #GtkTipsQuery widget will take control of the mouse and as the mouse
+moves it will display the tooltip of the widget beneath the mouse.
 </para>
 
-@tips_query: 
+@tips_query: a #GtkTipsQuery.
 
 
 <!-- ##### FUNCTION gtk_tips_query_stop_query ##### -->
 <para>
-
+Stops a query.
 </para>
 
-@tips_query: 
+@tips_query: a #GtkTipsQuery.
 
 
 <!-- ##### FUNCTION gtk_tips_query_set_caller ##### -->
 <para>
-
+Sets the widget which initiates the query, usually a button.
+If the @caller is selected while the query is running, the query is
+automatically stopped.
 </para>
 
-@tips_query: 
-@caller: 
+@tips_query: a #GtkTipsQuery.
+@caller: the widget which initiates the query.
 
 
 <!-- ##### FUNCTION gtk_tips_query_set_labels ##### -->
 <para>
-
+Sets the text to display when the query is not in effect,
+and the text to display when the query is in effect but the widget beneath
+the pointer has no tooltip.
 </para>
 
-@tips_query: 
-@label_inactive: 
-@label_no_tip: 
+@tips_query: a #GtkTipsQuery.
+@label_inactive: the text to display when the query is not running.
+@label_no_tip: the text to display when the query is running but the widget
+beneath the pointer has no tooltip.
 
 
 <!-- ##### SIGNAL GtkTipsQuery::start-query ##### -->
 <para>
-
+Emitted when the query is started.
 </para>
 
 @tipsquery: the object which received the signal.
 
 <!-- ##### SIGNAL GtkTipsQuery::stop-query ##### -->
 <para>
-
+Emitted when the query is stopped.
 </para>
 
 @tipsquery: the object which received the signal.
 
 <!-- ##### SIGNAL GtkTipsQuery::widget-entered ##### -->
 <para>
-
+Emitted when a widget is entered by the pointer while the query is in effect.
 </para>
 
 @tipsquery: the object which received the signal.
-@widget: 
-@tip_text: 
-@tip_private: 
+@widget: the widget that was entered by the pointer.
+@tip_text: the widget's tooltip.
+@tip_private: the widget's private tooltip (see gtk_tooltips_set_tip()).
 
 <!-- ##### SIGNAL GtkTipsQuery::widget-selected ##### -->
 <para>
-
+Emitted when a widget is selected during a query.
 </para>
 
 @tipsquery: the object which received the signal.
-@widget: 
-@tip_text: 
-@tip_private: 
-@event: 
-@Returns: 
+@widget: the widget that was selected.
+@tip_text: the widget's tooltip.
+@tip_private: the widget's private tooltip (see gtk_tooltips_set_tip()).
+@event: the button press or button release event.
+@Returns: TRUE if the query should be stopped.
 
 <!-- ##### ARG GtkTipsQuery:emit_always ##### -->
 <para>
-
+TRUE if the widget-entered and widget-selected signals are emitted even when
+the widget has no tooltip set.
 </para>
 
 <!-- ##### ARG GtkTipsQuery:caller ##### -->
 <para>
-
+The widget that starts the tips query, usually a button.
+If it is selected while the query is in effect the query is automatically
+stopped.
 </para>
 
 <!-- ##### ARG GtkTipsQuery:label_inactive ##### -->
 <para>
-
+The text to display in the #GtkTipsQuery widget when the query is not in
+effect.
 </para>
 
 <!-- ##### ARG GtkTipsQuery:label_no_tip ##### -->
 <para>
-
+The text to display in the #GtkTipsQuery widget when the query is running
+and the widget that the pointer is over has no tooltip.
 </para>
 
diff --git a/docs/reference/gtk/tmpl/gtktogglebutton.sgml b/docs/reference/gtk/tmpl/gtktogglebutton.sgml
index 3ba8121c4..83dd4acbb 100644
--- a/docs/reference/gtk/tmpl/gtktogglebutton.sgml
+++ b/docs/reference/gtk/tmpl/gtktogglebutton.sgml
@@ -78,10 +78,6 @@ void make_toggles(void) {
 The #GtkToggleButton struct contains private data only, and should be manipulated using the functions below.
 </para>
 
-@button: 
-@active: 
-@draw_indicator: 
-@event_window: 
 
 <!-- ##### FUNCTION gtk_toggle_button_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtktoolbar.sgml b/docs/reference/gtk/tmpl/gtktoolbar.sgml
index 7debeba9f..3ed9166ad 100644
--- a/docs/reference/gtk/tmpl/gtktoolbar.sgml
+++ b/docs/reference/gtk/tmpl/gtktoolbar.sgml
@@ -40,17 +40,6 @@ Widgets can be visibily grouped by adding gaps between widgets using gtk_toolbar
 <structfield>orientation</structfield>
 </para>
 
-@container: 
-@num_children: 
-@children: 
-@orientation: 
-@style: 
-@space_size: 
-@space_style: 
-@tooltips: 
-@button_maxw: 
-@button_maxh: 
-@relief: 
 
 <!-- ##### ENUM GtkToolbarChildType ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtktooltips.sgml b/docs/reference/gtk/tmpl/gtktooltips.sgml
index fba097eb9..a78350fc0 100644
--- a/docs/reference/gtk/tmpl/gtktooltips.sgml
+++ b/docs/reference/gtk/tmpl/gtktooltips.sgml
@@ -78,16 +78,6 @@ Information about the tooltip (if any) associated with an arbitrary widget can b
 <para>Holds information about a group of tooltips. Fields should be changed using the functions provided, rather than directly accessing the struct's members.
 </para>
 
-@data: 
-@tip_window: 
-@active_tips_data: 
-@tips_data_list: 
-@gc: 
-@foreground: 
-@background: 
-@delay: 
-@enabled: 
-@timer_tag: 
 
 <!-- ##### STRUCT GtkTooltipsData ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtktree.sgml b/docs/reference/gtk/tmpl/gtktree.sgml
index 84be04bd2..b42794aec 100644
--- a/docs/reference/gtk/tmpl/gtktree.sgml
+++ b/docs/reference/gtk/tmpl/gtktree.sgml
@@ -37,17 +37,6 @@ struct _GtkTree
 </programlisting>
 </para>
 
-@container: 
-@children: 
-@root_tree: 
-@tree_owner: 
-@selection: 
-@level: 
-@indent_value: 
-@current_indent: 
-@selection_mode: 
-@view_mode: 
-@view_line: 
 
 <!-- ##### MACRO GTK_IS_ROOT_TREE ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtktreeitem.sgml b/docs/reference/gtk/tmpl/gtktreeitem.sgml
index fd745a729..8c39ed77f 100644
--- a/docs/reference/gtk/tmpl/gtktreeitem.sgml
+++ b/docs/reference/gtk/tmpl/gtktreeitem.sgml
@@ -19,11 +19,6 @@ GtkTreeItem
 
 </para>
 
-@item: 
-@subtree: 
-@pixmaps_box: 
-@pixmaps: 
-@expanded: 
 
 <!-- ##### MACRO GTK_TREE_ITEM_SUBTREE ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkvbbox.sgml b/docs/reference/gtk/tmpl/gtkvbbox.sgml
index d0fe4c865..9ebcd7ed0 100644
--- a/docs/reference/gtk/tmpl/gtkvbbox.sgml
+++ b/docs/reference/gtk/tmpl/gtkvbbox.sgml
@@ -19,7 +19,6 @@ GtkVButtonBox
 
 </para>
 
-@button_box: 
 
 <!-- ##### FUNCTION gtk_vbutton_box_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkvbox.sgml b/docs/reference/gtk/tmpl/gtkvbox.sgml
index 306f685ab..2f317fa4b 100644
--- a/docs/reference/gtk/tmpl/gtkvbox.sgml
+++ b/docs/reference/gtk/tmpl/gtkvbox.sgml
@@ -33,7 +33,6 @@ All children are allocated the same width.
 <!-- ##### STRUCT GtkVBox ##### -->
 
 
-@box: 
 
 <!-- ##### FUNCTION gtk_vbox_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkviewport.sgml b/docs/reference/gtk/tmpl/gtkviewport.sgml
index a43582f0c..6ce665c5f 100644
--- a/docs/reference/gtk/tmpl/gtkviewport.sgml
+++ b/docs/reference/gtk/tmpl/gtkviewport.sgml
@@ -19,12 +19,6 @@ GtkViewport
 
 </para>
 
-@bin: 
-@shadow_type: 
-@view_window: 
-@bin_window: 
-@hadjustment: 
-@vadjustment: 
 
 <!-- ##### FUNCTION gtk_viewport_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkvpaned.sgml b/docs/reference/gtk/tmpl/gtkvpaned.sgml
index f6d41bc5a..edcff3251 100644
--- a/docs/reference/gtk/tmpl/gtkvpaned.sgml
+++ b/docs/reference/gtk/tmpl/gtkvpaned.sgml
@@ -21,7 +21,6 @@ a handle. See #GtkPaned for details.
 <para>
 </para>
 
-@paned: 
 
 <!-- ##### FUNCTION gtk_vpaned_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkvruler.sgml b/docs/reference/gtk/tmpl/gtkvruler.sgml
index 789cd16ce..aad5d12e2 100644
--- a/docs/reference/gtk/tmpl/gtkvruler.sgml
+++ b/docs/reference/gtk/tmpl/gtkvruler.sgml
@@ -19,14 +19,12 @@ rulers.
 
 </para>
 
-
 <!-- ##### STRUCT GtkVRuler ##### -->
 <para>
 The #GtkVRuler struct contains private data and should be accessed
 using the functions below. 
 </para>
 
-@ruler: 
 
 <!-- ##### FUNCTION gtk_vruler_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkvscale.sgml b/docs/reference/gtk/tmpl/gtkvscale.sgml
index 0b0e0171d..81a6ffa29 100644
--- a/docs/reference/gtk/tmpl/gtkvscale.sgml
+++ b/docs/reference/gtk/tmpl/gtkvscale.sgml
@@ -27,7 +27,6 @@ The #GtkVScale-struct struct contains private data only, and
 should be accessed using the functions below.
 </para>
 
-@scale: 
 
 <!-- ##### FUNCTION gtk_vscale_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkvscrollbar.sgml b/docs/reference/gtk/tmpl/gtkvscrollbar.sgml
index ecff50a5b..758fd4334 100644
--- a/docs/reference/gtk/tmpl/gtkvscrollbar.sgml
+++ b/docs/reference/gtk/tmpl/gtkvscrollbar.sgml
@@ -17,14 +17,12 @@ will be created you. See #GtkAdjustment for details.
 
 </para>
 
-
 <!-- ##### STRUCT GtkVScrollbar ##### -->
 <para>
 The #GtkVScrollbar struct contains private data and should be accessed
 using the functions below.
 </para>
 
-@scrollbar: 
 
 <!-- ##### FUNCTION gtk_vscrollbar_new ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkvseparator.sgml b/docs/reference/gtk/tmpl/gtkvseparator.sgml
index 6e4b7047c..dd4606d37 100644
--- a/docs/reference/gtk/tmpl/gtkvseparator.sgml
+++ b/docs/reference/gtk/tmpl/gtkvseparator.sgml
@@ -2,30 +2,37 @@
 GtkVSeparator
 
 <!-- ##### SECTION Short_Description ##### -->
-
+a vertical separator.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The #GtkVSeparator widget is a vertical separator, used to group the
+widgets within a window. It displays a vertical line with a shadow to
+make it appear sunken into the interface.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+<variablelist>
+<varlistentry>
+<term>#GtkHSeparator</term>
+<listitem><para>a horizontal separator.</para></listitem>
+</varlistentry>
+</variablelist>
 </para>
 
 <!-- ##### STRUCT GtkVSeparator ##### -->
 <para>
-
+The #GtkVSeparator-struct struct contains private data only, and
+should be accessed using the functions below.
 </para>
 
-@separator: 
 
 <!-- ##### FUNCTION gtk_vseparator_new ##### -->
 <para>
-
+Creates a new #GtkVSeparator.
 </para>
 
-@Returns: 
+@Returns: a new #GtkVSeparator.
 
 
diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml
index 3ecc84727..515a535e5 100644
--- a/docs/reference/gtk/tmpl/gtkwidget.sgml
+++ b/docs/reference/gtk/tmpl/gtkwidget.sgml
@@ -19,16 +19,6 @@ GtkWidget
 
 </para>
 
-@object: 
-@private_flags: 
-@state: 
-@saved_state: 
-@name: 
-@style: 
-@requisition: 
-@allocation: 
-@window: 
-@parent: 
 
 <!-- ##### ENUM GtkWidgetFlags ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkwindow.sgml b/docs/reference/gtk/tmpl/gtkwindow.sgml
index abb94a3fa..34cb93790 100644
--- a/docs/reference/gtk/tmpl/gtkwindow.sgml
+++ b/docs/reference/gtk/tmpl/gtkwindow.sgml
@@ -19,22 +19,6 @@ GtkWindow
 
 </para>
 
-@bin: 
-@title: 
-@wmclass_name: 
-@wmclass_class: 
-@type: 
-@focus_widget: 
-@default_widget: 
-@transient_parent: 
-@resize_count: 
-@allow_shrink: 
-@allow_grow: 
-@auto_shrink: 
-@handling_resize: 
-@position: 
-@use_uposition: 
-@modal: 
 
 <!-- ##### FUNCTION gtk_window_new ##### -->
 <para>
author	Damon Chaplin <damon@karuna.freeserve.co.uk>	1999-09-22 21:30:57 +0000
committer	Damon Chaplin <damon@src.gnome.org>	1999-09-22 21:30:57 +0000
commit	372c4d2627e4cb15a3bec51d051f4cc30afc5138 (patch)
tree	47494baccbd01d820fd39a00182bc7502d3f646e /docs/reference
parent	9e7433487be556e130e8c14c6317eb6f04697330 (diff)
download	gdk-pixbuf-372c4d2627e4cb15a3bec51d051f4cc30afc5138.tar.gz