From 0628133a110fea57c9bc97f1a369d622a32f5b54 Mon Sep 17 00:00:00 2001
From: Havoc Pennington <hp@pobox.com>
Date: Thu, 25 Oct 2001 14:38:45 +0000
Subject: [PATCH] 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                   |  5 +++++
 docs/reference/glib/tmpl/string_utils.sgml | 29 +++++++++++++++++++++++++++--
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index bc19506..3bcc1c3 100644
--- a/docs/reference/ChangeLog
+++ b/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.
diff --git a/docs/reference/glib/tmpl/string_utils.sgml b/docs/reference/glib/tmpl/string_utils.sgml
index 0135b3b..15115c8 100644
--- a/docs/reference/glib/tmpl/string_utils.sgml
+++ b/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.
-- 
2.7.4