[gnome-panel/wip/segeiger/reference-documentation] More changes

[Sebastian Geiger <segeiger src gnome org>]

commit 002a6904f2267495f1a7f391da0cc4bc075f2c83
Author: Sebastian Geiger <sbastig gmx net>
Date:   Tue Aug 25 23:23:28 2015 +0200

    More changes

 doc/reference/panel-applet/panel-applet-docs.sgml |   77 +++++++++++++--------
 1 files changed, 49 insertions(+), 28 deletions(-)
---
diff --git a/doc/reference/panel-applet/panel-applet-docs.sgml 
b/doc/reference/panel-applet/panel-applet-docs.sgml
index 2199bca..4310d61 100644
--- a/doc/reference/panel-applet/panel-applet-docs.sgml
+++ b/doc/reference/panel-applet/panel-applet-docs.sgml
@@ -122,11 +122,11 @@
                        [Applet Factory]
                        Id=HelloWorldFactory
                        Name=Hello World Applet Factory
-                       Description=Factory for the window navigation related applets
+                       Description=Factory for our example applets
 
                        [HelloWorldApplet]
                        Name=Hello World
-                       Description=Factory for the Hello World applet example
+                       Description=The Hello World example applet
                        Icon=hello-world-icon
                    </programlisting>
                </informalexample>
@@ -425,25 +425,28 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
 
     <para>
      The Panel Applet library uses <type>GAction</type> to define menu items appearing in the context menu 
of the
-     applet.
+     applet. This chapter provides some guidelines to applet developers and explains how to setup the 
context menu.
     </para>
 
     <sect1 id="getting-started.context-menu.content">
      <title>Guidelines for Context Menu</title>
 
      <para>
-      To help guarantee consistency in the interaction with applets, there are some guidelines that are 
recommended to follow:
+      To help guarantee consistency in the interaction with applets, there are some guidelines that are
+      recommended to follow:
      </para>
 
      <itemizedlist>
       <listitem>
        <para>
-        Do not make the context menu too long: if you have more than five or six menu items, then it might 
be worth investing efforts on rethinking what is important in the menu.
+        Do not make the context menu too long: if you have more than five or six menu items, then it might 
be worth
+        investing efforts on rethinking what is important in the menu.
        </para>
       </listitem>
       <listitem>
        <para>
-        For the menu item that will enable the user to configure the applet, use "Preferences" for the 
label, and try to avoid "Configure", "Configuration", "Settings", etc.
+        For the menu item that will enable the user to configure the applet, use "Preferences" for the label,
+        and try to avoid "Configure", "Configuration", "Settings", etc.
        </para>
       </listitem>
       <listitem>
@@ -630,48 +633,66 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
     <itemizedlist>
      <listitem>
       <para>
-       Global settings: those are settings that should be shared among all instances of the same applets. 
For instance, the preferred unit for temperature is something that the user will want to set only one. The 
way to store those settings is in no way specific to the Panel Applet library, as it should work like in any 
other application.
+       Global settings: those are settings that should be shared among all instances of the same applets.
+       For instance, the preferred unit for temperature is something that the user will want to set only one.
+       The way to store those settings is in no way specific to the Panel Applet library, as it should work
+       like in any other application.
       </para>
      </listitem>
      <listitem>
       <para>
-       Per-applet instance settings: those are settings that might be different depending on the instance of 
an applet. For instance, an applet whose goal is to display a picture should make it possible for the user to 
choose a different picture for each instance of the applet. The Panel Applet library provides API to help 
with this.
+       Per-applet instance settings: those are settings that might be different depending on the instance
+       of an applet. For instance, an applet whose goal is to display a picture should make it possible for
+       the user to choose a different picture for each instance of the applet. The Panel Applet library
+       provides API to help with this.
       </para>
      </listitem>
     </itemizedlist>
 
     <para>
-     There is actually a third case, which is rather rare, though: per-screen settings. It might be that 
some applets control some per-screen settings, like the layout of the workspaces. There is currently no API 
to help with this as it is a very specific case that you will probably never have to deal with for a usual 
applet.
+     There is actually a third case, which is rather rare, though: per-screen settings.
+     It might be that some applets control some per-screen settings, like the layout of the workspaces.
+     There is currently no API to help with this as it is a very specific case that you will probably
+     never have to deal with for a usual applet.
     </para>
 
-     TODO: describe settings-oriented API
+    <sect1 id="getting-started.settings.per-instance">
+       <title>Per Instance Settings</title>
+       <para>
+           In order to store per instance settings for an applet it is recommended to use GSettings. The
+           Panel Applet Library privides a function named <function>panel_applet_settings_new()</function>
+           for this purpose. You need to provide a GSettings schema file for your applet and the Panel
+           Applet library will setup the GSettings object for you.
+       </para>
+
+        TODO: describe settings-oriented API in more detail and give an example for per instance settings.
+
+    </sect1>
    </chapter>
 
    <chapter id="getting-started.install">
-    <title>Making the Applet Visible to the Panel</title>
+    <title>Panel Applet Files</title>
 
     <para>
-     Simply installing the applet binary will obviously not be enough to make this applet working in the 
panel. Two files should be installed for this:
+      Simply installing the applet binary will obviously not be enough. The applet also needs to be 
registered to the
+      panel. In order to do this you need to provide a Panel Applet File. Panel Applet files are ini-style 
text
+      files with an extension named <constant>.panel-applet</constant>.
     </para>
 
-    <itemizedlist>
-     <listitem>
-      <para>
-       a <filename>.panel-applet</filename> file so that the panel knows that the applet.
-      </para>
-     </listitem>
-     <listitem>
-      <para>
-       a D-Bus service file to autostart the binary when the panel wants to create an applet.
-      </para>
-     </listitem>
-    </itemizedlist>
+    <warning>
+        <simpara>
+          If you are creating an out-process applet, then you also need to provide a D-Bus service file
+          to automatically start the binary when the panel wants to create an applet.
+        </simpara>
+    </warning>
 
     <sect2 id="getting-started.install.panel-applet">
-     <title>Panel Applet File</title>
+     <title>Panel Applet File Syntax</title>
 
      <para>
-      The <filename>.panel-applet</filename> file is a key file about the applet binary, describing the 
<link linkend="getting-started.concepts.applet-factory">applet factory</link> from the binary and the <link 
linkend="getting-started.concepts.applet-types">applet types</link> this factory can create.
+      The <filename>.panel-applet</filename> file is a key file about the applet binary, describing the
+         <link linkend="getting-started.concepts.applet-factory">applet factory</link> of the binary and the
+         <link linkend="getting-started.concepts.applet-types">applet types</link> this factory can create.
      </para>
 
      <sect3>
@@ -681,11 +702,11 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
 [Applet Factory]
 Id=HelloWorldFactory
 Name=Hello World Applet Factory
-Description=Factory for the window navigation related applets
+Description=Factory for the our example applets
 
 [HelloWorldApplet]
 Name=Hello World
-Description=Factory for the Hello World applet example
+Description=Factory for the Hello World example applet
 Icon=hello-world-icon
        </programlisting>
       </informalexample>