Fix a comment.

        * gtk/gtkobject.c (gtk_object_dispose): Fix a comment.

        * gtk/gtkwidget.c (gtk_widget_set_sensitive): tiny docs change

        * gtk/changes-1.2.sgml, gtk/changes-2.0.sgml: SGML fixes.

        * gtk/tmpl/gtkobject.sgml: Document GTK_IN_DESTRUCTION.

        * gtk/tmpl/gtkwidget.sgml: Additions.

5 files changed, 163 insertions, 86 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 511d9ffa17..d8463a8e30 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,11 @@
+2002-01-04  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/changes-1.2.sgml, gtk/changes-2.0.sgml: SGML fixes.
+
+	* gtk/tmpl/gtkobject.sgml: Document GTK_IN_DESTRUCTION.
+	
+	* gtk/tmpl/gtkwidget.sgml: Additions.
+
 2002-01-04  Havoc Pennington  <hp@pobox.com>
 
 	* gtk/question_index.sgml: add question to help people find
diff --git a/docs/reference/gtk/changes-1.2.sgml b/docs/reference/gtk/changes-1.2.sgml
index f54a1dabec..1f013ba53f 100644
--- a/docs/reference/gtk/changes-1.2.sgml
+++ b/docs/reference/gtk/changes-1.2.sgml
@@ -36,7 +36,7 @@ provided to ease the migration phase.
 
 <listitem>
 <para>
-The <stuctname>GtkTypeInfo</structname> structures used in the 
+The <structname>GtkTypeInfo</structname> structures used in the 
 <function>gtk_*_type_init()</function> functions have
 changed a bit, the old format:
 <programlisting>
@@ -89,6 +89,7 @@ A number of GTK+ functions were renamed. For compatibility,
   Here is the list of the old names and replacements:
 
 <informaltable>
+<tgroup>
 <thead>
 <row><entry>Old</entry><entry>Replacement</entry></row>
 </thead>
@@ -106,6 +107,7 @@ A number of GTK+ functions were renamed. For compatibility,
 <row><entry><function>gtk_toggle_button_set_state</function></entry><entry><function>gtk_toggle_button_set_active</function></entry></row>
 <row><entry><function>gtk_window_position</function></entry><entry><function>gtk_window_set_position</function></entry></row>
 </tbody>
+</tgroup>
 </informaltable> 
 Note that <function>gtk_style_apply_default_background()</function> has an 
       additional argument, <literal>set_bg</literal>. This parameter should be 
@@ -120,6 +122,7 @@ During the development phase of the 1.1.x line of GTK+ certain functions
   were deprecated and later removed. Functions affected are:
 
 <informaltable>
+<tgroup>
 <thead>
 <row><entry>Removed</entry><entry>Replacement</entry></row>
 </thead>
@@ -140,6 +143,7 @@ During the development phase of the 1.1.x line of GTK+ certain functions
 <row><entry><function>gtk_widget_thaw_accelerators</function></entry><entry><function>gtk_widget_unlock_accelerators</function></entry></row>
 <row><entry><function>gtk_widget_freeze_accelerators</function></entry><entry><function>gtk_widget_lock_accelerators</function></entry></row>
 </tbody>
+</tgroup>
 </informaltable>
 
 Note that <function>gtk_entry_adjust_scroll()</function> is no longer needed 
@@ -226,19 +230,25 @@ Support for Themes has been added. In general, this does
   not affect application code, however, a few new rules should
   be observed:
 
-<programlisting>
-   - To set a shape for a window, you must use 
+  <itemizedlist>
+  <listitem>
+  <para>To set a shape for a window, you must use 
      <function>gtk_widget_shape_combine_mask()</function> instead of 
      <function>gdk_window_shape_combine_mask()</function>, or the shape will be
      reset when switching themes.
+  </para>
+  </listitem>
 
-   - It is no longer permissable to draw directly on an arbitrary
+  <listitem>
+  <para>It is no longer permissable to draw directly on an arbitrary
      widget, or to set an arbitrary widget's background pixmap.
      If you need to do that, use a <structname>GtkDrawingArea</structname> or 
      (for a toplevel) a <structname>GtkWindow</structname> where 
      <function>gtk_widget_set_app_paintable()</function>
      has been called.
-</programlisting>
+  </para>
+  </listitem>
+  </itemizedlist>
 </para>
 </listitem>
 
@@ -384,14 +394,10 @@ The thread safety in GTK+ 1.2 is slightly different than
            </para>
          </listitem>
          <listitem>
-           <para>Link with the libraries returned by:
- 
+           <para>Link with the libraries returned by
              <command>gtk-config --libs gthread</command>
-
-             and use the cflags from:
-
-             <command>gtk-config --cflags gthread</command>
-
+             and use the cflags from
+             <command>gtk-config --cflags gthread</command>.
              You can get these <envar>CFLAGS</envar> and <envar>LIBS</envar> by 
              passing <literal>gthread</literal> as the fourth parameter to the 
              <literal>AM_PATH_GTK</literal> <application>automake</application>
diff --git a/docs/reference/gtk/changes-2.0.sgml b/docs/reference/gtk/changes-2.0.sgml
index 27af0d19cd..6e5750e930 100644
--- a/docs/reference/gtk/changes-2.0.sgml
+++ b/docs/reference/gtk/changes-2.0.sgml
@@ -164,6 +164,7 @@ The type macros <function>GTK_TYPE_MAKE()</function> and <function>GTK_TYPE_SEQN
 <para>
 The following type functions vanished/were replaced:
 <informaltable>
+<tgroup>
 <thead>
 <row><entry>Old Function</entry><entry>Replacement</entry></row>
 </thead>
@@ -182,6 +183,7 @@ The following type functions vanished/were replaced:
 <row><entry><function>gtk_type_register_flags()</function></entry><entry><function>g_flags_register_static()</function></entry></row>
 <row><entry><function>gtk_type_parent_class()</function></entry><entry><functiono>g_type_parent()</function>/<function>g_type_class_peek_parent()</function></entry></row>
 </tbody>
+</tgroup>
 </informaltable>
     Use of <function>g_type_class_ref()</function>/<function>g_type_class_unref()</function> and <function>g_type_class_peek()</function>
     is recommended over usage of <function>gtk_type_class()</function>.
@@ -381,7 +383,7 @@ All drawables including pixmaps used to have a type tag, the
   (from class to instance). This gives themes a bit more flexibility
   and is generally more of the Right Thing. You can trivially fix
   your code with <literal>s/style-&gt;klass-&gt;xthickness/style-&gt;xthickness/g</literal> and 
-  same for <structfield>ythickness</structfield>.
+  same for <literal>ythickness</literal>.
 </para>
 </listitem>
 
@@ -422,6 +424,7 @@ A number of functions in GDK have been renamed for consistency and
   included, but can be disabled by defining <literal>GDK_DISABLE_DEPRECATED</literal>.
 
 <informaltable>
+<tgroup>
 <thead>
 <row><entry>Old function</entry><entry>Defined As</entry></row>
 </thead>
@@ -445,6 +448,7 @@ A number of functions in GDK have been renamed for consistency and
 <row><entry><function>gdk_window_copy_area(drawable,gc,x,y,source_drawable,source_x,source_y,width,height)</function></entry><entry><function>gdk_draw_pixmap(drawable,gc,source_drawable,source_x,source_y,x,y,width,height)</function></entry></row>
 <row><entry><function>gdk_rgb_get_cmap</function></entry><entry><function>gdk_rgb_get_colormap</function></entry></row>
 </tbody>
+</tgroup>
 </informaltable>
   (Note that <function>g_object_ref()</function> and 
   <function>g_object_unref()</function> may be used for all of the above ref 
@@ -744,6 +748,7 @@ The <function>set_child_arg()</function> and <function>get_child_arg()</function
 Other removed <structname>GtkContainer</structname> functions with the replacements:
 
 <informaltable>
+<tgroup>
 <thead>
 <row><entry>Old function</entry><entry>Replacement</entry></row>
 </thead>
@@ -755,6 +760,7 @@ Other removed <structname>GtkContainer</structname> functions with the replaceme
 <row><entry><function>gtk_container_add_with_args</function></entry><entry><function>gtk_container_add_with_properties</function></entry></row>
 <row><entry><function>gtk_container_addv</function></entry><entry><function>gtk_container_add</function>/<function>gtk_container_child_set_property</function></entry></row>
 </tbody>
+</tgroup>
 </informaltable>
 </para>
 </listitem>
@@ -902,20 +908,26 @@ The following variables are no longer exported from GDK. (Other variables
   are also no longer exported; the following are the ones found used
   externally in a large sample of GTK+ code.)
 
-<programlisting>
-   Variable                               Replacement
-   ========                               ===========
-   gdk_null_window_warnings               None - did nothing in GTK+ 1.2.
-   gdk_leader_window                      None - private variable
-   gdk_screen                             gdk_x11_get_default_screen ()
-   gdk_root_window                        gdk_x11_get_default_root_xwindow ()
-   gdk_root_parent                        gdk_get_default_root_window ()
-   gdk_error_code/gdk_error_warnings      gdk_error_trap_push()/pop()
-   gdk_display_name                       gdk_get_display ()
-   gdk_wm_delete_window                   gdk_atom_intern ("WM_DELETE_WINDOW", FALSE)
-   gdk_wm_take_focus                      gdk_atom_intern ("WM_TAKE_FOCUS", FALSE)
-   gdk_wm_protocols                       gdk_atom_intern ("WM_PROTOCOLS", FALSE)
-</programlisting>
+<informaltable>
+<tgroup>
+<thead>
+<row><entry>Variable</entry><entry>Replacement</entry></row>
+</thead>
+<tbody>
+<row><entry><literal>gdk_null_window_warnings</literal></entry><entry>None - did nothing in GTK+ 1.2</entry></row>
+<row><entry><literal>gdk_leader_window</literal></entry><entry>None - private variable</entry></row>
+<row><entry><literal>gdk_screen</literal></entry><entry><function>gdk_x11_get_default_screen ()</function></entry></row>
+<row><entry><literal>gdk_root_window</literal></entry><entry><function>gdk_x11_get_default_root_xwindow ()</function></entry></row>
+<row><entry><literal>gdk_root_parent</literal></entry><entry><function>gdk_get_default_root_window ()</function></entry></row>
+<row><entry><literal>gdk_error_code</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function>/entry></row>
+<row><entry><literal>gdk_error_warnings</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function></entry></row>
+<row><entry><literal>gdk_display_name</literal></entry><entry><function>gdk_get_display ()</function></entry></row>
+<row><entry><literal>gdk_wm_delete_window</literal></entry><entry><literal>gdk_atom_intern ("WM_DELETE_WINDOW", FALSE)</literal></entry></row>
+<row><entry><literal>gdk_wm_take_focus</literal></entry><entry><literal>gdk_atom_intern ("WM_TAKE_FOCUS", FALSE)</literal></entry></row>
+<row><entry><literal>gdk_wm_protocols</literal></entry><entry><literal>gdk_atom_intern ("WM_PROTOCOLS", FALSE)</literal></entry></row>
+</tbody>
+</tgroup>
+</informaltable>
 </para>
 </listitem>
    
@@ -1042,8 +1054,8 @@ If you are embedding one of these widgets in a custom widget,
 
 <listitem>
 <para>
-<structname>GtkLayout</structname> no longer has the <literal>xoffset</literal>,
-  <literal>yoffset</literal> fields, which used to store the difference between
+<structname>GtkLayout</structname> no longer has the <structfield>xoffset</structfield>,
+  <structfield>yoffset</structfield> fields, which used to store the difference between
   world and window coordinates for <literal>layout-&gt;bin_window</literal>. 
   These coordinate systems are now always the same.
 </para>
diff --git a/docs/reference/gtk/tmpl/gtkobject.sgml b/docs/reference/gtk/tmpl/gtkobject.sgml
index 3b975bc0f8..0cc15ca13d 100644
--- a/docs/reference/gtk/tmpl/gtkobject.sgml
+++ b/docs/reference/gtk/tmpl/gtkobject.sgml
@@ -119,13 +119,12 @@ Gets the name of an objects type.
 Tells about the state of the object.
 </para>
 
-@GTK_IN_DESTRUCTION: 
-@GTK_FLOATING: whether the object is orphaned.  Objects that take
-strong hold of an object may gtk_object_sink() it, after obtaining
-there own references, if they believe they are nearly primary
-ownership of the object.
-GTK_CONNECTED: refers to whether are signals are connected to this
-object.
+@GTK_IN_DESTRUCTION: the object is currently being destroyed. This is used 
+  internally by GTK+ to prevent reinvokations during destruction. 
+@GTK_FLOATING: the object is orphaned.  Objects that take strong hold of an 
+  object may gtk_object_sink() it, after obtaining their own references, if 
+  they believe they are nearly primary ownership of the object.
+GTK_CONNECTED: signals are connected to this object.
 @GTK_RESERVED_1: reserved for future use
 @GTK_RESERVED_2: reserved for future use
 
diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml
index 1a9670b1d0..92cac33bb3 100644
--- a/docs/reference/gtk/tmpl/gtkwidget.sgml
+++ b/docs/reference/gtk/tmpl/gtkwidget.sgml
@@ -22,27 +22,69 @@ GtkWidget
 
 <!-- ##### ENUM GtkWidgetFlags ##### -->
 <para>
-
+Tells about certain properties of the widget.
 </para>
 
 @GTK_TOPLEVEL: 
+        widgets without a real parent, as there are #GtkWindows and
+        #GtkMenus have this flag set throughout their lifetime.
+        Toplevel widgets always contain their own #GdkWindow.
 @GTK_NO_WINDOW: 
+        Indicative for a widget that does not provide its own #GdkWindow. 
+        Visible action (e.g. drawing) is performed on the parent's #GdkWindow.
 @GTK_REALIZED: 
+        Set by gtk_widget_realize(), unset by gtk_widget_unrealize().
+        A realized widget has an associated #GdkWindow.
 @GTK_MAPPED: 
+        Set by gtk_widget_map(), unset by gtk_widget_unmap().
+        Only realized widgets can be mapped. It means that gdk_window_show() 
+        has been called on the widgets window(s).
 @GTK_VISIBLE: 
+        Set by gtk_widget_show(), unset by gtk_widget_hide(). Implies that a 
+        widget will be mapped as soon as its parent is mapped.
 @GTK_SENSITIVE: 
+        Set and unset by gtk_widget_set_sensitive().
+        The sensitivity of a widget determines whether it will receive
+        certain events (e.g. button or key presses). One premise for
+        the widgets sensitivity is to have this flag set.
 @GTK_PARENT_SENSITIVE: 
+        Set and unset by gtk_widget_set_sensitive() operations on the
+        parents of the widget.
+        This is the second premise for the widgets sensitivity. Once
+        it has %GTK_SENSITIVE and %GTK_PARENT_SENSITIVE set, its state is
+        effectively sensitive. This is expressed (and can be examined) by
+        the #GTK_WIDGET_IS_SENSITIVE macro.
 @GTK_CAN_FOCUS: 
+        Determines whether a widget is able to handle focus grabs.
 @GTK_HAS_FOCUS: 
+        Set by gtk_widget_grab_focus() for widgets that also
+        have %GTK_CAN_FOCUS set. The flag will be unset once another widget
+        grabs the focus.
 @GTK_CAN_DEFAULT: 
+        The widget is allowed to receive the default action via 
+        gtk_widget_grab_default().
 @GTK_HAS_DEFAULT: 
+        The widget currently is receiving the default action.
 @GTK_HAS_GRAB: 
+        Set by gtk_grab_add(), unset by gtk_grab_remove(). It means that the 
+        widget is in the grab_widgets stack, and will be the preferred one for 
+        receiving events other than ones of cosmetic value.
 @GTK_RC_STYLE: 
+        Indicates that the widgets style has been looked up through the rc 
+        mechanism. It does not imply that the widget actually had a style 
+        defined through the rc mechanism.
 @GTK_COMPOSITE_CHILD: 
+        Indicates that the widget is a composite child of its parent; see 
+        gtk_widget_push_composite_child(), gtk_widget_pop_composite_child(). 
 @GTK_NO_REPARENT: 
 @GTK_APP_PAINTABLE: 
+        Set and unset by gtk_widget_set_app_paintable().
 @GTK_RECEIVES_DEFAULT: 
+        The widget when focused will receive the default action and have 
+        %GTK_HAS_DEFAULT set even if there is a different widget set as default.
 @GTK_DOUBLE_BUFFERED: 
+        Set and unset by gtk_widget_set_double_buffered().
+        Indicates that exposes done on the widget should be double-buffered.
 
 <!-- ##### MACRO GTK_WIDGET_TYPE ##### -->
 <para>
@@ -54,175 +96,185 @@ GtkWidget
 
 <!-- ##### MACRO GTK_WIDGET_STATE ##### -->
 <para>
-
+Returns the current state of the widget, as a #GtkStateType.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_SAVED_STATE ##### -->
 <para>
-
+Returns the saved state of the widget, as a #GtkStateType.
+</para>
+<para>
+The saved state will be restored when a widget gets sensitive
+again, after it has been made insensitive with gtk_widget_set_state()
+or gtk_widget_set_sensitive().
 </para>
 
-@wid: 
+@wid: a #GtkWidget. 
 
 
 <!-- ##### MACRO GTK_WIDGET_FLAGS ##### -->
 <para>
-
+Returns the widget flags from @wid.
 </para>
 
-@wid: 
+@wid: a #GtkWidget. 
 
 
 <!-- ##### MACRO GTK_WIDGET_TOPLEVEL ##### -->
 <para>
-
+Evaluates to %TRUE if the widget is a toplevel widget.
 </para>
 
-@wid: 
+@wid: a #GtkWidget. 
 
 
 <!-- ##### MACRO GTK_WIDGET_NO_WINDOW ##### -->
 <para>
-
+Evaluates to %TRUE if the widget doesn't have an own #GdkWindow.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_REALIZED ##### -->
 <para>
-
+Evaluates to %TRUE if the widget is realized.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_MAPPED ##### -->
 <para>
-
+Evaluates to %TRUE if the widget is mapped.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_VISIBLE ##### -->
 <para>
-
+Evaluates to %TRUE if the widget is visible.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_DRAWABLE ##### -->
 <para>
-
+Evaluates to %TRUE if the widget is mapped and visible.
 </para>
 
-@wid: 
+@wid: a #GtkWidget. 
 
 
 <!-- ##### MACRO GTK_WIDGET_SENSITIVE ##### -->
 <para>
-
+Evaluates to %TRUE if the #GTK_SENSITIVE flag has be set on the widget.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_PARENT_SENSITIVE ##### -->
 <para>
-
+Evaluates to %TRUE if the #GTK_PARENT_SENSITIVE flag has be set on the widget.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_IS_SENSITIVE ##### -->
 <para>
-
+Evaluates to %TRUE if the widget is effectively sensitive.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_CAN_FOCUS ##### -->
 <para>
-
+Evaluates to %TRUE if the widget is able to handle focus grabs.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_HAS_FOCUS ##### -->
 <para>
-
+Evaluates to %TRUE if the widget has grabbed the focus and no other
+widget has done so more recently.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_CAN_DEFAULT ##### -->
 <para>
-
+Evaluates to %TRUE if the widget is allowed to receive the default action 
+via gtk_widget_grab_default(). 
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_RECEIVES_DEFAULT ##### -->
 <para>
-
+Evaluates to %TRUE if the widget when focused will receive the default action 
+even if there is a different widget set as default.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_HAS_DEFAULT ##### -->
 <para>
-
+Evaluates to %TRUE if the widget currently is receiving the default action.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_HAS_GRAB ##### -->
 <para>
-
+Evaluates to %TRUE if the widget is in the grab_widgets stack, and will be 
+the preferred one for receiving events other than ones of cosmetic value.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_RC_STYLE ##### -->
 <para>
-
+Evaluates to %TRUE if the widgets style has been looked up through the rc
+mechanism.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_COMPOSITE_CHILD ##### -->
 <para>
-
+Evaluates to %TRUE if the widget is a composite child of its parent.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_APP_PAINTABLE ##### -->
 <para>
-
+Evaluates to %TRUE if the #GTK_APP_PAINTABLE flag has been set on the widget.
 </para>
 
-@wid: 
+@wid: a #GtkWidget.
 
 
 <!-- ##### MACRO GTK_WIDGET_DOUBLE_BUFFERED ##### -->
 <para>
-
+Evaluates to %TRUE if the #GTK_DOUBLE_BUFFERED flag has been set on the widget.
 </para>
 
 @wid: 
@@ -230,20 +282,20 @@ GtkWidget
 
 <!-- ##### MACRO GTK_WIDGET_SET_FLAGS ##### -->
 <para>
-
+Turns on certain widget flags.
 </para>
 
-@wid: 
-@flag: 
+@wid: a #GtkWidget. 
+@flag: the flags to set.
 
 
 <!-- ##### MACRO GTK_WIDGET_UNSET_FLAGS ##### -->
 <para>
-
+Turns off certain widget flags.
 </para>
 
-@wid: 
-@flag: 
+@wid: a #GtkWidget. 
+@flag: the flags to unset.
 
 
 <!-- ##### USER_FUNCTION GtkCallback ##### -->