Add some conceptual changes

docs/reference/gio/migrating-dbus-glib.xml

@@ -1,13 +1,48 @@
 <chapter>
   <title>Migrating from dbus-glib to GDBus</title>
 
+  <section>
+    <title>Conceptual differences</title>
+
+    <para>
+      The central concepts of D-Bus are modelled in a very similar way
+      in dbus-glib and GDBus. Both have a objects representing connections,
+      proxies and method invocations. But there are some important
+      differences:
+      <itemizedlist>
+        <listitem><para>
+          dbus-glib uses libdbus, GDBus doesn't. Instead, it relies on GIO
+          streams as transport layer, and has its own implementation for the
+          the D-Bus connection setup and authentication.
+        </para></listitem>
+        <listitem><para>
+          dbus-glib uses the GObject type system for method arguments and
+          return values, including a homegrown container specialization
+          mechanism. GDBus relies uses the #GVariant type system which is
+          explicitly designed to match D-Bus types.
+        </para></listitem>
+        <listitem><para>
+          The typical way to export an object in dbus-glib involves generating
+          glue code from XML introspection data using <command>dbus-binding-tool</command>. GDBus does not (yet?) use code generation; you are expected to
+          embed the introspection data in your application code.
+        </para></listitem>
+      </itemizedlist>
+    </para>
+  </section>
+
+  <section>
+    <title>Dbus-glib API conversion</title>
+
     <table id="dbus-glib-vs-gdbus">
-    <title>dbus-glib functions and their GDBus counterparts</title>
+      <title>dbus-glib APIs and their GDBus counterparts</title>
       <tgroup cols="2">
         <thead>
            <row><entry>dbus-glib</entry><entry>GDBus</entry></row>
         </thead>
         <tbody>
+          <row><entry>#DBusGConnection</entry></entry>#GDBusConnection</entry></row>
+          <row><entry>#DBusGProxy</entry></entry>#GDBusProxy</entry></row>
+          <row><entry>#DBusGMethodInvocation</entry></entry>#GDBusMethodInvocatoin</entry></row>
           <row><entry>dbus_g_bus_get()</entry><entry>g_bus_get_sync(), also see
                g_bus_get()</entry></row>
           <row><entry>dbus_g_proxy_new_for_name()</entry><entry>g_dbus_proxy_new_sync(), also see
@@ -29,7 +64,5 @@
         </tbody>
       </tgroup>
     </table>
-  <para>
+  </section>
-    More hints for migrating from dbus-glib to GDBus will appear here shortly...
-  </para>
 </chapter>

gio/gdbusaddress.c

@@ -46,7 +46,7 @@
  *
  * Routines for working with D-Bus addresses. A D-Bus address is a string
  * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
- * is explained in detail in the <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">D-Bus specification</link>.
+ * is explained in detail in the <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html&num;addresses">D-Bus specification</link>.
  */
 
 /* ---------------------------------------------------------------------------------------------------- */

gio/gdbusintrospection.c

@@ -41,7 +41,7 @@
  * used when registering objects with g_dbus_connection_register_object().
  *
  * The format of D-BUs introspection XML is specified in the
- * <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus specification</link>.
+ * <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html&num;introspection-format">D-Bus specification</link>.
  */
 
 /* ---------------------------------------------------------------------------------------------------- */