From dc8b03027d905bf22527aeaa7e31ad072231197a Mon Sep 17 00:00:00 2001
From: Ray Strode <rstrode@redhat.com>
Date: Mon, 17 Jan 2011 17:13:44 -0500
Subject: [PATCH] gsettings: Update documentation on schema naming convention

The existing docs are a bit inconsistent in that they say to follow
the dbus convention, but then give an example that doesn't.

This commit changes things to be how Ryan says they should be.
---
 docs/reference/gio/migrating-gconf.xml | 10 ++++++----
 gio/gsettings.c                        | 10 +++++++---
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/docs/reference/gio/migrating-gconf.xml b/docs/reference/gio/migrating-gconf.xml
index 44d455b..9e9f1a0 100644
--- a/docs/reference/gio/migrating-gconf.xml
+++ b/docs/reference/gio/migrating-gconf.xml
@@ -205,14 +205,16 @@ produces a <filename>org.gnome.font-rendering.gschema.xml</filename> file with t
       </example>
 
       <para>
-        GSettings schemas are identified at runtime by their id (as specified
-        in the XML source file). It is recommended to use a dotted name as schema
-        id, similar in style to a DBus bus name, e.g. "org.gnome.font-rendering".
+       GSettings schemas are identified at runtime by their id (as specified
+       in the XML source file). It is recommended to use a dotted name as schema
+       id, similar in style to a D-Bus bus name, e.g. "org.gnome.SessionManager".
+       In cases where the settings are general and not specific to one application,
+       the id should not use StudlyCaps, e.g. "org.gnome.font-rendering".
        The filename used for the XML schema source is immaterial, but
        schema compiler expects the files to have the extension
        <filename>.gschema.xml</filename>. It is recommended to simply
        use the schema id as the filename, followed by this extension,
-       e.g. <filename>org.gnome.font-rendering.gschema.xml</filename>.
+       e.g. <filename>org.gnome.SessionManager.gschema.xml</filename>.
       </para>
 
       <para>
diff --git a/gio/gsettings.c b/gio/gsettings.c
index ec48006..1d0dc56 100644
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -83,7 +83,11 @@
  * in the <tag class="attribute">id</tag> attribute of the
  * <tag class="starttag">schema</tag> element). The
  * convention for schema ids is to use a dotted name, similar in
- * style to a DBus bus name, e.g. "org.gnome.font-rendering".
+ * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular,
+ * if the settings are for a specific service that owns a D-Bus bus name,
+ * the D-Bus bus name and schema id should match. For schemas which deal
+ * with settings not associated with one named application, the id should
+ * not use StudlyCaps, e.g. "org.gnome.font-rendering".
  *
  * In addition to #GVariant types, keys can have types that have enumerated
  * types. These can be described by a <tag class="starttag">choice</tag>,
@@ -97,7 +101,7 @@
  * <example id="schema-default-values"><title>Default values</title>
  * <programlisting><![CDATA[
  * <schemalist>
- *   <schema id="org.gtk.test" path="/tests/" gettext-domain="test">
+ *   <schema id="org.gtk.Test" path="/tests/" gettext-domain="test">
  *
  *     <key name="greeting" type="s">
  *       <default l10n="messages">"Hello, earthlings"</default>
@@ -130,7 +134,7 @@
  *     <value nick="flag3" value="4"/>
  *   </enum>
  *
- *   <schema id="org.gtk.test">
+ *   <schema id="org.gtk.Test">
  *
  *     <key name="key-with-range" type="i">
  *       <range min="1" max="100"/>
-- 
2.7.4