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	11 Nov 2002 20:01:46 -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	11 Nov 2002 20:02:07 -0000
@@ -352,11 +352,33 @@
 <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>Unfortunately, the integration with the standard iostreams is
+not completely foolproof. <literal>gtkmm</literal> converts
+Glib::ustrings to a locale-specific encoding (which usually is not
+UTF-8) if you output them to an <literal>ostream</literal> with
+<literal>operator&lt;&lt;</literal>. Likewise, retrieving
+Glib::ustrings from <literal>istream</literal> with
+<literal>operator&gt;&gt;</literal> causes a conversion in the
+opposite direction. But this scheme breaks down if you go through a
+std::string, e.g. by inputting text from a stream to a std::string and
+then implicitly converting it to a Glib::ustring. If the string
+contained non-ASCII characters and the current locale is not UTF-8
+encoded, the result is a corrupted Glib::ustring. You can work around
+this with a manual conversion. For instance, to retrieve the
+std::string from a <literal>ostringstream</literal>:</para>
+<programlisting>
+std::ostringstream output;
+output.imbue(std::locale("")); // use the user's locale for this stream
+output &lt;&lt; percentage &lt;&lt; " % done";
+label-&gt;set_text(Glib::locale_to_utf8(output.str()));
+</programlisting>
+      
 <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>
