Documentation fixes.

* glib/gconvert.c, glib/grand.c, glib/ghash.c,
        glib/gthreadpool.c, glib/gtree.c: Documentation fixes.

        * glib/tmpl/allocators.sgml, glib/tmpl/arrays.sgml,
        glib/tmpl/arrays_byte.sgml, glib/tmpl/arrays_pointer.sgml,
        glib/tmpl/caches.sgml, glib/tmpl/completion.sgml,
        glib/tmpl/conversions.sgml,
        glib/tmpl/datalist.sgml, glib/tmpl/date.sgml,
        glib/tmpl/error_reporting.sgml, glib/tmpl/fileutils.sgml,
        glib/tmpl/hash_tables.sgml,
        glib/tmpl/hooks.sgml, glib/tmpl/macros.sgml,
        glib/tmpl/macros_misc.sgml, glib/tmpl/main.sgml, glib/tmpl/markup.sgml,
        glib/tmpl/memory.sgml, glib/tmpl/memory_chunks.sgml,
        glib/tmpl/messages.sgml, glib/tmpl/misc_utils.sgml,
        glib/tmpl/modules.sgml, glib/tmpl/numerical.sgml,
        glib/tmpl/patterns.sgml, glib/tmpl/queue.sgml,
        glib/tmpl/shell.sgml, glib/tmpl/spawn.sgml,
        glib/tmpl/string_utils.sgml, glib/tmpl/thread_pools.sgml,
        glib/tmpl/threads.sgml, glib/tmpl/timers.sgml,
        glib/tmpl/trees-binary.sgml, glib/tmpl/trees-nary.sgml,
        glib/tmpl/type_conversion.sgml, glib/tmpl/unicode.sgml,
        glib/tmpl/warnings.sgml, glib/tmpl/windows.sgml:
        Improve markup of examples, general consistency improvements.

ChangeLog

@@ -1,3 +1,8 @@
+2001-12-12  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gconvert.c, glib/grand.c, glib/ghash.c,
+	glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
 Mon Dec 10 14:08:39 2001  HideToshi Tajima  <hidetoshi.tajima@sun.com>
 
 	* glib/libcharset/config.charset (os):

ChangeLog.pre-2-0

@@ -1,3 +1,8 @@
+2001-12-12  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gconvert.c, glib/grand.c, glib/ghash.c,
+	glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
 Mon Dec 10 14:08:39 2001  HideToshi Tajima  <hidetoshi.tajima@sun.com>
 
 	* glib/libcharset/config.charset (os):

ChangeLog.pre-2-10

@@ -1,3 +1,8 @@
+2001-12-12  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gconvert.c, glib/grand.c, glib/ghash.c,
+	glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
 Mon Dec 10 14:08:39 2001  HideToshi Tajima  <hidetoshi.tajima@sun.com>
 
 	* glib/libcharset/config.charset (os):

ChangeLog.pre-2-12

@@ -1,3 +1,8 @@
+2001-12-12  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gconvert.c, glib/grand.c, glib/ghash.c,
+	glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
 Mon Dec 10 14:08:39 2001  HideToshi Tajima  <hidetoshi.tajima@sun.com>
 
 	* glib/libcharset/config.charset (os):

ChangeLog.pre-2-2

@@ -1,3 +1,8 @@
+2001-12-12  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gconvert.c, glib/grand.c, glib/ghash.c,
+	glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
 Mon Dec 10 14:08:39 2001  HideToshi Tajima  <hidetoshi.tajima@sun.com>
 
 	* glib/libcharset/config.charset (os):

ChangeLog.pre-2-4

@@ -1,3 +1,8 @@
+2001-12-12  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gconvert.c, glib/grand.c, glib/ghash.c,
+	glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
 Mon Dec 10 14:08:39 2001  HideToshi Tajima  <hidetoshi.tajima@sun.com>
 
 	* glib/libcharset/config.charset (os):

ChangeLog.pre-2-6

@@ -1,3 +1,8 @@
+2001-12-12  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gconvert.c, glib/grand.c, glib/ghash.c,
+	glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
 Mon Dec 10 14:08:39 2001  HideToshi Tajima  <hidetoshi.tajima@sun.com>
 
 	* glib/libcharset/config.charset (os):

ChangeLog.pre-2-8

@@ -1,3 +1,8 @@
+2001-12-12  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/gconvert.c, glib/grand.c, glib/ghash.c,
+	glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
 Mon Dec 10 14:08:39 2001  HideToshi Tajima  <hidetoshi.tajima@sun.com>
 
 	* glib/libcharset/config.charset (os):

docs/reference/ChangeLog

@@ -1,3 +1,26 @@
+2001-12-12  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/tmpl/allocators.sgml, glib/tmpl/arrays.sgml, 
+	glib/tmpl/arrays_byte.sgml, glib/tmpl/arrays_pointer.sgml,
+	glib/tmpl/caches.sgml, glib/tmpl/completion.sgml, 
+	glib/tmpl/conversions.sgml,
+	glib/tmpl/datalist.sgml, glib/tmpl/date.sgml, 
+	glib/tmpl/error_reporting.sgml, glib/tmpl/fileutils.sgml,
+	glib/tmpl/hash_tables.sgml,
+	glib/tmpl/hooks.sgml, glib/tmpl/macros.sgml,
+	glib/tmpl/macros_misc.sgml, glib/tmpl/main.sgml, glib/tmpl/markup.sgml,
+	glib/tmpl/memory.sgml, glib/tmpl/memory_chunks.sgml, 
+	glib/tmpl/messages.sgml, glib/tmpl/misc_utils.sgml,
+	glib/tmpl/modules.sgml, glib/tmpl/numerical.sgml, 
+	glib/tmpl/patterns.sgml, glib/tmpl/queue.sgml, 
+	glib/tmpl/shell.sgml, glib/tmpl/spawn.sgml,
+	glib/tmpl/string_utils.sgml, glib/tmpl/thread_pools.sgml,
+	glib/tmpl/threads.sgml, glib/tmpl/timers.sgml, 
+	glib/tmpl/trees-binary.sgml, glib/tmpl/trees-nary.sgml,
+	glib/tmpl/type_conversion.sgml, glib/tmpl/unicode.sgml,
+	glib/tmpl/warnings.sgml, glib/tmpl/windows.sgml:	
+	Improve markup of examples, general consistency improvements.
+
 2001-12-06  Havoc Pennington  <hp@redhat.com>
 
 	* glib/tmpl/messages.sgml: improve g_log_set_handler docs

docs/reference/glib/tmpl/allocators.sgml

@@ -36,7 +36,7 @@ elements. Each must use separate allocators.
 
 <!-- ##### STRUCT GAllocator ##### -->
 <para>
-The #GAllocator struct contains private data. and should only be accessed
+The <structname>GAllocator</structname> struct contains private data. and should only be accessed
 using the following functions.
 </para>
 

docs/reference/glib/tmpl/arrays.sgml

@@ -31,7 +31,7 @@ To set the size of an array, use g_array_set_size().
 To free an array, use g_array_free().
 </para>
 <example>
-<title>Using a GArray to store gint values.</title>
+<title>Using a <structname>GArray</structname> to store gint values.</title>
 <programlisting>
   GArray *garray;
   gint i;
@@ -240,7 +240,7 @@ Returns the element of a #GArray at the given index.
 The return value is cast to the given type.
 
 <example>
-<title>Getting a pointer to an element in a GArray.</title>
+<title>Getting a pointer to an element in a <structname>GArray</structname>.</title>
 <programlisting>
   EDayViewEvent *event;
 

docs/reference/glib/tmpl/arrays_byte.sgml

@@ -6,7 +6,7 @@ arrays of bytes, which grow automatically as elements are added.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-GByteArray is based on #GArray, to provide arrays of bytes which grow
+#GByteArray is based on #GArray, to provide arrays of bytes which grow
 automatically as elements are added.
 </para>
 <para>
@@ -17,19 +17,19 @@ To add elements to a #GByteArray, use g_byte_array_append(), and
 g_byte_array_prepend().
 </para>
 <para>
-To set the size of a GByteArray, use g_byte_array_set_size().
+To set the size of a #GByteArray, use g_byte_array_set_size().
 </para>
 <para>
-To free a GByteArray, use g_byte_array_free().
+To free a #GByteArray, use g_byte_array_free().
 </para>
 
 <example>
-<title>Using a GByteArray.</title>
+<title>Using a <structname>GByteArray</structname>.</title>
 <programlisting>
   GByteArray *gbarray;
   gint i;
 
-  gbarray = g_byte_array_new ();
+  gbarray = g_byte_array_new (<!>);
   for (i = 0; i < 10000; i++)
     g_byte_array_append (gbarray, (guint8*) "abcd", 4);
 
@@ -51,7 +51,7 @@ To free a GByteArray, use g_byte_array_free().
 
 <!-- ##### STRUCT GByteArray ##### -->
 <para>
-The #GByteArray struct allows access to the public fields of a #GByteArray.
+The <structname>GByteArray</structname> struct allows access to the public fields of a <structname>GByteArray</structname>.
 </para>
 
 @data: a pointer to the element data. The data may be moved as elements are
@@ -159,7 +159,7 @@ Sets the size of the #GByteArray, expanding it if necessary.
 <!-- ##### FUNCTION g_byte_array_free ##### -->
 <para>
 Frees the memory allocated by the #GByteArray.
-If free_segment is %TRUE it frees the actual byte data.
+If @free_segment is %TRUE it frees the actual byte data.
 </para>
 
 @array: a #GByteArray.

docs/reference/glib/tmpl/arrays_pointer.sgml

@@ -38,12 +38,12 @@ To set the size of a pointer array, use g_ptr_array_set_size().
 To free a pointer array, use g_ptr_array_free().
 </para>
 <example>
-<title>Using a GPtrArray.</title>
+<title>Using a <structname>GPtrArray</structname>.</title>
 <programlisting>
   GPtrArray *gparray;
   gchar *string1 = "one", *string2 = "two", *string3 = "three";
 
-  gparray = g_ptr_array_new ();
+  gparray = g_ptr_array_new (<!>);
   g_ptr_array_add (gparray, (gpointer) string1);
   g_ptr_array_add (gparray, (gpointer) string2);
   g_ptr_array_add (gparray, (gpointer) string3);
@@ -63,14 +63,10 @@ To free a pointer array, use g_ptr_array_free().
 <!-- ##### STRUCT GPtrArray ##### -->
 <para>
 Contains the public fields of a pointer array.
-The <structfield>pdata</structfield> field points to the array of pointers,
-which may as when the array grows.
-The <structfield>len</structfield> field is the number of pointers in the
-array.
 </para>
 
-@pdata: 
+@pdata: points to the array of pointers, which may be moved when the array grows.
-@len: 
+@len: number of pointers in the array.
 
 <!-- ##### FUNCTION g_ptr_array_new ##### -->
 <para>

docs/reference/glib/tmpl/caches.sgml

@@ -10,10 +10,10 @@ A #GCache allows sharing of complex data structures, in order to save
 system resources.
 </para>
 <para>
-GTK+ uses a #GCache for both GtkStyles and GdkGCs. These consume a lot of
+GTK+ uses a #GCache for #GtkStyles; GDK uses one for #GdkGCs. These consume a lot of
-resources, so a #GCache is used to see if a GtkStyle or GdkGC with the
+resources, so a #GCache is used to see if a #GtkStyle or #GdkGC with the
 required properties already exists. If it does, then the existing
-GtkStyle or GdkGC is used instead of creating a new one.
+object is used instead of creating a new one.
 </para>
 <para>
 #GCache uses keys and values.
@@ -29,7 +29,7 @@ A #GCache value is the actual resource.
 <!-- ##### STRUCT GCache ##### -->
 <para>
 The #GCache struct is an opaque data structure containing information about
-a #GCache. It should only be accesssed via the following functions.
+a #GCache. It should only be accessed via the following functions.
 </para>
 
 

docs/reference/glib/tmpl/completion.sgml

@@ -35,20 +35,13 @@ a different #GCompletionStrncmpFunc in g_completion_set_compare().
 <!-- ##### STRUCT GCompletion ##### -->
 <para>
 The data structure used for automatic completion.
-<structfield>items</structfield> is the list of target items (strings
-or data structures).
-<structfield>func</structfield> is the function called to get the string
-associated with a target item. It is %NULL if the target items are strings.
-<structfield>prefix</structfield> is the last prefix passed to
-g_completion_complete().
-<structfield>cache</structfield> is the list of items which begin with
-<structfield>prefix</structfield>.
 </para>
 
-@items: 
+@items: list of target items (strings or data structures).
-@func: 
+@func: function which is called to get the string associated with a target 
-@prefix: 
+  item. It is %NULL if the target items are strings.
-@cache: 
+@prefix: the last prefix passed to g_completion_complete().
+@cache: the list of items which begin with @prefix.
 @strncmp_func: 
 
 <!-- ##### FUNCTION g_completion_new ##### -->

docs/reference/glib/tmpl/conversions.sgml

@@ -2,7 +2,7 @@
 Character Set Conversion
 
 <!-- ##### SECTION Short_Description ##### -->
-convert strings between different character sets using <function>iconv()</function>
+convert strings between different character sets using <function>iconv()</function>.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/datalist.sgml

@@ -15,7 +15,7 @@ The #GQuark methods are quicker, since the strings have to be converted to
 </para>
 <para>
 Data lists are used in GTK+ for associating arbitrary data with
-GtkObjects, using gtk_object_set_data() and related functions.
+#GtkObjects, using gtk_object_set_data() and related functions.
 </para>
 
 <para>

docs/reference/glib/tmpl/date.sgml

@@ -20,7 +20,7 @@ time information; it represents a <emphasis>day</emphasis>.
 <para>
 The #GDate implementation has several nice features; it is only a
 64-bit struct, so storing large numbers of dates is very efficient. It
-can keep both a Julian and Day-Month-Year representation of the date,
+can keep both a Julian and day-month-year representation of the date,
 since some calculations are much easier with one representation or the
 other. A Julian representation is simply a count of days since some
 fixed day in the past; for #GDate the fixed day is January 1, 1 AD.
@@ -47,7 +47,7 @@ fail. Dates can be invalidated by calling g_date_clear() again.
 
 <para>
 <emphasis>It is very important to use the API to access the #GDate
-struct.</emphasis> Often only the DMY or only the Julian
+struct.</emphasis> Often only the day-month-year or only the Julian
 representation is valid. Sometimes neither is valid. Use the API.
 </para>
 
@@ -75,7 +75,7 @@ code readability.
 <para>
 Represents a precise time, with seconds and microseconds. Same as the
 <structname>struct timeval</structname> returned by the
-<function>gettimeofday()</function> UNIX call.
+<function>gettimeofday()</function> Unix call.
 </para>
 
 @tv_sec: seconds.
@@ -231,7 +231,7 @@ represent an existing day). Free the return value with g_date_free().
 <!-- ##### FUNCTION g_date_new_dmy ##### -->
 <para>
 Like g_date_new(), but also sets the value of the date. Assuming the
-day/month/year triplet you pass in represents an existing day, the
+day-month-year triplet you pass in represents an existing day, the
 returned date will be valid.
 </para>
 
@@ -685,7 +685,7 @@ though there is a 16-bit limit to what #GDate will understand.
 
 <!-- ##### FUNCTION g_date_valid_dmy ##### -->
 <para>
-Returns %TRUE if the day/month/year triplet forms a valid, existing day
+Returns %TRUE if the day-month-year triplet forms a valid, existing day
 in the range of days #GDate understands (Year 1 or later, no more than
 a few thousand years in the future).
 </para>

docs/reference/glib/tmpl/error_reporting.sgml

@@ -2,8 +2,7 @@
 Error Reporting
 
 <!-- ##### SECTION Short_Description ##### -->
-
+a system for reporting errors.
-System for reporting errors
 
 <!-- ##### SECTION Long_Description ##### -->
 
@@ -11,15 +10,15 @@ System for reporting errors
 GLib provides a standard method of reporting errors from a called function to
 the calling code. (This is the same problem solved by exceptions in other
 languages.) It's important to understand that this method is both a
-<emphasis>data type </emphasis> (the #GError object) and a <emphasis>set of
+<emphasis>data type</emphasis> (the #GError object) and a <emphasis>set of
-rules</emphasis>. If you use #GError incorrectly, then your code will not
+rules.</emphasis> If you use #GError incorrectly, then your code will not
 properly interoperate with other code that uses #GError, and users of your API
 will probably get confused.
 </para>
 
 <para>
 First and foremost: <emphasis>#GError should only be used to report
-recoverable runtime errors, never to report programming errors</emphasis>. If
+recoverable runtime errors, never to report programming errors.</emphasis> If
 the programmer has screwed up, then you should use g_warning(),
 g_return_if_fail(), g_assert(), g_error(), or some similar facility.
 (Incidentally, remember that the g_error() function should
@@ -39,12 +38,12 @@ This is why most functions in GLib and GTK+ do not use the #GError facility.
 <para>
 Functions that can fail take a return location for a #GError as their last argument. 
 For example:
-<programlisting>
+<informalexample><programlisting>
 gchar* g_file_get_contents (const gchar *filename, GError **error);
-</programlisting>
+</programlisting></informalexample>
 If you pass a non-%NULL value for the <literal>error</literal> argument, it should 
 point to a location where an error can be placed. For example:
-<programlisting>
+<informalexample><programlisting>
 gchar *contents;
 GError *err = NULL;
 contents = g_file_get_contents ("foo.txt", &amp;err);
@@ -61,7 +60,7 @@ else
     /* Use file contents */
     g_assert (contents != NULL);
   }
-</programlisting>
+</programlisting></informalexample>
 Note that <literal>err != NULL</literal> in this example is a
 <emphasis>reliable</emphasis> indicator of whether
 g_file_get_contents() failed. Also, g_file_get_contents() uses the
@@ -73,13 +72,13 @@ all functions use this convention).
 Because g_file_get_contents() returns %NULL on failure, if you are only
 interested in whether it failed and don't need to display an error message, you
 can pass %NULL for the <literal>error</literal> argument:
-<programlisting>
+<informalexample><programlisting>
 contents = g_file_get_contents ("foo.txt", NULL); /* ignore errors */
 if (contents != NULL)
   /* no error occurred */ ;
 else
   /* error */ ;
-</programlisting>
+</programlisting></informalexample>
 </para>
 
 <para>
@@ -103,7 +102,7 @@ When implementing a function that can report errors, the basic tool is
 g_set_error(). Typically, if a fatal error occurs you want to g_set_error(),
 then return immediately. g_set_error() does nothing if the error location passed
 to it is %NULL. Here's an example:
-<programlisting>
+<informalexample><programlisting>
 gint
 foo_open_file (GError **error)
 {
@@ -123,7 +122,7 @@ foo_open_file (GError **error)
   else
     return fd;
 }
-</programlisting>
+</programlisting></informalexample>
 </para>
 
 <para>
@@ -131,7 +130,7 @@ Things are somewhat more complicated if you yourself call another function that
 can report a #GError. If the sub-function indicates fatal errors in some way
 other than reporting a #GError, such as by returning %TRUE on success, you can
 simply do the following:
-<programlisting>
+<informalexample><programlisting>
 gboolean
 my_function_that_can_fail (GError **err)
 {
@@ -147,14 +146,14 @@ my_function_that_can_fail (GError **err)
   /* otherwise continue, no error occurred */
   g_assert (err == NULL || *err == NULL);
 }
-</programlisting>
+</programlisting></informalexample>
 </para>
 
 <para>
 If the sub-function does not indicate errors other than by reporting a #GError, 
 you need to create a temporary #GError since the passed-in one may be %NULL.
 g_propagate_error() is intended for use in this case.
-<programlisting>
+<informalexample><programlisting>
 gboolean
 my_function_that_can_fail (GError **err)
 {
@@ -168,7 +167,7 @@ my_function_that_can_fail (GError **err)
   if (tmp_error != NULL)
     {
        /* store tmp_error in err, if err != NULL,
-        * otherwise call g_error_free() on tmp_error 
+        * otherwise call g_error_free(<!>) on tmp_error 
         */
        g_propagate_error (err, tmp_error);
        return FALSE;
@@ -176,12 +175,12 @@ my_function_that_can_fail (GError **err)
 
   /* otherwise continue, no error occurred */
 }
-</programlisting>
+</programlisting></informalexample>
 </para>
 
 <para>
 Error pileups are always a bug. For example, this code is incorrect:
-<programlisting>
+<informalexample><programlisting>
 gboolean
 my_function_that_can_fail (GError **err)
 {
@@ -199,7 +198,7 @@ my_function_that_can_fail (GError **err)
        return FALSE;
     }
 }
-</programlisting>
+</programlisting></informalexample>
 <literal>tmp_error</literal> should be checked immediately after
 <function>sub_function_that_can_fail()</function>, and either cleared or propagated upward.  The rule
 is: <emphasis>after each error, you must either handle the error, or return it to the
@@ -207,7 +206,7 @@ calling function</emphasis>.  Note that passing %NULL for the error location is
 equivalent of handling an error by always doing nothing about it. So the
 following code is fine, assuming errors in <function>sub_function_that_can_fail()</function> are not
 fatal to <function>my_function_that_can_fail()</function>:
-<programlisting>
+<informalexample><programlisting>
 gboolean
 my_function_that_can_fail (GError **err)
 {
@@ -226,7 +225,7 @@ my_function_that_can_fail (GError **err)
        return FALSE;
     }
 }
-</programlisting>
+</programlisting></informalexample>
 </para>
 
 <para>

docs/reference/glib/tmpl/fileutils.sgml

@@ -17,9 +17,9 @@ various file-related functions.
 <!-- ##### ENUM GFileError ##### -->
 <para>
 Values corresponding to <literal>errno</literal> codes returned from file operations
-on UNIX. Unlike <literal>errno</literal> codes, #GFileError values are available on 
+on Unix. Unlike <literal>errno</literal> codes, #GFileError values are available on 
 all systems, even Windows. The exact meaning of each code depends on what
-sort of file operation you were performing; the UNIX documentation
+sort of file operation you were performing; the Unix documentation
 gives more details. The following error code descriptions come 
 from the GNU C Library manual, and are under the copyright
 of that manual.

docs/reference/glib/tmpl/hash_tables.sgml

@@ -53,7 +53,7 @@ To destroy a #GHashTable use g_hash_table_destroy().
 
 <!-- ##### STRUCT GHashTable ##### -->
 <para>
-The #GHashTable struct is an opaque data structure to represent a
+The <structname>GHashTable</structname> struct is an opaque data structure to represent a
 <link linkend="glib-Hash-Tables">Hash Table</link>.
 It should only be accessed via the following functions.
 </para>
@@ -289,7 +289,7 @@ parameter, when using pointers as keys in a #GHashTable.
 <para>
 Converts a gpointer to a hash value.
 It can be passed to g_hash_table_new() as the @hash_func parameter, when
-using gpointer values as keys in a #GHashTable.
+using pointers as keys in a #GHashTable.
 </para>
 
 @v: a gpointer key.
@@ -313,7 +313,7 @@ parameter, when using pointers to integers as keys in a #GHashTable.
 <para>
 Converts a pointer to a #gint to a hash value.
 It can be passed to g_hash_table_new() as the @hash_func parameter, when
-using pointers to #gint values as keys in a #GHashTable.
+using pointers to integers values as keys in a #GHashTable.
 </para>
 
 @v: a pointer to a #gint key.

docs/reference/glib/tmpl/hooks.sgml

@@ -19,53 +19,18 @@ and the list of hook functions can be invoked.
 
 <!-- ##### STRUCT GHookList ##### -->
 <para>
-
+The <structname>GHookList</structname> struct represents a 
-<informaltable pgwide=1 frame="none" role="struct">
+list of hook functions.
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>#guint seq_id;</entry>
-<entry>the next free #GHook id.</entry>
-</row>
-
-<row>
-<entry>#guint hook_size;</entry>
-<entry>the size of the #GHookList elements, in bytes.</entry>
-</row>
-
-<row>
-<entry>#guint is_setup : 1;</entry>
-<entry>1 if the #GHookList has been initialized.</entry>
-</row>
-
-<row>
-<entry>#GHook *hooks;</entry>
-<entry>the first #GHook element in the list.</entry>
-</row>
-
-<row>
-<entry>#GMemChunk *hook_memchunk;</entry>
-<entry>the #GMemChunk used for allocating the #GHook elements.</entry>
-</row>
-
-<row>
-<entry>#GHookFinalizeFunc finalize_hook;</entry>
-<entry>the function to call to finalize a #GHook element. 
-The default behaviour is to call the hooks <function>destroy</function> 
-function.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-
 </para>
 
-@seq_id: 
+@seq_id: the next free #GHook id.
-@hook_size: 
+@hook_size: the size of the #GHookList elements, in bytes.
-@is_setup: 
+@is_setup: 1 if the #GHookList has been initialized.
-@hooks: 
+@hooks: the first #GHook element in the list.
-@hook_memchunk: 
+@hook_memchunk: the #GMemChunk used for allocating the #GHook elements.
-@finalize_hook: 
+@finalize_hook: the function to call to finalize a #GHook element. The
+default behaviour is to call the hooks <function>destroy</function> function.
+
 
 <!-- ##### USER_FUNCTION GHookFinalizeFunc ##### -->
 <para>
@@ -79,65 +44,22 @@ list of hooks gets finalized.
 
 <!-- ##### STRUCT GHook ##### -->
 <para>
-
+The <structname>GHook</structname> struct represents a single hook 
-<informaltable pgwide=1 frame="none" role="struct">
+function in a #GHookList.
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>#gpointer data;</entry>
-<entry>data which is passed to func when this hook is invoked.</entry>
-</row>
-
-<row>
-<entry>#GHook *next;</entry>
-<entry>pointer to the next hook in the list.</entry>
-</row>
-
-<row>
-<entry>#GHook *prev;</entry>
-<entry>pointer to the previous hook in the list.</entry>
-</row>
-
-<row>
-<entry>#guint ref_count;</entry>
-<entry>the reference count of this hook.</entry>
-</row>
-
-<row>
-<entry>#guint hook_id;</entry>
-<entry>the id of this hook, which is unique within its list.</entry>
-</row>
-
-<row>
-<entry>#guint flags;</entry>
-<entry>flags which are set for this hook. See #GHookFlagMask for
-predefined flags.</entry>
-</row>
-
-<row>
-<entry>#gpointer func;</entry>
-<entry>the function to call when this hook is invoked. The possible 
-signatures for this function are #GHookFunc and #GHookCheckFunc.</entry>
-</row>
-
-<row>
-<entry>#GDestroyNotify destroy;</entry>
-<entry>the default <function>finalize_hook</function> function of a 
-#GHookList calls this member of the hook that is being finalized.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
 </para>
 
-@data: 
+@data: data which is passed to func when this hook is invoked.
-@next: 
+@next: pointer to the next hook in the list.
-@prev: 
+@prev: pointer to the previous hook in the list.
-@ref_count: 
+@ref_count: the reference count of this hook.
-@hook_id: 
+@hook_id: the id of this hook, which is unique within its list.
-@flags: 
+@flags: flags which are set for this hook. See #GHookFlagMask for
-@func: 
+predefined flags.
-@destroy: 
+@func: the function to call when this hook is invoked. The possible 
+signatures for this function are #GHookFunc and #GHookCheckFunc.
+@destroy: the default <function>finalize_hook</function> function of a 
+#GHookList calls this member of the hook that is being finalized.
+
 
 <!-- ##### USER_FUNCTION GHookFunc ##### -->
 <para>

docs/reference/glib/tmpl/macros.sgml

@@ -53,8 +53,8 @@ BeOS-specific code in "#ifdef G_OS_BEOS".
 
 <!-- ##### MACRO G_OS_UNIX ##### -->
 <para>
-This macro is defined only on UNIX. So you can bracket
+This macro is defined only on Unix. So you can bracket
-UNIX-specific code in "#ifdef G_OS_UNIX".
+Unix-specific code in "#ifdef G_OS_UNIX".
 </para>
 
 

docs/reference/glib/tmpl/macros_misc.sgml

@@ -42,7 +42,8 @@ only one statement is expected by the compiler.
 <!-- ##### MACRO G_BEGIN_DECLS ##### -->
 <para>
 Used (along with #G_END_DECLS) to bracket header files. If the
-compiler in use is a C++ compiler, adds 'extern "C"' around the header.
+compiler in use is a C++ compiler, adds <literal>extern "C"</literal> 
+around the header.
 </para>
 
 
@@ -92,16 +93,17 @@ Accepts a macro or a string and converts it into a string.
 
 <!-- ##### MACRO G_GNUC_EXTENSION ##### -->
 <para>
-Expands to <literal>__extension__</literal> when GNU C is used as the compiler.
+Expands to <literal>__extension__</literal> when <command>gcc</command> is 
-This simply tells GNU C not to warn about the following non-standard code
+used as the compiler.
-when compiling with the <literal>-pedantic</literal> option.
+This simply tells <command>gcc</command> not to warn about the following non-standard code
+when compiling with the <option>-pedantic</option> option.
 </para>
 
 
 
 <!-- ##### MACRO G_GNUC_CONST ##### -->
 <para>
-Expands to the GNU C const function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>const</literal> function attribute if the compiler is <command>gcc</command>.
 Declaring a function as const enables better optimization of the function.
 A const function doesn't examine any values except its parameters,
 and has no effects except its return value.
@@ -118,7 +120,7 @@ for a const function to return void.
 
 <!-- ##### MACRO G_GNUC_NORETURN ##### -->
 <para>
-Expands to the GNU C noreturn function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>noreturn</literal> function attribute if the compiler is <command>gcc</command>.
 It is used for declaring functions which never return.
 It enables optimization of the function, and avoids possible compiler
 warnings. See the GNU C documentation for details. 
@@ -128,7 +130,7 @@ warnings. See the GNU C documentation for details.
 
 <!-- ##### MACRO G_GNUC_UNUSED ##### -->
 <para>
-Expands to the GNU C unused function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>unused</literal> function attribute if the compiler is <command>gcc</command>.
 It is used for declaring functions which may never be used.
 It avoids possible compiler warnings. See the GNU C documentation for details. 
 </para>
@@ -137,7 +139,7 @@ It avoids possible compiler warnings. See the GNU C documentation for details.
 
 <!-- ##### MACRO G_GNUC_PURE ##### -->
 <para>
-Expands to the GNU C pure function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>pure</literal> function attribute if the compiler is <command>gcc</command>.
 Declaring a function as pure enables better optimization of the function.
 A pure function has no effects except its return value and the return 
 value depends only on the parameters and/or global variables.
@@ -148,7 +150,7 @@ See the GNU C documentation for details.
 
 <!-- ##### MACRO G_GNUC_PRINTF ##### -->
 <para>
-Expands to the GNU C format function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
 This is used for declaring functions which take a variable number of
 arguments, with the same syntax as <function>printf()</function>.
 It allows the compiler to type-check the arguments passed to the function.
@@ -168,7 +170,7 @@ gint g_snprintf (gchar  *string,
 
 <!-- ##### MACRO G_GNUC_SCANF ##### -->
 <para>
-Expands to the GNU C format function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
 This is used for declaring functions which take a variable number of
 arguments, with the same syntax as <function>scanf()</function>.
 It allows the compiler to type-check the arguments passed to the function.
@@ -182,8 +184,8 @@ See the GNU C documentation for details.
 
 <!-- ##### MACRO G_GNUC_FORMAT ##### -->
 <para>
-Expands to the GNU C format_arg function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>format_arg</literal> function attribute if the compiler is <command>gcc</command>.
-The format_arg function attribute specifies that a function takes a format
+This function attribute specifies that a function takes a format
 string for a <function>printf()</function>, <function>scanf()</function>, 
 <function>strftime()</function> or <function>strfmon()</function> style
 function and modifies it, so that the result can be passed to a 
@@ -203,7 +205,7 @@ gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
 <!-- ##### MACRO G_GNUC_FUNCTION ##### -->
 <para>
 Expands to the GNU C <literal>__FUNCTION__</literal> variable if the 
-compiler is GNU C, or "" if it isn't. The GNU C 
+compiler is <command>gcc</command>, or "" if it isn't. The GNU C 
 <literal>__FUNCTION__</literal> variable contains the name of the 
 current function. See the GNU C documentation for details. 
 </para>
@@ -213,7 +215,7 @@ current function. See the GNU C documentation for details.
 <!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
 <para>
 Expands to the GNU C <literal>__PRETTY_FUNCTION__</literal> variable 
-if the compiler is GNU C, or "" if it isn't.
+if the compiler is <command>gcc</command>, or "" if it isn't.
 The GNU C <literal>__PRETTY_FUNCTION__</literal> variable contains the 
 name of the current function. For a C program this is the same as the 
 <literal>__FUNCTION__</literal> variable but for C++ it also includes 
@@ -225,8 +227,9 @@ GNU C documentation for details.
 
 <!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
 <para>
-Expands to the GNU C no_instrument_function function attribute if 
+Expands to the GNU C <literal>no_instrument_function</literal> function 
-the compiler is GNU C. Functions with this attribute will not be 
+attribute if the compiler is <command>gcc</command>. Functions with this 
+attribute will not be 
 instrumented for profiling, when the compiler is called with the
 <option>-finstrument-functions</option> option.
 See the GNU C documentation for details. 

docs/reference/glib/tmpl/main.sgml

@@ -230,7 +230,7 @@ It is not used within GLib or GTK+.
 Use this for default priority event sources.
 In GLib this priority is used when adding timeout functions with
 g_timeout_add().
-In GDK this priority is used for events from the X Windows server.
+In GDK this priority is used for events from the X server.
 </para>
 
 
@@ -593,7 +593,7 @@ g_main_context_set_poll_func() for full details.
 
 <row>
 <entry>#gint fd;</entry>
-<entry>the file descriptor to poll (or a HANDLE on Win32 platforms).</entry>
+<entry>the file descriptor to poll (or a <type>HANDLE</type> on Win32 platforms).</entry>
 </row>
 
 <row>
@@ -640,9 +640,9 @@ event sources in a generic manner.
 <entry>
 Called before all the file descriptors are polled.
 If the source can determine that it is ready here (without waiting for the
-results of the poll() call) it should return %TRUE.
+results of the <function>poll()</function> call) it should return %TRUE.
 It can also return a @timeout value which should be the maximum timeout
-(in milliseconds) which should be passed to the poll() call.
+(in milliseconds) which should be passed to the <function>poll()</function> call.
 The actual timeout used will be -1 if all sources returned -1, or it will
 be the minimum of all the @timeout values returned which were >= 0.
 </entry>

docs/reference/glib/tmpl/markup.sgml

@@ -2,13 +2,12 @@
 Simple XML Subset Parser
 
 <!-- ##### SECTION Short_Description ##### -->
-
+parses a subset of XML.
-Parses a subset of XML
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
 The "GMarkup" parser is intended to parse a simple markup format
-that's a subset of XML format. This is a small, efficient, easy-to-use
+that's a subset of XML. This is a small, efficient, easy-to-use
 parser. It should not be used if you expect to interoperate with other 
 applications generating full-scale XML. However, it's very useful for
 application data files, config files, etc. where you know your

docs/reference/glib/tmpl/memory.sgml

@@ -124,12 +124,12 @@ If @mem is %NULL it simply returns.
 <!-- ##### MACRO g_alloca ##### -->
 <para>
 Allocates @size bytes on the stack; these bytes will be freed when the current
-stack frame is cleaned up. This macro essentially just wraps the alloca(3) function
+stack frame is cleaned up. This macro essentially just wraps the 
-present on most unix variants. Thus it provides the same advantages and pitfalls
+<function>alloca()</function> function present on most Unix variants. 
-as alloca():
+Thus it provides the same advantages and pitfalls as <function>alloca()</function>:
 <msgtext><variablelist>
   <varlistentry><term></term><listitem><para>
-    + alloca() is very fast, as on most systems it's implemented by just adjusting
+    + <function>alloca()</function> is very fast, as on most systems it's implemented by just adjusting
     the stack pointer register.
   </para></listitem></varlistentry>
   <varlistentry><term></term><listitem><para>
@@ -139,17 +139,17 @@ as alloca():
   <varlistentry><term></term><listitem><para>
     - Allocation sizes have to fit into the current stack frame. For instance in a
       threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
-      so be sparse with alloca() uses.
+      so be sparse with <funcion>alloca()</function> uses.
   </para></listitem></varlistentry>
   <varlistentry><term></term><listitem><para>
     - Allocation failure due to insufficient stack space is not indicated with a %NULL
-      return like e.g. with malloc(3). Instead, most systems probably handle it the same
+      return like e.g. with <function>malloc()</function>. Instead, most systems probably handle it the same
       way as out of stack space situations from infinite function recursion, i.e.
       with a segmentation fault.
   </para></listitem></varlistentry>
   <varlistentry><term></term><listitem><para>
-    - Special care has to be taken when mixing alloca(3) with GCC variable sized arrays.
+    - Special care has to be taken when mixing <function>alloca()</function> with GNU C variable sized arrays.
-      Stack space allocated with alloca(3) in the same scope as a variable sized array
+      Stack space allocated with <function>alloca()</function> in the same scope as a variable sized array
       will be freed together with the variable sized array upon exit of that scope, and
       not upon exit of the enclosing function scope.
   </para></listitem></varlistentry>
@@ -216,8 +216,7 @@ if it exists, should be prior to any use of GLib.
 <!-- ##### FUNCTION g_mem_set_vtable ##### -->
 <para>
 Sets the #GMemVTable to use for memory allocation. You can use this to provide
-custom memory allocation routines. THIS FUNCTION MUST BE CALLED BEFORE USING ANY
+custom memory allocation routines. <emphasis>This function must be called before using any other GLib functions.</emphasis> The @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
-OTHER GLIB FUNCTIONS. The @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
 functions; GLib can provide default implementations of the others.  The <function>malloc()</function>
 and <function>realloc()</function> implementations should return %NULL on failure, GLib will handle
 error-checking for you. @vtable is copied, so need not persist after this 

docs/reference/glib/tmpl/memory_chunks.sgml

@@ -95,7 +95,7 @@ To help debug memory chunks, use g_mem_chunk_info() and g_mem_chunk_print().
   GRealArray *array;
 
   /* Create a GMemChunk to hold GRealArray structures, using the
-     g_mem_chunk_create() convenience macro. We want 1024 atoms in each
+     g_mem_chunk_create(<!>) convenience macro. We want 1024 atoms in each
      memory block, and we want to be able to free individual atoms. */
   array_mem_chunk = g_mem_chunk_create (GRealArray, 1024, G_ALLOC_AND_FREE);
 

docs/reference/glib/tmpl/messages.sgml

@@ -32,8 +32,7 @@ But be careful not to define it in any public header files.
 For example, GTK+ uses this in its Makefile.am:
 </para>
 <informalexample><programlisting>
-INCLUDES = \
+INCLUDES = -DG_LOG_DOMAIN=\"Gtk\"
-	-DG_LOG_DOMAIN=\"Gtk\"
 </programlisting></informalexample>
 
 
@@ -112,7 +111,7 @@ documentation.
 A convenience function/macro to log a normal message.
 </para>
 
-@...: 
+@...: the parameters to insert into the format string.
 <!-- # Unused Parameters # -->
 @format: the message format. See the <function>printf()</function>
 documentation.
@@ -124,7 +123,7 @@ documentation.
 A convenience function/macro to log a warning message.
 </para>
 
-@...: format string, followed by parameters to insert into the format string (as with printf())
+@...: format string, followed by parameters to insert into the format string (as with <function>printf()</function>)
 
 
 <!-- ##### MACRO g_critical ##### -->
@@ -136,7 +135,7 @@ warnings exit the program, then use g_critical() for fatal errors, for
 example.
 </para>
 
-@...: format string, followed by parameters to insert into the format string (as with printf())
+@...: format string, followed by parameters to insert into the format string (as with <function>printf()</function>)
 
 
 <!-- ##### MACRO g_error ##### -->
@@ -149,7 +148,7 @@ expect. Using this function indicates a bug in your program, i.e. an
 assertion failure.
 </para>
 
-@...: 
+@...: the parameters to insert into the format string.
 <!-- # Unused Parameters # -->
 @format: the message format. See the <function>printf()</function>
 documentation.
@@ -160,11 +159,11 @@ documentation.
 <para>
 Sets the log handler for a domain and a set of log levels.
 To handle fatal and recursive messages the @log_levels parameter
-must be combined with the G_LOG_FLAG_FATAL and G_LOG_FLAG_RECURSIVE bit flags.
+must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSIVE bit flags.
 </para>
 <para>
-Note that since the G_LOG_LEVEL_ERROR log level is always fatal, if you want
+Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if you want
-to set a handler for this log level you must combine it with G_LOG_FLAG_FATAL.
+to set a handler for this log level you must combine it with #G_LOG_FLAG_FATAL.
 </para>
 <para>
 
@@ -250,6 +249,6 @@ stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, and
 @log_domain: the log domain of the message.
 @log_level: the level of the message.
 @message: the message.
-@unused_data: data passed from g_log which is unused.
+@unused_data: data passed from g_log() which is unused.
 
 

docs/reference/glib/tmpl/misc_utils.sgml

@@ -53,7 +53,7 @@ Gets the user name of the current user.
 
 <!-- ##### FUNCTION g_get_real_name ##### -->
 <para>
-Gets the real name of the user. This comes from the user's entry in the
+Gets the real name of the user. This usually comes from the user's entry in the
 <filename>passwd</filename> file.
 </para>
 
@@ -73,7 +73,8 @@ Gets the current user's home directory.
 Gets the directory to use for temporary files.
 This is found from inspecting the environment variables <envar>TMPDIR</envar>, 
 <envar>TMP</envar>, and <envar>TEMP</envar>
-in that order. If none of those are defined "/tmp" is returned.
+in that order. If none of those are defined "/tmp" is returned on Unix and 
+"C:\" on Windows.
 </para>
 
 @Returns: the directory to use for temporary files.
@@ -123,7 +124,7 @@ The returned string should be freed when no longer needed.
 <para>
 Returns %TRUE if the given @file_name is an absolute file name,
 i.e. it contains a full path from the root directory such as '/usr/local'
-or 'C:/windows' on windows systems.
+on Unix or 'C:\windows' on Windows systems.
 </para>
 
 @file_name: a file name.
@@ -133,7 +134,7 @@ or 'C:/windows' on windows systems.
 <!-- ##### FUNCTION g_path_skip_root ##### -->
 <para>
 Returns a pointer into @file_name after the root component, i.e. after
-the '/' in Unix or 'C:/' under Windows. If @file_name is not an absolute
+the '/' in Unix or 'C:\' under Windows. If @file_name is not an absolute
 path it returns %NULL.
 </para>
 
@@ -245,7 +246,7 @@ The built-in array of primes ranges from 11 to 13845163 such that
 each prime is approximately 1.5-2 times the previous prime.
 </para>
 
-@num: a guint.
+@num: a #guint.
 @Returns: the smallest prime number from a built-in array of primes which is
 larger than @num.
 

docs/reference/glib/tmpl/modules.sgml

@@ -199,7 +199,7 @@ It is passed the #GModule structure.
 <para>
 Expands to the proper shared library suffix for the current platform
 without the leading dot. For the most Unices and Linux this is "so",
-for some HPUX versions this is "sl" and for Windows this is "dll".
+for some HP-UX versions this is "sl" and for Windows this is "dll".
 </para>
 
 

docs/reference/glib/tmpl/numerical.sgml

@@ -2,8 +2,7 @@
 Numerical Definitions
 
 <!-- ##### SECTION Short_Description ##### -->
-
+mathematical constants, and floating point decomposition.
-Mathematical constants, and floating point decomposition.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -17,7 +16,7 @@ The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
 	sign, mantissa and exponent of IEEE floats and doubles. These
 	unions are defined as appropriate for a given platform. 
  IEEE floats and doubles are supported (used for
-	storage) by at least intel, ppc and sparc, for reference: <ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink>
+	storage) by at least Intel, PPC and Sparc, for reference: <ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink>
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -45,7 +44,7 @@ The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
 	sign, mantissa and exponent of IEEE floats and doubles. These
 	unions are defined as appropriate for a given platform. 
  IEEE floats and doubles are supported (used for
-	storage) by at least intel, ppc and sparc, for reference: 
+	storage) by at least Intel, PPC and Sparc, for reference: 
 <ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink>
 </para>
 
@@ -56,7 +55,7 @@ The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
 	sign, mantissa and exponent of IEEE floats and doubles. These
 	unions are defined as appropriate for a given platform. 
  IEEE floats and doubles are supported (used for
-	storage) by at least intel, ppc and sparc, for reference: 
+	storage) by at least Intel, PPC and Sparc, for reference: 
 <ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink>
 </para>
 

docs/reference/glib/tmpl/patterns.sgml

@@ -2,8 +2,7 @@
 Glob-style pattern matching
 
 <!-- ##### SECTION Short_Description ##### -->
-
+matches strings against patterns containing '*' (wildcard) and '?' (joker).
-Matches strings against patterns containing '*' (wildcard) and '?' (joker).
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/queue.sgml

@@ -2,7 +2,7 @@
 Double-ended Queues
 
 <!-- ##### SECTION Short_Description ##### -->
-double-ended queue data structure
+double-ended queue data structure.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/shell.sgml

@@ -2,7 +2,7 @@
 Shell-related Utilities
 
 <!-- ##### SECTION Short_Description ##### -->
-shell-like commandline handling
+shell-like commandline handling.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/spawn.sgml

@@ -2,7 +2,7 @@
 Spawning Processes
 
 <!-- ##### SECTION Short_Description ##### -->
-Process launching with <function>fork()</function>/<function>exec()</function>
+process launching with <function>fork()</function>/<function>exec()</function>.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/string_utils.sgml

@@ -122,11 +122,10 @@ an even better idea.
 
 <!-- ##### FUNCTION g_strlcat ##### -->
 <para>
-Portability wrapper that calls strlcat() on systems which have it, and emulates
+Portability wrapper that calls <function>strlcat()</function> on systems which have it, and emulates it otherwise. Appends nul-terminated @src string to @dest, guaranteeing
-strlcat() otherwise. Appends nul-terminated @src string to @dest, guaranteeing
 nul-termination for @dest. The total size of @dest won't exceed
-@dest_size. Caveat: this is supposedly a more secure alternative to strcat() or
+@dest_size. Caveat: this is supposedly a more secure alternative to <function>strcat()</function> or
-strncat(), but for real security g_strconcat() is harder to mess up.
+<function>strncat()</function>, but for real security g_strconcat() is harder to mess up.
 </para>
 
 @dest: destination buffer, already containing one nul-terminated string
@@ -230,12 +229,12 @@ documentation.
 Determines whether a character is alphanumeric.
 </para>
 <para>
-Unlike the standard C library isalnum function, this only
+Unlike the standard C library <function>isalnum()</function> function, this only
 recognizes standard ASCII letters and ignores the locale, returning
 %FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
+library function, this takes a <type>char</type>, not an <type>int</type>, 
-on EOF but no need to cast to guchar before passing a possibly
+so don't call it on %EOF but no need to cast to #guchar before passing a 
-non-ASCII character in.
+possibly non-ASCII character in.
 </para>
 
 @c: any character
@@ -247,12 +246,12 @@ non-ASCII character in.
 Determines whether a character is alphabetic (i.e. a letter).
 </para>
 <para>
-Unlike the standard C library isalpha function, this only
+Unlike the standard C library <function>isalpha()</function> function, this only
 recognizes standard ASCII letters and ignores the locale, returning
 %FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
+library function, this takes a <type>char</type>, not an <type>int</type, 
-on EOF but no need to cast to guchar before passing a possibly
+so don't call it on %EOF but no need to cast to #guchar before passing a 
-non-ASCII character in.
+possibly non-ASCII character in.
 </para>
 
 @c: any character
@@ -264,12 +263,12 @@ non-ASCII character in.
 Determines whether a character is a control character.
 </para>
 <para>
-Unlike the standard C library iscntrl function, this only
+Unlike the standard C library <function>iscntrl()</function> function, this only
 recognizes standard ASCII control characters and ignores the locale,
-returning%FALSE for all non-ASCII characters. Also unlike the standard
+returning %FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
+library function, this takes a <type>char</type>, not an <type>int</type>, 
-on EOF but no need to cast to guchar before passing a possibly
+so don't call it on %EOF but no need to cast to #guchar before passing a 
-non-ASCII character in.
+possibly non-ASCII character in.
 </para>
 
 @c: any character
@@ -281,9 +280,9 @@ non-ASCII character in.
 Determines whether a character is digit (0-9).
 </para>
 <para>
-Unlike the standard C library isdigit function,
+Unlike the standard C library <function>isdigit()</function> function,
-this takes a char, not an int, so don't call it
+this takes a <type>char</type>, not an <type>int</type>, so don't call it
-on EOF but no need to cast to guchar before passing a possibly
+on %EOF but no need to cast to #guchar before passing a possibly
 non-ASCII character in.
 </para>
 
@@ -296,12 +295,12 @@ non-ASCII character in.
 Determines whether a character is a printing character and not a space.
 </para>
 <para>
-Unlike the standard C library isgraph function, this only
+Unlike the standard C library <function>isgraph()</function> function, 
-recognizes standard ASCII characters and ignores the locale, returning
+this only recognizes standard ASCII characters and ignores the locale, 
-%FALSE for all non-ASCII characters. Also unlike the standard
+returning %FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
+library function, this takes a <type>char</type>, not an <type>int</type>, 
-on EOF but no need to cast to guchar before passing a possibly
+so don't call it on %EOF but no need to cast to #guchar before passing a 
-non-ASCII character in.
+possibly non-ASCII character in.
 </para>
 
 @c: any character
@@ -313,12 +312,12 @@ non-ASCII character in.
 Determines whether a character is an ASCII lower case letter.
 </para>
 <para>
-Unlike the standard C library islower function, this only
+Unlike the standard C library <function>islower()</function> function, 
-recognizes standard ASCII letters and ignores the locale, returning
+this only recognizes standard ASCII letters and ignores the locale,
-%FALSE for all non-ASCII characters. Also unlike the standard
+returning %FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
+library function, this takes a <type>char</type>, not an <type>int</type>, 
-on EOF but no need to worry about casting to guchar before passing
+so don't call it on %EOF but no need to worry about casting to #guchar 
-a possibly non-ASCII character in.
+before passing a possibly non-ASCII character in.
 </para>
 
 @c: any character
@@ -330,12 +329,12 @@ a possibly non-ASCII character in.
 Determines whether a character is a printing character.
 </para>
 <para>
-Unlike the standard C library isprint function, this only
+Unlike the standard C library <function>isprint()</function> function, 
-recognizes standard ASCII characters and ignores the locale, returning
+this only recognizes standard ASCII characters and ignores the locale, 
-%FALSE for all non-ASCII characters. Also unlike the standard
+returning %FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
+library function, this takes a <type>char</type>, not an <type>int</type>, 
-on EOF but no need to cast to guchar before passing a possibly
+so don't call it on %EOF but no need to cast to #guchar before passing a 
-non-ASCII character in.
+possibly non-ASCII character in.
 </para>
 
 @c: any character
@@ -347,12 +346,12 @@ non-ASCII character in.
 Determines whether a character is a punctuation character.
 </para>
 <para>
-Unlike the standard C library ispunct function, this only
+Unlike the standard C library <function>ispunct()</function> function, 
-recognizes standard ASCII letters and ignores the locale, returning
+this only recognizes standard ASCII letters and ignores the locale, 
-%FALSE for all non-ASCII characters. Also unlike the standard
+returning %FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
+library function, this takes a <type>char</type>, not an <type>int</type>, 
-on EOF but no need to cast to guchar before passing a possibly
+so don't call it on %EOF but no need to cast to #guchar before passing a 
-non-ASCII character in.
+possibly non-ASCII character in.
 </para>
 
 @c: any character
@@ -364,12 +363,12 @@ non-ASCII character in.
 Determines whether a character is a white-space character.
 </para>
 <para>
-Unlike the standard C library isspace function, this only
+Unlike the standard C library <function>isspace()</function> function, 
-recognizes standard ASCII white-space and ignores the locale, returning
+this only recognizes standard ASCII white-space and ignores the locale, 
-%FALSE for all non-ASCII characters. Also unlike the standard
+returning %FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
+library function, this takes a <type>char</type>, not an <type>int</type>, 
-on EOF but no need to cast to guchar before passing a possibly
+so don't call it on %EOF but no need to cast to #guchar before passing a 
-non-ASCII character in.
+possibly non-ASCII character in.
 </para>
 
 @c: any character
@@ -381,12 +380,12 @@ non-ASCII character in.
 Determines whether a character is an ASCII upper case letter.
 </para>
 <para>
-Unlike the standard C library isupper function, this only
+Unlike the standard C library <function>isupper()</function> function, 
-recognizes standard ASCII letters and ignores the locale, returning
+this only recognizes standard ASCII letters and ignores the locale, 
-%FALSE for all non-ASCII characters. Also unlike the standard
+returning %FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
+library function, this takes a <type>char</type>, not an <type>int</type>, 
-on EOF but no need to worry about casting to guchar before passing
+so don't call it on %EOF but no need to worry about casting to #guchar 
-a possibly non-ASCII character in.
+before passing a possibly non-ASCII character in.
 </para>
 
 @c: any character
@@ -398,9 +397,9 @@ a possibly non-ASCII character in.
 Determines whether a character is a hexadecimal-digit character.
 </para>
 <para>
-Unlike the standard C library isxdigit function,
+Unlike the standard C library <function>isxdigit()</function> function,
-this takes a char, not an int, so
+this takes a <type>char</type>, not an <type>int</type>, so
-don't call it on EOF but no need to cast to guchar before passing a
+don't call it on %EOF but no need to cast to #guchar before passing a
 possibly non-ASCII character in.
 </para>
 
@@ -554,7 +553,8 @@ of the strings.
 </para>
 <para>
 The problem with g_strncasecmp() is that it does the comparison by
-calling toupper()/tolower() on each byte. toupper()/tolower() are
+calling <function>toupper()</function>/<function>tolower()</function> 
+on each byte. <function>toupper()</function>/<function>tolower()</function> are
 locale-specific and operate on single bytes. However, it is impossible
 to handle things correctly from an i18n standpoint by operating on
 bytes, since characters may be multibyte. Thus g_strncasecmp() is
@@ -580,7 +580,7 @@ value if @s1 > @s2.
 <!-- ##### FUNCTION g_strreverse ##### -->
 <para>
 Reverses all of the characters in a string.
-For example, g_strreverse ("abcdef") will result in "fedcba".
+For example, <literal>g_strreverse ("abcdef")</literal> will result in "fedcba".
 </para>
 
 @string: the string to reverse.
@@ -589,19 +589,17 @@ For example, g_strreverse ("abcdef") will result in "fedcba".
 
 <!-- ##### MACRO G_ASCII_DTOSTR_BUF_SIZE ##### -->
 <para>
-A good size for a buffer to be passed into <function>g_ascii_dtostr</function>.
+A good size for a buffer to be passed into g_ascii_dtostr().
 It is guaranteed to be enough for all output of that function on systems with
- 64bit IEEE compatible doubles.
+ 64bit IEEE-compatible doubles.
 </para>
 <para>
 The typical usage would be something like:
-</para>
+<informalexample><programlisting>
-<para>
-<literal>
   char buf[G_ASCII_DTOSTR_BUF_SIZE];
 
   fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
-</literal>
+</programlisting></informalexample>
 </para>
 
 
@@ -694,7 +692,7 @@ standard delimiters defined in #G_STR_DELIMITERS.
 
 <!-- ##### MACRO G_STR_DELIMITERS ##### -->
 <para>
-The standard delimiters, used in #g_strdelimit.
+The standard delimiters, used in g_strdelimit().
 </para>
 
 

docs/reference/glib/tmpl/thread_pools.sgml

@@ -2,7 +2,7 @@
 Thread Pools
 
 <!-- ##### SECTION Short_Description ##### -->
-Pools of threads to execute work concurrently
+pools of threads to execute work concurrently.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/threads.sgml

@@ -158,7 +158,7 @@ really know what you are doing.
 <note>
 <para>
 g_thread_init() must not be called directly or indirectly as a
-call-back from GLib. Also no mutexes may be currently locked, while
+callback from GLib. Also no mutexes may be currently locked, while
 calling g_thread_init().
 </para>
 </note>
@@ -172,7 +172,7 @@ system is initialized, you can do that too:
 <para>
 <informalexample>
 <programlisting>
-if (!g_thread_supported ()) g_thread_init (NULL);
+if (!g_thread_supported (<!>)) g_thread_init (NULL);
 </programlisting>
 </informalexample>
 </para>
@@ -362,7 +362,7 @@ This functions returns the #GThread corresponding to the calling thread.
 <!-- ##### FUNCTION g_thread_join ##### -->
 <para>
 Waits until @thread finishes, i.e. the function @func, as given
-to g_thread_create, returns or g_thread_exit() is called by
+to g_thread_create(), returns or g_thread_exit() is called by
 @thread. All resources of @thread including the #GThread struct are
 released. @thread must have been created with @joinable=%TRUE in
 g_thread_create(). The value returned by @func or given to
@@ -375,7 +375,7 @@ g_thread_exit() by @thread is returned by this function.
 
 <!-- ##### FUNCTION g_thread_set_priority ##### -->
 <para>
-Change the priority of @thread to @priority.
+Changes the priority of @thread to @priority.
 </para>
 
 <note>
@@ -394,7 +394,7 @@ being dependent on priorities.
 
 <!-- ##### FUNCTION g_thread_yield ##### -->
 <para>
-Give way to other threads waiting to be scheduled. 
+Gives way to other threads waiting to be scheduled. 
 </para>
 
 <para>
@@ -407,7 +407,7 @@ to do that. So in general you shouldn't use that function.
 
 <!-- ##### FUNCTION g_thread_exit ##### -->
 <para>
-Exit the current thread. If another thread is waiting for that thread
+Exits the current thread. If another thread is waiting for that thread
 using g_thread_join() and the current thread is joinable, the waiting
 thread will be woken up and getting @retval as the return value of
 g_thread_join(). If the current thread is not joinable, @retval is
@@ -440,9 +440,8 @@ in the function @func, as given to g_thread_create().
 
 <note>
 <para>
-Never call g_thread_exit from within a thread of a #GThreadPool, as
+Never call g_thread_exit() from within a thread of a #GThreadPool, as
-that will mess up the bookkeeping and lead to funny and unwanted
+that will mess up the bookkeeping and lead to funny and unwanted results.
-results.
 </para>
 </note>
 
@@ -459,7 +458,7 @@ access. Take for example the following function:
 <example>
 <title>A function which will not work in a threaded environment</title>
 <programlisting>
-  int give_me_next_number ()
+  int give_me_next_number (<!>)
   {
     static int current_number = 0;
 
@@ -482,7 +481,7 @@ access. A first naive implementation would be:
 <example>
 <title>The wrong way to write a thread-safe function</title>
 <programlisting>
-  int give_me_next_number ()
+  int give_me_next_number (<!>)
   {
     static int current_number = 0;
     int ret_val;
@@ -513,13 +512,13 @@ not use such constructs in your own programs. One working solution is:
 
   /* this function must be called before any call to give_me_next_number ()
      it must be called exactly once. */
-  void init_give_me_next_number () 
+  void init_give_me_next_number (<!>) 
   {
     g_assert (give_me_next_number_mutex == NULL);
     give_me_next_number_mutex = g_mutex_new ();
   }
 
-  int give_me_next_number ()
+  int give_me_next_number (<!>)
   {
     static int current_number = 0;
     int ret_val;
@@ -650,14 +649,14 @@ Destroys @mutex.
 A #GStaticMutex works like a #GMutex, but it has one significant
 advantage. It doesn't need to be created at run-time like a #GMutex,
 but can be defined at compile-time. Here is a shorter, easier and
-safer version of our give_me_next_number() example:
+safer version of our <function>give_me_next_number()</function> example:
 </para>
 
 <para>
 <example>
-<title>Using GStaticMutex to simplify thread-safe programming</title>
+<title>Using <structname>GStaticMutex</structname> to simplify thread-safe programming</title>
 <programlisting>
-  int give_me_next_number ()
+  int give_me_next_number (<!>)
   {
     static int current_number = 0;
     int ret_val;
@@ -802,11 +801,11 @@ variable you intent to protect with the lock. Look at our
 
 <para>
 <example>
-<title>Using the G_LOCK_* convenience macros</title>
+<title>Using the %G_LOCK_* convenience macros</title>
 <programlisting>
 G_LOCK_DEFINE (current_number);
 
-int give_me_next_number ()
+int give_me_next_number (<!>)
   {
     static int current_number = 0;
     int ret_val;

docs/reference/glib/tmpl/timers.sgml

@@ -3,7 +3,7 @@ Timers
 
 <!-- ##### SECTION Short_Description ##### -->
 
-Keep track of elapsed time.
+keep track of elapsed time.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/trees-binary.sgml

@@ -2,13 +2,13 @@
 Balanced Binary Trees
 
 <!-- ##### SECTION Short_Description ##### -->
-a sorted collection of key/value pairs optimised for searching
+a sorted collection of key/value pairs optimized for searching
 and traversing in order.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
 The #GTree structure and its associated functions provide a sorted collection
-of key/value pairs optimised for searching and traversing in order.
+of key/value pairs optimized for searching and traversing in order.
 </para>
 <para>
 To create a new #GTree use g_tree_new().
@@ -42,7 +42,7 @@ To destroy a #GTree, use g_tree_destroy().
 
 <!-- ##### STRUCT GTree ##### -->
 <para>
-The #GTree struct is an opaque data structure representing a
+The <structname>GTree</structname> struct is an opaque data structure representing a
 <link linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>.
 It should be accessed only by using the following functions.
 </para>

docs/reference/glib/tmpl/trees-nary.sgml

@@ -51,16 +51,16 @@ g_node_destroy().
 
 <!-- ##### STRUCT GNode ##### -->
 <para>
-The #GNode struct represents one node in a
+The <structname>GNode</structname> struct represents one node in a
 <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
 The <structfield>data</structfield> field contains the actual data of the node.
 The <structfield>next</structfield> and <structfield>prev</structfield>
-fields point to the node's siblings (a sibling is another #GNode with the
+fields point to the node's siblings (a sibling is another <structname>GNode</structname> with the
 same parent).
-The <structfield>parent</structfield> field points to the parent of the #GNode,
+The <structfield>parent</structfield> field points to the parent of the <structname>GNode</structname>,
-or is %NULL if the #GNode is the root of the tree.
+or is %NULL if the <structname>GNode</structname> is the root of the tree.
 The <structfield>children</structfield> field points to the first child of the
-#GNode. The other children are accessed by using the
+<structname>GNode</structname>. The other children are accessed by using the
 <structfield>next</structfield> pointer of each child.
 </para>
 

docs/reference/glib/tmpl/type_conversion.sgml

@@ -3,7 +3,7 @@ Type Conversion Macros
 
 <!-- ##### SECTION Short_Description ##### -->
 
-Portably storing integers in pointer variables.
+portably storing integers in pointer variables.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -11,10 +11,10 @@ Many times GLib, GTK+, and other libraries allow you to pass "user
 data" to a callback, in the form of a void pointer. From time to time
 you want to pass an integer instead of a pointer. You could allocate
 an integer, with something like:
-<programlisting>
+<informalexample><programlisting>
  int *ip = g_new (int, 1);
  *ip = 42;
-</programlisting>
+</programlisting></informalexample>
 But this is inconvenient, and it's annoying to have to free the 
 memory at some later time.
 </para>
@@ -22,20 +22,20 @@ memory at some later time.
 Pointers are always at least 32 bits in size (on all platforms GLib
 intends to support). Thus you can store at least 32-bit integer values
 in a pointer value. Naively, you might try this, but it's incorrect:
-<programlisting>
+<informalexample><programlisting>
  gpointer p;
  int i;
  p = (void*) 42;
  i = (int) p;
-</programlisting>
+</programlisting></informalexample>
 Again, that example was <emphasis>not</emphasis> correct, don't copy it. 
 The problem is that on some systems you need to do this:
-<programlisting>
+<informalexample><programlisting>
  gpointer p;
  int i;
  p = (void*) (long) 42;
  i = (int) (long) p;
-</programlisting>
+</programlisting></informalexample>
 So GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. do the right thing
 on the current platform.
 </para>

docs/reference/glib/tmpl/unicode.sgml

@@ -346,7 +346,7 @@ See <ulink url="http://www.unicode.org/unicode/reports/tr14/"
 <!-- ##### MACRO g_utf8_next_char ##### -->
 <para>
 Skips to the next character in a UTF-8 string. The string must be
-valid; this macro is as fast as possible, and has zero error-checking.
+valid; this macro is as fast as possible, and has no error-checking.
 You would use this macro to iterate over a string character by
 character. The macro returns the start of the next UTF-8 character.
 Before using this macro, use g_utf8_validate() to validate strings
@@ -527,7 +527,7 @@ that may contain invalid UTF-8.
 
 <!-- ##### ENUM GNormalizeMode ##### -->
 <para>
-A #GNormalizeMode defines how a Unicode string is transformed in a canonical 
+Defines how a Unicode string is transformed in a canonical 
 form, standardizing such issues as whether a character with an accent is 
 represented as a base character and combining accent or as a single precomposed
 character. Unicode strings should generally be normalized before comparing them.

docs/reference/glib/tmpl/warnings.sgml

@@ -37,7 +37,7 @@ documentation.
 Sets the print handler.
 Any messages passed to g_print() will be output via the new handler.
 The default handler simply outputs the message to stdout.
-By providing your own handler you can redirect the output, to a GTK
+By providing your own handler you can redirect the output, to a GTK+
 widget or a log file for example.
 </para>
 
@@ -74,7 +74,7 @@ documentation.
 Sets the handler for printing error messages.
 Any messages passed to g_printerr() will be output via the new handler.
 The default handler simply outputs the message to stderr.
-By providing your own handler you can redirect the output, to a GTK
+By providing your own handler you can redirect the output, to a GTK+
 widget or a log file for example.
 </para>
 
@@ -172,7 +172,7 @@ The prompt is then shown again.
 If [P]roceed is selected, the function returns.
 </para>
 <para>
-This function may cause different actions on non-unix platforms.
+This function may cause different actions on non-Unix platforms.
 </para>
 
 @prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
@@ -186,7 +186,7 @@ Invokes <command>gdb</command>, which attaches to the current process and shows
 Called by g_on_error_query() when the [S]tack trace option is selected.
 </para>
 <para>
-This function may cause different actions on non-unix platforms.
+This function may cause different actions on non-Unix platforms.
 </para>
 
 @prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.

docs/reference/glib/tmpl/windows.sgml

@@ -2,7 +2,7 @@
 Windows Compatibility Functions
 
 <!-- ##### SECTION Short_Description ##### -->
-Unix emulation on Windows
+Unix emulation on Windows.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -16,7 +16,7 @@ Unix emulation on Windows
 
 <!-- ##### MACRO MAXPATHLEN ##### -->
 <para>
-Provided for UNIX emulation on Windows; equivalent to UNIX 
+Provided for Unix emulation on Windows; equivalent to Unix 
 macro %MAXPATHLEN, which is the maximum length of a filename
 (including full path).
 </para>
@@ -25,14 +25,14 @@ macro %MAXPATHLEN, which is the maximum length of a filename
 
 <!-- ##### TYPEDEF pid_t ##### -->
 <para>
-Provided for UNIX emulation on Windows; process ID type.
+Provided for Unix emulation on Windows; process ID type.
 </para>
 
 
 <!-- ##### MACRO pipe ##### -->
 <para>
-Provided for UNIX emulation on Windows; see documentation for <function>pipe()</function>
+Provided for Unix emulation on Windows; see documentation for <function>pipe()</function>
-in any UNIX manual.
+in any Unix manual.
 </para>
 
 @phandles: 
@@ -40,8 +40,8 @@ in any UNIX manual.
 
 <!-- ##### MACRO ftruncate ##### -->
 <para>
-Provided for UNIX emulation on Windows; see documentation for <function>ftruncate()</function>
+Provided for Unix emulation on Windows; see documentation for <function>ftruncate()</function>
-in any UNIX manual.
+in any Unix manual.
 </para>
 
 @fd: 

glib/gconvert.c

@@ -93,11 +93,11 @@ extern const char **_g_charset_get_aliases (const char *canonical_name);
  * @to_codeset: destination codeset
  * @from_codeset: source codeset
  * 
- * Same as the standard UNIX routine iconv_open(), but
+ * Same as the standard Unix routine <function>iconv_open()</function>, but
- * may be implemented via libiconv on UNIX flavors that lack
+ * may be implemented via libiconv on Unix flavors that lack
  * a native implementation.
  * 
- * GLib provides g_convert() and g_locale_to_utf8() which are likely
+ * &GLib; provides g_convert() and g_locale_to_utf8() which are likely
  * more convenient than the raw iconv wrappers.
  * 
  * Return value: a "conversion descriptor"
@@ -143,11 +143,11 @@ g_iconv_open (const gchar  *to_codeset,
  * @outbuf: converted output bytes
  * @outbytes_left: inout parameter, bytes available to fill in @outbuf
  * 
- * Same as the standard UNIX routine iconv(), but
+ * Same as the standard Unix routine <function>iconv()</function>, but
- * may be implemented via libiconv on UNIX flavors that lack
+ * may be implemented via libiconv on Unix flavors that lack
  * a native implementation.
  *
- * GLib provides g_convert() and g_locale_to_utf8() which are likely
+ * &GLib; provides g_convert() and g_locale_to_utf8() which are likely
  * more convenient than the raw iconv wrappers.
  * 
  * Return value: count of non-reversible conversions, or -1 on error
@@ -168,13 +168,13 @@ g_iconv (GIConv   converter,
  * g_iconv_close:
  * @converter: a conversion descriptor from g_iconv_open()
  *
- * Same as the standard UNIX routine iconv_close(), but
+ * Same as the standard Unix routine <function>iconv_close()</function>, but
- * may be implemented via libiconv on UNIX flavors that lack
+ * may be implemented via libiconv on Unix flavors that lack
  * a native implementation. Should be called to clean up
- * the conversion descriptor from iconv_open() when
+ * the conversion descriptor from g_iconv_open() when
  * you are done converting things.
  *
- * GLib provides g_convert() and g_locale_to_utf8() which are likely
+ * &GLib; provides g_convert() and g_locale_to_utf8() which are likely
  * more convenient than the raw iconv wrappers.
  * 
  * Return value: -1 on error, 0 on success
@@ -226,11 +226,11 @@ open_converter (const gchar *to_codeset,
  *                 stored will the byte offset after the last valid
  *                 input sequence.
  * @bytes_written: the number of bytes stored in the output buffer (not 
- *                 including the terminating NULL).
+ *                 including the terminating nul).
  * @error:         location to store the error occuring, or %NULL to ignore
  *                 errors. Any of the errors in #GConvertError may occur.
  *
- * Convert a string from one character set to another.
+ * Converts a string from one character set to another.
  *
  * Return value: If the conversion was successful, a newly allocated
  *               nul-terminated string, which must be freed with
@@ -281,18 +281,18 @@ g_convert (const gchar *str,
  * @converter:     conversion descriptor from g_iconv_open()
  * @bytes_read:    location to store the number of bytes in the
  *                 input string that were successfully converted, or %NULL.
- *                 Even if the conversion was succesful, this may be 
+ *                 Even if the conversion was successful, this may be 
  *                 less than @len if there were partial characters
  *                 at the end of the input. If the error
  *                 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
  *                 stored will the byte offset after the last valid
  *                 input sequence.
  * @bytes_written: the number of bytes stored in the output buffer (not 
- *                 including the terminating NULL).
+ *                 including the terminating nul).
  * @error:         location to store the error occuring, or %NULL to ignore
  *                 errors. Any of the errors in #GConvertError may occur.
  *
- * Convert a string from one character set to another.
+ * Converts a string from one character set to another.
  *
  * Return value: If the conversion was successful, a newly allocated
  *               nul-terminated string, which must be freed with
@@ -407,21 +407,21 @@ g_convert_with_iconv (const gchar *str,
  *                as Unicode escapes \x{XXXX} or \x{XXXXXX}.
  * @bytes_read:   location to store the number of bytes in the
  *                input string that were successfully converted, or %NULL.
- *                Even if the conversion was succesful, this may be 
+ *                Even if the conversion was successful, this may be 
  *                less than @len if there were partial characters
  *                at the end of the input.
  * @bytes_written: the number of bytes stored in the output buffer (not 
- *                including the terminating NULL).
+ *                including the terminating nul).
  * @error:        location to store the error occuring, or %NULL to ignore
  *                errors. Any of the errors in #GConvertError may occur.
  *
- * Convert a string from one character set to another, possibly
+ * Converts a string from one character set to another, possibly
  * including fallback sequences for characters not representable
  * in the output. Note that it is not guaranteed that the specification
  * for the fallback sequences in @fallback will be honored. Some
  * systems may do a approximate conversion from @from_codeset
- * to @to_codeset in their iconv() functions, in which case GLib
+ * to @to_codeset in their <function>iconv()</function> functions, 
- * will simply return that approximate conversion.
+ * in which case &GLib; will simply return that approximate conversion.
  *
  * Return value: If the conversion was successful, a newly allocated
  *               nul-terminated string, which must be freed with
@@ -665,14 +665,14 @@ strdup_len (const gchar *string,
  *                 nul-terminated.
  * @bytes_read:    location to store the number of bytes in the
  *                 input string that were successfully converted, or %NULL.
- *                 Even if the conversion was succesful, this may be 
+ *                 Even if the conversion was successful, this may be 
  *                 less than @len if there were partial characters
  *                 at the end of the input. If the error
  *                 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
  *                 stored will the byte offset after the last valid
  *                 input sequence.
  * @bytes_written: the number of bytes stored in the output buffer (not 
- *                 including the terminating NULL).
+ *                 including the terminating nul).
  * @error:         location to store the error occuring, or %NULL to ignore
  *                 errors. Any of the errors in #GConvertError may occur.
  * 
@@ -805,14 +805,14 @@ g_locale_to_utf8 (const gchar  *opsysstring,
  *                 nul-terminated.
  * @bytes_read:    location to store the number of bytes in the
  *                 input string that were successfully converted, or %NULL.
- *                 Even if the conversion was succesful, this may be 
+ *                 Even if the conversion was successful, this may be 
  *                 less than @len if there were partial characters
  *                 at the end of the input. If the error
  *                 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
  *                 stored will the byte offset after the last valid
  *                 input sequence.
  * @bytes_written: the number of bytes stored in the output buffer (not 
- *                 including the terminating NULL).
+ *                 including the terminating nul).
  * @error:         location to store the error occuring, or %NULL to ignore
  *                 errors. Any of the errors in #GConvertError may occur.
  * 
@@ -951,14 +951,14 @@ g_locale_from_utf8 (const gchar *utf8string,
  *                 nul-terminated.
  * @bytes_read:    location to store the number of bytes in the
  *                 input string that were successfully converted, or %NULL.
- *                 Even if the conversion was succesful, this may be 
+ *                 Even if the conversion was successful, this may be 
  *                 less than @len if there were partial characters
  *                 at the end of the input. If the error
  *                 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
  *                 stored will the byte offset after the last valid
  *                 input sequence.
  * @bytes_written: the number of bytes stored in the output buffer (not 
- *                 including the terminating NULL).
+ *                 including the terminating nul).
  * @error:         location to store the error occuring, or %NULL to ignore
  *                 errors. Any of the errors in #GConvertError may occur.
  * 
@@ -996,14 +996,14 @@ g_filename_to_utf8 (const gchar *opsysstring,
  *                 nul-terminated.
  * @bytes_read:    location to store the number of bytes in the
  *                 input string that were successfully converted, or %NULL.
- *                 Even if the conversion was succesful, this may be 
+ *                 Even if the conversion was successful, this may be 
  *                 less than @len if there were partial characters
  *                 at the end of the input. If the error
  *                 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
  *                 stored will the byte offset after the last valid
  *                 input sequence.
  * @bytes_written: the number of bytes stored in the output buffer (not 
- *                 including the terminating NULL).
+ *                 including the terminating nul).
  * @error:         location to store the error occuring, or %NULL to ignore
  *                 errors. Any of the errors in #GConvertError may occur.
  * 
@@ -1237,7 +1237,7 @@ g_unescape_uri_string (const gchar *escaped,
  * Converts an escaped UTF-8 encoded URI to a local filename in the
  * encoding used for filenames. 
  * 
- * Return value: a newly allocated string holding the resulting
+ * Return value: a newly-allocated string holding the resulting
  *               filename, or %NULL on an error.
  **/
 gchar *
@@ -1337,7 +1337,7 @@ g_filename_from_uri (const char *uri,
  * 
  * Converts an absolute filename to an escaped UTF-8 encoded URI.
  * 
- * Return value: a newly allocated string holding the resulting
+ * Return value: a newly-allocated string holding the resulting
  *               URI, or %NULL on an error.
  **/
 gchar *

glib/ghash.c

@@ -241,7 +241,7 @@ g_hash_table_lookup (GHashTable	  *hash_table,
  * is useful if you need to free the memory allocated for the original key, 
  * for example before calling g_hash_table_remove().
  * 
- * Return value: #TRUE if the key was found in the #GHashTable.
+ * Return value: %TRUE if the key was found in the #GHashTable.
  **/
 gboolean
 g_hash_table_lookup_extended (GHashTable    *hash_table,
@@ -371,7 +371,7 @@ g_hash_table_replace (GHashTable *hash_table,
  * you have to make sure that any dynamically allocated values are freed 
  * yourself.
  * 
- * Return value: #TRUE if the key was found and removed from the #GHashTable.
+ * Return value: %TRUE if the key was found and removed from the #GHashTable.
  **/
 gboolean
 g_hash_table_remove (GHashTable	   *hash_table,
@@ -407,7 +407,7 @@ g_hash_table_remove (GHashTable	   *hash_table,
  * Removes a key and its associated value from a #GHashTable without
  * calling the key and value destroy functions.
  *
- * Return value: #TRUE if the key was found and removed from the #GHashTable.
+ * Return value: %TRUE if the key was found and removed from the #GHashTable.
  **/
 gboolean
 g_hash_table_steal (GHashTable    *hash_table,

glib/grand.c

@@ -84,8 +84,8 @@ g_rand_new_with_seed (guint32 seed)
  * g_rand_new:
  * 
  * Creates a new random number generator initialized with a seed taken
- * either from /dev/urandom (if existing) or from the current time (as
+ * either from <filename>/dev/urandom</filename> (if existing) or from 
- * a fallback).
+ * the current time (as a fallback).
  * 
  * Return value: the new #GRand.
  **/
@@ -165,7 +165,7 @@ g_rand_set_seed (GRand* rand, guint32 seed)
  * g_rand_int:
  * @rand: a #GRand.
  *
- * Return the next random #guint32 from @rand equaly distributed over
+ * Returns the next random #guint32 from @rand equally distributed over
  * the range [0..2^32-1].
  *
  * Return value: A random number.
@@ -214,7 +214,7 @@ g_rand_int (GRand* rand)
  * @begin: lower closed bound of the interval.
  * @end: upper open bound of the interval.
  *
- * Return the next random #gint32 from @rand equaly distributed over
+ * Returns the next random #gint32 from @rand equally distributed over
  * the range [@begin..@end-1].
  *
  * Return value: A random number.
@@ -264,7 +264,7 @@ g_rand_int_range (GRand* rand, gint32 begin, gint32 end)
  * g_rand_double:
  * @rand: a #GRand.
  *
- * Return the next random #gdouble from @rand equaly distributed over
+ * Returns the next random #gdouble from @rand equally distributed over
  * the range [0..1).
  *
  * Return value: A random number.
@@ -291,7 +291,7 @@ g_rand_double (GRand* rand)
  * @begin: lower closed bound of the interval.
  * @end: upper open bound of the interval.
  *
- * Return the next random #gdouble from @rand equaly distributed over
+ * Returns the next random #gdouble from @rand equally distributed over
  * the range [@begin..@end).
  *
  * Return value: A random number.
@@ -305,7 +305,7 @@ g_rand_double_range (GRand* rand, gdouble begin, gdouble end)
 /**
  * g_random_int:
  *
- * Return a random #guint32 equaly distributed over the range
+ * Return a random #guint32 equally distributed over the range
  * [0..2^32-1].
  *
  * Return value: A random number.
@@ -328,7 +328,7 @@ g_random_int (void)
  * @begin: lower closed bound of the interval.
  * @end: upper open bound of the interval.
  *
- * Return a random #gint32 equaly distributed over the range
+ * Returns a random #gint32 equally distributed over the range
  * [@begin..@end-1].
  *
  * Return value: A random number.
@@ -349,7 +349,7 @@ g_random_int_range (gint32 begin, gint32 end)
 /**
  * g_random_double:
  *
- * Return a random #gdouble equaly distributed over the range [0..1).
+ * Returns a random #gdouble equally distributed over the range [0..1).
  *
  * Return value: A random number.
  **/
@@ -371,7 +371,7 @@ g_random_double (void)
  * @begin: lower closed bound of the interval.
  * @end: upper open bound of the interval.
  *
- * Return a random #gdouble equaly distributed over the range [@begin..@end).
+ * Returns a random #gdouble equally distributed over the range [@begin..@end).
  *
  * Return value: A random number.
  **/
@@ -393,7 +393,7 @@ g_random_double_range (gdouble begin, gdouble end)
  * @seed: a value to reinitialize the global random number generator.
  * 
  * Sets the seed for the global random number generator, which is used
- * by te g_random_* functions, to @seed.
+ * by the <function>g_random_*</function> functions, to @seed.
  **/
 void
 g_random_set_seed (guint32 seed)

glib/gthreadpool.c

@@ -251,15 +251,15 @@ g_thread_pool_start_thread (GRealThreadPool  *pool,
  *
  * The parameter @exclusive determines, whether the thread pool owns
  * all threads exclusive or whether the threads are shared
- * globally. If @exclusive is @TRUE, @max_threads threads are started
+ * globally. If @exclusive is %TRUE, @max_threads threads are started
  * immediately and they will run exclusively for this thread pool until
- * it is destroyed by g_thread_pool_free(). If @exclusive is @FALSE,
+ * it is destroyed by g_thread_pool_free(). If @exclusive is %FALSE,
  * threads are created, when needed and shared between all
  * non-exclusive thread pools. This implies that @max_threads may not
  * be -1 for exclusive thread pools.
  *
- * @error can be NULL to ignore errors, or non-NULL to report
+ * @error can be %NULL to ignore errors, or non-%NULL to report
- * errors. An error can only occur, when @exclusive is set to @TRUE and
+ * errors. An error can only occur when @exclusive is set to %TRUE and
  * not all @max_threads threads could be created.
  *
  * Return value: the new #GThreadPool
@@ -334,8 +334,8 @@ g_thread_pool_new (GFunc            func,
  * in the queue until a thread in this pool finishes its previous task
  * and processes @data. 
  *
- * @error can be NULL to ignore errors, or non-NULL to report
+ * @error can be %NULL to ignore errors, or non-%NULL to report
- * errors. An error can only occur, when a new thread couldn't be
+ * errors. An error can only occur when a new thread couldn't be
  * created. In that case @data is simply appended to the queue of work
  * to do.  
  **/
@@ -379,12 +379,12 @@ g_thread_pool_push (GThreadPool     *pool,
  * 
  * A thread is never terminated while calling @func, as supplied by
  * g_thread_pool_new (). Instead the maximal number of threads only
- * has effect for the allocation of new threads in g_thread_pool_push
+ * has effect for the allocation of new threads in g_thread_pool_push(). 
- * (). A new thread is allocated, whenever the number of currently
+ * A new thread is allocated, whenever the number of currently
  * running threads in @pool is smaller than the maximal number.
  *
- * @error can be NULL to ignore errors, or non-NULL to report
+ * @error can be %NULL to ignore errors, or non-%NULL to report
- * errors. An error can only occur, when a new thread couldn't be
+ * errors. An error can only occur when a new thread couldn't be
  * created. 
  **/
 void
@@ -505,13 +505,13 @@ g_thread_pool_unprocessed (GThreadPool     *pool)
  *
  * Frees all resources allocated for @pool.
  *
- * If @immediate is #TRUE, no new task is processed for
+ * If @immediate is %TRUE, no new task is processed for
  * @pool. Otherwise @pool is not freed before the last task is
  * processed. Note however, that no thread of this pool is
  * interrupted, while processing a task. Instead at least all still
  * running threads can finish their tasks before the @pool is freed.
  *
- * If @wait is #TRUE, the functions does not return before all tasks
+ * If @wait is %TRUE, the functions does not return before all tasks
  * to be processed (dependent on @immediate, whether all or only the
  * currently running) are ready. Otherwise the function returns immediately.
  *

glib/gtree.c

@@ -278,7 +278,7 @@ g_tree_destroy (GTree *tree)
  * Inserts a key/value pair into a #GTree. If the given key already exists 
  * in the #GTree its corresponding value is set to the new value. If you 
  * supplied a value_destroy_func when creating the #GTree, the old value is 
- * freed using that function. If you supplied a key_destroy_func when 
+ * freed using that function. If you supplied a @key_destroy_func when 
  * creating the #GTree, the passed key is freed using that function.
  *
  * The tree is automatically 'balanced' as new key/value pairs are added,
@@ -308,9 +308,9 @@ g_tree_insert (GTree    *tree,
  * 
  * Inserts a new key and value into a #GTree similar to g_tree_insert(). 
  * The difference is that if the key already exists in the #GTree, it gets 
- * replaced by the new key. If you supplied a value_destroy_func when 
+ * replaced by the new key. If you supplied a @value_destroy_func when 
  * creating the #GTree, the old value is freed using that function. If you 
- * supplied a key_destroy_func when creating the #GTree, the old key is 
+ * supplied a @key_destroy_func when creating the #GTree, the old key is 
  * freed using that function. 
  *
  * The tree is automatically 'balanced' as new key/value pairs are added,
@@ -340,7 +340,7 @@ g_tree_replace (GTree    *tree,
  * Removes a key/value pair from a #GTree.
  *
  * If the #GTree was created using g_tree_new_full(), the key and value 
- * are freed using the supplied destroy_functions, otherwise you have to 
+ * are freed using the supplied @destroy_functions, otherwise you have to 
  * make sure that any dynamically allocated values are freed yourself.
  **/
 void
@@ -402,11 +402,11 @@ g_tree_lookup (GTree         *tree,
  * @value: returns the value associated with the key.
  * 
  * Looks up a key in the #GTree, returning the original key and the
- * associated value and a gboolean which is TRUE if the key was found. This 
+ * associated value and a #gboolean which is %TRUE if the key was found. This 
  * is useful if you need to free the memory allocated for the original key, 
  * for example before calling g_tree_remove().
  * 
- * Return value: #TRUE if the key was found in the #GTree.
+ * Return value: %TRUE if the key was found in the #GTree.
  **/
 gboolean
 g_tree_lookup_extended (GTree         *tree,
@@ -527,7 +527,7 @@ g_tree_traverse (GTree         *tree,
  * To search for a specific value, you can use g_tree_foreach() or 
  * g_tree_traverse().
  *
- * Return value: the value corresponding to the found key, or NULL if the key 
+ * Return value: the value corresponding to the found key, or %NULL if the key 
  * is not found.
  **/
 gpointer