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>
* 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,
......
......@@ -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>
......
......@@ -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
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>
......@@ -684,21 +684,19 @@ to be a Sunday.)
<!-- ##### 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.
......
......@@ -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.
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
......@@ -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>
......
......@@ -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
* character set names. The special token "&commat;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 "&commat;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.
*
......@@ -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.
**/
......
......@@ -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 <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().
......
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