Updates.

        * gdk/tmpl/input_devices.sgml,
        gdk/gdk-sections.txt, gdk/tmpl/windows.sgml: Updates.

7 files changed, 122 insertions, 131 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index ac8cc55d3..9221783e5 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2001-12-03  Matthias Clasen  <matthiasc@poet.de>
+
+	* gdk/tmpl/input_devices.sgml, 
+	gdk/gdk-sections.txt, gdk/tmpl/windows.sgml: Updates.
+
 2001-12-02  Matthias Clasen  <matthiasc@poet.de>
 
 	* gdk/tmpl/dnd.sgml: Updates.
diff --git a/docs/reference/gdk/gdk-sections.txt b/docs/reference/gdk/gdk-sections.txt
index 2cdca0c5f..493bc693e 100644
--- a/docs/reference/gdk/gdk-sections.txt
+++ b/docs/reference/gdk/gdk-sections.txt
@@ -155,6 +155,7 @@ gdk_image_unref
 gdk_image_destroy
 gdk_image_get_colormap
 gdk_image_set_colormap
+
 <SUBSECTION>
 gdk_image_put_pixel
 gdk_image_get_pixel
@@ -317,7 +318,6 @@ gdk_font_get_type
 <TITLE>Drawing Primitives</TITLE>
 <FILE>drawing</FILE>
 GdkDrawable
-GdkDrawableClass
 gdk_drawable_ref
 gdk_drawable_unref
 gdk_drawable_set_data
@@ -365,6 +365,7 @@ GDK_DRAWABLE_CLASS
 GDK_IS_DRAWABLE_CLASS
 
 <SUBSECTION Private>
+GdkDrawableClass
 gdk_draw_bitmap
 </SECTION>
 
@@ -372,7 +373,6 @@ gdk_draw_bitmap
 <TITLE>Graphics Contexts</TITLE>
 <FILE>gcs</FILE>
 GdkGC
-GdkGCClass
 GdkGCValues
 GdkGCValuesMask
 
@@ -418,7 +418,6 @@ gdk_gc_offset
 GDK_GC
 GDK_TYPE_GC
 GDK_IS_GC
-gdk_gc_get_type
 GDK_GC_CLASS
 GDK_GC_GET_CLASS
 GDK_IS_GC_CLASS
@@ -430,6 +429,10 @@ GDK_TYPE_GC_VALUES_MASK
 GDK_TYPE_JOIN_STYLE
 GDK_TYPE_LINE_STYLE
 GDK_TYPE_SUBWINDOW_MODE
+
+<SUBSECTION Private>
+GdkGCClass
+gdk_gc_get_type
 </SECTION>
 
 <SECTION>
@@ -458,12 +461,12 @@ GDK_TYPE_VISUAL_TYPE
 GDK_TYPE_VISUAL
 GDK_IS_VISUAL
 GDK_IS_VISUAL_CLASS
-GdkVisualClass
 GDK_VISUAL
 GDK_VISUAL_CLASS
 GDK_VISUAL_GET_CLASS
 
 <SUBSECTION Private>
+GdkVisualClass
 gdk_visual_get_type
 </SECTION>
 
@@ -713,6 +716,8 @@ gdk_region_spans_intersect_foreach
 <SUBSECTION Standard>
 GDK_TYPE_OVERLAP_TYPE
 GDK_TYPE_RECTANGLE
+
+<SUBSECTION Private>
 gdk_rectangle_get_type
 </SECTION>
 
@@ -730,7 +735,6 @@ gdk_threads_mutex
 <TITLE>Keyboard Handling</TITLE>
 <FILE>keys</FILE>
 GdkKeymap
-GdkKeymapClass
 GdkKeymapKey
 GdkKeyInfo
 gdk_keymap_get_default
@@ -754,21 +758,24 @@ gdk_keyval_is_lower
 <SUBSECTION>
 gdk_keyval_to_unicode
 gdk_unicode_to_keyval
+
 <SUBSECTION Standard>
 GDK_KEYMAP
 GDK_IS_KEYMAP
 GDK_TYPE_KEYMAP
-gdk_keymap_get_type
 GDK_KEYMAP_CLASS
 GDK_IS_KEYMAP_CLASS
 GDK_KEYMAP_GET_CLASS
+
+<SUBSECTION Private>
+GdkKeymapClass
+gdk_keymap_get_type
 </SECTION>
 
 <SECTION>
 <TITLE>Input Devices</TITLE>
 <FILE>input_devices</FILE>
 GdkDevice
-GdkDeviceClass
 GdkInputSource
 GdkInputMode
 GdkDeviceKey
@@ -803,9 +810,10 @@ GDK_DEVICE_GET_CLASS
 GDK_IS_DEVICE
 GDK_IS_DEVICE_CLASS
 GDK_TYPE_DEVICE
-gdk_device_get_type
 
 <SUBSECTION Private>
+GdkDeviceClass
+gdk_device_get_type
 GDK_MAX_TIMECOORD_AXES
 </SECTION>
 
@@ -917,6 +925,8 @@ gdk_cursor_destroy
 <SUBSECTION Standard>
 GDK_TYPE_CURSOR_TYPE
 GDK_TYPE_CURSOR
+
+<SUBSECTION Private>
 gdk_cursor_get_type
 </SECTION>
 
diff --git a/docs/reference/gdk/tmpl/colors.sgml b/docs/reference/gdk/tmpl/colors.sgml
index 47396e8f8..8f5fa1eb2 100644
--- a/docs/reference/gdk/tmpl/colors.sgml
+++ b/docs/reference/gdk/tmpl/colors.sgml
@@ -47,75 +47,34 @@ gdk_color_change() will probably become aliases.
 <para>
 The #GdkColor structure is used to describe an 
 allocated or unallocated color.
-
-<informaltable pgwide=1 frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry><structfield>pixel</structfield></entry>
-<entry>For allocated colors, the value used to
-draw this color on the screen.</entry>
-</row>
-
-<row>
-<entry><structfield>red</structfield></entry>
-<entry>The red component of the color. This is
-a value between 0 and 65535, with 65535 indicating
-full intensitiy.</entry>
-</row>
-
-<row>
-<entry><structfield>green</structfield></entry>
-<entry>the blue component of the color.</entry>
-</row>
-
-<row>
-<entry><structfield>blue</structfield></entry>
-<entry>the green component of the color..</entry>
-</row>
-
-</tbody></tgroup></informaltable>
 </para>
 
-@pixel: 
-@red: 
-@green: 
-@blue: 
+@pixel: For allocated colors, the value used to
+  draw this color on the screen.
+@red: The red component of the color. This is
+  a value between 0 and 65535, with 65535 indicating
+  full intensitiy.
+@green: The blue component of the color.
+@blue: The green component of the color.
+
 
 <!-- ##### STRUCT GdkColormap ##### -->
 <para>
-The colormap structure contains the following public
-fields.
-
-<informaltable pgwide=1 frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry><structfield>size</structfield></entry>
-<entry>For pseudo-color colormaps, the number of colors
-in the colormap..</entry>
-</row>
-
-<row>
-<entry><structfield>colors</structfield></entry>
-<entry>An array containing the current values in the
-colormap. This can be used to map from pixel values
-back to RGB values. This is only meaningful for
-pseudo-color colormaps.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
+The colormap structure contains the following public fields.
 </para>
 
 @parent_instance: 
-@size: 
-@colors: 
+@size: For pseudo-color colormaps, the number of colors
+  in the colormap.
+@colors: An array containing the current values in the
+  colormap. This can be used to map from pixel values
+  back to RGB values. This is only meaningful for
+  pseudo-color colormaps.
+
 
 <!-- ##### FUNCTION gdk_colormap_new ##### -->
 <para>
-Create a new colormap for the given visual.
+Creates a new colormap for the given visual.
 </para>
 
 @visual: a #GdkVisual.
@@ -162,7 +121,7 @@ explanation of the size of a colormap.)
 
 <!-- ##### FUNCTION gdk_colormap_change ##### -->
 <para>
-Change the value of the first @ncolors in a private colormap
+Changes the value of the first @ncolors in a private colormap
 to match the values in the <structfield>colors</structfield>
 array in the color map. This function is obsolete and
 should not be used. See gdk_color_change().
@@ -196,7 +155,7 @@ Allocates colors from a colormap.
 
 <!-- ##### FUNCTION gdk_colormap_alloc_color ##### -->
 <para>
-Allocate a single color from a colormap.
+Allocates a single color from a colormap.
 </para>
 
 @colormap: a #GdkColormap.
@@ -214,7 +173,7 @@ filled in if allocation succeeds.
 
 <!-- ##### FUNCTION gdk_colormap_free_colors ##### -->
 <para>
-Free previously allocated colors.
+Frees previously allocated colors.
 </para>
 
 @colormap: a #GdkColormap.
@@ -234,7 +193,7 @@ Free previously allocated colors.
 
 <!-- ##### FUNCTION gdk_colormap_get_visual ##### -->
 <para>
-Return the visual for which a given colormap was created.
+Returns the visual for which a given colormap was created.
 </para>
 
 @colormap: a #GdkColormap.
@@ -243,7 +202,7 @@ Return the visual for which a given colormap was created.
 
 <!-- ##### FUNCTION gdk_colors_store ##### -->
 <para>
-Change the value of the first @ncolors colors in
+Changes the value of the first @ncolors colors in
 a private colormap. This function is obsolete and
 should not be used. See gdk_color_change().
 </para>
@@ -255,7 +214,7 @@ should not be used. See gdk_color_change().
 
 <!-- ##### FUNCTION gdk_color_copy ##### -->
 <para>
-Make a copy of a color structure. The result
+Makes a copy of a color structure. The result
 must be freed using gdk_color_free().
 </para>
 
@@ -265,7 +224,7 @@ must be freed using gdk_color_free().
 
 <!-- ##### FUNCTION gdk_color_free ##### -->
 <para>
-Free a color structure created with 
+Frees a color structure created with 
 gdk_color_copy().
 </para>
 
@@ -274,10 +233,10 @@ gdk_color_copy().
 
 <!-- ##### FUNCTION gdk_colors_alloc ##### -->
 <para>
-Allocate colors from a colormap. This function
+Allocates colors from a colormap. This function
 is obsolete. See gdk_colormap_alloc_colors().
 For full documentation of the fields, see 
-the Xlib documentation for XAllocColorCells.
+the Xlib documentation for <function>XAllocColorCells()</function>.
 </para>
 
 @colormap: a #GdkColormap.
@@ -295,7 +254,7 @@ the Xlib documentation for XAllocColorCells.
 
 <!-- ##### FUNCTION gdk_colors_free ##### -->
 <para>
-Free colors allocated with gdk_colors_alloc(). This
+Frees colors allocated with gdk_colors_alloc(). This
 function is obsolete. See gdk_colormap_free_colors().
 </para>
 
@@ -308,7 +267,7 @@ function is obsolete. See gdk_colormap_free_colors().
 
 <!-- ##### FUNCTION gdk_color_white ##### -->
 <para>
-Return the white color for a given colormap. The resulting
+Returns the white color for a given colormap. The resulting
 value has already allocated been allocated. 
 </para>
 
@@ -319,7 +278,7 @@ value has already allocated been allocated.
 
 <!-- ##### FUNCTION gdk_color_black ##### -->
 <para>
-Return the black color for a given colormap. The resulting
+Returns the black color for a given colormap. The resulting
 value has already benn allocated. 
 </para>
 
@@ -330,7 +289,7 @@ value has already benn allocated.
 
 <!-- ##### FUNCTION gdk_color_parse ##### -->
 <para>
-Parse a textual specification of a color and fill in
+Parses a textual specification of a color and fill in
 the <structfield>red</structfield>,
 <structfield>green</structfield>, and 
 <structfield>blue</structfield> fields of a 
@@ -350,7 +309,7 @@ such as <literal>305050</literal>.
 
 <!-- ##### FUNCTION gdk_color_alloc ##### -->
 <para>
-Allocate a single color from a colormap.
+Allocates a single color from a colormap.
 This function is obsolete. See gdk_colormap_alloc_color().
 </para>
 
@@ -363,7 +322,7 @@ filled in.
 
 <!-- ##### FUNCTION gdk_color_change ##### -->
 <para>
-Change the value of a color that has already
+Changes the value of a color that has already
 been allocated. If @colormap is not a private
 colormap, then the color must have been allocated
 using gdk_colormap_alloc_colors() with the 
@@ -379,7 +338,7 @@ and the new value in the remaining fields.
 
 <!-- ##### FUNCTION gdk_color_equal ##### -->
 <para>
-Compare two colors. 
+Compares two colors. 
 </para>
 
 @colora: a #GdkColor.
@@ -395,7 +354,5 @@ table that stores #GdkColor's.
 
 @colora: a #GdkColor.
 @Returns: The hash function appled to @colora
-<!-- # Unused Parameters # -->
-@colorb: NOT USED.
 
 
diff --git a/docs/reference/gdk/tmpl/general.sgml b/docs/reference/gdk/tmpl/general.sgml
index ad91d7cc8..db3b37962 100644
--- a/docs/reference/gdk/tmpl/general.sgml
+++ b/docs/reference/gdk/tmpl/general.sgml
@@ -91,8 +91,8 @@ set on all X windows created by the application to point to the leader window.
 <para>
 See the X Session Management Library documentation for more information on
 session management and the Inter-Client Communication Conventions Manual
-(ICCCM) for information on the <literal>WM_CLIENT_LEADER property</literal>. (Both documents are
-part of the X Windows distribution.)
+(ICCCM) for information on the <literal>WM_CLIENT_LEADER</literal> property. 
+(Both documents are part of the X Windows distribution.)
 </para>
 
 @sm_client_id: the client id assigned by the session manager when the
diff --git a/docs/reference/gdk/tmpl/input_devices.sgml b/docs/reference/gdk/tmpl/input_devices.sgml
index 4bbdabeb8..4984726ad 100644
--- a/docs/reference/gdk/tmpl/input_devices.sgml
+++ b/docs/reference/gdk/tmpl/input_devices.sgml
@@ -50,10 +50,7 @@ tilt to the right or down.)
 One additional field in each event is the
 <structfield>source</structfield> field, which contains an
 enumeration value describing the type of device; this currently
-can be one of 
-%GDK_SOURCE_MOUSE,
- %GDK_SOURCE_PEN,
-%GDK_SOURCE_ERASER,
+can be one of %GDK_SOURCE_MOUSE, %GDK_SOURCE_PEN, %GDK_SOURCE_ERASER,
 or %GDK_SOURCE_CURSOR. This field is present to allow simple
 applications to (for instance) delete when they detect eraser
 devices without having to keep track of complicated per-device
@@ -83,7 +80,8 @@ gdk_device_set_key().
 <para>
 The interfaces in this section will most likely be considerably
 modified in the future to accomodate devices that may have different
-sets of additional valuators than the pressure xtilt and ytilt.
+sets of additional valuators than the pressure <structfield>xtilt</structfield>
+and <structfield>ytilt</structfield>.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -93,18 +91,23 @@ sets of additional valuators than the pressure xtilt and ytilt.
 
 <!-- ##### STRUCT GdkDevice ##### -->
 <para>
-
+A <structname>GdkDevice</structname> structure contains
+a detailed description of an extended input device. All
+fields are read-only; but you can use gdk_device_set_source(),
+gdk_device_set_mode(), gdk_device_set_key() and gdk_device_set_axis_use()
+to configure various aspects of the device.
 </para>
 
 @parent_instance: 
-@name: 
-@source: 
-@mode: 
-@has_cursor: 
-@num_axes: 
-@axes: 
-@num_keys: 
-@keys: 
+@name: the name of this device. 
+@source: the type of this device.
+@mode: the mode of this device
+@has_cursor: %TRUE if the pointer follows device motion.
+@num_axes: the length of the @axes array.
+@axes: an array of #GdkDeviceAxis, describing the axes of this device.
+@num_keys: the length of the @keys array.
+@keys: an array of #GdkDeviceKey, describing the mapped macro buttons 
+  of this device.
 
 <!-- ##### STRUCT GdkDeviceClass ##### -->
 <para>
@@ -140,9 +143,9 @@ An enumeration that describes the mode of an input device.
 
 <!-- ##### STRUCT GdkDeviceKey ##### -->
 <para>
-The #GdkDeviceKey structure contains information
-about the mapping of one device macro button onto
-a normal X key event. It has the following fields:
+The <structname>GdkDeviceKey</structname> structure contains information
+about the mapping of one device macro button onto a normal X key event. 
+It has the following fields:
 </para>
 
 @keyval: the keyval to generate when the macro button is pressed.
@@ -151,12 +154,13 @@ a normal X key event. It has the following fields:
 
 <!-- ##### STRUCT GdkDeviceAxis ##### -->
 <para>
-
+The <structname>GdkDeviceAxis</structname> structure contains information
+about the range and mapping of a device axis.
 </para>
 
-@use: 
-@min: 
-@max: 
+@use: specifies how the axis is used.
+@min: the minimal value that will be reported by this axis. 
+@max: the maximal value that will be reported by this axis.
 
 <!-- ##### ENUM GdkAxisUse ##### -->
 <para>
@@ -249,16 +253,16 @@ Gets the current state of a device.
 
 <!-- ##### FUNCTION gdk_device_get_history ##### -->
 <para>
-
+Obtains the motion history for a device.
 </para>
 
-@device: 
-@window: 
-@start: 
-@stop: 
-@events: 
-@n_events: 
-@Returns: 
+@device: a #GdkDevice.
+@window: the window wrt. which the event coordinates will be translated. 
+@start: only return events newer than this timestamp. 
+@stop: only return events older than this timestamp. 
+@events: location to return a newly-allocated array of #GdkTimeCoord.
+@n_events: location to return the length of @events.
+@Returns: %TRUE if the @events were successfully filled.
 
 
 <!-- ##### FUNCTION gdk_device_free_history ##### -->
@@ -277,7 +281,7 @@ motion history. It contains the following fields:
 </para>
 
 @time: The timestamp for this event.
-@axes: 
+@axes: the values of the device's axes.
 
 <!-- ##### FUNCTION gdk_device_get_axis ##### -->
 <para>
diff --git a/docs/reference/gdk/tmpl/keys.sgml b/docs/reference/gdk/tmpl/keys.sgml
index 2460fd93f..b7236fd5d 100644
--- a/docs/reference/gdk/tmpl/keys.sgml
+++ b/docs/reference/gdk/tmpl/keys.sgml
@@ -10,8 +10,8 @@ Key values are the codes which are sent whenever a key is pressed or released.
 They appear in the <structfield>keyval</structfield> field of the
 #GdkEventKey structure, which is passed to signal handlers for the
 "key-press-event" and "key-release-event" signals.
-The complete list of key values can be found in the &lt;gdk/gdkkeysyms.h&gt;
-header file. &lt;gdk/gdkkeysyms.h&gt; is not included in &lt;gtk/gtk.h&gt;, 
+The complete list of key values can be found in the <filename>&lt;gdk/gdkkeysyms.h&gt;</filename>
+header file. <filename>&lt;gdk/gdkkeysyms.h&gt;</filename> is not included in <filename>&lt;gtk/gtk.h&gt;</filename>, 
 it must be included independently, because the file is quite large.
 </para>
 <para>
@@ -81,7 +81,12 @@ gdk_keymap_translate_keyboard_state() just to get the keyval.
 
 <!-- ##### STRUCT GdkKeymap ##### -->
 <para>
-
+A <structname>GdkKeymap</structname> defines the translation from keyboard state
+(including a hardware key, a modifier mask, and active keyboard group)
+to a keyval. This translation has two phases. The first phase is
+to determine the effective keyboard group and level for the keyboard
+state; the second phase is to look up the keycode/group/level triplet
+in the keymap and see what keyval it corresponds to.
 </para>
 
 @parent_instance: 
@@ -94,12 +99,21 @@ gdk_keymap_translate_keyboard_state() just to get the keyval.
 
 <!-- ##### STRUCT GdkKeymapKey ##### -->
 <para>
-
+A <structname>GdkKeymapKey</structname> is a hardware key that can 
+be mapped to a keyval.
 </para>
 
-@keycode: 
-@group: 
-@level: 
+@keycode: the hardware keycode. This is an identifying number for a 
+  physical key.
+@group: indicates movement in a horizontal direction. Usually groups are used 
+  for two different languages. In group 0, a key might have two English 
+  characters, and in group 1 it might have two Hebrew characters. The Hebrew 
+  characters will be printed on the key next to the English characters.
+@level: indicates which symbol on the key will be used, in a vertical direction.  So on a standard US keyboard, the key with the number "1" on it also has the 
+  exclamation point ("!") character on it. The level indicates whether to use 
+  the "1" or the "!" symbol. The letter keys are considered to have a lowercase
+  letter at level 0, and an uppercase letter at level 1, though only the 
+  uppercase letter is printed. 
 
 <!-- ##### STRUCT GdkKeyInfo ##### -->
 <para>
@@ -182,12 +196,12 @@ Returns: %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL.
 <!-- ##### FUNCTION gdk_keyval_name ##### -->
 <para>
 Converts a key value into a symbolic name.
-The names are the same as those in the &lt;gdk/gdkkeysyms.h&gt; header file
+The names are the same as those in the <filename>&lt;gdk/gdkkeysyms.h&gt;</filename> header file
 but without the leading "GDK_".
 </para>
 
 @keyval: a key value.
-@Returns: a string containing the name of the key, or NULL if @keyval is not
+@Returns: a string containing the name of the key, or %NULL if @keyval is not
 a valid key. The string should not be modified.
 
 
@@ -233,21 +247,21 @@ in lower case or it is not subject to case conversion.
 
 <!-- ##### FUNCTION gdk_keyval_is_upper ##### -->
 <para>
-Returns TRUE if the given key value is in upper case.
+Returns %TRUE if the given key value is in upper case.
 </para>
 
 @keyval: a key value.
-@Returns: TRUE if @keyval is in upper case, or if @keyval is not subject to
+@Returns: %TRUE if @keyval is in upper case, or if @keyval is not subject to
 case conversion.
 
 
 <!-- ##### FUNCTION gdk_keyval_is_lower ##### -->
 <para>
-Returns TRUE if the given key value is in lower case.
+Returns %TRUE if the given key value is in lower case.
 </para>
 
 @keyval: a key value.
-@Returns: TRUE if @keyval is in lower case, or if @keyval is not subject to
+@Returns: %TRUE if @keyval is in lower case, or if @keyval is not subject to
 case conversion.
 
 
diff --git a/docs/reference/gdk/tmpl/windows.sgml b/docs/reference/gdk/tmpl/windows.sgml
index 51337cabc..72c0ded37 100644
--- a/docs/reference/gdk/tmpl/windows.sgml
+++ b/docs/reference/gdk/tmpl/windows.sgml
@@ -838,11 +838,12 @@ backend, <type>MSG</type>s for Win32).
 
 <!-- ##### MACRO GDK_PARENT_RELATIVE ##### -->
 <para>
-
+A special value for <literal>GdkPixmap*</literal> variables, indicating
+that the background pixmap for a window should be inherited from the parent
+window.
 </para>
 
 
-
 <!-- ##### FUNCTION gdk_window_set_cursor ##### -->
 <para>