diff options
| author | Matthias Clasen <matthiasc@src.gnome.org> | 2001-12-12 20:32:07 +0000 |
|---|---|---|
| committer | Matthias Clasen <matthiasc@src.gnome.org> | 2001-12-12 20:32:07 +0000 |
| commit | 3fa33317b7e9866793ce1ea32d069e8c9270caa2 (patch) | |
| tree | 1ea1e0acca6a8bcb02c22ecbbe40c6ac420ddf7b /docs | |
| parent | 24608fc1565a8f28b507c5799b33091847b5cb7f (diff) | |
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.
Diffstat (limited to 'docs')
38 files changed, 279 insertions, 350 deletions
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 82a955dc6..cc38554b4 100644 --- a/docs/reference/ChangeLog +++ b/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 diff --git a/docs/reference/glib/tmpl/allocators.sgml b/docs/reference/glib/tmpl/allocators.sgml index 6b12fd27c..a98496c81 100644 --- a/docs/reference/glib/tmpl/allocators.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml index 0de6c9091..c5c5e2a70 100644 --- a/docs/reference/glib/tmpl/arrays.sgml +++ b/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; diff --git a/docs/reference/glib/tmpl/arrays_byte.sgml b/docs/reference/glib/tmpl/arrays_byte.sgml index 447f1360f..e59af2dd1 100644 --- a/docs/reference/glib/tmpl/arrays_byte.sgml +++ b/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. diff --git a/docs/reference/glib/tmpl/arrays_pointer.sgml b/docs/reference/glib/tmpl/arrays_pointer.sgml index 74dc81bf1..48f869b31 100644 --- a/docs/reference/glib/tmpl/arrays_pointer.sgml +++ b/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: -@len: +@pdata: points to the array of pointers, which may be moved when the array grows. +@len: number of pointers in the array. <!-- ##### FUNCTION g_ptr_array_new ##### --> <para> diff --git a/docs/reference/glib/tmpl/caches.sgml b/docs/reference/glib/tmpl/caches.sgml index 887d4674d..99c344b68 100644 --- a/docs/reference/glib/tmpl/caches.sgml +++ b/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 -resources, so a #GCache is used to see if a GtkStyle or GdkGC with the +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 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> diff --git a/docs/reference/glib/tmpl/completion.sgml b/docs/reference/glib/tmpl/completion.sgml index b2d9a037d..4a0cd6b78 100644 --- a/docs/reference/glib/tmpl/completion.sgml +++ b/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: -@func: -@prefix: -@cache: +@items: list of target items (strings or data structures). +@func: function which is called to get the string associated with a target + item. It is %NULL if the target items are strings. +@prefix: the last prefix passed to g_completion_complete(). +@cache: the list of items which begin with @prefix. @strncmp_func: <!-- ##### FUNCTION g_completion_new ##### --> diff --git a/docs/reference/glib/tmpl/conversions.sgml b/docs/reference/glib/tmpl/conversions.sgml index cc0affc2b..b6ffa55b7 100644 --- a/docs/reference/glib/tmpl/conversions.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/datalist.sgml b/docs/reference/glib/tmpl/datalist.sgml index 063639804..60c2bf418 100644 --- a/docs/reference/glib/tmpl/datalist.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/date.sgml b/docs/reference/glib/tmpl/date.sgml index 688480dd9..5b27683a7 100644 --- a/docs/reference/glib/tmpl/date.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/error_reporting.sgml b/docs/reference/glib/tmpl/error_reporting.sgml index 56842db51..336dee631 100644 --- a/docs/reference/glib/tmpl/error_reporting.sgml +++ b/docs/reference/glib/tmpl/error_reporting.sgml @@ -2,8 +2,7 @@ Error Reporting <!-- ##### SECTION Short_Description ##### --> - -System for reporting errors +a 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 -rules</emphasis>. If you use #GError incorrectly, then your code will not +<emphasis>data type</emphasis> (the #GError object) and a <emphasis>set of +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", &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> diff --git a/docs/reference/glib/tmpl/fileutils.sgml b/docs/reference/glib/tmpl/fileutils.sgml index c9ae8e8b5..9d71dedb1 100644 --- a/docs/reference/glib/tmpl/fileutils.sgml +++ b/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. diff --git a/docs/reference/glib/tmpl/hash_tables.sgml b/docs/reference/glib/tmpl/hash_tables.sgml index 13a81a249..31b778597 100644 --- a/docs/reference/glib/tmpl/hash_tables.sgml +++ b/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. diff --git a/docs/reference/glib/tmpl/hooks.sgml b/docs/reference/glib/tmpl/hooks.sgml index de5f5c273..49b1be5a8 100644 --- a/docs/reference/glib/tmpl/hooks.sgml +++ b/docs/reference/glib/tmpl/hooks.sgml @@ -19,53 +19,18 @@ and the list of hook functions can be invoked. <!-- ##### STRUCT GHookList ##### --> <para> - -<informaltable pgwide=1 frame="none" role="struct"> -<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> - +The <structname>GHookList</structname> struct represents a +list of hook functions. </para> -@seq_id: -@hook_size: -@is_setup: -@hooks: -@hook_memchunk: -@finalize_hook: +@seq_id: the next free #GHook id. +@hook_size: the size of the #GHookList elements, in bytes. +@is_setup: 1 if the #GHookList has been initialized. +@hooks: the first #GHook element in the list. +@hook_memchunk: the #GMemChunk used for allocating the #GHook elements. +@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 +function in a #GHookList. +</para> + +@data: data which is passed to func when this hook is invoked. +@next: pointer to the next hook in the list. +@prev: pointer to the previous hook in the list. +@ref_count: the reference count of this hook. +@hook_id: the id of this hook, which is unique within its list. +@flags: flags which are set for this hook. See #GHookFlagMask for +predefined flags. +@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. -<informaltable pgwide=1 frame="none" role="struct"> -<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: -@next: -@prev: -@ref_count: -@hook_id: -@flags: -@func: -@destroy: <!-- ##### USER_FUNCTION GHookFunc ##### --> <para> diff --git a/docs/reference/glib/tmpl/macros.sgml b/docs/reference/glib/tmpl/macros.sgml index 4912c67b8..c272600c2 100644 --- a/docs/reference/glib/tmpl/macros.sgml +++ b/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 -UNIX-specific code in "#ifdef G_OS_UNIX". +This macro is defined only on Unix. So you can bracket +Unix-specific code in "#ifdef G_OS_UNIX". </para> diff --git a/docs/reference/glib/tmpl/macros_misc.sgml b/docs/reference/glib/tmpl/macros_misc.sgml index 16d2ac28c..bdccfc629 100644 --- a/docs/reference/glib/tmpl/macros_misc.sgml +++ b/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. -This simply tells GNU C not to warn about the following non-standard code -when compiling with the <literal>-pedantic</literal> option. +Expands to <literal>__extension__</literal> when <command>gcc</command> is +used as the compiler. +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. -The format_arg function attribute specifies that a function takes a format +Expands to the GNU C <literal>format_arg</literal> function attribute if the compiler is <command>gcc</command>. +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 -the compiler is GNU C. Functions with this attribute will not be +Expands to the GNU C <literal>no_instrument_function</literal> function +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. diff --git a/docs/reference/glib/tmpl/main.sgml b/docs/reference/glib/tmpl/main.sgml index d7c0e86bc..46a010715 100644 --- a/docs/reference/glib/tmpl/main.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/markup.sgml b/docs/reference/glib/tmpl/markup.sgml index d2e27c9fb..58ac77988 100644 --- a/docs/reference/glib/tmpl/markup.sgml +++ b/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 diff --git a/docs/reference/glib/tmpl/memory.sgml b/docs/reference/glib/tmpl/memory.sgml index b20aa3f82..f83043fa9 100644 --- a/docs/reference/glib/tmpl/memory.sgml +++ b/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 -present on most unix variants. Thus it provides the same advantages and pitfalls -as alloca(): +stack frame is cleaned up. This macro essentially just wraps the +<function>alloca()</function> function present on most Unix variants. +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. - Stack space allocated with alloca(3) in the same scope as a variable sized array + - Special care has to be taken when mixing <function>alloca()</function> with GNU C variable sized arrays. + 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 -OTHER GLIB FUNCTIONS. The @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function> +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> 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 diff --git a/docs/reference/glib/tmpl/memory_chunks.sgml b/docs/reference/glib/tmpl/memory_chunks.sgml index 2f33963b9..c089a0850 100644 --- a/docs/reference/glib/tmpl/memory_chunks.sgml +++ b/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); diff --git a/docs/reference/glib/tmpl/messages.sgml b/docs/reference/glib/tmpl/messages.sgml index 2b8591235..ed7c4ad53 100644 --- a/docs/reference/glib/tmpl/messages.sgml +++ b/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 = \ - -DG_LOG_DOMAIN=\"Gtk\" +INCLUDES = -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 -to set a handler for this log level you must combine it with G_LOG_FLAG_FATAL. +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. </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. diff --git a/docs/reference/glib/tmpl/misc_utils.sgml b/docs/reference/glib/tmpl/misc_utils.sgml index 2b3892665..4540eeb6f 100644 --- a/docs/reference/glib/tmpl/misc_utils.sgml +++ b/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. diff --git a/docs/reference/glib/tmpl/modules.sgml b/docs/reference/glib/tmpl/modules.sgml index a3b1d3ad1..17488d1f2 100644 --- a/docs/reference/glib/tmpl/modules.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/numerical.sgml b/docs/reference/glib/tmpl/numerical.sgml index 661a3baa8..2fdf4e2b0 100644 --- a/docs/reference/glib/tmpl/numerical.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/patterns.sgml b/docs/reference/glib/tmpl/patterns.sgml index d3de5db03..cba7870cf 100644 --- a/docs/reference/glib/tmpl/patterns.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/queue.sgml b/docs/reference/glib/tmpl/queue.sgml index fc5bb53e8..99427edee 100644 --- a/docs/reference/glib/tmpl/queue.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/shell.sgml b/docs/reference/glib/tmpl/shell.sgml index 34efec3e9..399aa4f57 100644 --- a/docs/reference/glib/tmpl/shell.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/spawn.sgml b/docs/reference/glib/tmpl/spawn.sgml index bee83a102..7e2b9e994 100644 --- a/docs/reference/glib/tmpl/spawn.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/string_utils.sgml b/docs/reference/glib/tmpl/string_utils.sgml index 15115c8d2..1955df837 100644 --- a/docs/reference/glib/tmpl/string_utils.sgml +++ b/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 -strlcat() otherwise. Appends nul-terminated @src string to @dest, guaranteeing +Portability wrapper that calls <function>strlcat()</function> on systems which have it, and emulates it 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 -strncat(), but for real security g_strconcat() is harder to mess up. +@dest_size. Caveat: this is supposedly a more secure alternative to <function>strcat()</function> or +<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 -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +library function, 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 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 -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +library function, 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 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 -library function, this takes a char, not an int, so don't call it -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +returning %FALSE for all non-ASCII characters. Also unlike the standard +library function, 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 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, -this takes a char, not an int, so don't call it -on EOF but no need to cast to guchar before passing a possibly +Unlike the standard C library <function>isdigit()</function> function, +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 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 -recognizes standard ASCII characters 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 -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +Unlike the standard C library <function>isgraph()</function> function, +this only recognizes standard ASCII characters and ignores the locale, +returning %FALSE for all non-ASCII characters. Also unlike the standard +library function, 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 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 -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 -on EOF but no need to worry about casting to guchar before passing -a possibly non-ASCII character in. +Unlike the standard C library <function>islower()</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 <type>char</type>, not an <type>int</type>, +so don't call it on %EOF but no need to worry about casting to #guchar +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 -recognizes standard ASCII characters 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 -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +Unlike the standard C library <function>isprint()</function> function, +this only recognizes standard ASCII characters and ignores the locale, +returning %FALSE for all non-ASCII characters. Also unlike the standard +library function, 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 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 -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 -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +Unlike the standard C library <function>ispunct()</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 <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 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 -recognizes standard ASCII white-space 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 -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +Unlike the standard C library <function>isspace()</function> function, +this only recognizes standard ASCII white-space and ignores the locale, +returning %FALSE for all non-ASCII characters. Also unlike the standard +library function, 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 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 -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 -on EOF but no need to worry about casting to guchar before passing -a possibly non-ASCII character in. +Unlike the standard C library <function>isupper()</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 <type>char</type>, not an <type>int</type>, +so don't call it on %EOF but no need to worry about casting to #guchar +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, -this takes a char, not an int, so -don't call it on EOF but no need to cast to guchar before passing a +Unlike the standard C library <function>isxdigit()</function> function, +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 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> -<para> -<literal> +<informalexample><programlisting> 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> diff --git a/docs/reference/glib/tmpl/thread_pools.sgml b/docs/reference/glib/tmpl/thread_pools.sgml index f31bcc7a3..a13629a3e 100644 --- a/docs/reference/glib/tmpl/thread_pools.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/threads.sgml b/docs/reference/glib/tmpl/threads.sgml index 6e1aa4f80..99060d4a1 100644 --- a/docs/reference/glib/tmpl/threads.sgml +++ b/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 -that will mess up the bookkeeping and lead to funny and unwanted -results. +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 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; diff --git a/docs/reference/glib/tmpl/timers.sgml b/docs/reference/glib/tmpl/timers.sgml index 2ee0bfdd7..2cdb8f7a2 100644 --- a/docs/reference/glib/tmpl/timers.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/trees-binary.sgml b/docs/reference/glib/tmpl/trees-binary.sgml index 36af29ebb..d3838a86f 100644 --- a/docs/reference/glib/tmpl/trees-binary.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/trees-nary.sgml b/docs/reference/glib/tmpl/trees-nary.sgml index ee8316690..9cd1767a0 100644 --- a/docs/reference/glib/tmpl/trees-nary.sgml +++ b/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, -or is %NULL if the #GNode is the root of the tree. +The <structfield>parent</structfield> field points to the parent of the <structname>GNode</structname>, +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> diff --git a/docs/reference/glib/tmpl/type_conversion.sgml b/docs/reference/glib/tmpl/type_conversion.sgml index 5f36d5c39..41527e5cb 100644 --- a/docs/reference/glib/tmpl/type_conversion.sgml +++ b/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> diff --git a/docs/reference/glib/tmpl/unicode.sgml b/docs/reference/glib/tmpl/unicode.sgml index b9edb0dc3..0223c3f92 100644 --- a/docs/reference/glib/tmpl/unicode.sgml +++ b/docs/reference/glib/tmpl/unicode.sgml @@ -31,7 +31,7 @@ Convenience functions for converting between UTF-8 and the locale encoding. <!-- ##### TYPEDEF gunichar ##### --> <para> -A type which can hold any UCS-4 character code. +A type which can hold any UCS-4 character code. </para> @@ -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. diff --git a/docs/reference/glib/tmpl/warnings.sgml b/docs/reference/glib/tmpl/warnings.sgml index 2ecbed3fb..bcce91c9b 100644 --- a/docs/reference/glib/tmpl/warnings.sgml +++ b/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. diff --git a/docs/reference/glib/tmpl/windows.sgml b/docs/reference/glib/tmpl/windows.sgml index 774e4425e..26a92d836 100644 --- a/docs/reference/glib/tmpl/windows.sgml +++ b/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> -in any UNIX manual. +Provided for Unix emulation on Windows; see documentation for <function>pipe()</function> +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> -in any UNIX manual. +Provided for Unix emulation on Windows; see documentation for <function>ftruncate()</function> +in any Unix manual. </para> @fd: |