Index: ChangeLog
===================================================================
RCS file: /cvs/gnome/gtkmm-root/base/ChangeLog,v
retrieving revision 1.580
diff -u -r1.580 ChangeLog
--- ChangeLog	10 Nov 2002 02:05:45 -0000	1.580
+++ ChangeLog	10 Nov 2002 11:12:31 -0000
@@ -1,3 +1,8 @@
+2002-11-10  Ole Laursen  <olau@hardworking.dk>
+
+	* docs/tutorial/gtkmm-tut.xml: Added a note to the ustring section
+	that iostreams require special attention.
+
 2002-11-06  Murray Cumming  <murrayc@usa.net>
 
 	* docs/FAQ/Makefile.am, docs/tutorial/Makefile.am,
Index: docs/tutorial/gtkmm-tut.xml
===================================================================
RCS file: /cvs/gnome/gtkmm-root/doc-tutorial/gtkmm-tut.xml,v
retrieving revision 1.65
diff -u -r1.65 gtkmm-tut.xml
--- docs/tutorial/gtkmm-tut.xml	9 Nov 2002 12:20:53 -0000	1.65
+++ docs/tutorial/gtkmm-tut.xml	10 Nov 2002 11:12:38 -0000
@@ -352,11 +352,28 @@
 <para>You might be surprised to learn that gtkmm doesn't use std::string in it its interfaces. Instead it uses Glib::ustring, which is so similar and unobtrusive that you could actually pretend that each Glib::ustring is a std::string and ignore the rest of this section. But read on if you want to use languages other than English in your application.</para>
 <para>std::string uses 8 bit per character, but 8 bits aren't enough to encode languages such as Arabic, Chinese, and Japanese. Although the encodings for these languages has now been specified by the Unicode Constortium, the C and C++ languages do not yet provide any standardised Unicode support. GTK+ and GNOME chose to implement Unicode using UTF-8, and that's what is wrapped by Glib::ustring. It provides almost exactly the same interface as std::string, along with automatic conversions to and from std::string.</para>
 <para>One of the benefits of UTF-8 is that you don't need to use it unless you want to, so you don't need to retrofit all of your code at once. std::string will still work for 7-bit ASCII strings. But when you try to localize your application for languages like Chinese, for instance, you will start to see strange errors, and possible crashes. Then all you need to do is start using Glib::ustring instead.</para>
+
+<para>The automatic conversions between std::string and Glib::ustring
+make it possible to reuse many existing string algorithms without
+changing their interface to use Glib::ustring (you need to be very
+careful that they do not depend on the length of any characters
+outside the ASCII range, though). But there is one important pitfall:
+the standard iostreams works in a locale-dependent way.</para>
+
+<para><literal>gtkmm</literal> thus converts Glib::ustrings to the
+locale-specific encoding if you output them with
+<literal>operator&lt;&lt;</literal>. Likewise, retrieving
+Glib::ustrings with <literal>operator&gt;&gt;</literal> causes a
+conversion in the opposite direction. But this scheme breaks down if
+you use a std::string as an intermediate; for instance, retrieving the
+std::string from a stringstream requires a manual conversion. See the
+reference documentation on Glib::ustring for the details.</para>
+      
 <para>Note that UTF-8 isn't compatible with 8-bit encodings like ISO-8859-1. For instance, German umlauts are not in the ASCII range and need more than 1 byte in the UTF-8 encoding. If your code contains 8-bit string literals, you have to convert them to UTF-8 (e.g. the Bavarian greeting "Gr&uuml;&szlig; Gott" would be "Gr\xC3\xBC\xC3\x9F Gott").</para>
 <para>You should avoid C-style pointer arithmetic, and functions such as strlen(). In UTF-8, each character might need anywhere from 1 to 6 bytes, so it's not possible to assume that the next byte is another character. Glib::ustring worries about the details of this for you so you can use methods such as Glib::ustring::substr() while still thinking in terms of characters instead of bytes.</para>
 
 <para>Unlike the Windows UCS-2 Unicode solution, this does not require any special compiler options to process string literals, and it does not result in Unicode executables and libraries which are incompatible with ASCII ones.</para>
-
+      
 <para>See the <link linkend="sec-internationalization">Internationalization</link> section for information about providing the UTF-8 string literals.</para> 
 
 </sect1>
