[evolution-data-server/documentation-effort: 13/18] Reorganized documentation by subject, and updated eds-sections.txt.

From: Tristan Van Berkom <tvb src gnome org>
To: commits-list gnome org
Cc:
Subject: [evolution-data-server/documentation-effort: 13/18] Reorganized documentation by subject, and updated eds-sections.txt.
Date: Thu, 5 Dec 2013 13:21:25 +0000 (UTC)
commit 029c6325e228d41f3cba8c7f2241a00b8f630eba
Author: Tristan Van Berkom <tristan upstairslabs com>
Date:   Thu Dec 5 19:41:50 2013 +0900

    Reorganized documentation by subject, and updated eds-sections.txt.

 docs/reference/eds/eds-docs.sgml    |  269 ++++++++++++++++++++++-------------
 docs/reference/eds/eds-sections.txt |   41 +++++-
 2 files changed, 206 insertions(+), 104 deletions(-)
---
diff --git a/docs/reference/eds/eds-docs.sgml b/docs/reference/eds/eds-docs.sgml
index daaa652..633fc4b 100644
--- a/docs/reference/eds/eds-docs.sgml
+++ b/docs/reference/eds/eds-docs.sgml
@@ -10,13 +10,74 @@
     <releaseinfo>for &version;</releaseinfo>
     <abstract>
       <para>
-       EDS is a bla bla with an abstract explanation RIGHT HERE.
+       Evolution-Data-Server is a collection of libraries and services
+       for storing addressbooks and calendars.
       </para>
+      <para>
+       In this reference manual you will find documentation on using the client
+       libraries as well as implementing backends for calendars and addressbooks.
+      </para>
+      <para>
+       The documentation below is organized by subject material, below is an abstract
+       description of each component in the documentation.
+      </para>
+
+      <itemizedlist>
+       <listitem>
+          <para><link linkend="data-sources">Data Sources and Extensions</link></para>
+         <para>
+           Data sources are an abstract concept for describing sources of various data types.
+           Addressbook and Calendars must be accessed by their ESource, but the ESource
+           is also relevant for backends to access various internal data types. This section
+           also includes documentation on the various existing ESourceExtensions which are
+           important for configuring the functionality of a data source.
+         </para>
+       </listitem>
+       <listitem>
+          <para><link linkend="client">Client Programming Interfaces</link></para>
+         <para>
+           This section contains the main interfaces useful for interacting
+           with Evolution Data Server in your application
+         </para>
+       </listitem>
+       <listitem>
+          <para><link linkend="backend">Backend Programming Interfaces</link></para>
+         <para>
+           This section contains the main interfaces useful for implementing
+           Addressbook and Calendar backends.
+         </para>
+       </listitem>
+       <listitem>
+          <para><link linkend="misc">Miscellaneous Utilities</link></para>
+         <para>
+           A collection of utilities which can be useful to both clients and backends.
+         </para>
+       </listitem>
+       <listitem>
+          <para><link linkend="examples">Examples</link></para>
+         <para>
+           Working examples of how to use Evolution Data Server.
+         </para>
+       </listitem>
+       <listitem>
+          <para><link linkend="unit-testing">Unit Testing</link></para>
+         <para>
+           A description of how to test Evolution Data Server itself, and
+           how to use the general unit test fixture.
+         </para>
+       </listitem>
+       <listitem>
+          <para><link linkend="deprecated">Deprecated Classes</link></para>
+         <para>
+           A list of all deprecated classes in Evolution Data Server.
+         </para>
+       </listitem>
+      </itemizedlist>
     </abstract>
   </bookinfo>
 
-  <part id="core-library">
-    <title>Data Sources and Utilities</title>
+  <part id="data-sources">
+    <title>Data Sources and Extensions</title>
 
     <chapter>
       <title>Data Sources</title>
@@ -57,41 +118,40 @@
       <xi:include href="xml/e-source-task-list.xml"/>
       <xi:include href="xml/e-source-uoa.xml"/>
       <xi:include href="xml/e-source-webdav.xml"/>
+      <xi:include href="xml/e-source-backend-summary-setup.xml"/>
     </chapter>
-    
+  </part>
+
+  <part id="client">
+    <title>Client Programming Interfaces</title>
+
     <chapter>
-      <title>Miscellaneous Utilities</title>
-      <xi:include href="xml/e-categories.xml"/>
+      <title>Shared Interaces</title>
       <xi:include href="xml/e-client.xml"/>
-      <xi:include href="xml/e-collator.xml"/>
-      <xi:include href="xml/e-debug-log.xml"/>
-      <xi:include href="xml/e-flag.xml"/>
-      <xi:include href="xml/e-memory.xml"/>
-      <xi:include href="xml/e-operation-pool.xml"/>
-      <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-data-server-util.xml"/>
-      <xi:include href="xml/e-xml-hash-utils.xml"/>
-      <xi:include href="xml/eds-version.xml"/>
     </chapter>
 
     <chapter>
-      <title>Deprecated Classes</title>
-      <xi:include href="xml/e-credentials.xml"/>
-      <xi:include href="xml/e-iterator.xml"/>
-      <xi:include href="xml/e-list.xml"/>
-      <xi:include href="xml/e-list-iterator.xml"/>
-      <xi:include href="xml/e-proxy.xml"/>
-      <xi:include href="xml/e-url.xml"/>
+      <title>Addressbook</title>
+      <xi:include href="xml/e-book-client.xml"/>
+      <xi:include href="xml/e-book-client-view.xml"/>
+      <xi:include href="xml/e-book-client-cursor.xml"/>
+      <xi:include href="xml/e-book-query.xml"/>
+      <xi:include href="xml/e-vcard.xml"/>
+      <xi:include href="xml/e-contact.xml"/>
+    </chapter>
+
+    <chapter>
+      <title>Calendar</title>
+      <xi:include href="xml/e-cal-client.xml"/>
+      <xi:include href="xml/e-cal-client-view.xml"/>
+      <xi:include href="xml/e-cal-component.xml"/>
     </chapter>
   </part>
 
   <part id="backend">
-    <title>Backend core libraries</title>
-
+    <title>Backend Programming Interfaces</title>
     <chapter>
-      <title>Base Classes for Backends</title>
+      <title>Abstract Classes for Backends</title>
       <xi:include href="xml/e-backend.xml"/>
       <xi:include href="xml/e-backend-factory.xml"/>
       <xi:include href="xml/e-data-factory.xml"/>
@@ -113,45 +173,7 @@
     </chapter>
 
     <chapter>
-      <title>Miscellaneous Utilities</title>
-      <xi:include href="xml/e-file-cache.xml"/>
-      <xi:include href="xml/e-db3-utils.xml"/>
-      <xi:include href="xml/e-soup-auth-bearer.xml"/>
-      <xi:include href="xml/e-sqlite3-vfs.xml"/>
-      <xi:include href="xml/e-user-prompter.xml"/>
-      <xi:include href="xml/e-user-prompter-server.xml"/>
-      <xi:include href="xml/e-user-prompter-server-extension.xml"/>
-    </chapter>
-
-    <chapter>
-      <title>Deprecated Classes</title>
-      <xi:include href="xml/e-dbhash.xml"/>
-      <xi:include href="xml/e-offline-listener.xml"/>
-    </chapter> 
-  </part>
-
-  <part id="addressbook">
-    <title>Addressbook</title>
-
-    <chapter>
-      <title>Addressbook Client</title>
-      <xi:include href="xml/e-book-client.xml"/>
-      <xi:include href="xml/e-book-client-view.xml"/>
-      <xi:include href="xml/e-book-client-cursor.xml"/>
-      <xi:include href="xml/e-book-types.xml"/>
-      <xi:include href="xml/e-destination.xml"/>
-      <xi:include href="xml/e-book-query.xml"/>
-      <xi:include href="xml/e-book-contacts-types.xml"/>
-      <xi:include href="xml/e-vcard.xml"/>
-      <xi:include href="xml/e-contact.xml"/>
-      <xi:include href="xml/e-address-western.xml"/>
-      <xi:include href="xml/e-name-western.xml"/>
-      <xi:include href="xml/e-source-backend-summary-setup.xml"/>
-      <xi:include href="xml/e-phone-number.xml"/>
-    </chapter>
-
-    <chapter>
-      <title>Addressbook backend infrastructure</title>
+      <title>Addressbook Backend Classes</title>
       <xi:include href="xml/e-book-backend.xml"/>
       <xi:include href="xml/e-book-backend-factory.xml"/>
       <xi:include href="xml/e-book-backend-sexp.xml"/>
@@ -163,36 +185,9 @@
       <xi:include href="xml/e-data-book-factory.xml"/>
       <xi:include href="xml/e-data-book-view.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>
-
-  <part id="calendar">
-    <title>Calendar</title>
 
     <chapter>
-      <title>Calendar Client</title>
-      <xi:include href="xml/e-cal-client.xml"/>
-      <xi:include href="xml/e-cal-client-view.xml"/>
-      <xi:include href="xml/e-cal-component.xml"/>
-      <xi:include href="xml/e-cal-recur.xml"/>
-      <xi:include href="xml/e-cal-time-util.xml"/>
-      <xi:include href="xml/e-cal-util.xml"/>
-      <xi:include href="xml/e-cal-system-timezone.xml"/>
-      <xi:include href="xml/e-cal-check-timezones.xml"/>
-      <xi:include href="xml/e-timezone-cache.xml"/>
-    </chapter>
-
-    <chapter>
-      <title>Calendar backend infrastructure</title>
+      <title>Calendar Backend Classes</title>
       <xi:include href="xml/e-cal-backend.xml"/>
       <xi:include href="xml/e-cal-backend-cache.xml"/>
       <xi:include href="xml/e-cal-backend-factory.xml"/>
@@ -205,17 +200,95 @@
       <xi:include href="xml/e-data-cal-factory.xml"/>
       <xi:include href="xml/e-data-cal-view.xml"/>
     </chapter>
+  </part>
 
+  <part id="misc">
+    <title>Miscellaneous Utilities</title>
     <chapter>
-      <title>Deprecated Classes</title>
-      <xi:include href="xml/e-cal.xml"/>
-      <xi:include href="xml/e-cal-view.xml"/>
+      <title>Available for clients and backends</title>
+      <xi:include href="xml/e-categories.xml"/>
+      <xi:include href="xml/e-collator.xml"/>
+      <xi:include href="xml/e-debug-log.xml"/>
+      <xi:include href="xml/e-flag.xml"/>
+      <xi:include href="xml/e-memory.xml"/>
+      <xi:include href="xml/e-operation-pool.xml"/>
+      <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-data-server-util.xml"/>
+      <xi:include href="xml/e-xml-hash-utils.xml"/>
+      <xi:include href="xml/eds-version.xml"/>
+    </chapter>
+
+    <chapter>
+      <title>Available only for backends</title>
+      <xi:include href="xml/e-file-cache.xml"/>
+      <xi:include href="xml/e-db3-utils.xml"/>
+      <xi:include href="xml/e-soup-auth-bearer.xml"/>
+      <xi:include href="xml/e-sqlite3-vfs.xml"/>
+      <xi:include href="xml/e-user-prompter.xml"/>
+      <xi:include href="xml/e-user-prompter-server.xml"/>
+      <xi:include href="xml/e-user-prompter-server-extension.xml"/>
+    </chapter>
+
+    <chapter>
+      <title>Addressbook related utilities</title>
+      <xi:include href="xml/e-book-contacts-types.xml"/>
+      <xi:include href="xml/e-destination.xml"/>
+      <xi:include href="xml/e-address-western.xml"/>
+      <xi:include href="xml/e-name-western.xml"/>
+      <xi:include href="xml/e-phone-number.xml"/>
+    </chapter>
+
+    <chapter>
+      <title>Calendar related utilities</title>
+      <xi:include href="xml/e-cal-recur.xml"/>
+      <xi:include href="xml/e-cal-time-util.xml"/>
+      <xi:include href="xml/e-cal-util.xml"/>
+      <xi:include href="xml/e-cal-system-timezone.xml"/>
+      <xi:include href="xml/e-cal-check-timezones.xml"/>
+      <xi:include href="xml/e-timezone-cache.xml"/>
     </chapter>
   </part>
 
   <part id="examples">
     <title>Examples</title>
-    <xi:include href="xml/eds-cursor-example.sgml" />
+    <xi:include href="xml/eds-cursor-example.sgml"/>
+  </part>
+
+  <part id="unit-testing">
+    <title>Unit Testing</title>
+    <xi:include href="xml/e-test-server-utils.xml"/>
+  </part>
+
+  <part id="deprecated">
+    <title>Deprecated Classes</title>
+    <chapter>
+      <title>Common Deprecated Classes</title>
+      <xi:include href="xml/e-credentials.xml"/>
+      <xi:include href="xml/e-iterator.xml"/>
+      <xi:include href="xml/e-list.xml"/>
+      <xi:include href="xml/e-list-iterator.xml"/>
+      <xi:include href="xml/e-proxy.xml"/>
+      <xi:include href="xml/e-url.xml"/>
+    </chapter>
+    <chapter>
+      <title>Client Deprecated Classes</title>
+      <xi:include href="xml/e-book.xml"/>
+      <xi:include href="xml/e-book-view.xml"/>
+      <xi:include href="xml/e-cal.xml"/>
+      <xi:include href="xml/e-cal-view.xml"/>
+      <xi:include href="xml/e-book-types.xml"/>
+    </chapter>
+    <chapter>
+      <title>Backend Deprecated Classes</title>
+      <xi:include href="xml/e-dbhash.xml"/>
+      <xi:include href="xml/e-offline-listener.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>
 
   <index id="api-index-full">
diff --git a/docs/reference/eds/eds-sections.txt b/docs/reference/eds/eds-sections.txt
index fb1f18f..738b5ad 100644
--- a/docs/reference/eds/eds-sections.txt
+++ b/docs/reference/eds/eds-sections.txt
@@ -1,5 +1,6 @@
 <SECTION>
 <FILE>e-address-western</FILE>
+<TITLE>EAddressWestern</TITLE>
 EAddressWestern
 e_address_western_parse
 e_address_western_free
@@ -662,6 +663,7 @@ e_book_client_view_get_type
 
 <SECTION>
 <FILE>e-book-contacts-types</FILE>
+<TITLE>Addressbook related types</TITLE>
 E_BOOK_CLIENT_ERROR
 EBookClientViewFlags
 EBookClientError
@@ -680,7 +682,9 @@ e_book_client_error_create
 
 <SECTION>
 <FILE>e-book-query</FILE>
+<TITLE>EBookQuery</TITLE>
 EBookQueryTest
+EBookQuery
 e_book_query_from_string
 e_book_query_to_string
 e_book_query_ref
@@ -696,7 +700,6 @@ e_book_query_field_test
 e_book_query_vcard_field_test
 e_book_query_any_field_contains
 e_book_query_copy
-EBookQuery
 <SUBSECTION Standard>
 E_TYPE_BOOK_QUERY
 e_book_query_get_type
@@ -704,6 +707,7 @@ e_book_query_get_type
 
 <SECTION>
 <FILE>e-book-types</FILE>
+<TITLE>Deprecated addressbook types</TITLE>
 E_BOOK_ERROR
 e_book_error_quark
 EBookStatus
@@ -1064,6 +1068,7 @@ e_cal_backend_sync_get_type
 
 <SECTION>
 <FILE>e-cal-backend-util</FILE>
+<TITLE>Calendar Backend Utilities</TITLE>
 e_cal_backend_mail_account_get_default
 e_cal_backend_mail_account_is_valid
 e_cal_backend_user_declined
@@ -1071,6 +1076,7 @@ e_cal_backend_user_declined
 
 <SECTION>
 <FILE>e-cal-check-timezones</FILE>
+<TITLE>Calendar timezones</TITLE>
 e_cal_client_check_timezones
 e_cal_client_tzlookup
 e_cal_client_tzlookup_icomp
@@ -1384,6 +1390,7 @@ e_cal_component_get_type
 
 <SECTION>
 <FILE>e-cal-recur</FILE>
+<TITLE>Calendar recurrences</TITLE>
 ECalRecurInstanceFn
 ECalRecurResolveTimezoneFn
 e_cal_recur_generate_instances
@@ -1395,11 +1402,13 @@ e_cal_recur_nth
 
 <SECTION>
 <FILE>e-cal-system-timezone</FILE>
+<TITLE>Calendar system timezone</TITLE>
 e_cal_system_timezone_get_location
 </SECTION>
 
 <SECTION>
 <FILE>e-cal-time-util</FILE>
+<TITLE>Calendar time utilities</TITLE>
 time_days_in_month
 time_day_of_year
 time_day_of_week
@@ -1447,6 +1456,7 @@ CALOBJ_MOD_ONLY_THIS
 
 <SECTION>
 <FILE>e-cal-util</FILE>
+<TITLE>Calendar utilities</TITLE>
 CalObjInstance
 cal_obj_instance_list_free
 cal_obj_uid_list_free
@@ -1545,6 +1555,7 @@ ECancellableRecMutex
 
 <SECTION>
 <FILE>e-categories</FILE>
+<TITLE>ECategories</TITLE>
 e_categories_get_list
 e_categories_add
 e_categories_remove
@@ -1630,8 +1641,10 @@ e_client_set_online
 
 <SECTION>
 <FILE>e-collator</FILE>
+<TITLE>ECollator</TITLE>
 E_COLLATOR_ERROR
 ECollatorError
+ECollator
 e_collator_error_quark
 e_collator_new
 e_collator_new_interpret_country
@@ -1642,7 +1655,6 @@ e_collator_generate_key_for_index
 e_collator_collate
 e_collator_get_index_labels
 e_collator_get_index
-ECollator
 <SUBSECTION Standard>
 E_TYPE_COLLATOR
 e_collator_get_type
@@ -1778,6 +1790,7 @@ e_contact_photo_get_type
 
 <SECTION>
 <FILE>e-credentials</FILE>
+<TITLE>ECredentials</TITLE>
 ECredentials
 E_CREDENTIALS_KEY_USERNAME
 E_CREDENTIALS_KEY_PASSWORD
@@ -2084,6 +2097,7 @@ e_data_factory_get_type
 
 <SECTION>
 <FILE>e-data-server-util</FILE>
+<TITLE>Main Utility Toolbox</TITLE>
 e_get_user_cache_dir
 e_get_user_config_dir
 e_get_user_data_dir
@@ -2155,12 +2169,14 @@ e_named_parameters_get_type
 
 <SECTION>
 <FILE>e-db3-utils</FILE>
+<TITLE>Berkeley DB utilities</TITLE>
 e_db3_utils_maybe_recover
 e_db3_utils_upgrade_format
 </SECTION>
 
 <SECTION>
 <FILE>e-dbhash</FILE>
+<TITLE>EDbHash</TITLE>
 EDbHashStatus
 EDbHash
 EDbHashFunc
@@ -2197,6 +2213,7 @@ e_dbus_server_get_type
 
 <SECTION>
 <FILE>e-debug-log</FILE>
+<TITLE>Debug logging</TITLE>
 E_DEBUG_LOG_DOMAIN_USER
 E_DEBUG_LOG_DOMAIN_GLOG
 E_DEBUG_LOG_DOMAIN_CAL_QUERIES
@@ -2337,6 +2354,8 @@ e_file_cache_get_type
 
 <SECTION>
 <FILE>e-flag</FILE>
+<TITLE>EFlag</TITLE>
+EFlag
 e_flag_new
 e_flag_is_set
 e_flag_set
@@ -2345,7 +2364,6 @@ e_flag_wait
 e_flag_wait_until
 e_flag_free
 e_flag_timed_wait
-EFlag
 </SECTION>
 
 <SECTION>
@@ -2585,6 +2603,8 @@ e_list_iterator_get_type
 
 <SECTION>
 <FILE>e-memory</FILE>
+<TITLE>EMemChunk</TITLE>
+EMemChunk
 e_memchunk_new
 e_memchunk_alloc
 e_memchunk_alloc0
@@ -2592,7 +2612,6 @@ e_memchunk_free
 e_memchunk_empty
 e_memchunk_clean
 e_memchunk_destroy
-EMemChunk
 </SECTION>
 
 <SECTION>
@@ -2618,6 +2637,7 @@ e_module_get_type
 
 <SECTION>
 <FILE>e-name-western</FILE>
+<TITLE>ENameWestern</TITLE>
 ENameWestern
 e_name_western_parse
 e_name_western_free
@@ -2659,21 +2679,24 @@ e_offline_listener_get_type
 
 <SECTION>
 <FILE>e-operation-pool</FILE>
+<TITLE>EOperationPool</TITLE>
+EOperationPool
 e_operation_pool_new
 e_operation_pool_free
 e_operation_pool_reserve_opid
 e_operation_pool_release_opid
 e_operation_pool_push
-EOperationPool
 </SECTION>
 
 <SECTION>
 <FILE>e-phone-number</FILE>
+<TITLE>EPhoneNumber</TITLE>
 E_PHONE_NUMBER_ERROR
 EPhoneNumberFormat
 EPhoneNumberMatch
 EPhoneNumberError
 EPhoneNumberCountrySource
+EPhoneNumber
 e_phone_number_error_quark
 e_phone_number_is_supported
 e_phone_number_get_country_code_for_region
@@ -2687,7 +2710,6 @@ e_phone_number_compare_strings
 e_phone_number_compare_strings_with_region
 e_phone_number_copy
 e_phone_number_free
-EPhoneNumber
 <SUBSECTION Standard>
 E_TYPE_PHONE_NUMBER
 e_phone_number_get_type
@@ -3757,11 +3779,13 @@ e_source_webdav_get_type
 
 <SECTION>
 <FILE>e-sqlite3-vfs</FILE>
+<TITLE>SQLite vfs</TITLE>
 e_sqlite3_vfs_init
 </SECTION>
 
 <SECTION>
 <FILE>e-test-server-utils</FILE>
+<TITLE>ETestServerFixture</TITLE>
 E_TEST_SERVER_UTILS_SERVICE
 ETestSourceCustomizeFunc
 ETestServiceType
@@ -3777,6 +3801,7 @@ e_test_server_utils_run_full
 
 <SECTION>
 <FILE>e-time-utils</FILE>
+<TITLE>Time parsing and formatting</TITLE>
 ETimeParseStatus
 e_time_parse_date_and_time
 e_time_parse_date
@@ -3813,11 +3838,13 @@ ETransliterator
 
 <SECTION>
 <FILE>e-uid</FILE>
+<TITLE>Unique identifiers</TITLE>
 e_uid_new
 </SECTION>
 
 <SECTION>
 <FILE>e-url</FILE>
+<TITLE>EUri</TITLE>
 EUri
 e_uri_new
 e_uri_free
@@ -4038,6 +4065,7 @@ e_vcard_get_type
 
 <SECTION>
 <FILE>e-xml-hash-utils</FILE>
+<TITLE>EXmlHash</TITLE>
 EXmlHashType
 e_xml_to_hash
 e_xml_from_hash
@@ -4065,6 +4093,7 @@ e_xml_get_child_by_name
 
 <SECTION>
 <FILE>eds-version</FILE>
+<TITLE>Version Checking</TITLE>
 EDS_MAJOR_VERSION
 EDS_MINOR_VERSION
 EDS_MICRO_VERSION
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]