Bug 632169 - manual use of gsettings-data-convert

Add some words and example code to the documentation about why you might
want to manually invoke gsettings-data-convert and how you should go
about doing that.

docs/reference/gio/migrating-gconf.xml

@@ -449,5 +449,69 @@ some-odd-key1 = /apps/myapp/some_ODD-key1
         script if you are making use of the GConf backend or the conversion
         utility.
       </para>
+
+      <para>
+        If, as an application developer, you are interested in manually
+        ensuring that <command>gsettings-data-convert</command> has been
+        invoked (for example, to deal with the case where the user is
+        logged in during a distribution upgrade or for non-XDG desktop
+        environments which do not run the command as an autostart) you
+        may invoke it manually during your program initialisation.  This
+        is not recommended for all application authors -- it is your
+        choice if this use case concerns you enough.
+      </para>
+      <para>
+        Internally, <command>gsettings-data-convert</command> uses a
+        keyfile to track which settings have been migrated.  The
+        following code fragment will check that keyfile to see if your
+        data conversion script has been run yet and, if not, will
+        attempt to invoke the tool to run it.  You should adapt it to
+        your application as you see fit.
+      </para>
+      <para>
+        <programlisting>
+<![CDATA[
+static void
+ensure_migrated (const gchar *name)
+{
+  gboolean needed = TRUE;
+  GKeyFile *kf;
+  gchar **list;
+  gsize i, n;
+
+  kf = g_key_file_new ();
+
+  g_key_file_load_from_data_dirs (kf, "gsettings-data-convert",
+                                  NULL, G_KEY_FILE_NONE, NULL);
+  list = g_key_file_get_string_list (kf, "State", "converted", &n, NULL);
+
+  if (list)
+    {
+      for (i = 0; i < n; i++)
+        if (strcmp (list[i], name) == 0)
+          {
+            needed = FALSE;
+            break;
+          }
+
+      g_strfreev (list);
+    }
+
+  g_key_file_free (kf);
+
+  if (needed)
+    g_spawn_command_line_sync ("gsettings-data-convert",
+                               NULL, NULL, NULL, NULL);
+}
+
+]]>
+        </programlisting>
+      </para>
+      <para>
+        Although there is the possibility that the
+        <command>gsettings-data-convert</command> script will end up
+        running multiple times concurrently with this approach, it is
+        believed that this is safe.
+      </para>
     </section>
   </chapter>