From 61af83c5b6a632448e9330eedebf7f8aa225f2e3 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Thu, 17 Jun 2010 01:38:14 -0400
Subject: [PATCH] Add some schema examples

---
 gio/gsettings.c | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 2 deletions(-)

diff --git a/gio/gsettings.c b/gio/gsettings.c
index 1cd8289..3b31485 100644
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -79,7 +79,7 @@
  * utility. The input is a schema description in an XML format that can be
  * described by the following DTD:
  * |[<![CDATA[
- * <!ELEMENT schemalist (schema*) >
+ * <!ELEMENT schemalist (schema|enum)* >
  * <!ATTLIST schemalist gettext-domain #IMPLIED >
  *
  * <!ELEMENT schema (key|child)* >
@@ -87,11 +87,24 @@
  *                  path           CDATA #IMPLIED
  *                  gettext-domain CDATA #IMPLIED >
  *
+ * <!-- defines an enumerated type -->
+ * <!-- each value element maps a nick to a numeric value -->
+ * <!ELEMENT enum (value*) >
+ * <!ATTLIST enum id CDATA #REQUIRED >
+ * <!ELEMENT value EMPTY >
+ * <!-- nick must be at least 2 characters long -->
+ * <!-- value must be parsable as a 32-bit integer -->
+ * <!ELEMENT value nick  #REQUIRED
+ *                 value #REQUIRED >
+ *
  * <!ELEMENT key (default|summary?|description?|range?|choices?|aliases?) >
  * <!-- name can only contain lowercase letters, numbers and '-' -->
  * <!-- type must be a GVariant type string -->
+ * <!-- enum must be the id of an enum that has been defined earlier -->
+ * <!-- exactly one of enum or type must be given -->
  * <!ATTLIST key name CDATA #REQUIRED
- *               type CDATA #REQUIRED >
+ *               type CDATA #IMPLIED
+ *               enum CDATA #IMPLIED >
  *
  * <!-- the default value is specified a a serialized GVariant,
  *      i.e. you have to include the quotes when specifying a string -->
@@ -105,14 +118,21 @@
  * <!ELEMENT summary (#PCDATA) >
  * <!ELEMENT description (#PCDATA) >
  *
+ * <!-- range is only allowed for keys with numeric type -->
  * <!ELEMENT range EMPTY >
+ * <!-- min and max must be parseable as values of the key type and min < max -->
  * <!ATTLIST range min CDATA #REQUIRED
  *                 max CDATA #REQUIRED >
  *
+ * <!-- choices is only allowed for keys with string or string array type -->
  * <!ELEMENT choices (choice+) >
+ * <!-- each choice element specifies one possible value -->
  * <!ELEMENT choice EMPTY >
  * <!ATTLIST choice value CDATA #REQUIRED >
+ *
+ * <!-- aliases is only allowed for keys with enumerated type or with choices -->
  * <!ELEMENT aliases (alias+) >
+ * <!-- each alias element specifies an alias for one of the possible values -->
  * <!ELEMENT alias EMPTY >
  * <!ATTLIST alias value CDATA #REQUIRED >
  *
@@ -128,6 +148,64 @@
  * convention for schema ids is to use a dotted name, similar in
  * style to a DBus bus name, e.g. "org.gnome.font-rendering".
  *
+ * <example><title>Default values</title>
+ * <programlisting><![CDATA[
+ * <schemalist>
+ *   <schema id="org.gtk.test" path="/tests/" gettext-domain="test">
+ *     
+ *     <key name="greeting" type="s">
+ *       <default l10n="messages">"Hello, earthlings"</default>
+ *       <summary>A greeting</summary>
+ *       <description>
+ *         Greeting of the invading martians
+ *       </description>
+ *     </key>
+ *      
+ *     <key name="box" type="(ii)">
+ *       <default>(20,30)</default>
+ *     </key>
+ *      
+ *   </schema>
+ * </schemalist>
+ * ]]></programlisting></example>
+ *
+ * <example><title>Ranges, choices and enumerated types</title>
+ * <programlisting><![CDATA[
+ * <schemalist>
+ *     
+ *   <enum id="myenum">
+ *     <value nick="first" value="1"/>
+ *     <value nick="second" value="2"/>
+ *   </enum>
+ *      
+ *   <schema id="org.gtk.test">
+ *     
+ *     <key name="key-with-range" type="i">
+ *       <range min="1" max="100"/>
+ *       <default>10</default>
+ *     </key>
+ *      
+ *     <key name="key-with-choices" type="s">
+ *       <choices>
+ *         <choice value='Elisabeth'/>
+ *         <choice value='Annabeth'/>
+ *         <choice value='Joe'/>
+ *       </choices>
+ *       <aliases>
+ *         <alias value="Annabeth" alias="Anna"/>
+ *         <alias value="Elisabeth" alias="Beth"/>
+ *       </aliases>
+ *       <default>'Joe'</default>
+ *     </key>
+ *      
+ *     <key name="enumerated-key" enum="myenum">
+ *       <default>'first'</default>
+ *     </key>
+ *      
+ *   </schema>
+ * </schemalist>
+ * ]]></programlisting></example>
+ *
  * <refsect2>
  *  <title>Binding</title>
  *   <para>
-- 
2.7.4