From 9e8ebbbdfb83bd4bdd61eb3454300c2749232d43 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Thu, 28 Oct 2004 18:38:07 +0000
Subject: [PATCH] Add some introductory notes.

2004-10-28  Matthias Clasen  <mclasen@redhat.com>

	* glib/tmpl/keyfile.sgml: Add some introductory notes.
---
 docs/reference/ChangeLog              |  4 ++
 docs/reference/glib/tmpl/keyfile.sgml | 79 +++++++++++++++++++++++++++
 2 files changed, 83 insertions(+)

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 554734666..4c590cacd 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,7 @@
+2004-10-28  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/tmpl/keyfile.sgml: Add some introductory notes.
+
 2004-10-27 Matthias Clasen  <mclasen@redhat.com>
 
 	* === Released 2.5.4 ===
diff --git a/docs/reference/glib/tmpl/keyfile.sgml b/docs/reference/glib/tmpl/keyfile.sgml
index f64104cc3..de3d450c4 100644
--- a/docs/reference/glib/tmpl/keyfile.sgml
+++ b/docs/reference/glib/tmpl/keyfile.sgml
@@ -6,7 +6,86 @@ parses <filename>.ini</filename>-like config files
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+#GKeyFile lets you parse, edit or create files containing groups of
+key-value pairs, which we call <firstterm>key files</firstterm> for 
+lack of a better name. Several freedesktop.org specifications use
+key files now, e.g the 
+<ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
+Entry Specification</ulink> and the
+<ulink url="http://freedesktop.org/Standards/icon-theme-spec">Icon
+Theme Specification</ulink>. 
+</para>
 
+<para>
+The syntax of key files is described in detail in the 
+<ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
+Entry Specification</ulink>, here is a quick summary: Key files
+consists of groups of key-value pairs, interspersed with comments.
+</para>
+
+<informalexample><programlisting>
+# this is just an example
+# there can be comments before the first group
+
+[First Group]
+
+Name=Key File Example\tthis value shows\nescaping
+
+# localized strings are stored in multiple key-value pairs
+Welcome=Hello
+Welcome[de]=Hallo
+Welcome[fr]=Bonjour
+Welcome[it]=Ciao
+
+[Another Group]
+
+Numbers=2;20;-200;0
+
+Booleans=true;false;true;true
+
+</programlisting></informalexample>
+
+<para>
+Lines beginning with a '#' and blank lines are considered comments.
+</para>
+
+<para>
+Groups are started by a header line containing the group name enclosed
+in '[' and ']', and ended implicitly by the start of the next group or
+the end of the file. Each key-value pair must be contained in a group.
+</para>
+
+<para>
+Key-value pairs generally have the form <literal>key=value</literal>, 
+with the exception of localized strings, which have the form 
+<literal>key[locale]=value</literal>. Space before and after the 
+'=' character are ignored. Newline, tab, carriage return and backslash 
+characters are escaped as \n, \t, \r, and \\, respectively. To preserve
+initial and final spaces, these can also be escaped as \s.
+</para>
+
+<para>
+Key files can store strings (possibly with localized variants), integers,
+booleans and lists of these. Lists are separated by a separator character,
+typically ';' or ','. To use the list separator character in a value in
+a list, it has to be escaped by prefixing it with a backslash.
+</para>
+
+<para>
+This syntax is obviously inspired by the <filename>.ini</filename> 
+files commonly met on Windows, but there are some important differences:
+<itemizedlist>
+<listitem><para>
+<filename>.ini</filename> files use the ';' character to begin comments,
+ key files use the '#' character.
+</para></listitem>
+<listitem><para>
+Key files allow only comments before the first group.
+</para></listitem>
+<listitem><para>
+Key files are always encoded in UTF-8.
+</para></listitem>
+</itemizedlist>
 </para>
 
 <!-- ##### SECTION See_Also ##### -->