diff --git a/ChangeLog b/ChangeLog index f6c957823..6ff976dec 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,8 @@ 2006-12-26 Matthias Clasen + * 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. diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index a4bbd6927..38055fe80 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,9 @@ +2006-12-27 Matthias Clasen + + * glib/running.sgml: + * glib/tmpl/option.sgml: + * glib/tmpl/date.sgml: Add hints for locale-dependent functions. + 2006-12-18 Matthias Clasen * glib/tmpl/keyfile.sgml: Small clarification (#369908, diff --git a/docs/reference/glib/running.sgml b/docs/reference/glib/running.sgml index e38178cd7..0e65ad990 100644 --- a/docs/reference/glib/running.sgml +++ b/docs/reference/glib/running.sgml @@ -180,6 +180,16 @@ variables like LANG, PATH or HOME. + +Locale + + +A number of interfaces in GLib depend on the current locale in which +an application is running. Therefore, most GLib-using applications should +call setlocale (LC_ALL, "") to set up the current +locale. + + Traps and traces diff --git a/docs/reference/glib/tmpl/date.sgml b/docs/reference/glib/tmpl/date.sgml index 4ae06be5d..9879963d8 100644 --- a/docs/reference/glib/tmpl/date.sgml +++ b/docs/reference/glib/tmpl/date.sgml @@ -397,10 +397,10 @@ Sets the value of a #GDate from a Julian day number. 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 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. @@ -684,21 +684,19 @@ to be a Sunday.) -Generates a printed representation of the date, in a locale-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. +Generates a printed representation of the date, in a +locale-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. 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 g_date_strftime() would make -the %F provided by the C99 strftime() 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. @s: destination buffer. diff --git a/docs/reference/glib/tmpl/option.sgml b/docs/reference/glib/tmpl/option.sgml index 5e895ba7f..fe7dcf993 100644 --- a/docs/reference/glib/tmpl/option.sgml +++ b/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. - 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. Non-option arguments 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. + 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. -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 , , and groupname options @@ -80,7 +80,8 @@ to g_option_context_parse(). See gtk_get_option_group() for an example. 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(). diff --git a/glib/gconvert.c b/glib/gconvert.c index 0d27ed0f1..dcc798bf7 100644 --- a/glib/gconvert.c +++ b/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 current locale 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 current locale. * * 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. * - * G_FILENAME_ENCODING 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 G_FILENAME_ENCODING - * is not set, but G_BROKEN_FILENAMES 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 + * G_FILENAME_ENCODING 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 G_FILENAME_ENCODING is not set, but + * G_BROKEN_FILENAMES 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 - * G_FILENAME_ENCODING value, the actual file names present on a - * system might be in any random encoding or just gibberish. + * G_FILENAME_ENCODING 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. * @@ -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 current locale. * * 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 + * current locale. * * Return value: The converted string, or %NULL on an error. **/ diff --git a/glib/gutf8.c b/glib/gutf8.c index f9b719d2c..4b91334e0 100644 --- a/glib/gutf8.c +++ b/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 - * 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 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.) * * The return value is %TRUE if the locale's encoding is UTF-8, in that * case you can perhaps avoid calling g_convert().