Add an i18n section. Include the corresponding entity. Template for i18n

Thu Nov  6 01:42:36 2003  Matthias Clasen  <maclas@gmx.de>

	* glib/glib-sections.txt: Add an i18n section.
	* glib/glib-docs.sgml: Include the corresponding entity.
	* glib/tmpl/i18n.sgml: Template for i18n section.

Thu Nov  6 00:56:04 2003  Matthias Clasen  <maclas@gmx.de>

	* glib/running.sgml: Document G_FILENAME_ENCODING.

docs/reference/ChangeLog

@@ -1,3 +1,13 @@
+Thu Nov  6 01:42:36 2003  Matthias Clasen  <maclas@gmx.de>
+
+	* glib/glib-sections.txt: Add an i18n section.
+	* glib/glib-docs.sgml: Include the corresponding entity.
+	* glib/tmpl/i18n.sgml: Template for i18n section.
+
+Thu Nov  6 00:56:04 2003  Matthias Clasen  <maclas@gmx.de>
+
+	* glib/running.sgml: Document G_FILENAME_ENCODING.
+
 Sat Oct 25 01:07:45 2003  Matthias Clasen  <maclas@gmx.de>
 
 	* gobject/tmpl/gparamspec.sgml: 

docs/reference/glib/glib-docs.sgml

@@ -53,6 +53,7 @@
 <!ENTITY glib-Fileutils SYSTEM "xml/fileutils.xml">
 <!ENTITY glib-Shell SYSTEM "xml/shell.xml">
 <!ENTITY glib-Markup SYSTEM "xml/markup.xml">
+<!ENTITY glib-i18n SYSTEM "xml/i18n.xml">
 
 <!ENTITY glib-Compiling SYSTEM "compiling.sgml">
 <!ENTITY glib-Building SYSTEM "building.sgml">
@@ -126,6 +127,7 @@ synchronize their operation.
     &glib-String-Utility-Functions;
     &glib-Character-Set-Conversion;
     &glib-Unicode-Manipulation;
+    &glib-i18n;
     &glib-Date-and-Time-Functions;
     &glib-Random-Numbers;   
     &glib-Hook-Functions;

docs/reference/glib/glib-sections.txt

@@ -1960,3 +1960,14 @@ g_ucs4_to_utf16
 g_ucs4_to_utf8
 g_unichar_to_utf8
 </SECTION>
+
+<SECTION>
+<TITLE>I18N</TITLE>
+<FILE>i18n</FILE>
+<INCLUDE>glib.h,glib/gi18n.h</INCLUDE>
+_
+Q_
+N_
+g_strip_context
+
+</SECTION>

docs/reference/glib/running.sgml

@@ -23,12 +23,24 @@ GLib inspects a few of environment variables in addition to standard
 variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>. 
 </para>
 
+<formalpara>
+  <title><envar>G_FILENAME_ENCODING</envar></title>
+
+  <para>
+    This environment variable can be set to a comma-separated list of character
+    set names. GLib assumes that filenames are encoded in the first character 
+    set from that list rather than in UTF-8. The special token "@locale" can be
+    used to specify the character set for the current locale.
+  </para>
+</formalpara>
+
 <formalpara>
   <title><envar>G_BROKEN_FILENAMES</envar></title>
 
   <para>
     If this environment variable is set, GLib assumes that filenames are in 
-    the locale encoding rather than in UTF-8.
+    the locale encoding rather than in UTF-8. G_FILENAME_ENCODING takes
+    priority over G_BROKEN_FILENAMES. 
   </para>
 </formalpara>
 

docs/reference/glib/tmpl/i18n.sgml

@@ -0,0 +1,95 @@
+<!-- ##### SECTION Title ##### -->
+Internationalization
+
+<!-- ##### SECTION Short_Description ##### -->
+gettext support macros.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+GLib doesn't force any particular localization method upon its users.
+But since GLib itself is localized using the gettext() mechanism, it seems
+natural to offer the de-facto standard gettext() support macros in an 
+easy-to-use form.
+</para>
+<para>
+In order to use these macros in an application, you must include 
+<filename>glib/gi18n.h</filename>. For use in a library, must include
+<filename>glib/gi18n-lib.h</filename> <emphasis>after</emphasis> defining
+the GETTEXT_PACKAGE macro suitably for your library:
+<informalexample><programlisting>
+&num;define GETTEXT_PACKAGE "gtk20"
+&num;include &lt;glib/gi18n-lib.h&gt;
+</programlisting></informalexample>
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+The gettext manual.
+</para>
+
+
+<!-- ##### MACRO _ ##### -->
+<para>
+Marks a string for translation, gets replaced with the translated string
+at runtime.
+</para>
+
+@String: the string to be translated
+@Since: 2.4
+
+<!-- ##### MACRO Q_ ##### -->
+<para>
+Like _(), but applies g_strip_context() to the translation. This has the
+advantage that the string can be adorned with a prefix to guarantee 
+uniqueness and provide context to the translator.
+</para>
+<para>
+One use case given in the gettext manual is GUI translation, where one could 
+e.g. disambiguate two "Open" menu entries as "File|Open" and "Printer|Open". 
+Another use case is the string "Russian" which may have to be translated
+differently depending on whether it's the name of a character set or a 
+language. This could be solved by using "charset|Russian" and 
+"language|Russian".
+</para>
+
+@String: the string to be translated, with a '|'-separated prefix which 
+  must not be translated
+@Since: 2.4
+
+
+<!-- ##### MACRO N_ ##### -->
+<para>
+Marks a string for translation, gets replaced with the untranslated string
+at runtime. This is useful in situations where the translated strings can't
+be directly used, e.g. in string array initializers. 
+</para>
+<informalexample><programlisting>
+     {
+       static const char *messages[] = {
+         N_("some very meaningful message"),
+         N_("and another one")
+       };
+       const char *string;
+       ...
+       string
+         = index &gt; 1 ? _("a default message") : gettext (messages[index]);
+<!-- -->     
+       fputs (string);
+       ...
+     }
+</programlisting></informalexample>
+
+@String: the string to be translated
+@Since: 2.4
+
+
+<!-- ##### FUNCTION g_strip_context ##### -->
+<para>
+
+</para>
+
+@msgid: 
+@msgval: 
+@Returns: 
+
+