[evolution-data-server/documentation-effort: 11/18] Enhanced the cursor example sgml to include all related classes in the example.

[Tristan Van Berkom <tvb src gnome org>]

commit 2ea6c9f09262fdc1e3a24ce2f34c07a2e0261fe1
Author: Tristan Van Berkom <tristan upstairslabs com>
Date:   Thu Dec 5 18:13:34 2013 +0900

    Enhanced the cursor example sgml to include all related classes in the example.

 docs/reference/eds/eds-cursor-example.sgml |  112 +++++++++++++++++++++++-----
 1 files changed, 94 insertions(+), 18 deletions(-)
---
diff --git a/docs/reference/eds/eds-cursor-example.sgml b/docs/reference/eds/eds-cursor-example.sgml
index 7915357..dea758e 100644
--- a/docs/reference/eds/eds-cursor-example.sgml
+++ b/docs/reference/eds/eds-cursor-example.sgml
@@ -1,10 +1,10 @@
 <refentry id="eds-cursor-example" revision="30 Nov 2013">
   <refmeta>
-    <refentrytitle>Cursor Example</refentrytitle>
-    <refmiscinfo>Cursor Example</refmiscinfo>
+    <refentrytitle>Contacts Browser Example</refentrytitle>
+    <refmiscinfo>Contacts Browser Example</refmiscinfo>
   </refmeta>
   <refnamediv>
-    <refname>Scrolling Contacts Window Example</refname>
+    <refname>Contacts Browser Example</refname>
     <refpurpose>
       Explanation of how to create a scrolling window listing contacts in
       alphabetical order.
@@ -42,21 +42,6 @@
        </para>
       </listitem>
       <listitem>
-       <para>Efficient cursor operation and fallbacks</para>
-       <para>
-         Using the %E_BOOK_INDEX_SORT_KEY index to configure custom addressbooks
-         allow one to get quick results for just about any #EContactField. By default
-         %E_CONTACT_FILE_AS, %E_CONTACT_GIVEN_NAME and %E_CONTACT_FAMILY_NAME are
-         configured for efficient sorting.
-       </para>
-       <para>
-         Similarly, #EContactFields referenced in search expressions can effect
-         performance of cursor navigation. This can all be configured using
-         the #ESourceBackendSummarySetup extension. See an explanation of the
-         default optimizations in e_book_sqlite_new().
-       </para>
-      </listitem>
-      <listitem>
        <para>Display the the user's alphabet</para>
        <para>
          Using interesting features from ICU libraries allow us to display
@@ -66,6 +51,21 @@
       </listitem>
     </itemizedlist>
 
+    <para>
+      The actual example code is built into the 'example' subdirectory of the Evolution Data Server
+      sources. In order to run the example, just launch the program and give it a path to a directory
+      full of vcards, bearing the .vcf filename extention.
+    </para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Contact Browser</title>
+    <para>
+      Below is an example of the contact browser code itself, the example program is
+      broken down into a couple of object classes which are also listed below.
+    </para>
+
     <informalexample>
       <programlisting>
        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
@@ -75,7 +75,83 @@
        </xi:include>
       </programlisting>
     </informalexample>
+  </refsect1>
+
+  <refsect1>
+    <title>The alphabetic navigator</title>
+    <para>
+      This is a simple class which implements a vertical scroller and displays
+      various letters according to the currently active alphabet. The actual
+      interaction with #EBookClientCursor is done in the main contact browser
+      and this class is simply configured with the active alphabet.
+    </para>
+
+    <informalexample>
+      <programlisting>
+       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
+                    parse="text"
+                    href="../../../../examples/cursor/cursor-navigator.c">
+          <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+       </xi:include>
+      </programlisting>
+    </informalexample>
+  </refsect1>
+
+  <refsect1>
+    <title>The search entry</title>
+    <para>
+      The search entry is placed at the top of the contacts browser,
+      this class simply implements a drop down box choosing the appropriate
+      search expression which should be used to filter the contacts
+      in the browser display window.
+    </para>
+
+    <informalexample>
+      <programlisting>
+       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
+                    parse="text"
+                    href="../../../../examples/cursor/cursor-search.c">
+          <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+       </xi:include>
+      </programlisting>
+    </informalexample>
+  </refsect1>
 
+  <refsect1>
+    <title>The contact slot</title>
+    <para>
+      This is a very simple class who's only purpose is to display
+      contact related data, each entry in the list is a 'slot'
+    </para>
+
+    <informalexample>
+      <programlisting>
+       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
+                    parse="text"
+                    href="../../../../examples/cursor/cursor-slot.c">
+          <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+       </xi:include>
+      </programlisting>
+    </informalexample>
+  </refsect1>
+
+  <refsect1>
+    <title>Creating addressbooks and loading vcards</title>
+    <para>
+      This is the messy part of the example, here we take care
+      of creating a custom addressbook and populating it with
+      the contacts found in the directory given to the example.
+    </para>
+
+    <informalexample>
+      <programlisting>
+       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
+                    parse="text"
+                    href="../../../../examples/cursor/cursor-data.c">
+          <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+       </xi:include>
+      </programlisting>
+    </informalexample>
   </refsect1>
 
 </refentry>