[glib/gdbus-merge] Add some conceptual changes

[Matthias Clasen <matthiasc src gnome org>]

commit bb7106c5dfce5597bcc4a0682200fb50f5201c29
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun May 9 02:27:09 2010 -0400

    Add some conceptual changes

 docs/reference/gio/migrating-dbus-glib.xml |   95 +++++++++++++++++++---------
 gio/gdbusaddress.c                         |    2 +-
 gio/gdbusintrospection.c                   |    2 +-
 3 files changed, 66 insertions(+), 33 deletions(-)
---
diff --git a/docs/reference/gio/migrating-dbus-glib.xml b/docs/reference/gio/migrating-dbus-glib.xml
index a8863d1..68202d5 100644
--- a/docs/reference/gio/migrating-dbus-glib.xml
+++ b/docs/reference/gio/migrating-dbus-glib.xml
@@ -1,35 +1,68 @@
 <chapter>
   <title>Migrating from dbus-glib to GDBus</title>
 
-  <table id="dbus-glib-vs-gdbus">
-    <title>dbus-glib functions and their GDBus counterparts</title>
-    <tgroup cols="2">
-      <thead>
-        <row><entry>dbus-glib</entry><entry>GDBus</entry></row>
-      </thead>
-      <tbody>
-        <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
-             g_dbus_proxy_new()</entry></row>
-        <row><entry>dbus_g_proxy_add_signal()</entry><entry>not needed, use the generic #GDBusProxy::g-signal</entry></row>
-        <row><entry>dbus_g_proxy_connect_signal()</entry><entry>use g_signal_connect() with #GDBusProxy::g-signal</entry></row>
-        <row><entry>dbus_g_connection_register_g_object()</entry><entry>g_dbus_connection_register_object()</entry></row>
-        <row><entry>dbus_g_connection_unregister_g_object()</entry><entry>g_dbus_connection_unregister_object()</entry></row>
-        <row><entry>dbus_g_object_type_install_info()</entry><entry>introspection data is installed while registering
-             an object, see g_dbus_connection_register_object()</entry></row>
-        <row><entry>dbus_g_proxy_begin_call()</entry><entry>g_dbus_proxy_invoke_method()</entry></row>
-        <row><entry>dbus_g_proxy_end_call()</entry><entry>g_dbus_proxy_invoke_method_finish()</entry></row>
-        <row><entry>dbus_g_proxy_call()</entry><entry>g_dbus_proxy_invoke_method_sync()</entry></row>
-        <row><entry>dbus_g_error_domain_register()</entry><entry>g_dbus_error_register_error_domain()</entry></row>
-        <row><entry>dbus_g_error_has_name()</entry><entry>no direct equivalent, see g_dbus_error_get_remote_error()</entry></row>
-        <row><entry>dbus_g_method_return()</entry><entry>g_dbus_method_invocation_return_value()</entry></row>
-        <row><entry>dbus_g_method_return_error()</entry><entry>g_dbus_method_invocation_return_error() and variants</entry></row>
-        <row><entry>dbus_g_method_get_sender()</entry><entry>g_dbus_method_invocation_get_sender()</entry></row>
-      </tbody>
-    </tgroup>
-  </table>
-  <para>
-    More hints for migrating from dbus-glib to GDBus will appear here shortly...
-  </para>
+  <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 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
+               g_dbus_proxy_new()</entry></row>
+          <row><entry>dbus_g_proxy_add_signal()</entry><entry>not needed, use the generic #GDBusProxy::g-signal</entry></row>
+          <row><entry>dbus_g_proxy_connect_signal()</entry><entry>use g_signal_connect() with #GDBusProxy::g-signal</entry></row>
+          <row><entry>dbus_g_connection_register_g_object()</entry><entry>g_dbus_connection_register_object()</entry></row>
+          <row><entry>dbus_g_connection_unregister_g_object()</entry><entry>g_dbus_connection_unregister_object()</entry></row>
+          <row><entry>dbus_g_object_type_install_info()</entry><entry>introspection data is installed while registering
+               an object, see g_dbus_connection_register_object()</entry></row>
+          <row><entry>dbus_g_proxy_begin_call()</entry><entry>g_dbus_proxy_invoke_method()</entry></row>
+          <row><entry>dbus_g_proxy_end_call()</entry><entry>g_dbus_proxy_invoke_method_finish()</entry></row>
+          <row><entry>dbus_g_proxy_call()</entry><entry>g_dbus_proxy_invoke_method_sync()</entry></row>
+          <row><entry>dbus_g_error_domain_register()</entry><entry>g_dbus_error_register_error_domain()</entry></row>
+          <row><entry>dbus_g_error_has_name()</entry><entry>no direct equivalent, see g_dbus_error_get_remote_error()</entry></row>
+          <row><entry>dbus_g_method_return()</entry><entry>g_dbus_method_invocation_return_value()</entry></row>
+          <row><entry>dbus_g_method_return_error()</entry><entry>g_dbus_method_invocation_return_error() and variants</entry></row>
+          <row><entry>dbus_g_method_get_sender()</entry><entry>g_dbus_method_invocation_get_sender()</entry></row>
+        </tbody>
+      </tgroup>
+    </table>
+  </section>
 </chapter>
diff --git a/gio/gdbusaddress.c b/gio/gdbusaddress.c
index 923c973..8dcb0c9 100644
--- a/gio/gdbusaddress.c
+++ b/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>.
  */
 
 /* ---------------------------------------------------------------------------------------------------- */
diff --git a/gio/gdbusintrospection.c b/gio/gdbusintrospection.c
index e1ae213..017209d 100644
--- a/gio/gdbusintrospection.c
+++ b/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>.
  */
 
 /* ---------------------------------------------------------------------------------------------------- */