Flesh out the porting guide some more

docs/reference/gio/migrating.xml

@@ -229,6 +229,8 @@ start_monitoring_trash (void)
               <row><entry>GConfClient</entry><entry>GSettings</entry></row>
             </thead>
             <tbody>
+              <row><entry>gconf_client_get_default()</entry><entry>no direct equivalent,
+                                                                   instead you call g_settings_new() for the schemas you use</entry></row>
               <row><entry>gconf_client_set()</entry><entry>g_settings_set()</entry></row>
               <row><entry>gconf_client_get()</entry><entry>g_settings_get()</entry></row>
               <row><entry>gconf_client_get_bool()</entry><entry>g_settings_get_boolean()</entry></row>
@@ -318,10 +320,59 @@ start_monitoring_trash (void)
         an equivalent GSettings schema. The tool is not perfect and
         may need assistence in some cases.
       </para>
+      <example><title>An example for using gsettings-schema-convert</title>
+        <para>Running <userinput>gsettings-schema-convert --gconf --xml --schema-id "org.gnome.font-rendering" --output org.gnome.font-rendering.gschema.xml destop_gnome_font_rendering.schemas</userinput> on the following <filename>desktop_gnome_font_rendering.schemas</filename> file:
+        <programlisting>
+<![CDATA[
+<?xml version="1.0"?>
+<gconfschemafile>
+    <schemalist>
+        <schema>
+            <key>/schemas/desktop/gnome/font_rendering/dpi</key>
+            <applyto>/desktop/gnome/font_rendering/dpi</applyto>
+            <owner>gnome</owner>
+            <type>int</type>
+            <default>96</default>
+            <locale name="C">
+                <short>DPI</short>
+                <long>The resolution used for converting font sizes to pixel sizes, in dots per inch.</long>
+            </locale>
+        </schema>
+    </schemalist>
+</gconfschemafile>
+]]>
+</programlisting>
+produces a <filename>org.gnome.font-rendering.gschema.xml</filename> file with the following content:
+<programlisting>
+<![CDATA[
+<schemalist>
+  <schema id="org.gnome.font-rendering" path="/desktop/gnome/font_rendering/">
+    <key name="dpi" type="i">
+      <default>96</default>
+      <summary>DPI</summary>
+      <description>The resolution used for converting font sizes to pixel sizes, in dots per inch.</description>
+    </key>
+  </schema>
+</schemalist>
+]]>
+</programlisting>
+</para>
+      </example>
 
       <para>
-        GSettings schemas are described by XML files that need to get installed
+        GSettings schemas are identified at runtime by their id (as specified
-        into <filename>$datadir/glib-2.0/schemas</filename>, and need to be
+        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".
+       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>.
+      </para>
+
+      <para>
+        The XML source file for your GSettings schema needs to get installed
+        into <filename>$datadir/glib-2.0/schemas</filename>, and needs to be
         compiled into a binary form by the <link linkend="gschema-compile">gschema-compile</link>
         utility. GIO provides variables <literal>gsettingsschemadir</literal>
         and <literal>gsettingsupdateschemacache</literal> for the location
@@ -380,7 +431,9 @@ install-data-hook:
       </para>
       <para>
         Default values can be localized in both GConf and GSettings schemas,
-        but GSettings uses gettext for the localization, so
+        but GSettings uses gettext for the localization. You can specify
+        the gettext domain to use in the <tag class="attribute">gettext-domain</tag>
+        attribute. Therefore, when converting localized defaults in GConf,
         <programlisting>
 <![CDATA[
 <key>/schemas/apps/my_app/font_size</key>
@@ -396,6 +449,8 @@ install-data-hook:
         becomes
         <programlisting>
 <![CDATA[
+<schema id="..." gettext-domain="your-domain">
+ ...
 <key name="font-size" type="i">
   <default l10n="messages" context="font_size">18</default>
 </key>
@@ -403,18 +458,36 @@ install-data-hook:
         </programlisting>
         Note how we used the context attribute to add msgctxt - "18" is not a
         good string to look up in gettext by itself. Also note that the value
-        24 is not present in the schema anymore. It has to be added to the gettext
+        24 is not present in the schema anymore. It has to be added to the
-        catalog for "be" instead.
+        gettext catalog for "be" instead.
       </para>
       <para>
-        GSettings schemas have more stringent restrictions on key names
+        GSettings schemas have optional <tag class="starttag">summary</tag> and
-        than GConf. Key names in GSettings are restricted to at most 32
+        <tag class="starttag">description</tag> elements for each key which
-        characters, and must only consist of lowercase characters, numbers
+        correspond to the <tag class="starttag">short</tag> and
-        and dashes, with no consecutive dashes. The first character must
+        <tag class="starttag">long</tag> elements in the GConf schema and
-        not be a number or dash, and the last character cannot be '-'.
+        will be used in similar ways by a future gsettings-editor, so you
-        The <link linkend="gschema-compile">gschema-compile</link> schema
+        should use the same conventions for them: The summary is just a short
-        compiler has a <option>--allow-any-name</option> that lets you
+        label with no punctuation, the description can be one or more complete
-        ignore these restrictions. Note that this option is only meant
+        sentences. Translations for these strings will also be handled
+        via gettext, so you should arrange for these strings to be
+        extracted into your gettext catalog.
+      </para>
+      <para>
+        GSettings is a bit more restrictive about key names than GConf. Key
+        names in GSettings can be at most 32 characters long, and must only
+        consist of lowercase characters, numbers and dashes, with no
+        consecutive dashes. The first character must not be a number or dash,
+        and the last character cannot be '-'.
+      </para>
+      <para>
+        If you are using the GConf backend for GSettings during the
+        transition, you may want to keep your key names the same they
+        were in GConf, so that existing settings in the users GConf
+        database are preserved. You can achieve this by using the
+        <option>--allow-any-name</option> with the
+        <link linkend="gschema-compile">gschema-compile</link> schema
+        compiler. Note that this option is only meant
         to ease the process of porting your application, allowing parts
         of your application to continue to access GConf and parts to use
         GSettings. By the time you have finished porting your application
@@ -424,18 +497,31 @@ install-data-hook:
 
     <section><title>Data conversion</title>
       <para>
-        GConf comes with a utility called <command>gsettings-data-convert</command>,
+        GConf comes with a GSettings backend that can be used to
-        which is designed to help with the task of migrating user settings from
+        facility the transition to the GSettings API until you are
-        GConf into GSetting. <command>gsettings-data-convert</command> can be run
+        ready to make the jump to a different backend (most likely
-        manually, but it is designed to be run automatically, every time a user
+        dconf). To use it, you need to set the <envar>GSETTINGS_BACKEND</envar>
-        logs in. It keeps track of the conversion that it has already done, and it
+        to 'gconf', e.g. by using
-        is harmless to run it more than once.
+<programlisting>
+  g_setenv ("GSETTINGS_BACKEND", "gconf", TRUE);
+</programlisting>
+        early on in your program. Note that this backend is meant purely
+        as a transition tool, and should not be used in production.
+      </para>
+      <para>
+        GConf also comes with a utility called
+        <command>gsettings-data-convert</command>, which is designed to help
+        with the task of migrating user settings from GConf into another
+        GSettings backend. It can be run manually, but it is designed to be
+        executed automatically, every time a user logs in. It keeps track of
+        the data migrations that it has already done, and it is harmless to
+        run it more than once.
       </para>
       <para>
         To make use of this utility, you must install a keyfile in the
-        <filename>/usr/share/gsettings-data-convert</filename> which lists the GSettings
+        directory <filename>/usr/share/gconf/conf/gsettings</filename> which
-        and GConf paths to map to each other, for each schema that you want to migrate
+        lists the GSettings keys and GConf paths to map to each other, for
-        user data for.
+        each schema that you want to migrate user data for.
       </para>
       <para>
         Here is an example:
@@ -447,18 +533,24 @@ dpi = /desktop/gnome/font_rendering/dpi
 hinting = /desktop/gnome/font_rendering/hinting
 rgba-order = /desktop/gnome/font_rendering/rgba_order
 
-[apps.myapp]
+[apps.myapp:/path/to/myapps/]
 some-odd-key1 = /apps/myapp/some_ODD-key1
 ]]>
         </programlisting>
-        The last key demonstrates that it may be necessary to modify the key name
+        The last key demonstrates that it may be necessary to modify the key
-        to comply with stricter GSettings key name rules. Of course, that means your
+        name to comply with stricter GSettings key name rules. Of course,
-        application must make the corresponding adjustments.
+        that means your application must use the new key names when looking
+        up settings in GSettings.
       </para>
       <para>
-        There are some limitations: <command>gsettings-data-convert</command> does not
+        The last group in the example also shows how to handle the case
-        do any transformation of the values. And it does not handle complex GConf types
+        of 'relocatable' schemas, which don't have a fixed path. You can
-        other than lists of strings or integers.
+        specify the path to use in the group name, separated by a colon.
+      </para>
+      <para>
+        There are some limitations: <command>gsettings-data-convert</command>
+        does not do any transformation of the values. And it does not handle
+        complex GConf types other than lists of strings or integers.
       </para>
     </section>
   </chapter>

gio/gsettings.c

@@ -63,10 +63,11 @@
  *
  * Similar to GConf, the default values in GSettings schemas can be
  * localized, but the localized values are stored in gettext catalogs
- * and looked up with the domain that is specified in the gettext-domain
+ * and looked up with the domain that is specified in the
- * attribute of the <tag>schemalist</tag> or <tag>schema</tag> elements
+ * <tag class="attribute">gettext-domain</tag> attribute of the
- * and the category that is specified in the l10n attribute of the
+ * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag>
- * <tag>key</tag> element.
+ * elements and the category that is specified in the l10n attribute of the
+ * <tag class="starttag">key</tag> element.
  *
  * GSettings uses schemas in a compact binary form that is created
  * by the gschema-compile utility. The input is a schema description in
@@ -115,6 +116,12 @@
  * ]]>
  * ]|
  *
+ * At runtime, schemas are identified by their id (as specified
+ * 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".
+ *
  * <refsect2>
  *  <title>Binding</title>
  *   <para>
@@ -956,7 +963,7 @@ g_settings_is_writable (GSettings   *settings,
  * <replaceable>base-path</replaceable> is the base path of @settings.
  *
  * The schema for the child settings object must have been declared
- * in the schema of @settings using a <tag>child</tag> element.
+ * in the schema of @settings using a <tag class="starttag">child</tag> element.
  *
  * Since: 2.26
  */