[evolution-data-server/documentation-effort: 6/18] Unified documentation work in progress.

[Tristan Van Berkom <tvb src gnome org>]

commit 44fd10e39d9e4bb56c090a4ca155a26789c83647
Author: Tristan Van Berkom <tristanvb openismus com>
Date:   Sat Nov 30 20:59:46 2013 +0900

    Unified documentation work in progress.

 docs/reference/eds/Makefile.am             |    4 +-
 docs/reference/eds/eds-cursor-example.sgml |   81 ++++++++++++++++++++++++++++
 docs/reference/eds/eds-docs.sgml           |   19 ++++---
 docs/reference/eds/eds-sections.txt        |   64 ++++++++++++++++++++++
 4 files changed, 159 insertions(+), 9 deletions(-)
---
diff --git a/docs/reference/eds/Makefile.am b/docs/reference/eds/Makefile.am
index 2429bbd..80cad79 100644
--- a/docs/reference/eds/Makefile.am
+++ b/docs/reference/eds/Makefile.am
@@ -99,8 +99,8 @@ HTML_IMAGE_SOURCE_FILES = \
        $(IMAGE_SOURCE_DIR)/cursor-positions-step.odg           \
        $(IMAGE_SOURCE_DIR)/cursor-alphabetic-indexes.odg
 
-#SGML_FILES= \
-#      theater-manual-introduction.sgml ...
+SGML_FILES= \
+       eds-cursor-example.sgml
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
diff --git a/docs/reference/eds/eds-cursor-example.sgml b/docs/reference/eds/eds-cursor-example.sgml
new file mode 100644
index 0000000..7915357
--- /dev/null
+++ b/docs/reference/eds/eds-cursor-example.sgml
@@ -0,0 +1,81 @@
+<refentry id="eds-cursor-example" revision="30 Nov 2013">
+  <refmeta>
+    <refentrytitle>Cursor Example</refentrytitle>
+    <refmiscinfo>Cursor Example</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>Scrolling Contacts Window Example</refname>
+    <refpurpose>
+      Explanation of how to create a scrolling window listing contacts in
+      alphabetical order.
+    </refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Introduction</title>
+    <para>
+      This is a fully functional reference application for implementing scrolling contact
+      browsers using the #EBookClientCursor. With the cursor, the following features are
+      possible.
+    </para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Display contacts in a configurable sort order</para>
+       <para>
+         Sort by any #EContactField which conforms to #G_TYPE_STRING, this can be checked
+         with e_contact_field_type()
+       </para>
+      </listitem>
+      <listitem>
+        <para>Minimal memory constraints</para>
+       <para>
+         Only load into memory the contacts which are currently visible in the list
+       </para>
+      </listitem>
+      <listitem>
+       <para>Filter search results on the fly</para>
+       <para>
+         Set new search expressions generated with #EBookQuery on the fly. Refresh
+         the contact list at the current position without losing the current cursor
+         position.
+       </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
+         the user's alphabet, and implement features such as jumping to
+         a given letter in the user's alphabet.
+       </para>
+      </listitem>
+    </itemizedlist>
+
+    <informalexample>
+      <programlisting>
+       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
+                    parse="text"
+                    href="../../../../examples/cursor/cursor-example.c">
+          <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+       </xi:include>
+      </programlisting>
+    </informalexample>
+
+  </refsect1>
+
+</refentry>
diff --git a/docs/reference/eds/eds-docs.sgml b/docs/reference/eds/eds-docs.sgml
index 5046b5c..daaa652 100644
--- a/docs/reference/eds/eds-docs.sgml
+++ b/docs/reference/eds/eds-docs.sgml
@@ -71,7 +71,7 @@
       <xi:include href="xml/e-sexp.xml"/>
       <xi:include href="xml/e-time-utils.xml"/>
       <xi:include href="xml/e-uid.xml"/>
-      <xi:include href="xml/e-util.xml"/>
+      <xi:include href="xml/e-data-server-util.xml"/>
       <xi:include href="xml/e-xml-hash-utils.xml"/>
       <xi:include href="xml/eds-version.xml"/>
     </chapter>
@@ -153,25 +153,25 @@
     <chapter>
       <title>Addressbook backend infrastructure</title>
       <xi:include href="xml/e-book-backend.xml"/>
-      <xi:include href="xml/e-book-backend-cache.xml"/>
-      <xi:include href="xml/e-book-backend-db-cache.xml"/>
       <xi:include href="xml/e-book-backend-factory.xml"/>
       <xi:include href="xml/e-book-backend-sexp.xml"/>
-      <xi:include href="xml/e-book-backend-sqlitedb.xml"/>
-      <xi:include href="xml/e-book-backend-summary.xml"/>
+      <xi:include href="xml/e-book-sqlite.xml"/>
       <xi:include href="xml/e-data-book.xml"/>
       <xi:include href="xml/e-data-book-direct.xml"/>
       <xi:include href="xml/e-data-book-cursor.xml"/>
       <xi:include href="xml/e-data-book-cursor-sqlite.xml"/>
       <xi:include href="xml/e-data-book-factory.xml"/>
       <xi:include href="xml/e-data-book-view.xml"/>
-      <xi:include href="xml/ximian-vcard.xml"/>
     </chapter>
     
     <chapter>
       <title>Deprecated Classes</title>
       <xi:include href="xml/e-book.xml"/>
       <xi:include href="xml/e-book-view.xml"/>
+      <xi:include href="xml/e-book-backend-sqlitedb.xml"/>
+      <xi:include href="xml/e-book-backend-summary.xml"/>
+      <xi:include href="xml/e-book-backend-cache.xml"/>
+      <xi:include href="xml/e-book-backend-db-cache.xml"/>
     </chapter>
   </part>
 
@@ -200,10 +200,10 @@
       <xi:include href="xml/e-cal-backend-store.xml"/>
       <xi:include href="xml/e-cal-backend-sync.xml"/>
       <xi:include href="xml/e-cal-backend-util.xml"/>
+      <xi:include href="xml/e-cal-backend-intervaltree.xml"/>
       <xi:include href="xml/e-data-cal.xml"/>
       <xi:include href="xml/e-data-cal-factory.xml"/>
       <xi:include href="xml/e-data-cal-view.xml"/>
-      <xi:include href="xml/e-intervaltree.xml"/>
     </chapter>
 
     <chapter>
@@ -213,6 +213,11 @@
     </chapter>
   </part>
 
+  <part id="examples">
+    <title>Examples</title>
+    <xi:include href="xml/eds-cursor-example.sgml" />
+  </part>
+
   <index id="api-index-full">
     <title>Index</title>
     <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
diff --git a/docs/reference/eds/eds-sections.txt b/docs/reference/eds/eds-sections.txt
index 50ce89f..fb1f18f 100644
--- a/docs/reference/eds/eds-sections.txt
+++ b/docs/reference/eds/eds-sections.txt
@@ -24,6 +24,7 @@ e_authentication_mediator_wait_for_client_sync
 e_authentication_mediator_wait_for_client
 e_authentication_mediator_wait_for_client_finish
 e_authentication_mediator_dismiss
+e_authentication_mediator_server_error
 <SUBSECTION Standard>
 EAuthenticationMediatorPrivate
 E_AUTHENTICATION_MEDIATOR
@@ -331,6 +332,7 @@ e_book_backend_cache_get_type
 
 <SECTION>
 <FILE>e-book-backend-db-cache</FILE>
+<TITLE>Berkeley DB caching API</TITLE>
 e_book_backend_db_cache_get_contact
 e_book_backend_db_cache_get_filename
 e_book_backend_db_cache_set_filename
@@ -383,6 +385,65 @@ e_book_backend_sexp_get_type
 </SECTION>
 
 <SECTION>
+<FILE>e-book-sqlite</FILE>
+<TITLE>EBookSqlite</TITLE>
+E_BOOK_SQLITE_ERROR
+EbSqlChangeType
+EbSqlChangeCallback
+EbSqlVCardCallback
+EBookSqliteError
+EbSqlLockType
+EbSqlUnlockAction
+EbSqlSearchData
+EBookSqlite
+EBookSqliteClass
+EbSqlCursorOrigin
+EbSqlCursorStepFlags
+e_book_sqlite_error_quark
+e_book_sqlite_search_data_free
+e_book_sqlite_new
+e_book_sqlite_new_full
+e_book_sqlite_lock
+e_book_sqlite_unlock
+e_book_sqlite_set_locale
+e_book_sqlite_get_locale
+e_book_sqlite_ref_collator
+e_book_sqlite_add_contact
+e_book_sqlite_add_contacts
+e_book_sqlite_remove_contact
+e_book_sqlite_remove_contacts
+e_book_sqlite_has_contact
+e_book_sqlite_get_contact
+e_book_sqlite_get_vcard
+e_book_sqlite_set_contact_extra
+e_book_sqlite_get_contact_extra
+e_book_sqlite_search
+e_book_sqlite_search_uids
+e_book_sqlite_get_key_value
+e_book_sqlite_set_key_value
+e_book_sqlite_get_key_value_int
+e_book_sqlite_set_key_value_int
+e_book_sqlite_cursor_new
+e_book_sqlite_cursor_free
+e_book_sqlite_cursor_step
+e_book_sqlite_cursor_set_target_alphabetic_index
+e_book_sqlite_cursor_set_sexp
+e_book_sqlite_cursor_calculate
+e_book_sqlite_cursor_compare_contact
+EbSqlCursor
+<SUBSECTION Standard>
+EBookSqlitePrivate
+E_BOOK_SQLITE
+E_BOOK_SQLITE_CLASS
+E_BOOK_SQLITE_GET_CLASS
+E_BOOK_SQL_IS_POPULATED_KEY
+E_IS_BOOK_SQLITE
+E_IS_BOOK_SQLITE_CLASS
+E_TYPE_BOOK_SQLITE
+e_book_sqlite_get_type
+</SECTION>
+
+<SECTION>
 <FILE>e-book-backend-sqlitedb</FILE>
 <TITLE>EBookBackendSqliteDB</TITLE>
 E_BOOK_SDB_ERROR
@@ -1573,6 +1634,7 @@ E_COLLATOR_ERROR
 ECollatorError
 e_collator_error_quark
 e_collator_new
+e_collator_new_interpret_country
 e_collator_ref
 e_collator_unref
 e_collator_generate_key
@@ -1763,6 +1825,7 @@ e_data_book_new
 e_data_book_ref_backend
 e_data_book_get_connection
 e_data_book_get_object_path
+e_data_book_set_locale
 e_data_book_respond_open
 e_data_book_respond_refresh
 e_data_book_respond_create_contacts
@@ -3906,6 +3969,7 @@ EVCard
 EVCardClass
 e_vcard_construct
 e_vcard_construct_with_uid
+e_vcard_construct_full
 e_vcard_new
 e_vcard_new_from_string
 e_vcard_is_parsed