Add hints for locale-dependent interfaces. Add hints for locale-dependent

2006-12-26  Matthias Clasen  <mclasen@redhat.com>

        * glib/gutf8.c: Add hints for locale-dependent interfaces.
        * glib/gconvert.c: Add hints for locale-dependent interfaces.

ChangeLog

@@ -1,5 +1,8 @@
 2006-12-26  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/gutf8.c: Add hints for locale-dependent interfaces.
+	* glib/gconvert.c: Add hints for locale-dependent interfaces.
+
 	* glib/gconvert.c (g_get_filename_charsets): Improve
 	formatting of docs. 
 

docs/reference/ChangeLog

@@ -1,3 +1,9 @@
+2006-12-27  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/running.sgml:
+	* glib/tmpl/option.sgml:
+	* glib/tmpl/date.sgml: Add hints for locale-dependent functions.
+
 2006-12-18  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/tmpl/keyfile.sgml: Small clarification (#369908,

docs/reference/glib/running.sgml

@@ -180,6 +180,16 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
 
 </refsect2>
 
+<refsect2 id="setlocale">
+<title>Locale</title>
+
+<para>
+A number of interfaces in GLib depend on the current locale in which
+an application is running. Therefore, most GLib-using applications should
+call <function>setlocale (LC_ALL, "")</function> to set up the current 
+locale.
+</para>
+
 <refsect2>
 <title>Traps and traces</title>
 

docs/reference/glib/tmpl/date.sgml

@@ -397,10 +397,10 @@ Sets the value of a #GDate from a Julian day number.
 <!-- ##### FUNCTION g_date_set_parse ##### -->
 <para>
 Parses a user-inputted string @str, and try to figure out what date it
-represents, taking the current locale into account. If the string is
+represents, taking the <link linkend="setlocale">current locale</link> 
-successfully parsed, the date will be valid after the call. Otherwise,
+into account. If the string is successfully parsed, the date will be 
-it will be invalid. You should check using g_date_valid() to see
+valid after the call. Otherwise, it will be invalid. You should check 
-whether the parsing succeeded.
+using g_date_valid() to see whether the parsing succeeded.
 </para>
 
 <para>
@@ -684,21 +684,19 @@ to be a Sunday.)
 
 <!-- ##### FUNCTION g_date_strftime ##### -->
 <para>
-Generates a printed representation of the date, in a locale-specific
+Generates a printed representation of the date, in a 
-way. Works just like the platform's C library
+<link linkend="setlocale">locale</link>-specific way. Works just like 
-<function>strftime()</function> function, but only accepts
+the platform's C library strftime() function, but only accepts date-related 
-date-related formats; time-related formats give undefined
+formats; time-related formats give undefined results. Date must be valid. 
-results. Date must be valid. Unlike <function>strftime()</function>
+Unlike strftime() (which uses the locale encoding), works on a UTF-8 format 
-(which uses the locale encoding), works on a UTF-8 format string and
+string and stores a UTF-8 result.
-stores a UTF-8 result.
 </para>
 
 <para>
 This function does not provide any conversion specifiers in addition
 to those implemented by the platform's C library. For example, don't
-expect that using <function>g_date_strftime()</function> would make
+expect that using g_date_strftime() would make the %F provided by the C99 
-the %F provided by the C99 <function>strftime()</function> work on
+strftime() work on Windows where the C library only complies to C89.
-Windows where the C library only complies to C89.
 </para>
 
 @s: destination buffer.

docs/reference/glib/tmpl/option.sgml

@@ -26,24 +26,24 @@ The example demonstrates a number of features of the GOption commandline parser
   Long options are prefixed by two consecutive dashes.
 </para></listitem>
 <listitem><para>
-  Options can have an extra argument, which can be a number, a string or a filename.
+  Options can have an extra argument, which can be a number, a string or a 
-  For long options, the extra argument can be appended with an equals sign after the
+  filename. For long options, the extra argument can be appended with an 
-  option name.
+  equals sign after the option name.
 </para></listitem>
 <listitem><para>
   Non-option arguments are returned to the application as rest arguments.
 </para></listitem>
 <listitem><para>
-  An argument consisting solely of two dashes turns off further parsing, any remaining
+  An argument consisting solely of two dashes turns off further parsing, 
-  arguments (even those starting with a dash) are returned to the application as rest 
+  any remaining arguments (even those starting with a dash) are returned 
-  arguments.
+  to the application as rest arguments.
 </para></listitem>
 </itemizedlist>
 </para>
 
 <para>
-Another important feature of GOption is that it can automatically generate nicely
+Another important feature of GOption is that it can automatically generate 
-formatted help output. Unless it is explicitly turned off with 
+nicely formatted help output. Unless it is explicitly turned off with 
 g_option_context_set_help_enabled(), GOption will recognize the 
 <option>--help</option>, <option>-?</option>, <option>--help-all</option>
 and <option>--help-</option><replaceable>groupname</replaceable> options 
@@ -80,7 +80,8 @@ to g_option_context_parse(). See gtk_get_option_group() for an example.
 <para>
 If an option is declared to be of type string or filename, GOption takes
 care of converting it to the right encoding; strings are returned in UTF-8,
-filenames are returned in the GLib filename encoding.
+filenames are returned in the GLib filename encoding. Note that this only
+works if setlocale() has been called before g_option_context_parse().
 </para>
 
 <para>

glib/gconvert.c

@@ -1050,7 +1050,8 @@ strdup_len (const gchar *string,
  * 
  * Converts a string which is in the encoding used for strings by
  * the C runtime (usually the same as that used by the operating
- * system) in the current locale into a UTF-8 string.
+ * system) in the <link linkend="setlocale">current locale</link> into a
+ * UTF-8 string.
  * 
  * Return value: The converted string, or %NULL on an error.
  **/
@@ -1090,7 +1091,7 @@ g_locale_to_utf8 (const gchar  *opsysstring,
  * 
  * Converts a string from UTF-8 to the encoding used for strings by
  * the C runtime (usually the same as that used by the operating
- * system) in the current locale.
+ * system) in the <link linkend="setlocale">current locale</link>.
  * 
  * Return value: The converted string, or %NULL on an error.
  **/
@@ -1144,19 +1145,20 @@ filename_charset_cache_free (gpointer data)
  * used in the GLib API is always UTF-8 and said environment variables
  * have no effect.
  *
- * <envar>G_FILENAME_ENCODING</envar> may be set to a comma-separated list of 
+ * <envar>G_FILENAME_ENCODING</envar> may be set to a comma-separated list 
- * character set names. The special token "&commat;locale" is taken to mean the
+ * of character set names. The special token "&commat;locale" is taken to 
- * character set for the current locale. If <envar>G_FILENAME_ENCODING</envar> 
+ * mean the character set for the <link linkend="setlocale">current 
- * is not set, but <envar>G_BROKEN_FILENAMES</envar> is, the character set of 
+ * locale</link>. If <envar>G_FILENAME_ENCODING</envar> is not set, but 
- * the current locale is taken as the filename encoding. If neither environment
+ * <envar>G_BROKEN_FILENAMES</envar> is, the character set of the current 
- * variable is set, UTF-8 is taken as the filename encoding, but the character
+ * locale is taken as the filename encoding. If neither environment variable 
+ * is set, UTF-8 is taken as the filename encoding, but the character
  * set of the current locale is also put in the list of encodings.
  *
  * The returned @charsets belong to GLib and must not be freed.
  *
  * Note that on Unix, regardless of the locale character set or
- * <envar>G_FILENAME_ENCODING</envar> value, the actual file names present on a
+ * <envar>G_FILENAME_ENCODING</envar> value, the actual file names present 
- * system might be in any random encoding or just gibberish.
+ * on a system might be in any random encoding or just gibberish.
  *
  * Return value: %TRUE if the filename encoding is UTF-8.
  * 
@@ -1300,7 +1302,8 @@ _g_convert_thread_init (void)
  * 
  * Converts a string which is in the encoding used by GLib for
  * filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
- * for filenames.
+ * for filenames; on other platforms, this function indirectly depends on 
+ * the <link linkend="setlocale">current locale</link>.
  * 
  * Return value: The converted string, or %NULL on an error.
  **/
@@ -1363,7 +1366,9 @@ g_filename_to_utf8 (const gchar *opsysstring,
  *                 errors. Any of the errors in #GConvertError may occur.
  * 
  * Converts a string from UTF-8 to the encoding GLib uses for
- * filenames. Note that on Windows GLib uses UTF-8 for filenames.
+ * filenames. Note that on Windows GLib uses UTF-8 for filenames;
+ * on other platforms, this function indirectly depends on the 
+ * <link linkend="setlocale">current locale</link>.
  * 
  * Return value: The converted string, or %NULL on an error.
  **/

glib/gutf8.c

@@ -504,11 +504,11 @@ charset_cache_free (gpointer data)
  * g_get_charset:
  * @charset: return location for character set name
  * 
- * Obtains the character set for the current locale; you might use
+ * Obtains the character set for the <link linkend="setlocale">current 
- * this character set as an argument to g_convert(), to convert from
+ * locale</link>; you might use this character set as an argument to 
- * the current locale's encoding to some other encoding. (Frequently
+ * g_convert(), to convert from the current locale's encoding to some 
- * g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts,
+ * other encoding. (Frequently g_locale_to_utf8() and g_locale_from_utf8()
- * though.)
+ * are nice shortcuts, though.)
  *
  * The return value is %TRUE if the locale's encoding is UTF-8, in that
  * case you can perhaps avoid calling g_convert().