[gnome-panel] doc: update overview chapter of reference manual

[Sebastian Geiger <segeiger src gnome org>]

commit 508a6c770880e4954a0b3d06979d7a1f8789a41b
Author: Sebastian Geiger <sbastig gmx net>
Date:   Fri Sep 11 23:11:18 2015 +0200

    doc: update overview chapter of reference manual

 doc/reference/panel-applet/Makefile.am            |    3 +-
 doc/reference/panel-applet/add_to_panel.png       |  Bin 0 -> 50415 bytes
 doc/reference/panel-applet/panel-applet-docs.sgml |   46 ++++++++++++++++-----
 3 files changed, 38 insertions(+), 11 deletions(-)
---
diff --git a/doc/reference/panel-applet/Makefile.am b/doc/reference/panel-applet/Makefile.am
index fd26b1c..b57a793 100644
--- a/doc/reference/panel-applet/Makefile.am
+++ b/doc/reference/panel-applet/Makefile.am
@@ -35,7 +35,8 @@ IGNORE_HFILES =                                       \
        panel-applet-marshal.h
 
 # Images to copy into HTML directory.
-HTML_IMAGES =
+HTML_IMAGES = \
+       add_to_panel.png
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 content_files = \
diff --git a/doc/reference/panel-applet/add_to_panel.png b/doc/reference/panel-applet/add_to_panel.png
new file mode 100644
index 0000000..0d6f05f
Binary files /dev/null and b/doc/reference/panel-applet/add_to_panel.png differ
diff --git a/doc/reference/panel-applet/panel-applet-docs.sgml 
b/doc/reference/panel-applet/panel-applet-docs.sgml
index c82d6bd..7f54cbd 100644
--- a/doc/reference/panel-applet/panel-applet-docs.sgml
+++ b/doc/reference/panel-applet/panel-applet-docs.sgml
@@ -16,19 +16,45 @@
   </bookinfo>
 
   <part id="overview">
-   <title>Panel Applet Library Overview</title>
+    <title>Panel Applet Library Overview</title>
+    <partintro>
+      <para>
+        The Panel Applet Library is used in the GNOME Flashback desktop to write applets that can be added 
to GNOME
+        Panel. GNOME Panel is the main user interface used in the GNOME Flashback desktop environment, 
through which
+        users interact with their computer and open applications.
+      </para>
 
-    <para>
-     Applets are small applications that are embedded in the GNOME panel. They can be used to give quick 
access to some features, or to display the state of something specific.
-    </para>
+      <para>
+        Applets are small applications that are embedded in the GNOME Panel. They can be used to give quick 
access
+        to some features, or to display the state of something specific. Most features in GNOME Panel such 
as the clock,
+        the application menu, the calendar and many others are written with this Panel Applet Library. 
Applets are added
+        through the "Add to Panel" dialog which can be opened from the "Add to Panel..." option on the 
context menu of
+        a GNOME Panel.
+      </para>
+
+      <mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="add_to_panel.png" format="PNG"/>
+        </imageobject>
+      </mediaobject>
 
-   <para>
-     The Panel Applet library is what should be used to write applets as it handles all the communication 
with the GNOME panel. It hides all of the embedding process of the applet behind a <link 
linkend="PanelApplet"><type>PanelApplet</type></link> widget. It also provides <link 
linkend="PanelApplet"><type>PanelApplet</type></link> API to properly integrate the applet in the panel.
-   </para>
+      <para>
+        The Panel Applet Library is what should be used to write applets as it handles all the communication 
with
+        the GNOME panel. It hides all of the embedding process of the applet behind a
+        <link linkend="PanelApplet"><type>PanelApplet</type></link> widget. It also provides
+        <link linkend="reference"><type>PanelApplet API</type></link> to properly integrate the applet in the
+        panel.
+      </para>
 
-   <note><simpara>
-    Keep in mind that starting with GNOME 3, the panel and applets are only available in the fallback mode. 
An applet will therefore not be usable in the default GNOME that users may use.
-   </simpara></note>
+      <note>
+        <simpara>
+          The Panel Applet Library was original part of the default GNOME desktop but was deprecated with 
GNOME 3,
+          when GNOME Shell was released. Nowadays development continues as part of the GNOME Flashback 
project. The
+          default desktop of GNOME now uses GNOME Shell, which uses a different system for extension, so an 
applet
+          written with the Panel Applet Library will not be usable in the default GNOME that users may use.
+        </simpara>
+      </note>
+    </partintro>
 
   </part>