Documentation updates. Updates.

        * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c: Documentation updates.
        * gtk/tmpl/gtkdnd.sgml, gtk/tmpl/gtkclipboard.sgml,
        gdk/tmpl/general.sgml, gdk/tmpl/threads.sgml,
        gdk/tmpl/x_interaction.sgml: Updates.

6 files changed, 84 insertions, 49 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index a33a344289..98c492c516 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,9 @@
+2001-10-17  Matthias Clasen   <matthiasc@poet.de>
+
+	* gtk/tmpl/gtkdnd.sgml, gtk/tmpl/gtkclipboard.sgml,
+	gdk/tmpl/general.sgml, gdk/tmpl/threads.sgml, 
+	gdk/tmpl/x_interaction.sgml: Updates.
+
 2001-10-13  Matthias Clasen   <matthiasc@poet.de>
 
 	* gdk/tmpl/x_interaction.sgml: Update.
diff --git a/docs/reference/gdk/tmpl/general.sgml b/docs/reference/gdk/tmpl/general.sgml
index 92c429a57b..3908c48299 100644
--- a/docs/reference/gdk/tmpl/general.sgml
+++ b/docs/reference/gdk/tmpl/general.sgml
@@ -369,21 +369,21 @@ Removes the X error trap installed with gdk_error_trap_push().
 
 <!-- ##### MACRO GDK_WINDOWING_X11 ##### -->
 <para>
-
+This macro is defined if GDK is configured to use the X backend.
 </para>
 
 
 
 <!-- ##### MACRO GDK_WINDOWING_WIN32 ##### -->
 <para>
-
+This macro is defined if GDK is configured to use the Win32 backend.
 </para>
 
 
 
 <!-- ##### MACRO GDK_WINDOWING_FB ##### -->
 <para>
-
+This macro is defined if GDK is configured to use the Linux framebuffer backend.
 </para>
 
 
diff --git a/docs/reference/gdk/tmpl/threads.sgml b/docs/reference/gdk/tmpl/threads.sgml
index 5e7e049abb..59a79ee86c 100644
--- a/docs/reference/gdk/tmpl/threads.sgml
+++ b/docs/reference/gdk/tmpl/threads.sgml
@@ -2,11 +2,33 @@
 Threads
 
 <!-- ##### SECTION Short_Description ##### -->
-
+functions for using GDK in multi-threaded programs
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+For thread safety, GDK relies on the thread primitives in GLib, 
+and on the thread-safe GLib main loop.
+</para>
+<para>
+You must call g_thread_init() before executing any other GTK+ or GDK 
+functions in a threaded GTK+ program.
+</para>
+<para>
+Idles, timeouts, and input functions are executed outside
+of the main GTK+ lock. So, if you need to call GTK+
+inside of such a callback, you must surround the callback
+with a gdk_threads_enter()/gdk_threads_leave() pair.
+(However, signals are still executed within the main
+GTK+ lock.)
+</para>
+<para>
+In particular, this means, if you are writing widgets that might 
+be used in threaded programs, you <emphasis>must</emphasis> surround 
+timeouts and idle functions in this matter.
+</para>
+<para>
+As always, you must also surround any calls to GTK+ not made within 
+a signal handler with a gdk_threads_enter()/gdk_threads_leave() pair.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,35 +38,40 @@ Threads
 
 <!-- ##### MACRO GDK_THREADS_ENTER ##### -->
 <para>
-
+This macro marks the begin of a critical section
+in which GDK and GTK+ functions can be called.
+Only one thread at a time can be in such a critial 
+section.
 </para>
 
 
 
 <!-- ##### MACRO GDK_THREADS_LEAVE ##### -->
 <para>
-
+This macro marks the end of a critical section 
+begun with #GDK_THREADS_ENTER.
 </para>
 
 
 
 <!-- ##### FUNCTION gdk_threads_enter ##### -->
 <para>
-
+Enters a critical region like #GDK_THREADS_ENTER.
 </para>
 
 
 
 <!-- ##### FUNCTION gdk_threads_leave ##### -->
 <para>
-
+Leaves a critical region begun with gdk_threads_enter(). 
 </para>
 
 
 
 <!-- ##### VARIABLE gdk_threads_mutex ##### -->
 <para>
-
+The #GMutex used to implement the critical region for
+gdk_threads_enter()/gdk_threads_leave().
 </para>
 
 
diff --git a/docs/reference/gdk/tmpl/x_interaction.sgml b/docs/reference/gdk/tmpl/x_interaction.sgml
index 0a484e557c..9ac4d7f3f5 100644
--- a/docs/reference/gdk/tmpl/x_interaction.sgml
+++ b/docs/reference/gdk/tmpl/x_interaction.sgml
@@ -382,28 +382,29 @@ Returns the X font belonging to a #GdkFont.
 
 <!-- ##### FUNCTION gdk_x11_gc_get_xdisplay ##### -->
 <para>
-
+Returns the display of a #GdkGC.
 </para>
 
-@gc: 
-@Returns: 
+@gc: a #GdkGC. 
+@Returns: an Xlib <type>Display*</type>.
 
 
 <!-- ##### FUNCTION gdk_x11_gc_get_xgc ##### -->
 <para>
-
+Returns the X GC of a #GdkGC.
 </para>
 
-@gc: 
-@Returns: 
+@gc: a #GdkGC.
+@Returns: an Xlib <type>GC</type>.
 
 
 <!-- ##### FUNCTION gdk_x11_get_default_root_xwindow ##### -->
 <para>
-
+Gets the root window of the default screen 
+(see gdk_x11_get_default_screen()).  
 </para>
 
-@Returns: 
+@Returns: an Xlib <type>Window</type>.
 
 
 <!-- ##### FUNCTION gdk_x11_get_default_screen ##### -->
@@ -416,10 +417,12 @@ Returns the X font belonging to a #GdkFont.
 
 <!-- ##### FUNCTION gdk_x11_get_default_xdisplay ##### -->
 <para>
-
+Gets the default GTK+ display.
 </para>
 
-@Returns: 
+@Returns: the Xlib <type>Display*</type> for the display
+  specified in the <option>--display</option> command line option 
+  or the <envar>DISPLAY</envar> environment variable.
 
 
 <!-- ##### FUNCTION gdk_x11_grab_server ##### -->
@@ -434,11 +437,11 @@ gdk_x11_grab_server()/gdk_x11_ungrab_server() calls can be nested.
 
 <!-- ##### FUNCTION gdk_x11_image_get_xdisplay ##### -->
 <para>
-
+Returns the display of a #GdkImage.
 </para>
 
-@image: 
-@Returns: 
+@drawable: a #GdkImage.
+@Returns: an Xlib <type>Display*</type>.
 
 
 <!-- ##### FUNCTION gdk_x11_image_get_ximage ##### -->
diff --git a/docs/reference/gtk/tmpl/gtkclipboard.sgml b/docs/reference/gtk/tmpl/gtkclipboard.sgml
index 1fcefb4b6c..a066dd9f08 100644
--- a/docs/reference/gtk/tmpl/gtkclipboard.sgml
+++ b/docs/reference/gtk/tmpl/gtkclipboard.sgml
@@ -92,7 +92,7 @@ Storing data on Clipboards.
 
 <!-- ##### USER_FUNCTION GtkClipboardReceivedFunc ##### -->
 <para>
-    A function to be called when the results of gtk_clipboard_request_text()
+    A function to be called when the results of gtk_clipboard_request_contents()
     are received, or when the request fails.
 </para>
 
@@ -120,10 +120,10 @@ Storing data on Clipboards.
 A function that will be called to provide the contents of the selection.
 If multiple types of data were advertised, the requested type can
 be determined from the @info parameter or by checking the target field
-of @selection_data. If the data could succesfully be converted into
+of @selection_data. If the data could successfully be converted into
 then it should be stored into the @selection_data object by
 calling gtk_selection_data_set() (or related functions such
-as gtk_seletion_data_get().) If no data is set, the requestor
+as gtk_selection_data_set_text()). If no data is set, the requestor
 will be informed that the attempt to get the data failed.    
 </para>
 
diff --git a/docs/reference/gtk/tmpl/gtkdnd.sgml b/docs/reference/gtk/tmpl/gtkdnd.sgml
index f278e854af..5d860b9fe7 100644
--- a/docs/reference/gtk/tmpl/gtkdnd.sgml
+++ b/docs/reference/gtk/tmpl/gtkdnd.sgml
@@ -7,8 +7,8 @@ Functions for controlling drag and drop handling.
 <!-- ##### SECTION Long_Description ##### -->
 <para>
 GTK+ has a rich set of functions for doing inter-process
-communication via the drag-and-drop metaphore. GTK+
-can do drag and drop (DND) via multiple protocols.
+communication via the drag-and-drop metaphor. GTK+
+can do drag-and-drop (DND) via multiple protocols.
 The currently supported protocols are the Xdnd and
 Motif protocols.
 
@@ -49,7 +49,7 @@ of the user for a drag destination site.
 <entry>
    If set for a widget, GTK+ will draw a highlight on
    this widget as long as a drag is over this widget
-   and the wiget drag format and action is accetable.</entry>
+   and the widget drag format and action are acceptable.</entry>
 </row>
 
 <row>
@@ -59,9 +59,9 @@ of the user for a drag destination site.
    will check if the drag matches this widget's
    list of possible targets and actions. If so, 
    GTK+ will call gtk_drag_data_get() on behalf 
-   of the widget. Whether or not the drop is succesful,
+   of the widget. Whether or not the drop is successful,
    GTK+ will call gtk_drag_finish(). If the action
-   was a move, then if the drag was succesful, then
+   was a move, then if the drag was successful, then
    %TRUE will be passed for the @delete parameter
    to gtk_drag_finish().
 </entry>
@@ -84,8 +84,8 @@ of the user for a drag destination site.
 
 <!-- ##### ENUM GtkTargetFlags ##### -->
 <para>
-The #GtkTargetFlags enumeration is used to specifies
-constraints on an entry in a GtkTargetTable. 
+The #GtkTargetFlags enumeration is used to specify
+constraints on an entry in a #GtkTargetTable. 
 </para>
 <variablelist>
  <varlistentry><term> %GTK_TARGET_SAME_APP </term>
@@ -111,10 +111,10 @@ constraints on an entry in a GtkTargetTable.
 
 <!-- ##### FUNCTION gtk_drag_dest_set ##### -->
 <para>
-Set a widget as a potential drop destination.
+Sets a widget as a potential drop destination.
 </para>
 
-@widget: a widget
+@widget: a #GtkWidget
 @flags: the flags that specify what actions GTK+ should take
  on behalf of a widget for drops onto that widget. The @targets
  and @actions fields only are used if %GTK_DEST_DEFAULT_MOTION
@@ -128,7 +128,7 @@ Set a widget as a potential drop destination.
 
 <!-- ##### FUNCTION gtk_drag_dest_set_proxy ##### -->
 <para>
-Set this widget as a proxy for drops to another window.
+Sets this widget as a proxy for drops to another window.
 </para>
 
 @widget: a #GtkWidget
@@ -136,13 +136,13 @@ Set this widget as a proxy for drops to another window.
 @protocol: the drag protocol which the @proxy_window accepts
            (You can use gdk_drag_get_protocol() to determine this)
 @use_coordinates: If true, send the same coordinates to the
-                  destination, because it is a embedded 
+                  destination, because it is an embedded 
                   subwindow.
 
 
 <!-- ##### FUNCTION gtk_drag_dest_unset ##### -->
 <para>
-Clear information about a drop destination set with
+Clears information about a drop destination set with
 gtk_drag_dest_set(). The widget will no longer receive
 notification of drags.
 </para>
@@ -181,12 +181,12 @@ notification of drags.
 
 <!-- ##### FUNCTION gtk_drag_finish ##### -->
 <para>
-Inform the drag source that the drop is finished, and
+Informs the drag source that the drop is finished, and
 that the data of the drag will no longer be required.
 </para>
 
 @context: the drag context.
-@success: a flag indicating whether the drop was succesful
+@success: a flag indicating whether the drop was successful
 @del: a flag indicating whether the source should delete the
       original data. (This should be %TRUE for a move)
 @time: the timestamp from the "drag_data_drop" signal.
@@ -215,19 +215,19 @@ drops.
 
 <!-- ##### FUNCTION gtk_drag_get_source_widget ##### -->
 <para>
-Determine the source widget for a drag.
+Determines the source widget for a drag.
 </para>
 
 @context: a (destination side) drag context.
 @Returns: if the drag is occurring within a single application,
-          a pointer to the source widget. Otherwise, NULL.
+          a pointer to the source widget. Otherwise, %NULL.
 
 
 <!-- ##### FUNCTION gtk_drag_highlight ##### -->
 <para>
-Draw a highlight around a widget. This will attach
+Draws a highlight around a widget. This will attach
 handlers to  "expose_event" and "draw", so the highlight
-will continue to be displayed until gtk_drag_unhighlight
+will continue to be displayed until gtk_drag_unhighlight()
 is called.
 </para>
 
@@ -236,9 +236,8 @@ is called.
 
 <!-- ##### FUNCTION gtk_drag_unhighlight ##### -->
 <para>
-Remove a highlight set by gtk_drag_highlight() from
+Removes a highlight set by gtk_drag_highlight() from
 a widget.
-is called.
 </para>
 
 @widget: a widget to remove the highlight from.
@@ -246,7 +245,7 @@ is called.
 
 <!-- ##### FUNCTION gtk_drag_begin ##### -->
 <para>
-Initiate a drag on the source side. The function
+Initiates a drag on the source side. The function
 only needs to be used when the application is
 starting drags itself, and is not needed when
 gtk_drag_source_set() is used.
@@ -259,7 +258,7 @@ gtk_drag_source_set() is used.
           drag.
 @button: The button the user clicked to start the drag.
 @event: The event that triggered the start of the
-        drag. Usually
+        drag. 
 @Returns: The context for this drag.
 
 
@@ -384,7 +383,7 @@ widget. The widget must have a window.
 
 <!-- ##### FUNCTION gtk_drag_source_unset ##### -->
 <para>
-Undo the effects of gtk_drag_source_set().
+Undoes the effects of gtk_drag_source_set().
 </para>
 
 @widget: a #GtkWidget