+2001-10-01 Matthias Clasen <matthiasc@poet.de>
+
+ * glib/tmpl/caches.sgml, glib/tmpl/datalist.sgml,
+ glib/tmpl/hash_tables.sgml, glib/tmpl/messages.sgml,
+ glib/tmpl/misc_utils.sgml: consistently refer to GTK+.
+
+ * glib/tmpl/error_reporting.sgml, glib/tmpl/fileutils.sgml,
+ glib/tmpl/windows.sgml, glib/tmpl/modules.sgml,
+ glib/tmpl/linked_lists_single.sgml, glib/tmpl/trees-nary.sgml,
+ glib/tmpl/trees-binary.sgml, glib/tmpl/timers.sgml: Markup fixes.
+
2001-09-30 Matthias Clasen <matthiasc@poet.de>
* glib/tmpl/arrays.sgml,glib/tmpl/arrays_byte.sgml
system resources.
</para>
<para>
-GTK uses a #GCache for both GtkStyles and GdkGCs. These consume a lot of
+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
required properties already exists. If it does, then the existing
GtkStyle or GdkGC is used instead of creating a new one.
#GQuarks anyway.
</para>
<para>
-Data lists are used in GTK for associating arbitrary data with
+Data lists are used in GTK+ for associating arbitrary data with
GtkObjects, using gtk_object_set_data() and related functions.
</para>
<programlisting>
gchar* g_file_get_contents (const gchar *filename, GError **error);
</programlisting>
-If you pass a non-NULL value for the <literal>error</literal> argument, it should
+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>
gchar *contents;
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
-convention that a NULL return value means an error occurred (but not
+convention that a %NULL return value means an error occurred (but not
all functions use this convention).
</para>
<para>
-Because g_file_get_contents() returns NULL on failure, if you are only
+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:
+can pass %NULL for the <literal>error</literal> argument:
<programlisting>
contents = g_file_get_contents ("foo.txt", NULL); /* ignore errors */
if (contents != NULL)
indicates the specific error that occurred, and <literal>message</literal> is a
user-readable error message with as many details as possible. Several functions
are provided to deal with an error received from a called function:
-g_error_matches() returns TRUE if the error matches a given domain and code,
+g_error_matches() returns %TRUE if the error matches a given domain and code,
g_propagate_error() copies an error into an error location (so the calling
function will receive it), and g_clear_error() clears an error location by
-freeing the error and resetting the location to NULL. To display an error to the
+freeing the error and resetting the location to %NULL. To display an error to the
user, simply display <literal>error->message</literal>, perhaps along with
additional context known only to the calling function (the file being opened, or
whatever -- though in the g_file_get_contents() case,
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:
+to it is %NULL. Here's an example:
<programlisting>
gint
foo_open_file (GError **error)
<para>
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
+other than reporting a #GError, such as by returning %TRUE on success, you can
simply do the following:
<programlisting>
gboolean
<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.
+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>
gboolean
}
</programlisting>
<literal>tmp_error</literal> should be checked immediately after
-sub_function_that_can_fail(), and either cleared or propagated upward. The rule
+<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
-calling function</emphasis>. Note that passing NULL for the error location is the
+calling function</emphasis>. Note that passing %NULL for the error location is the
equivalent of handling an error by always doing nothing about it. So the
-following code is fine, assuming errors in sub_function_that_can_fail() are not
-fatal to my_function_that_can_fail():
+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>
gboolean
my_function_that_can_fail (GError **err)
</para>
<para>
-Note that passing NULL for the error location <emphasis>ignores</emphasis>
+Note that passing %NULL for the error location <emphasis>ignores</emphasis>
errors; it's equivalent to <literal>try { sub_function_that_can_fail (); } catch
(...) {}</literal> in C++. It does <emphasis>not</emphasis> mean to leave errors
unhandled; it means to handle them by doing nothing.
<listitem>
<para>
- The caller may pass NULL for the #GError** if they are not interested
+ The caller may pass %NULL for the #GError** if they are not interested
in details of the exact error that occurred.
</para>
</listitem>
<listitem>
<para>
- If NULL is passed for the #GError** argument, then errors should
+ If %NULL is passed for the #GError** argument, then errors should
not be returned to the caller, but your function should still
abort and return if an error occurs. That is, control flow should
- not be affected by whether the caller wants to get a #GError.
+ not be affected by whether the caller wants to get a #GError.
</para>
</listitem>
<listitem>
<para>
- A #GError* must be initialized to NULL before passing its address to
+ A #GError* must be initialized to %NULL before passing its address to
a function that can report errors.
</para>
</listitem>
<listitem>
<para>
"Piling up" errors is always a bug. That is, if you assign a new
- #GError to a #GError* that is non-NULL, thus overwriting the previous
+ #GError to a #GError* that is non-%NULL, thus overwriting the previous
error, it indicates that you should have aborted the operation instead
of continuing. If you were able to continue, you should have cleared
the previous error with g_clear_error(). g_set_error() will complain
<listitem>
<para>
By convention, if you return a boolean value indicating success
- then TRUE means success and FALSE means failure. If FALSE is returned,
- the error <emphasis>must</emphasis> be set to a non-NULL value.
+ then %TRUE means success and %FALSE means failure. If %FALSE is returned,
+ the error <emphasis>must</emphasis> be set to a non-%NULL value.
</para>
</listitem>
<listitem>
<para>
- A NULL return value is also frequently used to mean that an error
- occurred. You should make clear in your documentation whether NULL is
- a valid return value in non-error cases; if NULL is a valid value,
+ A %NULL return value is also frequently used to mean that an error
+ occurred. You should make clear in your documentation whether %NULL is
+ a valid return value in non-error cases; if %NULL is a valid value,
then users must check whether an error was returned to see if the
function succeeded.
</para>
<para>
When implementing a function that can report errors, you may want to
add a check at the top of your function that the error return location
- is either NULL or contains a NULL error
+ is either %NULL or contains a %NULL error
(e.g. <literal>g_return_if_fail (error == NULL || *error ==
NULL);</literal>).
</para>
</para>
-@domain: error domain, e.g. #G_FILE_ERROR
-@code: error code, e.g. %G_FILE_ERROR_NOENT
-@message: human-readable informative error message
+@domain: error domain, e.g. #G_FILE_ERROR.
+@code: error code, e.g. %G_FILE_ERROR_NOENT.
+@message: human-readable informative error message.
<!-- ##### FUNCTION g_error_new ##### -->
<para>
<!-- ##### ENUM GFileError ##### -->
<para>
-Values corresponding to "errno" codes returned from file operations on
-UNIX. Unlike errno codes, #GFileError values are available on all
-systems, even Windows. The exact meaning of each code depends on what
+Values corresponding to <literal>errno</literal> codes returned from file operations
+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
gives more details. The following error code descriptions come
from the GNU C Library manual, and are under the copyright
Note that neither keys nor values are copied when inserted into the
#GHashTable, so they must exist for the lifetime of the #GHashTable.
This means that the use of static strings is OK, but temporary
-strings (i.e. those created in buffers and those returned by GTK widgets)
+strings (i.e. those created in buffers and those returned by GTK+ widgets)
should be copied with g_strdup() before being inserted.
</para>
<para>
the new start of the list, which may have changed.
</para>
<para>
-There is no function to create a #GSList. NULL is considered to be the empty
-list so you simply set a #GSList* to NULL.
+There is no function to create a #GSList. %NULL is considered to be the empty
+list so you simply set a #GSList* to %NULL.
</para>
<para>
To add elements, use g_slist_append(), g_slist_prepend(), g_slist_insert()
Inserts a node before @sibling containing @data. Returns the new head of the list.
</para>
-@slist: a #GSList
-@sibling: node to insert @data before
-@data: data to put in the newly-inserted node
-@Returns: new head of the list
+@slist: a #GSList.
+@sibling: node to insert @data before.
+@data: data to put in the newly-inserted node.
+@Returns: new head of the list.
<!-- ##### FUNCTION g_slist_insert_sorted ##### -->
<!-- ##### FUNCTION g_slist_remove_link ##### -->
<para>
Removes an element from a #GSList, without freeing the element.
-The removed element's next link is set to NULL, so that it becomes a
+The removed element's next link is set to %NULL, so that it becomes a
self-contained list with one element.
</para>
Deletes a node of @list. Returns the new list head.
</para>
-@list: a #GSList
-@link: node to delete
-@Returns: new head of @list
+@list: a #GSList.
+@link: node to delete.
+@Returns: new head of @list.
<!-- ##### FUNCTION g_slist_remove_all ##### -->
the first node matching the given data.
</para>
-@list: a #GSList
-@data: data to remove
-@Returns: new head of @list
+@list: a #GSList.
+@data: data to remove.
+@Returns: new head of @list.
<!-- ##### FUNCTION g_slist_free ##### -->
</para>
@list: a #GSList.
-@compare_func: the comparison function used to sort the #GSList. This function
-is passed 2 elements of the #GSList and should return 0 if they are equal,
-a negative value if the first element comes before the second, or a positive
-value if the first element comes after the second.
+@compare_func: <function>qsort()</function>-style comparison function.
@Returns: the start of the sorted #GList.
</para>
@list: a #GSList
-@compare_func: qsort()-style comparison function
-@user_data: data to pass to comparison function
-@Returns: new head of the list
+@compare_func: comparison function.
+@user_data: data to pass to comparison function.
+@Returns: new head of the list.
<!-- ##### FUNCTION g_slist_concat ##### -->
</para>
@list: a #GSList.
-@Returns: the last element in the #GSList, or NULL if the #GSList has no
+@Returns: the last element in the #GSList, or %NULL if the #GSList has no
elements.
</para>
@slist: an element in a #GSList.
-@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_slist_nth ##### -->
@list: a #GSList.
@n: the position of the element, counting from 0.
-@Returns: the element, or NULL if the position is off the end of the #GSList.
+@Returns: the element, or %NULL if the position is off the end of the #GSList.
<!-- ##### FUNCTION g_slist_nth_data ##### -->
@list: a #GSList.
@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
#GSList.
@list: a #GSList.
@data: the element data to find.
-@Returns: the found #GSList element, or NULL if it is not found.
+@Returns: the found #GSList element, or %NULL if it is not found.
<!-- ##### FUNCTION g_slist_find_custom ##### -->
@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 #GSList element, or NULL if it is not found.
+@Returns: the found #GSList element, or %NULL if it is not found.
<!-- ##### FUNCTION g_slist_position ##### -->
But be careful not to define it in any public header files.
</para>
<para>
-For example, GTK uses this in its Makefile.am:
+For example, GTK+ uses this in its Makefile.am:
</para>
<informalexample><programlisting>
INCLUDES = \
<!-- ##### FUNCTION g_get_prgname ##### -->
<para>
Gets the name of the program.
-(If you are using GDK or GTK the program name is set in gdk_init(), which
+(If you are using GDK or GTK+ the program name is set in gdk_init(), which
is called by gtk_init(). The program name is found by taking the last
-component of argv[0].)
+component of <literal>argv[0]</literal>.)
</para>
@Returns: the name of the program.
</para>
@variable: the environment variable to get.
-@Returns: the value of the environment variable, or NULL if the environment
+@Returns: the value of the environment variable, or %NULL if the environment
variable is not found.
<!-- ##### FUNCTION g_get_real_name ##### -->
<para>
Gets the real name of the user. This comes from the user's entry in the
-passwd file.
+<filename>passwd</filename> file.
</para>
@Returns: the user's real name.
<!-- ##### FUNCTION g_get_tmp_dir ##### -->
<para>
Gets the directory to use for temporary files.
-This is found from inspecting the environment variables TMPDIR, TMP, and TEMP
+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.
</para>
<!-- ##### FUNCTION g_path_is_absolute ##### -->
<para>
-Returns TRUE if the given @file_name is an absolute file name,
+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.
</para>
<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
-path it returns NULL.
+path it returns %NULL.
</para>
@file_name: a file name.
<para>
Parses a string containing debugging options separated by ':' into a guint
containing bit flags.
-This is used within GDK and GTK to parse the debug options passed on the
+This is used within GDK and GTK+ to parse the debug options passed on the
command line or through environment variables.
</para>
and has no return value. It is not currently used in GLib or GTK+.
</para>
-@data:
+@data: a data pointer.
<!-- ##### FUNCTION g_qsort_with_data ##### -->
These functions provide a portable way to dynamically load object files
(commonly known as 'plug-ins').
The current implementation supports all systems that provide
-an implementation of dlopen() (e.g. Linux/Sun), as well as HP-UX via its
-shl_load() mechanism, and Windows platforms via DLLs.
+an implementation of <function>dlopen()</function> (e.g. Linux/Sun), as well as HP-UX via its
+<function>shl_load()</function> mechanism, and Windows platforms via DLLs.
</para>
<para>
A program, which wants to use these functions must be linked to the
-libraries output by the command "glib-config --libs gmodule".
+libraries output by the command <command>glib-config --libs gmodule</command>.
</para>
<para>
</para>
<para>
If your module introduces static data to common subsystems in the running
-program, e.g. through calling g_quark_from_static_string ("my-module-stuff"),
+program, e.g. through calling <literal>g_quark_from_static_string ("my-module-stuff")</literal>,
it must ensure that it is never unloaded, by calling g_module_make_resident().
</para>
Checks if modules are supported on the current platform.
</para>
-@Returns: TRUE if modules are supported.
+@Returns: %TRUE if modules are supported.
<!-- ##### FUNCTION g_module_build_path ##### -->
</para>
<para>
The directory should specify the directory where the module can be found.
-It can be NULL or an empty string to indicate that the module is in a standard
+It can be %NULL or an empty string to indicate that the module is in a standard
operating-system specific directory, though this is not recommended since the
wrong module may be found.
</para>
<para>
For example, calling g_module_build_path() on a Linux system with a directory
-of "/lib" and a module_name of "mylibrary" will return "/lib/libmylibrary.so".
-On a Windows system, using "\Windows" as the directory it will return
-"\Windows\mylibrary.dll".
+of <filename>/lib</filename> and a module_name of "mylibrary" will return <filename>/lib/libmylibrary.so</filename>.
+On a Windows system, using <filename>\Windows</filename> as the directory it will return
+<filename>\Windows\mylibrary.dll</filename>.
</para>
-@directory: the directory where the module is. This can be NULL or the empty
+@directory: the directory where the module is. This can be %NULL or the empty
string to indicate that the standard operating system-specific directories
will be used, though that is not recommended.
@module_name: the name of the module.
<para>
First of all g_module_open() tries to open @file_name as a module. If
-that fails and @file_name has the ".la"-suffix (and is a libtool
-archive) it tries to open the corresponding module. If that fails and
-it doesn't have the proper module suffix for that plaform
-(#G_MODULE_SUFFIX,) this suffix will be appended and the coresponding
-module will be opended. If that fails and @file_name doesn't have the
-".la"-suffix, this suffix is appended and g_module_open() tries to
-open the corresponding module. If eventually that fails as well, NULL
-is returned.
+that fails and @file_name has the ".la"-suffix (and is a libtool archive)
+it tries to open the corresponding module. If that fails and it doesn't
+have the proper module suffix for that platform (#G_MODULE_SUFFIX), this
+suffix will be appended and the corresponding module will be opended. If
+that fails and @file_name doesn't have the ".la"-suffix, this suffix is
+appended and g_module_open() tries to open the corresponding module. If
+eventually that fails as well, %NULL is returned.
</para>
@file_name: the name of the file containing the module.
@flags: the flags used for opening the module. Currently this can be 0 or
-G_MODULE_BIND_LAZY for lazy binding, where symbols are only bound when needed.
-@Returns: a #GModule on success, or NULL on failure.
+#G_MODULE_BIND_LAZY for lazy binding, where symbols are only bound when needed.
+@Returns: a #GModule on success, or %NULL on failure.
<!-- ##### ENUM GModuleFlags ##### -->
<para>
Flags passed to g_module_open().
-G_MODULE_BIND_LAZY specifies that symbols are only resolved when needed.
+#G_MODULE_BIND_LAZY specifies that symbols are only resolved when needed.
The default action is to bind all symbols when the module is loaded.
-(G_MODULE_BIND_LAZY is not supported on all platforms.)
+(#G_MODULE_BIND_LAZY is not supported on all platforms.)
</para>
@G_MODULE_BIND_LAZY:
@module: the module.
@symbol_name: the name of the symbol to find.
@symbol: returns the pointer to the symbol value.
-@Returns: TRUE on success.
+@Returns: %TRUE on success.
<!-- ##### FUNCTION g_module_name ##### -->
</para>
@module: the module to close.
-@Returns: TRUE on success.
+@Returns: %TRUE on success.
<!-- ##### FUNCTION g_module_error ##### -->
Specifies the type of the module initialization function.
If a module contains a function named g_module_check_init() it is called
automatically when the module is loaded. It is passed the #GModule structure
-and should return NULL on success or a string describing the initialization
+and should return %NULL on success or a string describing the initialization
error.
</para>
@module: the #GModule corresponding to the module which has just been loaded.
-@Returns: NULL on success, or a string describing the initialization error.
+@Returns: %NULL on success, or a string describing the initialization error.
<!-- ##### USER_FUNCTION GModuleUnload ##### -->
called for you).
</para>
-@Returns: a new #GTimer
+@Returns: a new #GTimer.
<!-- ##### FUNCTION g_timer_start ##### -->
timer.
</para>
-@timer: a #GTimer
+@timer: a #GTimer.
<!-- ##### FUNCTION g_timer_stop ##### -->
between this end time and the start time.
</para>
-@timer: a #GTimer
+@timer: a #GTimer.
<!-- ##### FUNCTION g_timer_elapsed ##### -->
microseconds.
</para>
-@timer: a #GTimer
-@microseconds: return location for microseconds elapsed, or %NULL
-@Returns: seconds elapsed
+@timer: a #GTimer.
+@microseconds: return location for microseconds elapsed, or %NULL.
+@Returns: seconds elapsed.
<!-- ##### FUNCTION g_timer_reset ##### -->
purpose.
</para>
-@timer: a #GTimer
+@timer: a #GTimer.
<!-- ##### FUNCTION g_timer_destroy ##### -->
Destroys a timer, freeing associated resources.
</para>
-@timer: a #GTimer to destroy
+@timer: a #GTimer to destroy.
Specifies the type of function passed to g_tree_traverse().
It is passed the key and value of each node, together with
the @user_data parameter passed to g_tree_traverse().
-If the function returns TRUE, the traversal is stopped.
+If the function returns %TRUE, the traversal is stopped.
</para>
@key: a key of a #GTree node.
@value: the value corresponding to the key.
@data: user data passed to g_tree_traverse().
-@Returns: TRUE to stop the traversal.
+@Returns: %TRUE to stop the traversal.
<!-- ##### ENUM GTraverseType ##### -->
since there's no way for GLib to know how to do that).
</para>
-@node: a #GNode
-@Returns: a new #GNode containing the same data pointers
+@node: a #GNode.
+@Returns: a new #GNode containing the same data pointers.
<!-- ##### FUNCTION g_node_insert ##### -->
</para>
@parent: the #GNode to place @node under.
-@sibling: the sibling #GNode to place @node before. If sibling is NULL,
+@sibling: the sibling #GNode to place @node before. If sibling is %NULL,
the node is inserted as the last child of @parent.
@node: the #GNode to insert.
@Returns: the inserted #GNode.
</para>
@parent: the #GNode to place @node under.
-@sibling: the sibling #GNode to place @node after. If sibling is NULL,
+@sibling: the sibling #GNode to place @node after. If sibling is %NULL,
the node is inserted as the first child of @parent.
@node: the #GNode to insert.
@Returns: the inserted #GNode.
<para>
Traverses a tree starting at the given root #GNode.
It calls the given function for each node visited.
-The traversal can be halted at any point by returning TRUE from @func.
+The traversal can be halted at any point by returning %TRUE from @func.
</para>
@root: the root #GNode of the tree to traverse.
Specifies the type of function passed to g_node_traverse().
The function is called with each of the nodes visited, together with the
user data passed to g_node_traverse().
-If the function returns TRUE, then the traversal is stopped.
+If the function returns %TRUE, then the traversal is stopped.
</para>
@node: a #GNode.
@data: user data passed to g_node_traverse().
-@Returns: TRUE to stop the traversal.
+@Returns: %TRUE to stop the traversal.
<!-- ##### FUNCTION g_node_children_foreach ##### -->
@flags: which types of children are to be searched, one of %G_TRAVERSE_ALL,
%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
@data: the data to find.
-@Returns: the found #GNode, or NULL if the data is not found.
+@Returns: the found #GNode, or %NULL if the data is not found.
<!-- ##### FUNCTION g_node_find_child ##### -->
@flags: which types of children are to be searched, one of %G_TRAVERSE_ALL,
%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
@data: the data to find.
-@Returns: the found child #GNode, or NULL if the data is not found.
+@Returns: the found child #GNode, or %NULL if the data is not found.
<!-- ##### FUNCTION g_node_child_index ##### -->
</para>
@node: a #GNode.
-@Returns: the last child of @node, or NULL if @node is NULL or has no children.
+@Returns: the last child of @node, or %NULL if @node is %NULL or has no children.
<!-- ##### FUNCTION g_node_last_child ##### -->
Gets the last child of a #GNode.
</para>
-@node: a #GNode (must not be NULL).
-@Returns: the last child of @node, or NULL if @node has no children.
+@node: a #GNode (must not be %NULL).
+@Returns: the last child of @node, or %NULL if @node has no children.
<!-- ##### FUNCTION g_node_nth_child ##### -->
<para>
Gets a child of a #GNode, using the given index.
-The first child is at index 0. If the index is too big, NULL is returned.
+The first child is at index 0. If the index is too big, %NULL is returned.
</para>
@node: a #GNode.
</para>
@node: a #GNode.
-@Returns: the next sibling of @node, or NULL if @node is NULL.
+@Returns: the next sibling of @node, or %NULL if @node is %NULL.
<!-- ##### MACRO g_node_prev_sibling ##### -->
</para>
@node: a #GNode.
-@Returns: the previous sibling of @node, or NULL if @node is NULL.
+@Returns: the previous sibling of @node, or %NULL if @node is %NULL.
<!-- ##### FUNCTION g_node_last_sibling ##### -->
<!-- ##### MACRO G_NODE_IS_LEAF ##### -->
<para>
-Returns TRUE if a #GNode is a leaf node.
+Returns %TRUE if a #GNode is a leaf node.
</para>
@node: a #GNode.
-@Returns: TRUE if the #GNode is a leaf node (i.e. it has no children).
+@Returns: %TRUE if the #GNode is a leaf node (i.e. it has no children).
<!-- ##### MACRO G_NODE_IS_ROOT ##### -->
<para>
-Returns TRUE if a #GNode is the root of a tree.
+Returns %TRUE if a #GNode is the root of a tree.
</para>
@node: a #GNode.
-@Returns: TRUE if the #GNode is the root of a tree (i.e. it has no parent
+@Returns: %TRUE if the #GNode is the root of a tree (i.e. it has no parent
or siblings).
Gets the depth of a #GNode.
</para>
<para>
-If @node is NULL the depth is 0.
+If @node is %NULL the depth is 0.
The root node has a depth of 1.
For the children of the root node the depth is 2. And so on.
</para>
<!-- ##### FUNCTION g_node_is_ancestor ##### -->
<para>
-Returns TRUE if @node is an ancestor of @descendant.
-This is true if node is the parent of descendant, or if node is the
-grandparent of descendant etc.
+Returns %TRUE if @node is an ancestor of @descendant.
+This is true if node is the parent of @descendant, or if node is the
+grandparent of @descendant etc.
</para>
@node: a #GNode.
@descendant: a #GNode.
-@Returns: TRUE if @node is an ancestor of @descendant.
+@Returns: %TRUE if @node is an ancestor of @descendant.
<!-- ##### FUNCTION g_node_max_height ##### -->
This is the maximum distance from the #GNode to all leaf nodes.
</para>
<para>
-If @root is NULL, 0 is returned. If @root has no children, 1 is returned.
+If @root is %NULL, 0 is returned. If @root has no children, 1 is returned.
If @root has children, 2 is returned. And so on.
</para>
<!-- ##### SECTION Title ##### -->
-Windows Compatability Functions
+Windows Compatibility Functions
<!-- ##### SECTION Short_Description ##### -->
<!-- ##### MACRO MAXPATHLEN ##### -->
<para>
Provided for UNIX emulation on Windows; equivalent to UNIX
-macro MAXPATHLEN, which is the maximum length of a filename
+macro %MAXPATHLEN, which is the maximum length of a filename
(including full path).
</para>
<!-- ##### MACRO NAME_MAX ##### -->
<para>
Provided for UNIX emulation on Windows; equivalent to UNIX macro
-NAME_MAX, which is the maximum length of a single path component.
-i.e. just the "foo" in "/usr/bin/foo".
+%NAME_MAX, which is the maximum length of a single path component.
+i.e. just the <filename>foo</filename> in <filename>/usr/bin/foo</filename>.
</para>
<!-- ##### MACRO pipe ##### -->
<para>
-Provided for UNIX emulation on Windows; see documentation for pipe()
+Provided for UNIX emulation on Windows; see documentation for <function>pipe()</function>
in any UNIX manual.
</para>
<!-- ##### MACRO ftruncate ##### -->
<para>
-Provided for UNIX emulation on Windows; see documentation for ftruncate()
+Provided for UNIX emulation on Windows; see documentation for <function>ftruncate()</function>
in any UNIX manual.
</para>
<!-- ##### MACRO opendir ##### -->
<para>
-Provided for UNIX emulation on Windows; see documentation for opendir()
+Provided for UNIX emulation on Windows; see documentation for <function>opendir()</function>
in any UNIX manual.
</para>
<!-- ##### MACRO readdir ##### -->
<para>
-Provided for UNIX emulation on Windows; see documentation for readdir()
+Provided for UNIX emulation on Windows; see documentation for <function>readdir()</function>
in any UNIX manual.
</para>
<!-- ##### MACRO rewinddir ##### -->
<para>
-Provided for UNIX emulation on Windows; see documentation for rewinddir()
+Provided for UNIX emulation on Windows; see documentation for <function>rewinddir()</function>
in any UNIX manual.
</para>
<!-- ##### MACRO closedir ##### -->
<para>
-Provided for UNIX emulation on Windows; see documentation for closedir()
+Provided for UNIX emulation on Windows; see documentation for <function>closedir()</function>
in any UNIX manual.
</para>
projects / platform / upstream / glib.git / commitdiff