add glibintl.h

2001-05-19  Havoc Pennington  <hp@pobox.com>

	* glib/Makefile.am (IGNORE_HFILES): add glibintl.h

	* glib/tmpl/*.sgml: fix various missing docs

docs/reference/ChangeLog

@@ -1,3 +1,9 @@
+2001-05-19  Havoc Pennington  <hp@pobox.com>
+
+	* glib/Makefile.am (IGNORE_HFILES): add glibintl.h
+
+	* glib/tmpl/*.sgml: fix various missing docs
+
 2001-05-18  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>
 
 	* glib/glib-overrides.txt, glib/glib-sections.txt,

docs/reference/glib/Makefile.am

@@ -26,6 +26,7 @@ CFILE_GLOB=$(top_srcdir)/*.c $(top_srcdir)/gmodule/*.c
 IGNORE_HFILES=			\
 	gobject 		\
 	config.h 		\
+	glibintl.h		\
 	gmoduleconf.h		\
 	gunibreak.h		\
 	gunidecomp.h		\

docs/reference/glib/glib-sections.txt

@@ -589,6 +589,7 @@ GIOChannel
 g_io_channel_unix_new
 g_io_channel_unix_get_fd
 
+
 <SUBSECTION>
 g_io_channel_init
 
@@ -617,6 +618,7 @@ GIOFuncs
 <SUBSECTION Private>
 g_io_channel_win32_new_fd
 g_io_channel_win32_new_messages
+g_io_channel_win32_new_socket
 g_io_channel_win32_poll
 g_io_channel_win32_make_pollfd
 g_io_channel_win32_get_fd
@@ -949,6 +951,7 @@ GHookFunc
 GHookCheckFunc
 GHookMarshaller
 GHookCheckMarshaller
+GHookFinalizeFunc
 
 <SUBSECTION>
 g_hook_list_init
@@ -1160,6 +1163,8 @@ closedir
 
 g_win32_error_message
 g_win32_getlocale
+g_win32_get_package_installation_directory
+g_win32_get_package_installation_subdirectory
 
 <SUBSECTION Private>
 g_win32_ftruncate
@@ -1373,6 +1378,8 @@ g_string_sized_new
 g_string_assign
 g_string_sprintf
 g_string_sprintfa
+g_string_printf
+g_string_printfa
 g_string_append
 g_string_append_c
 g_string_append_len
@@ -1713,6 +1720,7 @@ gunichar2
 g_get_charset
 
 <SUBSECTION>
+g_unichar_validate
 g_unichar_isalnum
 g_unichar_isalpha
 g_unichar_iscntrl

docs/reference/glib/tmpl/conversions.sgml

@@ -47,7 +47,9 @@ Character Set Conversion
 
 <!-- ##### MACRO G_CONVERT_ERROR ##### -->
 <para>
-
+Error domain for character set conversions. Errors in this domain will
+be from the #GConvertError enumeration. See #GError for information on 
+error domains.
 </para>
 
 

docs/reference/glib/tmpl/datalist.sgml

@@ -168,11 +168,11 @@ The data element's destroy function is called if it has been set.
 
 <!-- ##### MACRO g_datalist_remove_no_notify ##### -->
 <para>
-
+Removes an element, without calling its destroy notifier.
 </para>
 
-@dl: 
+@dl: a datalist.
-@k: 
+@k: the string identifying the data element.
 
 
 <!-- ##### FUNCTION g_datalist_foreach ##### -->

docs/reference/glib/tmpl/datasets.sgml

@@ -165,11 +165,11 @@ Its destroy function is called if it has been set.
 
 <!-- ##### MACRO g_dataset_remove_no_notify ##### -->
 <para>
-
+Removes an element, without calling its destroy notifier.
 </para>
 
-@l: 
+@l: the location identifying the dataset.
-@k: 
+@k: the string identifying the data element.
 
 
 <!-- ##### FUNCTION g_dataset_foreach ##### -->

docs/reference/glib/tmpl/fileutils.sgml

@@ -16,51 +16,107 @@ File Utilities
 
 <!-- ##### 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
+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.
 </para>
 
-@G_FILE_ERROR_EXIST: 
+<para>
-@G_FILE_ERROR_ISDIR: 
+It's not very portable to make detailed assumptions about exactly
-@G_FILE_ERROR_ACCES: 
+which errors will be returned from a given operation. Some errors
-@G_FILE_ERROR_NAMETOOLONG: 
+don't occur on some systems, etc., sometimes there are subtle
-@G_FILE_ERROR_NOENT: 
+differences in when a system will report a given error, etc.
-@G_FILE_ERROR_NOTDIR: 
+</para>
-@G_FILE_ERROR_NXIO: 
+
-@G_FILE_ERROR_NODEV: 
+@G_FILE_ERROR_EXIST: Operation not permitted; only the owner of the
-@G_FILE_ERROR_ROFS: 
+     file (or other resource) or processes with special privileges can
-@G_FILE_ERROR_TXTBSY: 
+     perform the operation.
-@G_FILE_ERROR_FAULT: 
+@G_FILE_ERROR_ISDIR: File is a directory; you cannot open a directory
-@G_FILE_ERROR_LOOP: 
+     for writing, or create or remove hard links to it.
-@G_FILE_ERROR_NOSPC: 
+@G_FILE_ERROR_ACCES: Permission denied; the file permissions do not
-@G_FILE_ERROR_NOMEM: 
+     allow the attempted operation.
-@G_FILE_ERROR_MFILE: 
+@G_FILE_ERROR_NAMETOOLONG: Filename too long.
-@G_FILE_ERROR_NFILE: 
+@G_FILE_ERROR_NOENT: No such file or directory.  This is a "file
-@G_FILE_ERROR_BADF: 
+     doesn't exist" error for ordinary files that are referenced in
-@G_FILE_ERROR_INVAL: 
+     contexts where they are expected to already exist.
-@G_FILE_ERROR_PIPE: 
+@G_FILE_ERROR_NOTDIR: A file that isn't a directory was specified when
-@G_FILE_ERROR_AGAIN: 
+     a directory is required.
-@G_FILE_ERROR_INTR: 
+@G_FILE_ERROR_NXIO: No such device or address.  The system tried to
-@G_FILE_ERROR_IO: 
+     use the device represented by a file you specified, and it
-@G_FILE_ERROR_PERM: 
+     couldn't find the device.  This can mean that the device file was
-@G_FILE_ERROR_FAILED: 
+     installed incorrectly, or that the physical device is missing or
+     not correctly attached to the computer.
+@G_FILE_ERROR_NODEV: This file is of a type that doesn't support
+     mapping.
+@G_FILE_ERROR_ROFS: The directory containing the new link can't be
+          modified because it's on a read-only file system.
+@G_FILE_ERROR_TXTBSY: Text file busy.
+@G_FILE_ERROR_FAULT: You passed in a pointer to bad memory.
+  (GLib won't reliably return this, don't pass in pointers to bad
+  memory.)
+@G_FILE_ERROR_LOOP: Too many levels of symbolic links were encountered
+  in looking up a file name.  This often indicates a cycle of symbolic
+  links.
+@G_FILE_ERROR_NOSPC: No space left on device; write operation on a
+  file failed because the disk is full.
+@G_FILE_ERROR_NOMEM: No memory available.  The system cannot allocate
+     more virtual memory because its capacity is full.
+@G_FILE_ERROR_MFILE: The current process has too many files open and
+     can't open any more.  Duplicate descriptors do count toward this
+     limit.
+@G_FILE_ERROR_NFILE: There are too many distinct file openings in the
+     entire system.
+@G_FILE_ERROR_BADF: Bad file descriptor; for example, I/O on a
+     descriptor that has been closed or reading from a descriptor open
+     only for writing (or vice versa).
+@G_FILE_ERROR_INVAL: Invalid argument.  This is used to indicate
+     various kinds of problems with passing the wrong argument to a
+     library function.
+@G_FILE_ERROR_PIPE: Broken pipe; there is no process reading from the
+     other end of a pipe.  Every library function that returns this
+     error code also generates a `SIGPIPE' signal; this signal
+     terminates the program if not handled or blocked.  Thus, your
+     program will never actually see this code unless it has handled or
+     blocked `SIGPIPE'.
+@G_FILE_ERROR_AGAIN: Resource temporarily unavailable; the call might
+     work if you try again later.
+@G_FILE_ERROR_INTR: Interrupted function call; an asynchronous signal
+     occurred and prevented completion of the call.  When this
+     happens, you should try the call again.
+@G_FILE_ERROR_IO: Input/output error; usually used for physical read
+    or write errors. i.e. the disk or other physical device hardware
+    is returning errors.
+@G_FILE_ERROR_PERM: Operation not permitted; only the owner of the
+     file (or other resource) or processes with special privileges can
+     perform the operation.
+@G_FILE_ERROR_FAILED: Does not correspond to a UNIX error code; this
+  is the standard "failed for unspecified reason" error code present in 
+  all #GError error code enumerations. Returned if no specific
+  code applies.
 
 <!-- ##### MACRO G_FILE_ERROR ##### -->
 <para>
-
+Error domain for file operations. Errors in this domain will
+be from the #GFileError enumeration. See #GError for information on 
+error domains.
 </para>
 
 
 
 <!-- ##### ENUM GFileTest ##### -->
 <para>
-
+A test to perform an a file using g_file_test().
 </para>
 
-@G_FILE_TEST_IS_REGULAR: 
+@G_FILE_TEST_IS_REGULAR: %TRUE if the file is a regular file (not a symlink or directory)
-@G_FILE_TEST_IS_SYMLINK: 
+@G_FILE_TEST_IS_SYMLINK: %TRUE if the file is a symlink.
-@G_FILE_TEST_IS_DIR: 
+@G_FILE_TEST_IS_DIR: %TRUE if the file is a directory.
-@G_FILE_TEST_IS_EXECUTABLE: 
+@G_FILE_TEST_IS_EXECUTABLE: %TRUE if the file is executable.
-@G_FILE_TEST_EXISTS: 
+@G_FILE_TEST_EXISTS: %TRUE if the file exists. It may or may not be a regular file.
 
 <!-- ##### FUNCTION g_file_error_from_errno ##### -->
 <para>

docs/reference/glib/tmpl/hooks.sgml

@@ -169,6 +169,15 @@ and the list of hook functions can be invoked.
 @data: 
 
 
+<!-- ##### USER_FUNCTION GHookFinalizeFunc ##### -->
+<para>
+
+</para>
+
+@hook_list: 
+@hook: 
+
+
 <!-- ##### FUNCTION g_hook_list_init ##### -->
 <para>
 Initializes a #GHookList.

docs/reference/glib/tmpl/linked_lists_double.sgml

@@ -191,12 +191,14 @@ Deletes the node @link from @list.
 
 <!-- ##### FUNCTION g_list_remove_all ##### -->
 <para>
-
+Removes all list nodes with data equal to @data. Returns the new
+head of the list. Contrast with g_list_remove() which removes only 
+the first node matching the given data.
 </para>
 
-@list: 
+@list: a #GList
-@data: 
+@data: data to remove
-@Returns: 
+@Returns: new head of @list
 
 
 <!-- ##### FUNCTION g_list_free ##### -->

docs/reference/glib/tmpl/linked_lists_single.sgml

@@ -211,12 +211,14 @@ Deletes a node of @list. Returns the new list head.
 
 <!-- ##### FUNCTION g_slist_remove_all ##### -->
 <para>
-
+Removes all list nodes with data equal to @data. Returns the new
+head of the list. Contrast with g_slist_remove() which removes only 
+the first node matching the given data.
 </para>
 
-@list: 
+@list: a #GSList
-@data: 
+@data: data to remove
-@Returns: 
+@Returns: new head of @list
 
 
 <!-- ##### FUNCTION g_slist_free ##### -->

docs/reference/glib/tmpl/macros.sgml

@@ -37,21 +37,24 @@ The micro version number of the GLib library.
 
 <!-- ##### MACRO G_OS_WIN32 ##### -->
 <para>
-
+This macro is defined only on Windows. So you can bracket
+Windows-specific code in "#ifdef G_OS_WIN32".
 </para>
 
 
 
 <!-- ##### MACRO G_OS_BEOS ##### -->
 <para>
-
+This macro is defined only on BeOS. So you can bracket
+BeOS-specific code in "#ifdef G_OS_BEOS".
 </para>
 
 
 
 <!-- ##### MACRO G_OS_UNIX ##### -->
 <para>
-
+This macro is defined only on UNIX. So you can bracket
+UNIX-specific code in "#ifdef G_OS_UNIX".
 </para>
 
 
@@ -110,21 +113,21 @@ This is ":" on Unix machines and ";" under Windows.
 
 <!-- ##### MACRO TRUE ##### -->
 <para>
-Defines the TRUE value for the #gboolean type.
+Defines the %TRUE value for the #gboolean type.
 </para>
 
 
 
 <!-- ##### MACRO FALSE ##### -->
 <para>
-Defines the FALSE value for the #gboolean type.
+Defines the %FALSE value for the #gboolean type.
 </para>
 
 
 
 <!-- ##### MACRO NULL ##### -->
 <para>
-Defines the standard NULL pointer.
+Defines the standard %NULL pointer.
 </para>
 
 
@@ -228,14 +231,21 @@ Returns the offset, in bytes, of a member of a struct.
 
 <!-- ##### MACRO G_MEM_ALIGN ##### -->
 <para>
-
+Indicates the number of bytes to which memory will be aligned on the
+current platform.
 </para>
 
 
 
 <!-- ##### MACRO G_CONST_RETURN ##### -->
 <para>
-
+If %G_DISABLE_CONST_RETURNS is defined, this macro expands to nothing.
+By default, the macro expands to "const". The macro should be used 
+in place of "const" for functions that return a value that should not
+be modified. The purpose of this macro is to allow us to turn on
+"const" for returned constant strings by default, while allowing programmers
+who find that annoying to turn it off. This macro should only be used
+for return values, it doesn't make sense for function arguments.
 </para>
 
 

docs/reference/glib/tmpl/macros_misc.sgml

@@ -41,24 +41,29 @@ 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.
 </para>
 
 
 
 <!-- ##### MACRO G_END_DECLS ##### -->
 <para>
-
+Used (along with #G_BEGIN_DECLS) to bracket header files. If the
+compiler in use is a C++ compiler, adds 'extern "C"' around the header.
 </para>
 
 
 
 <!-- ##### MACRO G_N_ELEMENTS ##### -->
 <para>
-
+Determines the number of elements in an array. The array must be
+declared so the compiler knows its size at compile-time; this 
+macro will not work on an array allocated on the heap, only static
+arrays or arrays on the stack.
 </para>
 
-@arr: 
+@arr: the array
 
 
 <!-- ##### MACRO G_VA_COPY ##### -->

docs/reference/glib/tmpl/markup.sgml

@@ -89,7 +89,7 @@ Character references
 
 <!-- ##### ENUM GMarkupError ##### -->
 <para>
-
+Error codes returned by markup parsing.
 </para>
 
 @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8
@@ -101,21 +101,26 @@ Character references
 
 <!-- ##### MACRO G_MARKUP_ERROR ##### -->
 <para>
-
+Error domain for markup parsing. Errors in this domain will
+be from the #GMarkupError enumeration. See #GError for information on 
+error domains.
 </para>
 
 
 
 <!-- ##### ENUM GMarkupParseFlags ##### -->
 <para>
-There are no flags right now
+There are no flags right now. Pass "0" for the flags argument to all 
+functions.
 </para>
 
-@G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: 
+@G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use.
 
 <!-- ##### STRUCT GMarkupParseContext ##### -->
 <para>
-
+A parse context is used to parse a stream of bytes that you expect to
+contain marked-up text. See g_markup_parse_context_new(),
+#GMarkupParser, and so on for more details.
 </para>
 
 

docs/reference/glib/tmpl/messages.sgml

@@ -130,19 +130,19 @@ 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())
-<!-- # Unused Parameters # -->
-@format: the message format. See the <function>printf()</function>
-documentation.
-@args...: the parameters to insert into the format string.
 
 
 <!-- ##### MACRO g_critical ##### -->
 <para>
-
+Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). It's more or less
+application-defined what constitutes a critical vs. a regular
+warning. You could call g_log_set_always_fatal() to make critical
+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())
 
 
 <!-- ##### MACRO g_error ##### -->
@@ -150,6 +150,9 @@ documentation.
 A convenience function/macro to log an error message.
 Error messages are always fatal, resulting in a call to
 <function>abort()</function> to terminate the application.
+This function will result in a core dump; don't use it for errors you
+expect. Using this function indicates a bug in your program, i.e. an
+assertion failure.
 </para>
 
 @...: 

docs/reference/glib/tmpl/numerical.sgml

@@ -3,95 +3,114 @@ Numerical Definitions
 
 <!-- ##### SECTION Short_Description ##### -->
 
+Mathematical constants, and floating point decomposition.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+GLib offers mathematical constants such as #G_PI for the value of pi;
+many platforms have these in the C library, but some don't, the GLib
+versions always exist.
+</para>
 
+<para>
+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: http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html
 </para>
 
 <!-- ##### MACRO G_IEEE754_FLOAT_BIAS ##### -->
 <para>
-
+See http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html
 </para>
 
 
 
 <!-- ##### MACRO G_IEEE754_DOUBLE_BIAS ##### -->
 <para>
-
+See http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html
 </para>
 
 
 
 <!-- ##### UNION GFloatIEEE754 ##### -->
 <para>
-
+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: http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html
 </para>
 
 
 <!-- ##### UNION GDoubleIEEE754 ##### -->
 <para>
-
+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: http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html
 </para>
 
 
 <!-- ##### MACRO G_E ##### -->
 <para>
-
+The base of natural logarithms.
 </para>
 
 
 
 <!-- ##### MACRO G_LN2 ##### -->
 <para>
-
+The natural logarithm of 2.
 </para>
 
 
 
 <!-- ##### MACRO G_LN10 ##### -->
 <para>
-
+The natural logarithm of 10.
 </para>
 
 
 
 <!-- ##### MACRO G_PI ##### -->
 <para>
-
+The value of pi (ratio of circle's circumference to its diameter).
 </para>
 
 
 
 <!-- ##### MACRO G_PI_2 ##### -->
 <para>
-
+Pi divided by 2.
 </para>
 
 
 
 <!-- ##### MACRO G_PI_4 ##### -->
 <para>
-
+Pi divided by 4.
 </para>
 
 
 
 <!-- ##### MACRO G_SQRT2 ##### -->
 <para>
-
+The square root of two.
 </para>
 
 
 
 <!-- ##### MACRO G_LOG_2_BASE_10 ##### -->
 <para>
-
+Used for fooling around with float formats, see http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html
 </para>
 
 

docs/reference/glib/tmpl/strings.sgml

@@ -105,6 +105,26 @@ documentation.
 @Varargs: the parameters to insert into the format string.
 
 
+<!-- ##### FUNCTION g_string_printf ##### -->
+<para>
+
+</para>
+
+@string: 
+@format: 
+@Varargs: 
+
+
+<!-- ##### FUNCTION g_string_printfa ##### -->
+<para>
+
+</para>
+
+@string: 
+@format: 
+@Varargs: 
+
+
 <!-- ##### FUNCTION g_string_append ##### -->
 <para>
 Adds a string onto the end of a #GString, expanding it if necessary.

docs/reference/glib/tmpl/type_conversion.sgml

@@ -3,10 +3,51 @@ Type Conversion Macros
 
 <!-- ##### SECTION Short_Description ##### -->
 
+Portably storing integers in pointer variables.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+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>
+ int *ip = g_new (int, 1);
+ *ip = 42;
+</programlisting>
+But this is inconvenient, and it's annoying to have to free the 
+memory at some later time.
+</para>
+<para>
+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>
+ gpointer p;
+ int i;
+ p = (void*) 42;
+ i = (int) p;
+</programlisting>
+Again, that example was NOT correct, don't copy it. The problem is
+that on some systems you need to do this:
+<programlisting>
+ gpointer p;
+ int i;
+ p = (void*) (long) 42;
+ i = (int) (long) p;
+</programlisting>
+So GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. do the right thing
+on the current platform.
+</para>
+<para>
+<warning>
+<para>
+YOU MAY NOT STORE POINTERS IN INTEGERS. THIS IS NOT PORTABLE IN ANY
+WAY SHAPE OR FORM. These macros <emphasis>ONLY</emphasis> allow
+storing integers in pointers, and only preserve 32 bits of the
+integer; values outside the range of a 32-bit integer will be mangled.
+</para>
+</warning>
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,33 +57,46 @@ Type Conversion Macros
 
 <!-- ##### MACRO GINT_TO_POINTER ##### -->
 <para>
-
+Stuffs an integer into a pointer type.
+</para>
+<para>
+Remember, YOU MAY NOT STORE POINTERS IN INTEGERS. THIS IS NOT PORTABLE
+IN ANY WAY SHAPE OR FORM. These macros <emphasis>ONLY</emphasis> allow
+storing integers in pointers, and only preserve 32 bits of the
+integer; values outside the range of a 32-bit integer will be mangled.
 </para>
 
-@i: 
+@i: integer to stuff into a pointer
 
 
 <!-- ##### MACRO GPOINTER_TO_INT ##### -->
 <para>
-
+Extracts an integer from a pointer. The integer must have
+been stored in the pointer with GINT_TO_POINTER().
+</para>
+<para>
+Remember, YOU MAY NOT STORE POINTERS IN INTEGERS. THIS IS NOT PORTABLE
+IN ANY WAY SHAPE OR FORM. These macros <emphasis>ONLY</emphasis> allow
+storing integers in pointers, and only preserve 32 bits of the
+integer; values outside the range of a 32-bit integer will be mangled.
 </para>
 
-@p: 
+@p: pointer containing an integer.
 
 
 <!-- ##### MACRO GUINT_TO_POINTER ##### -->
 <para>
-
+Same as GINT_TO_POINTER(), but for unsigned integers.
 </para>
 
-@u: 
+@u: integer to stuff into the pointer
 
 
 <!-- ##### MACRO GPOINTER_TO_UINT ##### -->
 <para>
-
+Same as GPOINTER_TO_INT(), but for unsigned integers.
 </para>
 
-@p: 
+@p: pointer to extract an integer from
 
 

docs/reference/glib/tmpl/unicode.sgml

@@ -35,6 +35,15 @@ Unicode Manipulation
 @Returns: 
 
 
+<!-- ##### FUNCTION g_unichar_validate ##### -->
+<para>
+
+</para>
+
+@ch: 
+@Returns: 
+
+
 <!-- ##### FUNCTION g_unichar_isalnum ##### -->
 <para>
 
@@ -316,10 +325,15 @@ Unicode Manipulation
 
 <!-- ##### 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.
+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
+that may contain invalid UTF-8.
 </para>
 
-@p: 
+@p: Pointer to the start of a valid UTF-8 character.
 
 
 <!-- ##### FUNCTION g_utf8_get_char ##### -->

docs/reference/glib/tmpl/windows.sgml

@@ -16,27 +16,32 @@ Windows Compatability Functions
 
 <!-- ##### MACRO MAXPATHLEN ##### -->
 <para>
-
+Provided for UNIX emulation on Windows; equivalent to UNIX 
+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".
 </para>
 
 
 
 <!-- ##### TYPEDEF pid_t ##### -->
 <para>
-
+Provided for UNIX emulation on Windows; process ID type.
 </para>
 
 
 <!-- ##### MACRO pipe ##### -->
 <para>
-
+Provided for UNIX emulation on Windows; see documentation for pipe()
+in any UNIX manual.
 </para>
 
 @phandles: 
@@ -44,7 +49,8 @@ Windows Compatability Functions
 
 <!-- ##### MACRO ftruncate ##### -->
 <para>
-
+Provided for UNIX emulation on Windows; see documentation for ftruncate()
+in any UNIX manual.
 </para>
 
 @fd: 
@@ -53,28 +59,32 @@ Windows Compatability Functions
 
 <!-- ##### MACRO opendir ##### -->
 <para>
-
+Provided for UNIX emulation on Windows; see documentation for opendir()
+in any UNIX manual.
 </para>
 
 
 
 <!-- ##### MACRO readdir ##### -->
 <para>
-
+Provided for UNIX emulation on Windows; see documentation for readdir()
+in any UNIX manual.
 </para>
 
 
 
 <!-- ##### MACRO rewinddir ##### -->
 <para>
-
+Provided for UNIX emulation on Windows; see documentation for rewinddir()
+in any UNIX manual.
 </para>
 
 
 
 <!-- ##### MACRO closedir ##### -->
 <para>
-
+Provided for UNIX emulation on Windows; see documentation for closedir()
+in any UNIX manual.
 </para>
 
 
@@ -96,3 +106,24 @@ Windows Compatability Functions
 @Returns: 
 
 
+<!-- ##### FUNCTION g_win32_get_package_installation_directory ##### -->
+<para>
+
+</para>
+
+@package: 
+@dll_name: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_win32_get_package_installation_subdirectory ##### -->
+<para>
+
+</para>
+
+@package: 
+@dll_name: 
+@subdir: 
+@Returns: 
+
+

glib/gutf8.c

@@ -172,7 +172,7 @@ g_utf8_find_next_char (const gchar *p,
  * g_utf8_prev_char:
  * @p: a pointer to a position within a UTF-8 encoded string
  *
- * Find the previous UTF-8 character in the string before @p
+ * Find the previous UTF-8 character in the string before @p.
  *
  * @p does not have to be at the beginning of a UTF-8 character. No check
  * is made to see if the character found is actually valid other than
@@ -202,7 +202,8 @@ g_utf8_prev_char (const gchar *p)
  * Return value: the length of the string in characters
  **/
 gint
-g_utf8_strlen (const gchar *p, gint max)
+g_utf8_strlen (const gchar *p,
+               gint         max)
 {
   int len = 0;
   const gchar *start = p;

gutf8.c

@@ -172,7 +172,7 @@ g_utf8_find_next_char (const gchar *p,
  * g_utf8_prev_char:
  * @p: a pointer to a position within a UTF-8 encoded string
  *
- * Find the previous UTF-8 character in the string before @p
+ * Find the previous UTF-8 character in the string before @p.
  *
  * @p does not have to be at the beginning of a UTF-8 character. No check
  * is made to see if the character found is actually valid other than
@@ -202,7 +202,8 @@ g_utf8_prev_char (const gchar *p)
  * Return value: the length of the string in characters
  **/
 gint
-g_utf8_strlen (const gchar *p, gint max)
+g_utf8_strlen (const gchar *p,
+               gint         max)
 {
   int len = 0;
   const gchar *start = p;