Documented some functions, markup fixes. New file. Add entity for

* glib/tmpl/warnings.sgml, glib/tmpl/linked_lists_double.sgml,
glib/tmpl/completion.sgml, glib/tmpl/strings.sgml: Documented
some functions, markup fixes.
* glib/tmpl/patterns.sgml: New file.
* glib/glib-docs.sgml: Add entity for patterns.sgml.

docs/reference/ChangeLog

@@ -1,3 +1,11 @@
+2001-09-27  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/tmpl/warnings.sgml, glib/tmpl/linked_lists_double.sgml,
+	glib/tmpl/completion.sgml, glib/tmpl/strings.sgml: Documented
+	some functions, markup fixes.
+	* glib/tmpl/patterns.sgml: New file.
+	* glib/glib-docs.sgml: Add entity for patterns.sgml.
+	
 2001-09-26  Matthias Clasen <matthiasc@poet.de>
 
 	* glib/glib-sections.txt: Add g_mem_is_system_malloc.

docs/reference/glib/glib-docs.sgml

@@ -10,6 +10,7 @@
 <!entity glib-Error-Reporting SYSTEM "sgml/error_reporting.sgml">
 <!entity glib-Warnings-and-Assertions SYSTEM "sgml/warnings.sgml">
 <!entity glib-Message-Logging SYSTEM "sgml/messages.sgml">
+<!entity glib-Pattern-Matching SYSTEM "sgml/patterns.sgml">
 <!entity glib-Timers SYSTEM "sgml/timers.sgml">
 <!entity glib-String-Utility-Functions SYSTEM "sgml/string_utils.sgml">
 <!entity glib-Character-Set-Conversion SYSTEM "sgml/conversions.sgml">
@@ -97,6 +98,7 @@
     &glib-Spawn;
     &glib-Fileutils;
     &glib-Shell;
+    &glib-Pattern-Matching;
     &glib-Markup;
     &glib-Windows-Compatability-Functions;
   </chapter>

docs/reference/glib/tmpl/completion.sgml

@@ -23,6 +23,8 @@ Items in the completion can be simple strings (e.g. file names),
 or pointers to arbitrary data structures. If data structures are used
 you must provide a #GCompletionFunc in g_completion_new(),
 which retrieves the item's string from the data structure.
+You can change the way in which strings are compared by setting
+a different #GCompletionStrncmpFunc in g_completion_set_compare().
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -55,7 +57,7 @@ Creates a new #GCompletion.
 </para>
 
 @func: the function to be called to return the string representing an item
-in the #GCompletion, or NULL if strings are going to be used as the
+in the #GCompletion, or %NULL if strings are going to be used as the
 #GCompletion items.
 @Returns: the new #GCompletion.
 
@@ -105,8 +107,8 @@ Attempts to complete the string @prefix using the #GCompletion target items.
 @cmp: the #GCompletion.
 @prefix: the prefix string, typically typed by the user, which is compared
 with each of the items.
-@new_prefix: if non-NULL, returns the longest prefix which is common to all
+@new_prefix: if non-%NULL, returns the longest prefix which is common to all
-items that matched @prefix, or NULL if no items matched @prefix.
+items that matched @prefix, or %NULL if no items matched @prefix.
 This string should be freed when no longer needed.
 @Returns: the list of items whose strings begin with @prefix. This should
 not be changed.
@@ -114,24 +116,28 @@ not be changed.
 
 <!-- ##### FUNCTION g_completion_set_compare ##### -->
 <para>
-
+Sets the function to use for string comparisons. The default
+string comparison function is <function>strncmp()</function>.
 </para>
 
-@cmp: 
+@cmp: a #GCompletion.
-@strncmp_func: 
+@strncmp_func: the string comparison function.
 
 
 <!-- ##### USER_FUNCTION GCompletionStrncmpFunc ##### -->
 <para>
-
+Specifies the type of the function passed to g_completion_set_compare().
+This is used when you use strings as #GCompletion items.
 </para>
 
-@s1: 
+@s1: string to compare with @s2.
-@s2: 
+@s2: string to compare with @s1.
-@n: 
+@n: maximal number of bytes to compare.
-@Returns: 
+@Returns: an integer less than, equal to, or greater than zero if the 
-
+first @n bytes of @s1 is found, respectively, to be less than, to match, 
+or to be greater than the first @n bytes of @s2.
 
+ 
 <!-- ##### FUNCTION g_completion_free ##### -->
 <para>
 Frees all memory used by the #GCompletion.

docs/reference/glib/tmpl/linked_lists_double.sgml

@@ -34,8 +34,8 @@ the first element in the list. The functions which insert elements return
 the new start of the list, which may have changed.
 </para>
 <para>
-There is no function to create a #GList. NULL is considered to be the empty
+There is no function to create a #GList. %NULL is considered to be the empty
-list so you simply set a #GList* to NULL.
+list so you simply set a #GList* to %NULL.
 </para>
 <para>
 To add elements, use g_list_append(), g_list_prepend(), g_list_insert()
@@ -143,13 +143,14 @@ to the end of the list.
 
 <!-- ##### FUNCTION g_list_insert_before ##### -->
 <para>
-
+Inserts a new element into the list before the given position.
 </para>
 
-@list: 
+@list: a pointer to a #GList.
-@sibling: 
+@sibling: the list element before which the new element is inserted
-@data: 
+  or %NULL to insert at the end of the list.
-@Returns: 
+@data: the data for the new element.
+@Returns: the new start of the #GList.
 
 
 <!-- ##### FUNCTION g_list_insert_sorted ##### -->
@@ -181,7 +182,7 @@ If none of the elements contain the data, the #GList is unchanged.
 <!-- ##### FUNCTION g_list_remove_link ##### -->
 <para>
 Removes an element from a #GList, without freeing the element.
-The removed element's prev and next links are set to NULL, so that it becomes a
+The removed element's prev and next links are set to %NULL, so that it becomes a
 self-contained list with one element.
 </para>
 
@@ -195,9 +196,9 @@ self-contained list with one element.
 Deletes the node @link from @list.
 </para>
 
-@list: a #GList
+@list: a #GList.
-@link: node to delete from @list
+@link: node to delete from @list.
-@Returns: the new head of @list
+@Returns: the new head of @list.
 
 
 <!-- ##### FUNCTION g_list_remove_all ##### -->
@@ -207,9 +208,9 @@ head of the list. Contrast with g_list_remove() which removes only
 the first node matching the given data.
 </para>
 
-@list: a #GList
+@list: a #GList.
-@data: data to remove
+@data: data to remove.
-@Returns: new head of @list
+@Returns: new head of @list.
 
 
 <!-- ##### FUNCTION g_list_free ##### -->
@@ -224,7 +225,7 @@ first.
 </para>
 </note>
 
-@list: 
+@list: a #GList.
 
 
 <!-- ##### FUNCTION g_list_alloc ##### -->
@@ -296,10 +297,10 @@ value if the first element comes after the second.
 Like g_list_sort(), but the comparison function accepts a user data argument.
 </para>
 
-@list: a #GList
+@list: a #GList.
-@compare_func: comparison function
+@compare_func: comparison function.
-@user_data: user data to pass to comparison function
+@user_data: user data to pass to comparison function.
-@Returns: the new head of @list
+@Returns: the new head of @list.
 
 
 <!-- ##### USER_FUNCTION GCompareFunc ##### -->
@@ -354,7 +355,7 @@ Gets the first element in a #GList.
 </para>
 
 @list: a #GList.
-@Returns: the first element in a #GList, or NULL if the #GList has no elements.
+@Returns: the first element in a #GList, or %NULL if the #GList has no elements.
 
 
 <!-- ##### FUNCTION g_list_last ##### -->
@@ -363,7 +364,7 @@ Gets the last element in a #GList.
 </para>
 
 @list: a #GList.
-@Returns: the last element in the #GList, or NULL if the #GList has no
+@Returns: the last element in the #GList, or %NULL if the #GList has no
 elements.
 
 
@@ -373,7 +374,7 @@ A convenience macro to gets the previous element in a #GList.
 </para>
 
 @list: an element in a #GList.
-@Returns: the previous element, or NULL if there are no previous elements.
+@Returns: the previous element, or %NULL if there are no previous elements.
 
 
 <!-- ##### MACRO g_list_next ##### -->
@@ -382,7 +383,7 @@ A convenience macro to gets the next element in a #GList.
 </para>
 
 @list: an element in a #GList.
-@Returns: the next element, or NULL if there are no more elements.
+@Returns: the next element, or %NULL if there are no more elements.
 
 
 <!-- ##### FUNCTION g_list_nth ##### -->
@@ -392,7 +393,7 @@ Gets the element at the given position in a #GList.
 
 @list: a #GList.
 @n: the position of the element, counting from 0.
-@Returns: the element, or NULL if the position is off the end of the #GList.
+@Returns: the element, or %NULL if the position is off the end of the #GList.
 
 
 <!-- ##### FUNCTION g_list_nth_data ##### -->
@@ -402,18 +403,18 @@ Gets the data of the element at the given position.
 
 @list: a #GList.
 @n: the position of the element.
-@Returns: the element's data, or NULL if the position is off the end of the
+@Returns: the element's data, or %NULL if the position is off the end of the
 #GList.
 
 
 <!-- ##### FUNCTION g_list_nth_prev ##### -->
 <para>
-
+Gets the element @n places before @list.
 </para>
 
-@list: 
+@list: a #GList.
-@n: 
+@n: the position of the element, counting from 0.
-@Returns: 
+@Returns: the element, or %NULL if the position is off the end of the #GList.
 
 
 <!-- ##### FUNCTION g_list_find ##### -->
@@ -423,7 +424,7 @@ Finds the element in a #GList which contains the given data.
 
 @list: a #GList.
 @data: the element data to find.
-@Returns: the found #GList element, or NULL if it is not found.
+@Returns: the found #GList element, or %NULL if it is not found.
 
 
 <!-- ##### FUNCTION g_list_find_custom ##### -->
@@ -440,7 +441,7 @@ and the given user data.
 @data: user data passed to the function.
 @func: the function to call for each element. It should return 0 when the
 desired element is found.
-@Returns: the found #GList element, or NULL if it is not found.
+@Returns: the found #GList element, or %NULL if it is not found.
 
 
 <!-- ##### FUNCTION g_list_position ##### -->

docs/reference/glib/tmpl/strings.sgml

@@ -22,10 +22,10 @@ The #GString struct contains the public fields of a #GString.
 The <structfield>str</structfield> field points to the character data.
 It may move as text is added.
 The <structfield>len</structfield> field contains the length of the string,
-not including the terminating null character.
+not including the terminating nul character.
 </para>
 <para>
-The str field is zero-terminated and so can be used as an ordinary C
+The <structfield>str</structfield> field is nul-terminated and so can be used as an ordinary C
 string. But it may be moved when text is appended or inserted into the
 string.
 </para>
@@ -49,14 +49,14 @@ Creates a new #GString with @len bytes of the @init buffer.  Because a length is
 provided, @init need not be nul-terminated, and can contain embedded nul bytes.
 </para>
 
-@init: initial contents of string
+@init: initial contents of string.
-@len: length of @init to use
+@len: length of @init to use.
-@Returns: a new #GString
+@Returns: a new #GString.
 
 
 <!-- ##### FUNCTION g_string_sized_new ##### -->
 <para>
-Creates a new GString, with enough space for @dfl_size characters.
+Creates a new #GString, with enough space for @dfl_size characters.
 This is useful if you are going to add a lot of text to the string and
 don't want it to be reallocated too often.
 </para>
@@ -68,7 +68,7 @@ don't want it to be reallocated too often.
 <!-- ##### FUNCTION g_string_assign ##### -->
 <para>
 Copies the characters from one #GString into another, destroying any previous
-contents. It is rather like the standard strcpy() function, except that
+contents. It is rather like the standard <function>strcpy()</function> function, except that
 you do not have to worry about having enough space to copy the string.
 </para>
 
@@ -81,8 +81,8 @@ you do not have to worry about having enough space to copy the string.
 <para>
 Writes a formatted string into a #GString.
 This is similar to the standard <function>sprintf()</function> function,
-except that the GString buffer automatically expands to contain the results.
+except that the #GString buffer automatically expands to contain the results.
-The previous contents of the GString are destroyed.
+The previous contents of the #GString are destroyed.
 </para>
 
 <!-- # Unused Parameters # -->
@@ -96,7 +96,7 @@ documentation.
 <para>
 Appends a formatted string onto the end of a #GString.
 This function is is similar to g_string_sprintf() except that
-the text is appended to the GString.
+the text is appended to the #GString.
 </para>
 
 <!-- # Unused Parameters # -->
@@ -108,22 +108,29 @@ documentation.
 
 <!-- ##### FUNCTION g_string_printf ##### -->
 <para>
-
+Writes a formatted string into a #GString.
+This is similar to the standard <function>sprintf()</function> function,
+except that the #GString buffer automatically expands to contain the results.
+The previous contents of the #GString are destroyed.
 </para>
 
-@string: 
+@string: a #GString.
-@format: 
+@format: the string format. See the <function>sprintf()</function>
-@Varargs: 
+documentation.
+@Varargs: the parameters to insert into the format string.
 
 
 <!-- ##### FUNCTION g_string_printfa ##### -->
 <para>
-
+Appends a formatted string onto the end of a #GString.
+This function is is similar to g_string_sprintf() except that
+the text is appended to the #GString.
 </para>
 
-@string: 
+@string: a #GString.
-@format: 
+@format: the string format. See the <function>sprintf()</function>
-@Varargs: 
+documentation.
+@Varargs: the parameters to insert into the format string.
 
 
 <!-- ##### FUNCTION g_string_append ##### -->
@@ -162,10 +169,10 @@ Appends @len bytes of @val to @string. Because @len is provided,
 @val may contain embedded nuls and need not be nul-terminated.
 </para>
 
-@string: a #GString
+@string: a #GString.
-@val: bytes to append
+@val: bytes to append.
-@len: number of bytes of @val to use
+@len: number of bytes of @val to use.
-@Returns: the #GString
+@Returns: the #GString.
 
 
 <!-- ##### FUNCTION g_string_prepend ##### -->
@@ -204,10 +211,10 @@ Prepends @len bytes of @val to @string. Because @len is provided,
 @val may contain embedded nuls and need not be nul-terminated.
 </para>
 
-@string: a #GString
+@string: a #GString.
-@val: bytes to prepend
+@val: bytes to prepend.
-@len: number of bytes in @val to prepend
+@len: number of bytes in @val to prepend.
-@Returns: the #GString passed in
+@Returns: the #GString passed in.
 
 
 <!-- ##### FUNCTION g_string_insert ##### -->
@@ -249,11 +256,11 @@ Inserts @len bytes of @val into @string at @pos.  Because @len is provided, @val
  may contain embedded nuls and need not be nul-terminated. If @pos is -1, bytes are inserted at the end of the string.
 </para>
 
-@string: a #GString
+@string: a #GString.
-@pos: position in @string where insertion should happen, or -1 for at the end
+@pos: position in @string where insertion should happen, or -1 for at the end.
-@val: bytes to insert
+@val: bytes to insert.
-@len: number of bytes of @val to insert
+@len: number of bytes of @val to insert.
-@Returns: the #GString
+@Returns: the #GString.
 
 
 <!-- ##### FUNCTION g_string_erase ##### -->
@@ -292,12 +299,11 @@ Cuts off the end of the GString, leaving the first @len characters.
 <!-- ##### FUNCTION g_string_free ##### -->
 <para>
 Frees the memory allocated for the #GString.
-If free_segment is TRUE it also frees the character data.
+If @free_segment is %TRUE it also frees the character data.
 </para>
 
 @string: a #GString.
-@free_segment: if TRUE the actual character data is freed as well.
+@free_segment: if %TRUE the actual character data is freed as well.
-@Returns: 
 
 
 <!-- ##### FUNCTION g_string_up ##### -->
@@ -323,8 +329,8 @@ Converts a #GString to lower case.
 Creates a hash code for @str; for use with #GHashTable.
 </para>
 
-@str: a string to hash
+@str: a string to hash.
-@Returns: hash code for @str
+@Returns: hash code for @str.
 
 
 <!-- ##### FUNCTION g_string_equal ##### -->
@@ -333,8 +339,8 @@ Compares two strings for equality, returning %TRUE if they are equal.
 For use with #GHashTable.
 </para>
 
-@v: a #GString
+@v: a #GString.
-@v2: another #GString
+@v2: another #GString.
-@Returns: %TRUE if they strings are the same length and contain the same bytes
+@Returns: %TRUE if they strings are the same length and contain the same bytes.
 
 

docs/reference/glib/tmpl/warnings.sgml

@@ -85,7 +85,7 @@ widget or a log file for example.
 <!-- ##### MACRO g_return_if_fail ##### -->
 <para>
 Returns from the current function if the expression is not true.
-If the expression evaluates to FALSE, a critical message is logged and
+If the expression evaluates to %FALSE, a critical message is logged and
 the function returns. This can only be used in functions which do not return
 a value.
 </para>
@@ -97,7 +97,7 @@ a value.
 <para>
 Returns from the current function, returning the value @val, if the expression
 is not true.
-If the expression evaluates to FALSE, a critical message is logged and
+If the expression evaluates to %FALSE, a critical message is logged and
 @val is returned.
 </para>
 
@@ -108,17 +108,18 @@ true.
 
 <!-- ##### MACRO g_return_if_reached ##### -->
 <para>
-
+Logs a critical message and returns from the current function. 
+This can only be used in functions which do not return a value.
 </para>
 
 
 
 <!-- ##### MACRO g_return_val_if_reached ##### -->
 <para>
-
+Logs a critical message and returns @val. 
 </para>
 
-@val: 
+@val: the value to return from the current function.
 
 
 <!-- ##### MACRO g_assert ##### -->
@@ -129,7 +130,7 @@ is logged and the application is terminated.
 </para>
 <para>
 The macro can be turned off in final releases of code by defining
-G_DISABLE_ASSERT when compiling the application.
+#G_DISABLE_ASSERT when compiling the application.
 </para>
 
 @expr: the expression to check.
@@ -142,54 +143,54 @@ If it is reached, an error message is logged and the application is terminated.
 </para>
 <para>
 The macro can be turned off in final releases of code by defining
-G_DISABLE_ASSERT when compiling the application.
+#G_DISABLE_ASSERT when compiling the application.
 </para>
 
 
 
 <!-- ##### FUNCTION g_on_error_query ##### -->
 <para>
-Prompts the user with "[E]xit, [H]alt, show [S]tack trace or [P]roceed".
+Prompts the user with <computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>.
 This function is intended to be used for debugging use only.
 FIXME: How do you set it up?
 </para>
 <para>
-If Exit is selected, the application terminates with a call to
+If [E]xit is selected, the application terminates with a call to
 <function>_exit(0)</function>.
 </para>
 <para>
-If Halt is selected, the application enters an infinite loop.
+If [H]alt is selected, the application enters an infinite loop.
 The infinite loop can only be stopped by killing the application,
-or by setting glib_on_error_halt to FALSE (possibly via a debugger).
+or by setting #glib_on_error_halt to %FALSE (possibly via a debugger).
 </para>
 <para>
-If Stack trace is selected, g_on_error_stack_trace() is called. This
+If [S]tack trace is selected, g_on_error_stack_trace() is called. This
-invokes gdb, which attaches to the current process and shows a stack trace.
+invokes <command>gdb</command>, which attaches to the current process and shows a stack trace.
 The prompt is then shown again.
 </para>
 <para>
-If Proceed is selected, the function returns.
+If [P]roceed is selected, the function returns.
 </para>
 <para>
 This function may cause different actions on non-unix platforms.
 </para>
 
-@prg_name: the program name, needed by gdb for the [S]tack trace option.
+@prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
-If @prg_name is NULL, g_get_prgname() is called to get the program name
+If @prg_name is %NULL, g_get_prgname() is called to get the program name
 (which will work correctly if gdk_init() or gtk_init() has been called).
 
 
 <!-- ##### FUNCTION g_on_error_stack_trace ##### -->
 <para>
-Invokes gdb, which attaches to the current process and shows a stack trace.
+Invokes <command>gdb</command>, which attaches to the current process and shows a stack trace.
 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.
 </para>
 
-@prg_name: the program name, needed by gdb for the [S]tack trace option.
+@prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
-If @prg_name is NULL, g_get_prgname() is called to get the program name
+If @prg_name is %NULL, g_get_prgname() is called to get the program name
 (which will work correctly if gdk_init() or gtk_init() has been called).