[glib] Document vendor override files

[Matthias Clasen <matthiasc src gnome org>]

commit ea8a963936655ee3c13c5552cce96c309f8a384f
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Aug 13 21:21:43 2010 -0400

    Document vendor override files
    
    Features without documentation, tsk tsk.

 docs/reference/gio/glib-compile-schemas.xml |    6 +++
 gio/gsettings.c                             |   48 +++++++++++++++++++--------
 2 files changed, 40 insertions(+), 14 deletions(-)
---
diff --git a/docs/reference/gio/glib-compile-schemas.xml b/docs/reference/gio/glib-compile-schemas.xml
index ab2d0b7..9ac5c3e 100644
--- a/docs/reference/gio/glib-compile-schemas.xml
+++ b/docs/reference/gio/glib-compile-schemas.xml
@@ -35,6 +35,12 @@ specified in the <envar>XDG_DATA_DIRS</envar> environment variable. The
 usual location to install schema files is
 <filename>/usr/share/glib-2.0/schemas</filename>.
 </para>
+<para>
+In addition to schema files, glib-compile-schemas reads 'vendor override'
+files, which are key files that can override default values for keys in
+the schemas. The group names in the key files are the schema id, and the
+values are written in serialized GVariant form.
+</para>
 
 <refsect2><title>Options</title>
 <variablelist>
diff --git a/gio/gsettings.c b/gio/gsettings.c
index 4433971..9faac84 100644
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -144,24 +144,44 @@
  * ]]></programlisting></example>
  *
  * <refsect2>
- *  <title>Binding</title>
+ *   <title>Vendor overrides</title>
  *   <para>
- *    A very convenient feature of GSettings lets you bind #GObject properties
- *    directly to settings, using g_settings_bind(). Once a GObject property
- *    has been bound to a setting, changes on either side are automatically
- *    propagated to the other side. GSettings handles details like
- *    mapping between GObject and GVariant types, and preventing infinite
- *    cycles.
+ *     Default values are defined in the schemas that get installed by
+ *     an application. Sometimes, it is necessary for a vendor or distributor
+ *     to adjust these defaults. Since patching the XML source for the schema
+ *     is inconvenient and error-prone,
+ *     <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads
+ *     so-called 'vendor override' files. These are keyfiles in the same
+ *     directory as the XML schema sources which can override default values.
+ *     The schema id serves as the group name in the key file, and the values
+ *     are expected in serialized GVariant form, as in the following example:
+ *     <informalexample><programlisting>
+ *     [org.gtk.Example]
+ *     key1='string'
+ *     key2=1.5
+ *     </programlisting></informalexample>
+ *   </para>
+ * </refsect2>
+ *
+ * <refsect2>
+ *   <title>Binding</title>
+ *   <para>
+ *     A very convenient feature of GSettings lets you bind #GObject properties
+ *     directly to settings, using g_settings_bind(). Once a GObject property
+ *     has been bound to a setting, changes on either side are automatically
+ *     propagated to the other side. GSettings handles details like
+ *     mapping between GObject and GVariant types, and preventing infinite
+ *     cycles.
  *   </para>
  *   <para>
- *    This makes it very easy to hook up a preferences dialog to the
- *    underlying settings. To make this even more convenient, GSettings
- *    looks for a boolean property with the name "sensitivity" and
- *    automatically binds it to the writability of the bound setting.
- *    If this 'magic' gets in the way, it can be suppressed with the
- *    #G_SETTINGS_BIND_NO_SENSITIVITY flag.
+ *     This makes it very easy to hook up a preferences dialog to the
+ *     underlying settings. To make this even more convenient, GSettings
+ *     looks for a boolean property with the name "sensitivity" and
+ *     automatically binds it to the writability of the bound setting.
+ *     If this 'magic' gets in the way, it can be suppressed with the
+ *     #G_SETTINGS_BIND_NO_SENSITIVITY flag.
  *   </para>
- *  </refsect2>
+ * </refsect2>
  **/
 
 struct _GSettingsPrivate