docs on why the deprecated functions are deprecated.

2001-10-25  Havoc Pennington  <hp@pobox.com>

	* glib/tmpl/string_utils.sgml: docs on why the deprecated
	functions are deprecated.

docs/reference/ChangeLog

@@ -1,3 +1,8 @@
+2001-10-25  Havoc Pennington  <hp@pobox.com>
+
+	* glib/tmpl/string_utils.sgml: docs on why the deprecated
+	functions are deprecated.
+
 2001-10-15  Sven Neumann  <sven@gimp.org>
 
 	* glib/tmpl/random_numbers.sgml: fixed typo.

docs/reference/glib/tmpl/string_utils.sgml

@@ -509,7 +509,9 @@ possibly non-ASCII character in.
 
 <!-- ##### FUNCTION g_strup ##### -->
 <para>
-Converts a string to upper case.
+Converts a string to upper case. This function is totally broken
+for the reasons discussed in the g_strncasecmp() docs - 
+use g_ascii_strup() or g_utf8_strup() instead.
 </para>
 
 @string: the string to convert.
@@ -518,7 +520,9 @@ Converts a string to upper case.
 
 <!-- ##### FUNCTION g_strdown ##### -->
 <para>
-Converts a string to lower case.
+Converts a string to lower case.  This function is totally broken for
+the reasons discussed in the g_strncasecmp() docs - use
+g_ascii_strdown() or g_utf8_strdown() instead.
 </para>
 
 @string: the string to convert.
@@ -530,6 +534,10 @@ Converts a string to lower case.
 A case-insensitive string comparison, corresponding to the standard
 <function>strcasecmp()</function> function on platforms which support it.
 </para>
+<para>
+See g_strncasecmp() for a discussion of why this is deprecated and
+how to replace it.
+</para>
 
 @s1: a string.
 @s2: a string to compare with @s1.
@@ -544,6 +552,23 @@ A case-insensitive string comparison, corresponding to the standard
 It is similar to g_strcasecmp() except it only compares the first @n characters
 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
+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
+broken if your string is guaranteed to be ASCII, since it's
+locale-sensitive, and it's broken if your string is localized, since
+it doesn't work on many encodings at all, including UTF-8, EUC-JP,
+etc.
+</para>
+<para>
+There are therefore two replacement functions: g_ascii_strncasecmp(),
+which only works on ASCII and is not locale-sensitive, and
+g_utf8_casefold(), which is good for case-insensitive sorting of
+UTF-8.
+</para>
 
 @s1: a string.
 @s2: a string to compare with @s1.