updated.

2000-04-16  Damon Chaplin  <damon@helixcode.com>

        * tmpl/linked_lists_single.sgml:
        * tmpl/linked_lists_double.sgml:
        * tmpl/trees-nary.sgml: updated.

        * tmpl/modules.sgml: described g_module_build_path().

        * tmpl/date.sgml: made short description lower case and end in a '.'.

        * glib-sections.txt: rearranged GDate section.

        * tmpl/arrays.sgml:
        * tmpl/arrays_byte.sgml:
        * tmpl/arrays_pointer.sgml: updated.

11 files changed, 222 insertions, 126 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index fe546374d..2cf0ed214 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,19 @@
+2000-04-16  Damon Chaplin  <damon@helixcode.com>
+
+	* tmpl/linked_lists_single.sgml: 
+	* tmpl/linked_lists_double.sgml: 
+	* tmpl/trees-nary.sgml: updated.
+
+	* tmpl/modules.sgml: described g_module_build_path().
+
+	* tmpl/date.sgml: made short description lower case and end in a '.'.
+
+	* glib-sections.txt: rearranged GDate section.
+
+	* tmpl/arrays.sgml: 
+	* tmpl/arrays_byte.sgml: 
+	* tmpl/arrays_pointer.sgml: updated.
+
 2000-02-21  Damon Chaplin  <damon@helixcode.com>
 
 	* tmpl/main.sgml: updated the g_source_remove_by_XXX() descriptions
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 63b1bcdbd..e48890e01 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -569,58 +569,74 @@ GTimeVal
 g_get_current_time
 
 <SUBSECTION>
-GTime
 GDate
+GTime
 GDateDMY
 GDateDay
 GDateMonth
-GDateWeekday
 GDateYear
+GDateWeekday
+
+<SUBSECTION>
 G_DATE_BAD_DAY
 G_DATE_BAD_JULIAN
 G_DATE_BAD_YEAR
+
+<SUBSECTION>
+g_date_new
+g_date_new_dmy
+g_date_new_julian
+g_date_clear
+g_date_free
+
+<SUBSECTION>
+g_date_set_day
+g_date_set_month
+g_date_set_year
+g_date_set_dmy
+g_date_set_julian
+g_date_set_time
+g_date_set_parse
+
+<SUBSECTION>
 g_date_add_days
+g_date_subtract_days
 g_date_add_months
+g_date_subtract_months
 g_date_add_years
-g_date_clear
+g_date_subtract_years
 g_date_compare
+
+<SUBSECTION>
 g_date_day
+g_date_month
+g_date_year
+g_date_julian
+g_date_weekday
 g_date_day_of_year
+
+<SUBSECTION>
 g_date_days_in_month
-g_date_free
 g_date_is_first_of_month
 g_date_is_last_of_month
 g_date_is_leap_year
-g_date_julian
 g_date_monday_week_of_year
 g_date_monday_weeks_in_year
-g_date_month
-g_date_new
-g_date_new_dmy
-g_date_new_julian
-g_date_set_day
-g_date_set_dmy
-g_date_set_julian
-g_date_set_month
-g_date_set_parse
-g_date_set_time
-g_date_set_year
-g_date_strftime
-g_date_subtract_days
-g_date_subtract_months
-g_date_subtract_years
 g_date_sunday_week_of_year
 g_date_sunday_weeks_in_year
+
+<SUBSECTION>
+g_date_strftime
 g_date_to_struct_tm
+
+<SUBSECTION>
 g_date_valid
 g_date_valid_day
+g_date_valid_month
+g_date_valid_year
 g_date_valid_dmy
 g_date_valid_julian
-g_date_valid_month
 g_date_valid_weekday
-g_date_valid_year
-g_date_weekday
-g_date_year
 </SECTION>
 
 <SECTION>
@@ -924,8 +940,8 @@ g_list_position
 g_list_index
 
 <SUBSECTION>
-g_list_pop_allocator
 g_list_push_allocator
+g_list_pop_allocator
 </SECTION>
 
 <SECTION>
@@ -965,8 +981,8 @@ g_slist_position
 g_slist_index
 
 <SUBSECTION>
-g_slist_pop_allocator
 g_slist_push_allocator
+g_slist_pop_allocator
 </SECTION>
 
 <SECTION>
@@ -1155,8 +1171,8 @@ g_node_unlink
 g_node_destroy
 
 <SUBSECTION>
-g_node_pop_allocator
 g_node_push_allocator
+g_node_pop_allocator
 </SECTION>
 
 
diff --git a/docs/reference/glib/glib/ChangeLog b/docs/reference/glib/glib/ChangeLog
index fe546374d..2cf0ed214 100644
--- a/docs/reference/glib/glib/ChangeLog
+++ b/docs/reference/glib/glib/ChangeLog
@@ -1,3 +1,19 @@
+2000-04-16  Damon Chaplin  <damon@helixcode.com>
+
+	* tmpl/linked_lists_single.sgml: 
+	* tmpl/linked_lists_double.sgml: 
+	* tmpl/trees-nary.sgml: updated.
+
+	* tmpl/modules.sgml: described g_module_build_path().
+
+	* tmpl/date.sgml: made short description lower case and end in a '.'.
+
+	* glib-sections.txt: rearranged GDate section.
+
+	* tmpl/arrays.sgml: 
+	* tmpl/arrays_byte.sgml: 
+	* tmpl/arrays_pointer.sgml: updated.
+
 2000-02-21  Damon Chaplin  <damon@helixcode.com>
 
 	* tmpl/main.sgml: updated the g_source_remove_by_XXX() descriptions
diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml
index d05a1de81..d985d4e3b 100644
--- a/docs/reference/glib/tmpl/arrays.sgml
+++ b/docs/reference/glib/tmpl/arrays.sgml
@@ -58,14 +58,11 @@ To free an array, use g_array_free().
 <!-- ##### STRUCT GArray ##### -->
 <para>
 Contains the public fields of an <link linkend="glib-arrays">Array</link>.
-The <structfield>data</structfield> field points to the element data.
-It may change as elements are added to the array.
-The <structfield>len</structfield> field contains the number of elements
-in the array.
 </para>
 
-@data: 
-@len: 
+@data: a pointer to the element data. The data may be moved as elements are
+added to the #GArray.
+@len: the number of elements in the #GArray.
 
 <!-- ##### FUNCTION g_array_new ##### -->
 <para>
@@ -148,51 +145,73 @@ in the array have to be moved to make space for the new elements.
 
 <!-- ##### MACRO g_array_insert_val ##### -->
 <para>
-
+Inserts an element into an array at the given index.
+</para>
+<note>
+<para>
+g_array_insert_val() is a macro which uses a reference to the value
+parameter @v. This means that you cannot use it with literal values
+such as "27". You must use variables.
 </para>
+</note>
 
-@a: 
-@i: 
-@v: 
+@a: a #GArray.
+@i: the index to place the element at.
+@v: the value to insert into the array.
+@Returns: the #GArray.
 
 
 <!-- ##### FUNCTION g_array_insert_vals ##### -->
 <para>
-
+Inserts @len elements into a #GArray at the given index.
 </para>
 
-@array: 
-@index: 
-@data: 
-@len: 
-@Returns: 
+@array: a #GArray.
+@index: the index to place the elements at.
+@data: a pointer to the elements to insert.
+@len: the number of elements to insert.
+@Returns: the #GArray.
 
 
 <!-- ##### FUNCTION g_array_remove_index ##### -->
 <para>
-
+Removes the element at the given index from a #GArray.
+The following elements are moved down one place.
 </para>
 
-@array: 
-@index: 
-@Returns: 
+@array: a #GArray.
+@index: the index of the element to remove.
+@Returns: the #GArray.
 
 
 <!-- ##### FUNCTION g_array_remove_index_fast ##### -->
 <para>
-
+Removes the element at the given index from a #GArray.
+The last element in the array is used to fill in the space, so this function
+does not preserve the order of the #GArray. But it is faster than
+g_array_remove_index().
 </para>
 
-@array: 
-@index: 
-@Returns: 
+@array: a @GArray.
+@index: the index of the element to remove.
+@Returns: the #GArray.
 
 
 <!-- ##### MACRO g_array_index ##### -->
 <para>
 Returns the element of a #GArray at the given index.
 The return value is cast to the given type.
-FIXME: need more info on how it works with structures.
+
+<example>
+<title>Getting a pointer to an element in a GArray.</title>
+<programlisting>
+  EDayViewEvent *event;
+
+  /* This gets a pointer to the 3rd element in the array of EDayViewEvent
+     structs. */
+  event = &amp;g_array_index (events, EDayViewEvent, 3);
+</programlisting>
+</example>
 </para>
 
 @a: a #GArray.
diff --git a/docs/reference/glib/tmpl/arrays_byte.sgml b/docs/reference/glib/tmpl/arrays_byte.sgml
index cba774b85..17c1a8d96 100644
--- a/docs/reference/glib/tmpl/arrays_byte.sgml
+++ b/docs/reference/glib/tmpl/arrays_byte.sgml
@@ -51,15 +51,12 @@ 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 <structfield>data</structfield> field points to the element data.
-It may change as elements are added to the array.
-The <structfield>len</structfield> field contains the number of elements
-in the array.
+The #GByteArray struct allows access to the public fields of a #GByteArray.
 </para>
 
-@data: 
-@len: 
+@data: a pointer to the element data. The data may be moved as elements are
+added to the #GByteArray.
+@len: the number of elements in the #GByteArray.
 
 <!-- ##### FUNCTION g_byte_array_new ##### -->
 <para>
@@ -95,22 +92,26 @@ The array will grow in size automatically if necessary.
 
 <!-- ##### FUNCTION g_byte_array_remove_index ##### -->
 <para>
-
+Removes the byte at the given index from a #GByteArray.
+The following bytes are moved down one place.
 </para>
 
-@array: 
-@index: 
-@Returns: 
+@array: a #GByteArray.
+@index: the index of the byte to remove.
+@Returns: the #GByteArray.
 
 
 <!-- ##### FUNCTION g_byte_array_remove_index_fast ##### -->
 <para>
-
+Removes the byte at the given index from a #GByteArray.
+The last element in the array is used to fill in the space, so this function
+does not preserve the order of the #GByteArray. But it is faster than
+g_byte_array_remove_index().
 </para>
 
-@array: 
-@index: 
-@Returns: 
+@array: a #GByteArray.
+@index: the index of the byte to remove.
+@Returns: the #GByteArray.
 
 
 <!-- ##### FUNCTION g_byte_array_set_size ##### -->
diff --git a/docs/reference/glib/tmpl/arrays_pointer.sgml b/docs/reference/glib/tmpl/arrays_pointer.sgml
index 59e1b44b2..cc8595c80 100644
--- a/docs/reference/glib/tmpl/arrays_pointer.sgml
+++ b/docs/reference/glib/tmpl/arrays_pointer.sgml
@@ -25,8 +25,8 @@ To create a pointer array, use g_ptr_array_new().
 To add elements to a pointer array, use g_ptr_array_add().
 </para>
 <para>
-To remove elements from a pointer array, use g_ptr_array_remove(), and
-g_ptr_array_remove_index().
+To remove elements from a pointer array, use g_ptr_array_remove(),
+g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
 </para>
 <para>
 To access an element of a pointer array, use g_ptr_array_index().
@@ -92,19 +92,13 @@ The array will grow in size automatically if necessary.
 
 <!-- ##### FUNCTION g_ptr_array_remove ##### -->
 <para>
-Removes the first occurrence of given pointer from the pointer array.
-It returns TRUE if the pointer was removed, or FALSE if the pointer
-was not found.
+Removes the first occurrence of the given pointer from the pointer array.
+The following elements are moved down one place.
 </para>
-<note>
 <para>
-If you remove elements from the array, elements at the end of the array
-are moved into the space previously occupied by the removed element.
-This means that you should not rely on the index of particular elements
-remaining the same. You should also be careful when deleting elements while
-iterating over the array.
+It returns TRUE if the pointer was removed, or FALSE if the pointer
+was not found.
 </para>
-</note>
 
 @array: a #GPtrArray.
 @data: the pointer to remove.
@@ -115,16 +109,8 @@ in the array.
 <!-- ##### FUNCTION g_ptr_array_remove_index ##### -->
 <para>
 Removes the pointer at the given index from the pointer array.
+The following elements are moved down one place.
 </para>
-<note>
-<para>
-If you remove elements from the array, elements at the end of the array
-are moved into the space previously occupied by the removed element.
-This means that you should not rely on the index of particular elements
-remaining the same. You should also be careful when deleting elements while
-iterating over the array.
-</para>
-</note>
 
 @array: a #GPtrArray.
 @index: the index of the pointer to remove.
@@ -133,22 +119,32 @@ iterating over the array.
 
 <!-- ##### FUNCTION g_ptr_array_remove_fast ##### -->
 <para>
-
+Removes the first occurrence of the given pointer from the pointer array.
+The last element in the array is used to fill in the space, so this function
+does not preserve the order of the array. But it is faster than
+g_ptr_array_remove().
+</para>
+<para>
+It returns TRUE if the pointer was removed, or FALSE if the pointer
+was not found.
 </para>
 
-@array: 
-@data: 
-@Returns: 
+@array: a #GPtrArray.
+@data: the pointer to remove.
+@Returns: TRUE if the pointer was found in the array.
 
 
 <!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### -->
 <para>
-
+Removes the pointer at the given index from the pointer array.
+The last element in the array is used to fill in the space, so this function
+does not preserve the order of the array. But it is faster than
+g_ptr_array_remove_index().
 </para>
 
-@array: 
-@index: 
-@Returns: 
+@array: a #GPtrArray.
+@index: the index of the pointer to remove.
+@Returns: the pointer which was removed.
 
 
 <!-- ##### FUNCTION g_ptr_array_set_size ##### -->
diff --git a/docs/reference/glib/tmpl/date.sgml b/docs/reference/glib/tmpl/date.sgml
index 7350193b3..cfced74dc 100644
--- a/docs/reference/glib/tmpl/date.sgml
+++ b/docs/reference/glib/tmpl/date.sgml
@@ -2,8 +2,7 @@
 Date and Time Functions

 

 <!-- ##### SECTION Short_Description ##### -->

-

-Calendrical Calculations and Miscellaneous Time Stuff

+calendrical calculations and miscellaneous time stuff.

 

 <!-- ##### SECTION Long_Description ##### -->

 <para>

diff --git a/docs/reference/glib/tmpl/linked_lists_double.sgml b/docs/reference/glib/tmpl/linked_lists_double.sgml
index 7add0adbd..995379c8c 100644
--- a/docs/reference/glib/tmpl/linked_lists_double.sgml
+++ b/docs/reference/glib/tmpl/linked_lists_double.sgml
@@ -224,11 +224,15 @@ Gets the number of elements in a #GList.
 
 <!-- ##### FUNCTION g_list_copy ##### -->
 <para>
-
+Copies a #GList.
+</para>
+<para>
+Note that this is a "shallow" copy. If the list elements consist of pointers
+to data, the pointers are copied but the actual data isn't.
 </para>
 
-@list: 
-@Returns: 
+@list: a #GList.
+@Returns: a copy of @list.
 
 
 <!-- ##### FUNCTION g_list_reverse ##### -->
@@ -243,12 +247,15 @@ It simply switches the next and prev pointers of each element.
 
 <!-- ##### FUNCTION g_list_sort ##### -->
 <para>
-
+Sorts a #GList using the given comparison function.
 </para>
 
-@list: 
-@compare_func: 
-@Returns: 
+@list: a #GList.
+@compare_func: the comparison function used to sort the #GList. This function
+is passed 2 elements of the #GList and should return 0 if they are equal,
+a negative value if the first element comes before the second, or a positive
+value if the first element comes after the second.
+@Returns: the start of the sorted #GList.
 
 
 <!-- ##### FUNCTION g_list_concat ##### -->
@@ -392,16 +399,17 @@ is not found.
 
 <!-- ##### FUNCTION g_list_pop_allocator ##### -->
 <para>
-
+Restores the previous #GAllocator, used when allocating #GList elements.
 </para>
 
 
 
 <!-- ##### FUNCTION g_list_push_allocator ##### -->
 <para>
-
+Sets the allocator to use to allocate #GList elements.
+Use g_list_pop_allocator() to restore the previous allocator.
 </para>
 
-@allocator: 
+@allocator: the #GAllocator to use when allocating #GList elements.
 
 
diff --git a/docs/reference/glib/tmpl/linked_lists_single.sgml b/docs/reference/glib/tmpl/linked_lists_single.sgml
index 95dc4df99..61f9bb9e4 100644
--- a/docs/reference/glib/tmpl/linked_lists_single.sgml
+++ b/docs/reference/glib/tmpl/linked_lists_single.sgml
@@ -217,11 +217,15 @@ Gets the number of elements in a #GSList.
 
 <!-- ##### FUNCTION g_slist_copy ##### -->
 <para>
-
+Copies a #GSList.
+</para>
+<para>
+Note that this is a "shallow" copy. If the list elements consist of pointers
+to data, the pointers are copied but the actual data isn't.
 </para>
 
-@list: 
-@Returns: 
+@list: a #GSList.
+@Returns: a copy of @list.
 
 
 <!-- ##### FUNCTION g_slist_reverse ##### -->
@@ -235,12 +239,15 @@ Reverses a #GSList.
 
 <!-- ##### FUNCTION g_slist_sort ##### -->
 <para>
-
+Sorts a #GSList using the given comparison function.
 </para>
 
-@list: 
-@compare_func: 
-@Returns: 
+@list: a #GSList.
+@compare_func: the comparison function used to sort the #GSList. This function
+is passed 2 elements of the #GSList and should return 0 if they are equal,
+a negative value if the first element comes before the second, or a positive
+value if the first element comes after the second.
+@Returns: the start of the sorted #GList.
 
 
 <!-- ##### FUNCTION g_slist_concat ##### -->
@@ -356,16 +363,16 @@ is not found.
 
 <!-- ##### FUNCTION g_slist_pop_allocator ##### -->
 <para>
-
+Restores the previous #GAllocator, used when allocating #GSList elements.
 </para>
 
 
-
 <!-- ##### FUNCTION g_slist_push_allocator ##### -->
 <para>
-
+Sets the allocator to use to allocate #GSList elements.
+Use g_slist_pop_allocator() to restore the previous allocator.
 </para>
 
-@allocator: 
+@allocator: the #GAllocator to use when allocating #GSList elements.
 
 
diff --git a/docs/reference/glib/tmpl/modules.sgml b/docs/reference/glib/tmpl/modules.sgml
index 24c1a4ba9..f3d0ba83e 100644
--- a/docs/reference/glib/tmpl/modules.sgml
+++ b/docs/reference/glib/tmpl/modules.sgml
@@ -58,12 +58,29 @@ Checks if modules are supported on the current platform.
 
 <!-- ##### FUNCTION g_module_build_path ##### -->
 <para>
-
+A portable way to build the filename of a module. The platform-specific
+prefix and suffix are added to the filename, if needed, and the result is
+added to the directory, using the correct separator character.
+</para>
+<para>
+The directory should specify the directory where the module can be found.
+It can be NULL or an empty string to indicate that the module is in a standard
+operating-system specific directory, though this is not recommended since the
+wrong module may be found.
+</para>
+<para>
+For example, calling g_module_build_path() on a Linux system with a directory
+of "/lib" and a module_name of "mylibrary" will return "/lib/libmylibrary.so".
+On a Windows system, using "\Windows" as the directory it will return
+"\Windows\mylibrary.dll".
 </para>
 
-@directory: 
-@module_name: 
-@Returns: 
+@directory: the directory where the module is. This can be NULL or the empty
+string to indicate that the standard operating system-specific directories
+will be used, though that is not recommended.
+@module_name: the name of the module.
+@Returns: the complete path of the module, including the standard library
+prefix and suffix. This should be freed when no longer needed.
 
 
 <!-- ##### FUNCTION g_module_open ##### -->
diff --git a/docs/reference/glib/tmpl/trees-nary.sgml b/docs/reference/glib/tmpl/trees-nary.sgml
index d45683127..7a8aca2e8 100644
--- a/docs/reference/glib/tmpl/trees-nary.sgml
+++ b/docs/reference/glib/tmpl/trees-nary.sgml
@@ -478,16 +478,17 @@ allocated.
 
 <!-- ##### FUNCTION g_node_pop_allocator ##### -->
 <para>
-
+Restores the previous #GAllocator, used when allocating #GNode elements.
 </para>
 
 
 
 <!-- ##### FUNCTION g_node_push_allocator ##### -->
 <para>
-
+Sets the allocator to use to allocate #GNode elements.
+Use g_node_pop_allocator() to restore the previous allocator.
 </para>
 
-@allocator: 
+@allocator: the #GAllocator to use when allocating #GNode elements.