rearranged a bit.

2000-02-03  Damon Chaplin  <damon@karuna.freeserve.co.uk>

	* gdk/gdk-sections.txt: rearranged a bit.

	* gdk/tmpl/event_structs.sgml: updated.

	* gtk/gtk-sections.txt: added INCLUDE tag for Private Info section.

	* gdk/tmpl/color_contexts.sgml: added note saying it is deprecated.
	* gdk/tmpl/dnd.sgml: added note saying read the GTK+ DnD docs.

8 files changed, 245 insertions, 149 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 320c8cd2b..7488baa57 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,14 @@
+2000-02-03  Damon Chaplin  <damon@karuna.freeserve.co.uk>
+
+	* gdk/gdk-sections.txt: rearranged a bit.
+
+	* gdk/tmpl/event_structs.sgml: updated.
+
+	* gtk/gtk-sections.txt: added INCLUDE tag for Private Info section.
+
+	* gdk/tmpl/color_contexts.sgml: added note saying it is deprecated.
+	* gdk/tmpl/dnd.sgml: added note saying read the GTK+ DnD docs.
+
 2000-02-02  Damon Chaplin  <damon@karuna.freeserve.co.uk>
 
 	* gdk/tmpl/*.sgml: ran make templates.
diff --git a/docs/reference/gdk/gdk-sections.txt b/docs/reference/gdk/gdk-sections.txt
index 9f84c8106..18ea372c9 100644
--- a/docs/reference/gdk/gdk-sections.txt
+++ b/docs/reference/gdk/gdk-sections.txt
@@ -306,6 +306,7 @@ gdk_window_add_filter
 gdk_window_remove_filter
 GdkFilterFunc
 GdkFilterReturn
+GdkXEvent
 gdk_window_shape_combine_mask
 gdk_window_set_child_shapes
 gdk_window_merge_child_shapes
@@ -552,27 +553,30 @@ gdk_set_show_events
 <SECTION>
 <TITLE>Event Structures</TITLE>
 <FILE>event_structs</FILE>
+GdkEvent
+
+<SUBSECTION>
 GdkEventAny
+GdkEventKey
+GdkEventButton
+GdkEventMotion
 GdkEventExpose
-GdkEventNoExpose
 GdkEventVisibility
-GdkVisibilityState
-GdkEventMotion
-GdkEventButton
-GdkEventKey
 GdkEventCrossing
-GdkCrossingMode
-GdkNotifyType
 GdkEventFocus
 GdkEventConfigure
 GdkEventProperty
-GdkPropertyState
 GdkEventSelection
+GdkEventDND
 GdkEventProximity
 GdkEventClient
-GdkEventDND
-GdkEvent
-GdkXEvent
+GdkEventNoExpose
+
+<SUBSECTION>
+GdkVisibilityState
+GdkCrossingMode
+GdkNotifyType
+GdkPropertyState
 </SECTION>
 
 <SECTION>
diff --git a/docs/reference/gdk/tmpl/color_contexts.sgml b/docs/reference/gdk/tmpl/color_contexts.sgml
index 506b77f51..af6455024 100644
--- a/docs/reference/gdk/tmpl/color_contexts.sgml
+++ b/docs/reference/gdk/tmpl/color_contexts.sgml
@@ -2,11 +2,16 @@
 Color Contexts
 
 <!-- ##### SECTION Short_Description ##### -->
-
+routines for allocating colors (deprecated).
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The #GdkColorContext type is used for allocating groups of colors.
+</para>
+<para>
+It is now deprecated in favor of the gdk_colormap_*() functions described in
+the <link linkend="gdk-Colormaps-and-Colors">Colormaps and Colors</link>
+section.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/docs/reference/gdk/tmpl/dnd.sgml b/docs/reference/gdk/tmpl/dnd.sgml
index 1d7110169..c61ad4c6f 100644
--- a/docs/reference/gdk/tmpl/dnd.sgml
+++ b/docs/reference/gdk/tmpl/dnd.sgml
@@ -2,11 +2,18 @@
 Drag and Drop
 
 <!-- ##### SECTION Short_Description ##### -->
-
+functions for controlling drag and drop handling.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+These functions provide a low level interface for drag and drop.
+GDK supports both the Xdnd and Motif drag and drop protocols transparently.
+</para>
+<para>
+GTK+ provides a higher level abstraction based on top of these functions,
+and so they are not normally needed in GTK+ applications.
+See the <link linkend="gtk-Drag-and-Drop">Drag and Drop</link> section of
+the GTK+ documentation for more information.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/docs/reference/gdk/tmpl/event_structs.sgml b/docs/reference/gdk/tmpl/event_structs.sgml
index 75961e8b3..b5a9d1344 100644
--- a/docs/reference/gdk/tmpl/event_structs.sgml
+++ b/docs/reference/gdk/tmpl/event_structs.sgml
@@ -2,11 +2,11 @@
 Event Structures
 
 <!-- ##### SECTION Short_Description ##### -->
-
+data structures specific to each type of event.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The event structs contain data specific to each type of event in GDK.
 </para>
 <note>
 <para>
@@ -20,75 +20,81 @@ required events are received. See gtk_widget_set_events().
 
 </para>
 
-<!-- ##### STRUCT GdkEventAny ##### -->
-<para>
-Contains the fields which are common to all event structs.
-Any event can safely be cast to a #GdkEventAny to access these fields.
-</para>
-
-@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).
-
-<!-- ##### STRUCT GdkEventExpose ##### -->
+<!-- ##### UNION GdkEvent ##### -->
 <para>
-
+The #GdkEvent struct contains a union of all of the event structs,
+and allows access to the data fields in a number of ways.
 </para>
-
-@type: 
-@window: 
-@send_event: 
-@area: 
-@count: 
-
-<!-- ##### STRUCT GdkEventNoExpose ##### -->
 <para>
-
+The event type is always the first field in all of the event structs, and
+can always be accessed with the following code, no matter what type of event
+it is:
+<informalexample>
+<programlisting>
+  GdkEvent *event;  
+  GdkEventType type;
+
+  type = event->type;
+</programlisting>
+</informalexample>
 </para>
 
-@type: 
-@window: 
-@send_event: 
-
-<!-- ##### STRUCT GdkEventVisibility ##### -->
 <para>
-
+To access other fields of the event structs, the pointer to the event can be
+cast to the appropriate event struct pointer, or the union member name can be
+used. For example if the event type is %GDK_BUTTON_PRESS then the x coordinate
+of the button press can be accessed with:
+<informalexample>
+<programlisting>
+  GdkEvent *event;  
+  gdouble x;
+
+  x = ((GdkEventButton*)event)->x;
+</programlisting>
+</informalexample>
+or:
+<informalexample>
+<programlisting>
+  GdkEvent *event;  
+  gdouble x;
+
+  x = event->button.x;
+</programlisting>
+</informalexample>
 </para>
 
-@type: 
-@window: 
-@send_event: 
-@state: 
 
-<!-- ##### ENUM GdkVisibilityState ##### -->
+<!-- ##### STRUCT GdkEventAny ##### -->
 <para>
-
+Contains the fields which are common to all event structs.
+Any event pointer can safely be cast to a pointer to a #GdkEventAny to access
+these fields.
 </para>
 
-@GDK_VISIBILITY_UNOBSCURED: 
-@GDK_VISIBILITY_PARTIAL: 
-@GDK_VISIBILITY_FULLY_OBSCURED: 
+@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).
 
-<!-- ##### STRUCT GdkEventMotion ##### -->
+<!-- ##### STRUCT GdkEventKey ##### -->
 <para>
-
+Describes a key press or key release event.
 </para>
 
-@type: 
-@window: 
-@send_event: 
-@time: 
-@x: 
-@y: 
-@pressure: 
-@xtilt: 
-@ytilt: 
-@state: 
-@is_hint: 
-@source: 
-@deviceid: 
-@x_root: 
-@y_root: 
+@type: the type of the event (%GDK_KEY_RELEASE or %GDK_KEY_RELEASE).
+@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.
+@state: a bit-mask representing the state of the modifier keys (e.g. Control,
+Shift and Alt) and the pointer buttons. See #GdkModifierType.
+@keyval: the key that was pressed or released. See the &lt;gdk/gdkkeysym.h&gt;
+header file for a complete list of GDK key codes.
+@length: the length of @string.
+@string: a null-terminated multi-byte string containing the composed characters
+resulting from the key press. When text is being input, in a GtkEntry for
+example, it is these characters which should be added to the input buffer.
+When using <link linkend="gdk-Input-Methods"> Input Methods</link> to support
+internationalized text input, the composed characters appear here after the
+pre-editing has been completed.
 
 <!-- ##### STRUCT GdkEventButton ##### -->
 <para>
@@ -97,7 +103,7 @@ Used for button press and button release events. The
 %GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, and %GDK_BUTTON_RELEASE.
 </para>
 <para>
-Double and treble-clicks result in a sequence of events being received.
+Double and triple-clicks result in a sequence of events being received.
 For double-clicks the order of events will be:
 <orderedlist>
 <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
@@ -111,7 +117,7 @@ button press, while the second click results in a %GDK_2BUTTON_PRESS being
 received just after the %GDK_BUTTON_PRESS.
 </para>
 <para>
-Treble-clicks are very similar to double-clicks, except that %GDK_3BUTTON_PRESS
+Triple-clicks are very similar to double-clicks, except that %GDK_3BUTTON_PRESS
 is inserted after the third click. The order of the events is:
 <orderedlist>
 <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
@@ -124,49 +130,101 @@ is inserted after the third click. The order of the events is:
 <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
 </orderedlist>
 </para>
+<para>
+For a double click to occur, the second button press must occur within 1/4 of
+a second of the first. For a triple click to occur, the third button press
+must also occur within 1/2 second of the first button press.
+</para>
 
-@type: the type of the event.
+@type: the type of the event (%GDK_BUTTON_PRESS, %GDK_2BUTTON_PRESS,
+%GDK_3BUTTON_PRESS or %GDK_BUTTON_RELEASE).
 @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 roughly every
-50 days.
+@time: the time of the event in milliseconds.
 @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
 as graphics tablets. It defaults to 0.5.
+@xtilt: the horizontal tilt of the input device. Defaults to 0.
+@ytilt: the vertical tilt of the input device. Defaults to 0.
+@state: a bit-mask representing the state of the modifier keys (e.g. Control,
+Shift and Alt) and the pointer buttons. See #GdkModifierType.
+@button: the button which was pressed or released, numbered from 1 to 5.
+Normally button 1 is the left mouse button, 2 is the middle button,
+and 3 is the right button. On 2-button mice, the middle button can often
+be simulated by pressing both mouse buttons together.
+@source: the input device where the event came from, usually %GDK_SOURCE_MOUSE.
+@deviceid: the input device ID, usually %GDK_CORE_POINTER but may be
+different if touch screens or graphics tablets are being used.
+@x_root: the x coordinate of the mouse relative to the root of the screen.
+@y_root: the y coordinate of the mouse relative to the root of the screen.
+
+<!-- ##### STRUCT GdkEventMotion ##### -->
+<para>
+
+</para>
+
+@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: 
+@x: 
+@y: 
+@pressure: 
 @xtilt: 
 @ytilt: 
 @state: 
-@button: 
+@is_hint: 
 @source: 
 @deviceid: 
-@x_root: the x coordinate of the mouse relative to the root of the screen.
-@y_root: the y coordinate of the mouse relative to the root of the screen.
+@x_root: 
+@y_root: 
 
-<!-- ##### STRUCT GdkEventKey ##### -->
+<!-- ##### STRUCT GdkEventExpose ##### -->
 <para>
+Generated when all or part of a window becomes visible and needs to be
+redrawn.
+</para>
 
+@type: the type of the event (%GDK_EXPOSE).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@area: the area that needs to be redrawn.
+@count: the number of contiguous %GDK_EXPOSE events following this one.
+The only use for this is "exposure compression", i.e. handling all contiguous
+%GDK_EXPOSE events in one go, though GDK performs some exposure compression
+so this is not normally needed.
+
+<!-- ##### STRUCT GdkEventVisibility ##### -->
+<para>
+Generated when the window visibility status has changed.
 </para>
 
-@type: 
-@window: 
-@send_event: 
-@time: 
-@state: 
-@keyval: 
-@length: 
-@string: 
+@type: the type of the event (%GDK_VISIBILITY_NOTIFY).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@state: the new visibility state (%GDK_VISIBILITY_FULLY_OBSCURED,
+%GDK_VISIBILITY_PARTIAL or %GDK_VISIBILITY_UNOBSCURED).
+
+<!-- ##### ENUM GdkVisibilityState ##### -->
+<para>
+Specifies the visiblity status of a window for a #GdkEventVisibility.
+</para>
+
+@GDK_VISIBILITY_UNOBSCURED: the window is completely visible.
+@GDK_VISIBILITY_PARTIAL: the window is partially visible.
+@GDK_VISIBILITY_FULLY_OBSCURED: the window is not visible at all.
 
 <!-- ##### STRUCT GdkEventCrossing ##### -->
 <para>
 
 </para>
 
-@type: 
-@window: 
-@send_event: 
+@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).
 @subwindow: 
-@time: 
+@time: the time of the event in milliseconds.
 @x: 
 @y: 
 @x_root: 
@@ -199,106 +257,112 @@ as graphics tablets. It defaults to 0.5.
 
 <!-- ##### STRUCT GdkEventFocus ##### -->
 <para>
-
+Describes a change of keyboard focus.
 </para>
 
-@type: 
-@window: 
-@send_event: 
-@in: 
+@type: the type of the event (%GDK_FOCUS_CHANGE).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@in: TRUE if the window has gained the keyboard focus, FALSE if it has lost
+the focus.
 
 <!-- ##### STRUCT GdkEventConfigure ##### -->
 <para>
-
+Generated when a window size or position has changed.
 </para>
 
-@type: 
-@window: 
-@send_event: 
-@x: 
-@y: 
-@width: 
-@height: 
+@type: the type of the event (%GDK_CONFIGURE).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@x: the new x coordinate of the window, relative to its parent.
+@y: the new y coordinate of the window, relative to its parent.
+@width: the new width of the window.
+@height: the new height of the window.
 
 <!-- ##### STRUCT GdkEventProperty ##### -->
 <para>
-
+Describes a property change on a window.
 </para>
 
-@type: 
-@window: 
-@send_event: 
-@atom: 
-@time: 
-@state: 
+@type: the type of the event (%GDK_PROPERTY_NOTIFY).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@atom: the property that was changed.
+@time: the time of the event in milliseconds.
+@state: whether the property was changed (%GDK_PROPERTY_NEW_VALUE) or
+deleted (%GDK_PROPERTY_DELETE).
 
 <!-- ##### ENUM GdkPropertyState ##### -->
 <para>
-
+Specifies the type of a property change for a #GdkEventProperty.
 </para>
 
-@GDK_PROPERTY_NEW_VALUE: 
-@GDK_PROPERTY_DELETE: 
+@GDK_PROPERTY_NEW_VALUE: the property value wan changed.
+@GDK_PROPERTY_DELETE: the property was deleted.
 
 <!-- ##### STRUCT GdkEventSelection ##### -->
 <para>
 
 </para>
 
-@type: 
-@window: 
-@send_event: 
+@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).
 @selection: 
 @target: 
 @property: 
 @requestor: 
-@time: 
+@time: the time of the event in milliseconds.
 
-<!-- ##### STRUCT GdkEventProximity ##### -->
+<!-- ##### STRUCT GdkEventDND ##### -->
 <para>
 
 </para>
 
-@type: 
-@window: 
-@send_event: 
-@time: 
-@source: 
-@deviceid: 
+@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).
+@context: 
+@time: the time of the event in milliseconds.
+@x_root: 
+@y_root: 
 
-<!-- ##### STRUCT GdkEventClient ##### -->
+<!-- ##### STRUCT GdkEventProximity ##### -->
 <para>
 
 </para>
 
-@type: 
-@window: 
-@send_event: 
-@message_type: 
-@data_format: 
+@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.
+@source: 
+@deviceid: 
 
-<!-- ##### STRUCT GdkEventDND ##### -->
+<!-- ##### STRUCT GdkEventClient ##### -->
 <para>
-
+An event sent by another client application.
 </para>
 
-@type: 
-@window: 
-@send_event: 
-@context: 
-@time: 
-@x_root: 
-@y_root: 
+@type: the type of the event (%GDK_CLIENT_EVENT).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@message_type: the type of the message, which can be defined by the
+application.
+@data_format: the format of the data, given as the number of bits in each
+data element, i.e. 8, 16, or 32. 8-bit data uses the b array of the data
+union, 16-bit data uses the s array, and 32-bit data uses the l array.
 
-<!-- ##### UNION GdkEvent ##### -->
+<!-- ##### STRUCT GdkEventNoExpose ##### -->
 <para>
-
+Generated when the area of a #GdkDrawable being copied, with gdk_draw_pixmap()
+or gdk_window_copy_area(), was completely available.
 </para>
-
-
-<!-- ##### TYPEDEF GdkXEvent ##### -->
 <para>
-
+FIXME: add more here.
 </para>
 
+@type: the type of the event (%GDK_NO_EXPOSE).
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 
diff --git a/docs/reference/gdk/tmpl/events.sgml b/docs/reference/gdk/tmpl/events.sgml
index 9a4fe5e96..dca821ca7 100644
--- a/docs/reference/gdk/tmpl/events.sgml
+++ b/docs/reference/gdk/tmpl/events.sgml
@@ -56,9 +56,7 @@ of time. Note that each click also generates a %GDK_BUTTON_PRESS event.
 @GDK_KEY_RELEASE: a key has been released.
 @GDK_ENTER_NOTIFY: the pointer has entered the window.
 @GDK_LEAVE_NOTIFY: the pointer has left the window.
-@GDK_FOCUS_CHANGE: the keyboard focus has entered or left the window. Note that
-in GTK+ keyboard focus is handled mostly within GTK+ itself, so it is usually
-only toplevel windows which receive these events.
+@GDK_FOCUS_CHANGE: the keyboard focus has entered or left the window.
 @GDK_CONFIGURE: the size, position or stacking order of the window has changed.
 Note that GTK+ discards these events for %GDK_WINDOW_CHILD windows.
 @GDK_MAP: the window has been mapped.
diff --git a/docs/reference/gdk/tmpl/windows.sgml b/docs/reference/gdk/tmpl/windows.sgml
index 78addd966..5a4ddfdf6 100644
--- a/docs/reference/gdk/tmpl/windows.sgml
+++ b/docs/reference/gdk/tmpl/windows.sgml
@@ -365,6 +365,12 @@ Windows
 @GDK_FILTER_TRANSLATE: 
 @GDK_FILTER_REMOVE: 
 
+<!-- ##### TYPEDEF GdkXEvent ##### -->
+<para>
+
+</para>
+
+
 <!-- ##### FUNCTION gdk_window_shape_combine_mask ##### -->
 <para>
 
diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt
index fe99b4d45..aa0908cd7 100644
--- a/docs/reference/gtk/gtk-sections.txt
+++ b/docs/reference/gtk/gtk-sections.txt
@@ -2916,6 +2916,7 @@ GtkSortType
 <SECTION>
 <FILE>gtkprivate</FILE>
 <TITLE>Private Information</TITLE>
+<INCLUDE>gtk/gtkprivate.h</INCLUDE>
 GtkPrivateFlags
 GTK_PRIVATE_FLAGS
 GTK_WIDGET_USER_STYLE