[glib/new-gsettings] Add section on schema migration

[Matthias Clasen <matthiasc src gnome org>]

commit 5614143e2bcf1aaf71a62e4c341e72ddc0a5db54
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Apr 16 12:45:40 2010 -0400

    Add section on schema migration

 docs/reference/gio/Makefile.am                  |    6 +-
 docs/reference/gio/gio-docs.xml                 |    1 +
 docs/reference/gio/gsettings-schema-convert.xml |   86 +++++++++++++++++++++++
 docs/reference/gio/migrating.xml                |   51 +++++++++++++-
 4 files changed, 141 insertions(+), 3 deletions(-)
---
diff --git a/docs/reference/gio/Makefile.am b/docs/reference/gio/Makefile.am
index 9ea1904..a171c2c 100644
--- a/docs/reference/gio/Makefile.am
+++ b/docs/reference/gio/Makefile.am
@@ -115,7 +115,8 @@ content_files =			\
 expand_content_files =		\
 	overview.xml		\
 	migrating.xml		\
-	gschema-compile.xml
+	gschema-compile.xml	\
+	gsettings-schema-convert.xml
 
 extra_files =			\
 	version.xml.in		\
@@ -129,7 +130,8 @@ EXTRA_DIST +=			\
 if ENABLE_MAN
 
 man_MANS =			\
-	gschema-compile.1
+	gschema-compile.1	\
+	gsettings-schema-convert.1
 
 %.1 : xml/%.xml
 	@XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index 3bb20c5..c20be29 100644
--- a/docs/reference/gio/gio-docs.xml
+++ b/docs/reference/gio/gio-docs.xml
@@ -142,6 +142,7 @@
     <chapter id="tools">
         <title>GIO Tools</title>
         <xi:include href="xml/gschema-compile.xml"/>
+        <xi:include href="xml/gsettings-schema-convert.xml"/>
     </chapter>
   </part>
 
diff --git a/docs/reference/gio/gsettings-schema-convert.xml b/docs/reference/gio/gsettings-schema-convert.xml
new file mode 100644
index 0000000..fc3b632
--- /dev/null
+++ b/docs/reference/gio/gsettings-schema-convert.xml
@@ -0,0 +1,86 @@
+<refentry id="gsettings-schema-convert">
+
+<refmeta>
+<refentrytitle>gsettings-schema-convert</refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname>gsettings-schema-convert</refname>
+<refpurpose>GConf to GSettings schema conversion</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>gsettings-schema-convert</command>
+<arg choice="opt" rep="repeat">option</arg>
+<arg choice="req">file</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>gsettings-schema-convert</command> converts between GConf
+and GSettings schema file formats. Note that the conversion is not
+expected to be fully automated. You are expected to verify and edit
+the result of the conversion.
+</para>
+<para>
+Note that GSettings schemas need to be converted into binary form
+with <link linkend="gschema-compile">gschema-compile</link> before they
+can be used by applications.
+</para>
+
+<refsect2><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>-h</option>, <option>--help</option></term>
+<listitem><para>
+Print help and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-o <replaceable>OUTPUT</replaceable></option>, <option>--output=<replaceable>OUTPUT</replaceable></option></term>
+<listitem><para>
+Store the generated output in the file <replaceable>OUTPUT</replaceable>. If no output file is specified, the generated output is written to stdout.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-f</option>, <option>--force</option></term>
+<listitem><para>
+Overwrite the output file if it already exists.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-g</option>, <option>--gconf</option></term>
+<listitem><para>
+The input file is a GConf schema.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-s</option>, <option>--simple</option></term>
+<listitem><para>
+The input file is a simple GSettings schema. If the input
+format is not explicitly specified, this is the default.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-x</option>, <option>--xml</option></term>
+<listitem><para>
+Produce a GSettings schema in XML format. If the output format
+is not explicitly specified, a GConf schema will be converted
+into a simple Gsettings schema, and a simple GSettings schema
+will be converted into XML.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect2>
+</refsect1>
+</refentry>
+
diff --git a/docs/reference/gio/migrating.xml b/docs/reference/gio/migrating.xml
index 2b8588e..93ec963 100644
--- a/docs/reference/gio/migrating.xml
+++ b/docs/reference/gio/migrating.xml
@@ -232,6 +232,56 @@ start_monitoring_trash (void)
       </para>
     </section>
 
+    <section>
+      <title>Schema conversion</title>
+
+      <para>
+        One possible pitfall in doing schema conversion is that the default
+        values in GSettings schemas are in the format of a serialized #GVariant,
+        and the types are specified as #GVariant type strings.
+        This means that strings need to include quotes in the XML, so
+        <programlisting>
+<![CDATA[
+<type>string</type>
+<default>rgb</default>
+]]>
+        </programlisting>
+        becomes
+        <programlisting>
+<![CDATA[
+<key name="rgba_order" type="s">
+  <default>'rgb'</default>
+</key>
+]]>
+        </programlisting>
+      </para>
+      <para>
+        Another possible complication is that GConf specifies full paths
+        for each key, while a GSettings schema has a 'path' attribute that
+        contains the prefix for all the keys in the schema, and individual
+        keys just have a simple name. So
+        <programlisting>
+<![CDATA[
+<key>/schemas/desktop/gnome/font_rendering/antialiasing</key>
+]]>
+        </programlisting>
+        becomes
+        <programlisting>
+<![CDATA[
+<schema id="org.gnome.font" path="/desktop/gnome/font_rendering/">
+  <key name="antialiasing" type="s">
+]]>
+        </programlisting>
+      </para>
+      <para>
+        GIO comes with a commandline tool
+        <link linkend="gsettings-schema-convert">gsettings-schema-convert</link>
+        that can help with the task of converting a GConf schema into
+        an equivalent GSettings schema. The tool is not perfect and
+        may need assistence in some cases.
+      </para>
+    </section>
+
     <section><title>More information</title>
       <para>
         More information about migration from GConf to GSettings will appear
@@ -239,7 +289,6 @@ start_monitoring_trash (void)
         <itemizedlist>
           <listitem><para>Defaults</para></listitem>
           <listitem><para>Change sets</para></listitem>
-          <listitem><para>Schema conversion</para></listitem>
           <listitem><para>Data conversion</para></listitem>
         </itemizedlist>
       </para>