Commit 3ab1139a authored by Matthias Clasen's avatar Matthias Clasen Committed by Matthias Clasen

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.
parent 63534187
2006-12-26 Matthias Clasen <mclasen@redhat.com> 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 * glib/gconvert.c (g_get_filename_charsets): Improve
formatting of docs. 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> 2006-12-18 Matthias Clasen <mclasen@redhat.com>
* glib/tmpl/keyfile.sgml: Small clarification (#369908, * glib/tmpl/keyfile.sgml: Small clarification (#369908,
......
...@@ -180,6 +180,16 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>. ...@@ -180,6 +180,16 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
</refsect2> </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> <refsect2>
<title>Traps and traces</title> <title>Traps and traces</title>
......
...@@ -397,10 +397,10 @@ Sets the value of a #GDate from a Julian day number. ...@@ -397,10 +397,10 @@ Sets the value of a #GDate from a Julian day number.
<!-- ##### FUNCTION g_date_set_parse ##### --> <!-- ##### FUNCTION g_date_set_parse ##### -->
<para> <para>
Parses a user-inputted string @str, and try to figure out what date it 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>
<para> <para>
...@@ -684,21 +684,19 @@ to be a Sunday.) ...@@ -684,21 +684,19 @@ to be a Sunday.)
<!-- ##### FUNCTION g_date_strftime ##### --> <!-- ##### FUNCTION g_date_strftime ##### -->
<para> <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>
<para> <para>
This function does not provide any conversion specifiers in addition This function does not provide any conversion specifiers in addition
to those implemented by the platform's C library. For example, don't 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> </para>
@s: destination buffer. @s: destination buffer.
......
...@@ -26,24 +26,24 @@ The example demonstrates a number of features of the GOption commandline parser ...@@ -26,24 +26,24 @@ The example demonstrates a number of features of the GOption commandline parser
Long options are prefixed by two consecutive dashes. Long options are prefixed by two consecutive dashes.
</para></listitem> </para></listitem>
<listitem><para> <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> </para></listitem>
<listitem><para> <listitem><para>
Non-option arguments are returned to the application as rest arguments. Non-option arguments are returned to the application as rest arguments.
</para></listitem> </para></listitem>
<listitem><para> <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> </para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<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 g_option_context_set_help_enabled(), GOption will recognize the
<option>--help</option>, <option>-?</option>, <option>--help-all</option> <option>--help</option>, <option>-?</option>, <option>--help-all</option>
and <option>--help-</option><replaceable>groupname</replaceable> options 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. ...@@ -80,7 +80,8 @@ to g_option_context_parse(). See gtk_get_option_group() for an example.
<para> <para>
If an option is declared to be of type string or filename, GOption takes 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, 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>
<para> <para>
......
...@@ -1050,7 +1050,8 @@ strdup_len (const gchar *string, ...@@ -1050,7 +1050,8 @@ strdup_len (const gchar *string,
* *
* Converts a string which is in the encoding used for strings by * Converts a string which is in the encoding used for strings by
* the C runtime (usually the same as that used by the operating * 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. * Return value: The converted string, or %NULL on an error.
**/ **/
...@@ -1090,7 +1091,7 @@ g_locale_to_utf8 (const gchar *opsysstring, ...@@ -1090,7 +1091,7 @@ g_locale_to_utf8 (const gchar *opsysstring,
* *
* Converts a string from UTF-8 to the encoding used for strings by * 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 * 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. * Return value: The converted string, or %NULL on an error.
**/ **/
...@@ -1144,19 +1145,20 @@ filename_charset_cache_free (gpointer data) ...@@ -1144,19 +1145,20 @@ filename_charset_cache_free (gpointer data)
* used in the GLib API is always UTF-8 and said environment variables * used in the GLib API is always UTF-8 and said environment variables
* have no effect. * 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. * set of the current locale is also put in the list of encodings.
* *
* The returned @charsets belong to GLib and must not be freed. * The returned @charsets belong to GLib and must not be freed.
* *
* Note that on Unix, regardless of the locale character set or * 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. * Return value: %TRUE if the filename encoding is UTF-8.
* *
...@@ -1300,7 +1302,8 @@ _g_convert_thread_init (void) ...@@ -1300,7 +1302,8 @@ _g_convert_thread_init (void)
* *
* Converts a string which is in the encoding used by GLib for * 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 * 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. * Return value: The converted string, or %NULL on an error.
**/ **/
...@@ -1363,7 +1366,9 @@ g_filename_to_utf8 (const gchar *opsysstring, ...@@ -1363,7 +1366,9 @@ g_filename_to_utf8 (const gchar *opsysstring,
* errors. Any of the errors in #GConvertError may occur. * errors. Any of the errors in #GConvertError may occur.
* *
* Converts a string from UTF-8 to the encoding GLib uses for * 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. * Return value: The converted string, or %NULL on an error.
**/ **/
......
...@@ -504,11 +504,11 @@ charset_cache_free (gpointer data) ...@@ -504,11 +504,11 @@ charset_cache_free (gpointer data)
* g_get_charset: * g_get_charset:
* @charset: return location for character set name * @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 * The return value is %TRUE if the locale's encoding is UTF-8, in that
* case you can perhaps avoid calling g_convert(). * case you can perhaps avoid calling g_convert().
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment