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.

ChangeLog

@@ -1,3 +1,8 @@
+2001-10-17  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+	Documentation updates.
+
 Wed Oct 17 15:17:20 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake

ChangeLog.pre-2-0

@@ -1,3 +1,8 @@
+2001-10-17  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+	Documentation updates.
+
 Wed Oct 17 15:17:20 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake

ChangeLog.pre-2-10

@@ -1,3 +1,8 @@
+2001-10-17  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+	Documentation updates.
+
 Wed Oct 17 15:17:20 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake

ChangeLog.pre-2-2

@@ -1,3 +1,8 @@
+2001-10-17  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+	Documentation updates.
+
 Wed Oct 17 15:17:20 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake

ChangeLog.pre-2-4

@@ -1,3 +1,8 @@
+2001-10-17  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+	Documentation updates.
+
 Wed Oct 17 15:17:20 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake

ChangeLog.pre-2-6

@@ -1,3 +1,8 @@
+2001-10-17  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+	Documentation updates.
+
 Wed Oct 17 15:17:20 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake

ChangeLog.pre-2-8

@@ -1,3 +1,8 @@
+2001-10-17  Matthias Clasen  <matthiasc@poet.de>
+
+	* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+	Documentation updates.
+
 Wed Oct 17 15:17:20 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake

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.

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>
 
 

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>
 
 

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: 
+@gc: a #GdkGC. 
-@Returns: 
+@Returns: an Xlib <type>Display*</type>.
 
 
 <!-- ##### FUNCTION gdk_x11_gc_get_xgc ##### -->
 <para>
-
+Returns the X GC of a #GdkGC.
 </para>
 
-@gc: 
+@gc: a #GdkGC.
-@Returns: 
+@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: 
+@drawable: a #GdkImage.
-@Returns: 
+@Returns: an Xlib <type>Display*</type>.
 
 
 <!-- ##### FUNCTION gdk_x11_image_get_ximage ##### -->

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>
 

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+
+communication via the drag-and-drop metaphor. GTK+
-can do drag and drop (DND) via multiple protocols.
+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
+The #GtkTargetFlags enumeration is used to specify
-constraints on an entry in a GtkTargetTable. 
+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

gtk/gtkclipboard.c

@@ -88,10 +88,10 @@ static GQuark clipboards_owned_key_id = 0;
 /**
  * gtk_clipboard_get:
  * @selection: a #GdkAtom which identifies the clipboard
- *             to use. A value of GDK_NONE here is the
+ *             to use. A value of %GDK_NONE here is the
  *             same as gdk_atom_intern ("CLIPBOARD", FALSE),
  *             and provides the default clipboard. Another
- *             common value is GDK_SELECTION_PRIMARY, which
+ *             common value is %GDK_SELECTION_PRIMARY, which
  *             identifies the primary X selection. 
  * 
  * Returns the clipboard object for the given selection.
@@ -99,7 +99,7 @@ static GQuark clipboards_owned_key_id = 0;
  * Return value: the appropriate clipboard object. If no
  *             clipboard already exists, a new one will
  *             be created. Once a clipboard object has
- *             been created, it is persistant for all time.
+ *             been created, it is persistent for all time.
  **/
 GtkClipboard *
 gtk_clipboard_get (GdkAtom selection)
@@ -359,10 +359,10 @@ gtk_clipboard_set_contents (GtkClipboard         *clipboard,
  * @n_targets:  number of elements in @targets
  * @get_func:   function to call to get the actual clipboard data
  * @clear_func: when the clipboard contents are set again, this function will
- *              be called, and get_func will not be subsequently called.
+ *              be called, and @get_func will not be subsequently called.
  * @user_data:  user data to pass to @get_func and @clear_func.
  * 
- * Virtually set the contents of the specified clipboard by providing
+ * Virtually sets the contents of the specified clipboard by providing
  * a list of supported formats for the clipboard data and a function
  * to call to get the actual data when it is requested.
  * 
@@ -395,17 +395,17 @@ gtk_clipboard_set_with_data (GtkClipboard          *clipboard,
  * @n_targets:  number of elements in @targets
  * @get_func:   function to call to get the actual clipboard data
  * @clear_func: when the clipboard contents are set again, this function will
- *              be called, and get_func will not be subsequently called.
+ *              be called, and @get_func will not be subsequently called.
  * @owner:      an object that "owns" the data. This object will be passed
  *              to the callbacks when called. 
  * 
- * Virtually set the contents of the specified clipboard by providing
+ * Virtually sets the contents of the specified clipboard by providing
  * a list of supported formats for the clipboard data and a function
  * to call to get the actual data when it is requested.
  *
  * The difference between this function and gtk_clipboard_set_with_data
  * is that instead of an generic @user_data pointer, a #GObject is passed
- * in. Because of this, 
+ * in. 
  * 
  * Return value: %TRUE if setting the clipboard data succeeded. If setting
  *               the clipboard data failed the provided callback functions
@@ -477,7 +477,7 @@ clipboard_unset (GtkClipboard *clipboard)
  * gtk_clipboard_clear:
  * @clipboard:  a #GtkClipboard
  * 
- * Clear the contents of the clipboard. Generally this should only
+ * Clears the contents of the clipboard. Generally this should only
  * be called between the time you call gtk_clipboard_set_contents(),
  * and when the @clear_func you supplied is called. Otherwise, the
  * clipboard may be owned by someone else.
@@ -515,7 +515,7 @@ text_clear_func (GtkClipboard *clipboard,
  * @len:       length of @text, in bytes, or -1, in which case
  *             the length will be determined with strlen().
  * 
- * Set the contents of the clipboard to the given UTF-8 string. GTK+ will
+ * Sets the contents of the clipboard to the given UTF-8 string. GTK+ will
  * make a copy of the text and take responsibility for responding
  * for requests for the text, and for converting the text into
  * the requested format.
@@ -590,7 +590,7 @@ selection_received (GtkWidget            *widget,
  * @target:    an atom representing the form into which the clipboard
  *             owner should convert the selection.
  * @callback:  A function to call when the results are received
- *             (or the retrieval fails.) If the retrieval fails
+ *             (or the retrieval fails). If the retrieval fails
  *             the length field of @selection_data will be
  *             negative.
  * @user_data: user data to pass to @callback
@@ -786,7 +786,7 @@ clipboard_text_received_func (GtkClipboard *clipboard,
  * the data to be received using the main loop, so events,
  * timeouts, etc, may be dispatched during the wait.
  * 
- * Return value: a newly allocated UTF-8 string which must
+ * Return value: a newly-allocated UTF-8 string which must
  *               be freed with g_free(), or %NULL if retrieving
  *               the selection data failed. (This could happen
  *               for various reasons, in particular if the

gtk/gtkdnd.c

@@ -1972,8 +1972,8 @@ gtk_drag_source_unset_icon (GtkDragSourceSite *site)
  * @mask: the transparency mask for an image.
  * 
  * Sets the icon that will be used for drags from a particular widget
- * from a pixmap/mask. GTK+ retains a reference count for the
+ * from a pixmap/mask. GTK+ retains references for the arguments, and 
- * arguments, and will release them when they are no longer needed.
+ * will release them when they are no longer needed.
  * Use gtk_drag_source_set_icon_pixbuf() instead.
  **/
 void 
@@ -2012,8 +2012,8 @@ gtk_drag_source_set_icon (GtkWidget     *widget,
  * @pixbuf: the #GdkPixbuf for the drag icon
  * 
  * Sets the icon that will be used for drags from a particular widget
- * from a #GdkPixbuf. GTK+ retains a reference count @pixbuf.
+ * from a #GdkPixbuf. GTK+ retains a reference for @pixbuf and will 
- * and will release it when it is no longer needed.
+ * release it when it is no longer needed.
  **/
 void 
 gtk_drag_source_set_icon_pixbuf (GtkWidget   *widget,
@@ -2025,8 +2025,7 @@ gtk_drag_source_set_icon_pixbuf (GtkWidget   *widget,
   g_return_if_fail (GDK_IS_PIXBUF (pixbuf));
 
   site = gtk_object_get_data (GTK_OBJECT (widget), "gtk-site-data");
-  g_return_if_fail (site != NULL);
+  g_return_if_fail (site != NULL); 
-  
   gdk_pixbuf_ref (pixbuf);
 
   gtk_drag_source_unset_icon (site);
@@ -2038,11 +2037,11 @@ gtk_drag_source_set_icon_pixbuf (GtkWidget   *widget,
 /**
  * gtk_drag_source_set_icon_stock:
  * @widget: a #GtkWidget
- * @stock: the ID of the stock icon to use..
+ * @stock: the ID of the stock icon to use
  * @size: size at which to render the stock icon
  *
- * Sets the icon that will be used for drags from a particular to
+ * Sets the icon that will be used for drags from a particular source
- * a stock icon. 
+ * to a stock icon. 
  **/
 void 
 gtk_drag_source_set_icon_stock (GtkWidget   *widget,
@@ -2199,7 +2198,7 @@ gtk_drag_set_icon_pixbuf  (GdkDragContext *context,
 }
 
 /**
- * gtk_drag_set_icon_pixbuf:
+ * gtk_drag_set_icon_stock:
  * @context: the context for a drag. (This must be called 
  *            with a  context for the source side of a drag)
  * @stock: the ID of the stock icon to use for the drag.
@@ -2230,8 +2229,8 @@ gtk_drag_set_icon_stock  (GdkDragContext *context,
  * @hot_x: the X offset within @pixmap of the hotspot.
  * @hot_y: the Y offset within @pixmap of the hotspot.
  * 
- * Sets @pixmap as the icon for a given drag. GTK+ retains a
+ * Sets @pixmap as the icon for a given drag. GTK+ retains
- * reference count for the arguments, and will release them when
+ * references for the arguments, and will release them when
  * they are no longer needed. In general, gtk_drag_set_icon_pixbuf()
  * will be more convenient to use.
  **/
@@ -2303,10 +2302,10 @@ gtk_drag_set_icon_default (GdkDragContext    *context)
  * @hot_x: The X offset within @widget of the hotspot.
  * @hot_y: The Y offset within @widget of the hotspot.
  * 
- * Changes the default drag icon. GTK+ retains a reference count for the
+ * Changes the default drag icon. GTK+ retains references for the
  * arguments, and will release them when they are no longer needed.
  * This function is obsolete. The default icon should now be changed
- * via the stock system by changing the stock pixbuf for GTK_STOCK_DND.
+ * via the stock system by changing the stock pixbuf for %GTK_STOCK_DND.
  **/
 void 
 gtk_drag_set_default_icon (GdkColormap   *colormap,