[gnome-panel/wip/segeiger/reference-documentation] Doc: Improve the porting section

[Sebastian Geiger <segeiger src gnome org>]

commit 6cd69885c528f1c7bba90bd5b7f67a8620e70302
Author: Sebastian Geiger <sbastig gmx net>
Date:   Thu Sep 10 23:09:08 2015 +0200

    Doc: Improve the porting section
    
    Add the DBusAppletMigration guide

 doc/reference/panel-applet/panel-applet-docs.sgml |  137 +++++++++++++++++++-
 1 files changed, 130 insertions(+), 7 deletions(-)
---
diff --git a/doc/reference/panel-applet/panel-applet-docs.sgml 
b/doc/reference/panel-applet/panel-applet-docs.sgml
index face04c..af2b96f 100644
--- a/doc/reference/panel-applet/panel-applet-docs.sgml
+++ b/doc/reference/panel-applet/panel-applet-docs.sgml
@@ -949,16 +949,139 @@ PanelApplet.Applet.factory_main("HelloWorldFactory",
   </part>
 
   <part id="port-gnome2">
-    <title>Porting Applets from GNOME 2.x</title>
+    <title>Porting older Applets</title>
+
+   <chapter id="port-gnome2.dbus">
+    <title>Porting to a D-Bus-based Applet</title>
+
+   <para>
+       Applets that were written for Gnome 2.x must we ported to be usable with Gnome 3 and the latest Panel 
Applet
+       Library. First of all if the applet was written for Gnome 2.x then it will still use GTK+ 2 and must 
be migrated
+       to GTK+ 3. Please refer to the
+       <ulink url="http://library.gnome.org/devel/gtk3/stable/gtk-migrating-2-to-3.html";>GTK+ 2 to GTK+ 3 
migration guide</ulink>
+       for further details.
+   </para>
+
+   <para>
+       Once the GTK+ 2 to 3 migration has been completed you must migrate the Panel Applet Library specific 
parts of the
+       applet. During Gnome 2 times, the Panel Applet Library used LibBonobo, which was replaced by a DBUS 
API
+       during the switch to Panel Applet Library version 4.0.
+   </para>
+
+   <para>
+       To migrate from LibBonobo to the DBUS API remove PANEL_APPLET_BONOBO_FACTORY and replace it with
+       either PANEL_APPLET_OUT_PROCESS_FACTORY or PANEL_APPLET_IN_PROCESS_FACTORY depending if you want
+       an out-process or in-process applet, respectively.
+   </para>
+   <para>
+       The new macros have the same parameters as the old, except the version and description parameters 
have been
+       removed. Also the <constant>OAFIID:GNOME_</constant> prefix of the first parameter can be dropped 
both from
+       the factory ID and the applet type name. The following
+       two code listings show the difference between the old and new macro definitions:
+   </para>
+
+       <informalexample>
+           <programlisting>
+               PANEL_APPLET_BONOBO_FACTORY ("OAFIID:GNOME_HelloWorldFactory",
+               PANEL_TYPE_APPLET,
+               "WindowNavigationApplets",
+               "0",
+               hello_world_factory,
+               NULL)
+           </programlisting>
+       </informalexample>
+
+       The new version of the macro should be:
+
+       <informalexample>
+           <programlisting>
+               PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
+               PANEL_TYPE_APPLET,
+               hello_world_factory,
+               NULL)
+           </programlisting>
+       </informalexample>
 
-   <refsect1 id="port-gnome2.dbus">
-    <title>Porting a D-Bus-based Applet</title>
+     <para>
+         The applet factory callback, in this case the <function>hello_world_factory</function> usually 
contains a
+         check to ensure that the applet factory supports the requested applet. Here the
+         <constant>OAFIID:GNOME_</constant> prefix should be dropped as well, see the following two code 
listings.
+     </para>
 
-    <para>
-     There is no major issue porting a D-Bus-based applet from GNOME 2.x, from a Panel Applet library 
perspective. It is actually likely that the main issues will be that the applet has to be ported to GTK+ 3. 
Please refer to the <ulink url="http://library.gnome.org/devel/gtk3/stable/gtk-migrating-2-to-3.html";>GTK+ 2 
to GTK+ 3 migration guide</ulink> for this.
-    </para>
+       <note>
+           <simpara>
+               When you drop the prefix here, you must also remove the prefix from the applet name in the 
Panel Applet File.
+           </simpara>
+       </note>
+
+       Old definition:
+
+       <informalexample>
+           <programlisting>
+               static gboolean
+               hello_world_factory (PanelApplet *applet,
+                                    const char  *iid,
+                                    gpointer     data)
+               {
+
+                   if (!g_strcmp (iid, "OAFIID:GNOME_HelloWorldApplet") != 0)
+                       return FALSE;
+
+                   hello_world_applet_fill (applet);
+
+                   return TRUE;
+               }
+           </programlisting>
+       </informalexample>
+
+       The new version of of the factory callback should be:
+
+       <informalexample>
+           <programlisting>
+               static gboolean
+               hello_world_factory (PanelApplet *applet,
+                                    const char  *iid,
+                                    gpointer     data)
+               {
+
+                   if (!g_strcmp0 (iid, "HelloWorldApplet") != 0)
+                       return FALSE;
+
+                   hello_world_applet_fill (applet);
 
-   </refsect1>
+                   return TRUE;
+               }
+           </programlisting>
+       </informalexample>
+
+   </chapter>
+
+   <chapter>
+     <title>Porting Applets from Panel Applet Library 4.0</title>
+       <para>
+           The Panel Applet Library name has been renamed during the switch from version 4.0 to 5.0 and is 
now called
+           <constant>libpanel-applet</constant>.
+       </para>
+       <note>
+           <simpara>
+               Note that the version information in the library name has been dropped and there is now an
+               additional hypen between 'panel' and 'applet'.
+           </simpara>
+       </note>
+
+       <para>
+           GConf support has been removed and was replaced by GSettings. If the applet still uses GConf it 
must
+           migrate to GSettings. It is recommended to use the 
<function>panel_applet_settings_new()</function> function
+           to store your settings.
+       </para>
+
+       <para>
+           The <function>panel_applet_setup_menu</function> familiy of functions have been changed and now 
accept the
+           <type>GActionGroup</type> interface instead of the deprecated <type>GtkActionGroup</type>. Thus 
older applets
+           need to be changed and must migrate their menus to the <type>GAction</type> model. Please refer 
to the Gtk+
+           documentation for more details about <type>GAction</type> and the related interfaces.
+       </para>
+   </chapter>
 
   </part>