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.
+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,
</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>
<!-- ##### 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
-successfully parsed, the date will be valid after the call. Otherwise,
-it will be invalid. You should check using g_date_valid() to see
-whether the parsing succeeded.
+represents, taking the <link linkend="setlocale">current locale</link>
+into account. If the string is successfully parsed, the date will be
+valid after the call. Otherwise, it will be invalid. You should check
+using g_date_valid() to see whether the parsing succeeded.
</para>
<para>
<!-- ##### FUNCTION g_date_strftime ##### -->
<para>
-Generates a printed representation of the date, in a locale-specific
-way. Works just like the platform's C library
-<function>strftime()</function> function, but only accepts
-date-related formats; time-related formats give undefined
-results. Date must be valid. Unlike <function>strftime()</function>
-(which uses the locale encoding), works on a UTF-8 format string and
-stores a UTF-8 result.
+Generates a printed representation of the date, in a
+<link linkend="setlocale">locale</link>-specific way. Works just like
+the platform's C library strftime() function, but only accepts date-related
+formats; time-related formats give undefined results. Date must be valid.
+Unlike strftime() (which uses the locale encoding), works on a UTF-8 format
+string and 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
-the %F provided by the C99 <function>strftime()</function> work on
-Windows where the C library only complies to C89.
+expect that using g_date_strftime() would make the %F provided by the C99
+strftime() work on Windows where the C library only complies to C89.
</para>
@s: destination buffer.
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.
- For long options, the extra argument can be appended with an equals sign after the
- option name.
+ Options can have an extra argument, which can be a number, a string or a
+ filename. For long options, the extra argument can be appended with an
+ 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
- arguments (even those starting with a dash) are returned to the application as rest
- arguments.
+ An argument consisting solely of two dashes turns off further parsing,
+ any remaining arguments (even those starting with a dash) are returned
+ to the application as rest arguments.
</para></listitem>
</itemizedlist>
</para>
<para>
-Another important feature of GOption is that it can automatically generate nicely
-formatted help output. Unless it is explicitly turned off with
+Another important feature of GOption is that it can automatically generate
+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
<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>
*
* 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.
**/
*
* 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.
**/
* 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
- * character set names. The special token "@locale" is taken to mean the
- * character set for the current locale. If <envar>G_FILENAME_ENCODING</envar>
- * is not set, but <envar>G_BROKEN_FILENAMES</envar> is, the character set of
- * the current locale is taken as the filename encoding. If neither environment
- * variable is set, UTF-8 is taken as the filename encoding, but the character
+ * <envar>G_FILENAME_ENCODING</envar> may be set to a comma-separated list
+ * of character set names. The special token "@locale" is taken to
+ * mean the character set for the <link linkend="setlocale">current
+ * locale</link>. If <envar>G_FILENAME_ENCODING</envar> is not set, but
+ * <envar>G_BROKEN_FILENAMES</envar> is, the character set of the current
+ * 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
- * system might be in any random encoding or just gibberish.
+ * <envar>G_FILENAME_ENCODING</envar> value, the actual file names present
+ * on a system might be in any random encoding or just gibberish.
*
* Return value: %TRUE if the filename encoding is UTF-8.
*
*
* 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.
**/
* 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.
**/
* g_get_charset:
* @charset: return location for character set name
*
- * Obtains the character set for the current locale; you might use
- * this character set as an argument to g_convert(), to convert from
- * the current locale's encoding to some other encoding. (Frequently
- * g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts,
- * though.)
+ * Obtains the character set for the <link linkend="setlocale">current
+ * locale</link>; you might use this character set as an argument to
+ * g_convert(), to convert from the current locale's encoding to some
+ * other encoding. (Frequently g_locale_to_utf8() and g_locale_from_utf8()
+ * 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().
projects / platform / upstream / glib.git / commitdiff