New <book> toplevel for the Evolution Developer's Guide.

2000-07-17  Federico Mena Quintero  <federico@helixcode.com>

	* evolution-devel-guide.sgml: New <book> toplevel for the
	Evolution Developer's Guide.

	* calendar/evolution-calendar.sgml: New <part> for the calendar
	developer's documentation.

	* calendar/architecture.sgml: New <chapter> for the calendar
	architecture.

	* calendar/reference.sgml: New <reference> for the calendar API
	reference.

svn path=/trunk/; revision=4191

16 files changed, 590 insertions, 0 deletions

diff --git a/doc/devel/calendar/.cvsignore b/doc/devel/calendar/.cvsignore
new file mode 100644
index 0000000000..282522db03
--- /dev/null
+++ b/doc/devel/calendar/.cvsignore
@@ -0,0 +1,2 @@
+Makefile
+Makefile.in
diff --git a/doc/devel/calendar/Makefile.am b/doc/devel/calendar/Makefile.am
new file mode 100644
index 0000000000..7efde02896
--- /dev/null
+++ b/doc/devel/calendar/Makefile.am
@@ -0,0 +1,6 @@
+SUBDIRS = cal-client
+
+EXTRA_DIST =				\
+	architecture.sgml		\
+	evolution-calendar.sgml		\
+	reference.sgml
diff --git a/doc/devel/calendar/architecture.sgml b/doc/devel/calendar/architecture.sgml
new file mode 100644
index 0000000000..b174965fc3
--- /dev/null
+++ b/doc/devel/calendar/architecture.sgml
@@ -0,0 +1,17 @@
+  <chapter>
+    <title>Overview of the Calendar</title>
+
+    <para>
+      This chapter gives an overview of the Evolution Calendar
+      architecture.  It describes the model/view split of the calendar
+      into a personal calendar server (PCS) and the GUI clients that
+      appear inside the Evolution shell.
+    </para>
+  </chapter>
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../evolution-devel-guide.sgml" "book" "part" "")
+End:
+-->
diff --git a/doc/devel/calendar/cal-client/.cvsignore b/doc/devel/calendar/cal-client/.cvsignore
new file mode 100644
index 0000000000..0842a93f7a
--- /dev/null
+++ b/doc/devel/calendar/cal-client/.cvsignore
@@ -0,0 +1,3 @@
+sgml
+Makefile
+Makefile.in
diff --git a/doc/devel/calendar/cal-client/Makefile.am b/doc/devel/calendar/cal-client/Makefile.am
new file mode 100644
index 0000000000..44d43639a8
--- /dev/null
+++ b/doc/devel/calendar/cal-client/Makefile.am
@@ -0,0 +1,76 @@
+## Process this file with automake to produce Makefile.in
+
+# The name of the module.
+DOC_MODULE=evolution-cal-client
+
+# The top-level SGML file.
+DOC_MAIN_SGML_FILE=evolution-cal-client.sgml
+
+# The directory containing the source code (if it contains documentation).
+DOC_SOURCE_DIR=$(EVOLUTION_DIR)/calendar/cal-client
+
+CFLAGS ="						\
+	-I$(top_srcdir)/calendar			\
+	-I$(top_srcdir)					\
+	-I$(top_builddir)				\
+	-I$(top_builddir)/libical/src/libical		\
+	-I$(top_srcdir)/libical/src/libical		\
+	$(BONOBO_VFS_GNOME_CFLAGS)			\
+	"
+
+LDFLAGS="								\
+	$(BONOBO_VFS_GNOME_LIBS)					\
+	$(top_builddir)/calendar/cal-client/.libs/libcal-client.a	\
+	$(top_builddir)/calendar/cal-util/.libs/libcal-util.a		\
+	$(top_builddir)/libical/src/libical/libical.a			\
+	$(top_builddir)/libversit/.libs/libversit.al			\
+	"
+
+HTML_DIR=$(datadir)/gnome/html
+
+TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
+
+tmpl_sources =					\
+	tmpl/cal-client.sgml			\
+	tmpl/evolution-cal-client-unused.sgml
+
+evolution_cal_client_docdir = $(HTML_DIR)
+evolution_cal_client_doc_DATA =			\
+	evolution-cal-client.hierarchy		\
+	evolution-cal-client.types		\
+	evolution-cal-client-decl.txt		\
+	evolution-cal-client-sections.txt
+
+EXTRA_DIST = 					\
+	$(evolution_cal_client_doc_DATA)
+
+sgml/evolution-cal-client-doc.bottom: $(tmpl_sources)
+	$(MAKE) sgml
+
+scan:
+	-(cd $(srcdir) \
+	&& env CFLAGS=$(CFLAGS) LDFLAGS=$(LDFLAGS) \
+		 gtkdoc-scanobj --module=$(DOC_MODULE) \
+	&& gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="cal-listener.h evolution-calendar.h" )
+
+templates: scan
+	cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
+
+sgml:
+	cd $(srcdir) \
+	&& gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR)
+
+clean-local:
+	rm -f *~ *.bak *.signals *-unused.txt
+
+maintainer-clean-local: clean
+	cd $(srcdir) && rm -rf sgml $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
+
+dist-hook:
+	mkdir $(distdir)/sgml
+	mkdir $(distdir)/tmpl
+	-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
+	-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
+	-cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml
+
+.PHONY : sgml templates scan
diff --git a/doc/devel/calendar/cal-client/evolution-cal-client-decl.txt b/doc/devel/calendar/cal-client/evolution-cal-client-decl.txt
new file mode 100644
index 0000000000..9fffd4c201
--- /dev/null
+++ b/doc/devel/calendar/cal-client/evolution-cal-client-decl.txt
@@ -0,0 +1,127 @@
+<MACRO>
+<NAME>CAL_CLIENT_TYPE</NAME>
+#define CAL_CLIENT_TYPE            (cal_client_get_type ())
+</MACRO>
+<MACRO>
+<NAME>CAL_CLIENT</NAME>
+#define CAL_CLIENT(obj)            (GTK_CHECK_CAST ((obj), CAL_CLIENT_TYPE, CalClient))
+</MACRO>
+<MACRO>
+<NAME>CAL_CLIENT_CLASS</NAME>
+#define CAL_CLIENT_CLASS(klass)    (GTK_CHECK_CLASS_CAST ((klass), CAL_CLIENT_TYPE, CalClientClass))
+</MACRO>
+<MACRO>
+<NAME>IS_CAL_CLIENT</NAME>
+#define IS_CAL_CLIENT(obj)         (GTK_CHECK_TYPE ((obj), CAL_CLIENT_TYPE))
+</MACRO>
+<MACRO>
+<NAME>IS_CAL_CLIENT_CLASS</NAME>
+#define IS_CAL_CLIENT_CLASS(klass) (GTK_CHECK_CLASS_TYPE ((klass), CAL_CLIENT_TYPE))
+</MACRO>
+<STRUCT>
+<NAME>CalClient</NAME>
+</STRUCT>
+<STRUCT>
+<NAME>CalClientClass</NAME>
+</STRUCT>
+<ENUM>
+<NAME>CalClientLoadStatus</NAME>
+typedef enum {
+	CAL_CLIENT_LOAD_SUCCESS,
+	CAL_CLIENT_LOAD_ERROR,
+	CAL_CLIENT_LOAD_IN_USE,
+	CAL_CLIENT_LOAD_METHOD_NOT_SUPPORTED
+} CalClientLoadStatus;
+</ENUM>
+<ENUM>
+<NAME>CalClientGetStatus</NAME>
+typedef enum {
+	CAL_CLIENT_GET_SUCCESS,
+	CAL_CLIENT_GET_NOT_FOUND,
+	CAL_CLIENT_GET_SYNTAX_ERROR
+} CalClientGetStatus;
+</ENUM>
+<STRUCT>
+<NAME>CalClient</NAME>
+struct CalClient {
+	GtkObject object;
+
+	/* Private data */
+	gpointer priv;
+};
+</STRUCT>
+<FUNCTION>
+<NAME>cal_client_get_type</NAME>
+<RETURNS>GtkType  </RETURNS>
+void
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_construct</NAME>
+<RETURNS>CalClient  *</RETURNS>
+CalClient *client
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_new</NAME>
+<RETURNS>CalClient  *</RETURNS>
+void
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_load_calendar</NAME>
+<RETURNS>gboolean  </RETURNS>
+CalClient *client, const char *str_uri
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_create_calendar</NAME>
+<RETURNS>gboolean  </RETURNS>
+CalClient *client, const char *str_uri
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_get_n_objects</NAME>
+<RETURNS>int  </RETURNS>
+CalClient *client, CalObjType type
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_get_object</NAME>
+<RETURNS>CalClientGetStatus  </RETURNS>
+CalClient *client,const char *uid,iCalObject **ico
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_get_uid_by_pilot_id</NAME>
+<RETURNS>CalClientGetStatus  </RETURNS>
+CalClient *client,unsigned long pilot_id,char **uid
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_update_pilot_id</NAME>
+<RETURNS>void  </RETURNS>
+CalClient *client, char *uid,unsigned long pilot_id,unsigned long pilot_status
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_get_uids</NAME>
+<RETURNS>GList  *</RETURNS>
+CalClient *client, CalObjType type
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_get_events_in_range</NAME>
+<RETURNS>GList  *</RETURNS>
+CalClient *client, time_t start, time_t end
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_get_alarms_in_range</NAME>
+<RETURNS>GList  *</RETURNS>
+CalClient *client, time_t start, time_t end
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_get_alarms_for_object</NAME>
+<RETURNS>gboolean  </RETURNS>
+CalClient *client, const char *uid,time_t start, time_t end,GList **alarms
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_update_object</NAME>
+<RETURNS>gboolean  </RETURNS>
+CalClient *client, iCalObject *ico
+</FUNCTION>
+<FUNCTION>
+<NAME>cal_client_remove_object</NAME>
+<RETURNS>gboolean  </RETURNS>
+CalClient *client, const char *uid
+</FUNCTION>
diff --git a/doc/devel/calendar/cal-client/evolution-cal-client-sections.txt b/doc/devel/calendar/cal-client/evolution-cal-client-sections.txt
new file mode 100644
index 0000000000..5496f2f0f2
--- /dev/null
+++ b/doc/devel/calendar/cal-client/evolution-cal-client-sections.txt
@@ -0,0 +1,36 @@
+<INCLUDE>cal-client/cal-client.h</INCLUDE>
+
+<SECTION>
+<FILE>cal-client</FILE>
+CAL_CLIENT
+<TITLE>CalClient</TITLE>
+
+CalClientLoadStatus
+CalClientGetStatus
+cal_client_new
+cal_client_load_calendar
+cal_client_create_calendar
+cal_client_get_n_objects
+cal_client_get_object
+cal_client_get_uid_by_pilot_id
+cal_client_update_pilot_id
+cal_client_get_uids
+cal_client_get_events_in_range
+cal_client_get_alarms_in_range
+cal_client_get_alarms_for_object
+cal_client_update_object
+cal_client_remove_object
+
+<SUBSECTION Standard>
+
+CAL_CLIENT_TYPE
+IS_CAL_CLIENT
+CAL_CLIENT_CLASS
+IS_CAL_CLIENT_CLASS
+cal_client_get_type
+cal_client_construct
+
+<SUBSECTION Private>
+CalClient
+
+</SECTION>
diff --git a/doc/devel/calendar/cal-client/evolution-cal-client.args b/doc/devel/calendar/cal-client/evolution-cal-client.args
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/doc/devel/calendar/cal-client/evolution-cal-client.args
diff --git a/doc/devel/calendar/cal-client/evolution-cal-client.hierarchy b/doc/devel/calendar/cal-client/evolution-cal-client.hierarchy
new file mode 100644
index 0000000000..88efa3e673
--- /dev/null
+++ b/doc/devel/calendar/cal-client/evolution-cal-client.hierarchy
@@ -0,0 +1,2 @@
+GtkObject
+  CalClient
diff --git a/doc/devel/calendar/cal-client/evolution-cal-client.signals b/doc/devel/calendar/cal-client/evolution-cal-client.signals
new file mode 100644
index 0000000000..97e360b6a2
--- /dev/null
+++ b/doc/devel/calendar/cal-client/evolution-cal-client.signals
@@ -0,0 +1,21 @@
+<SIGNAL>
+<NAME>CalClient::cal-loaded</NAME>
+<RETURNS>void</RETURNS>
+CalClient *calclient
+GtkEnum  arg1
+</SIGNAL>
+
+<SIGNAL>
+<NAME>CalClient::obj-updated</NAME>
+<RETURNS>void</RETURNS>
+CalClient *calclient
+GtkString  arg1
+</SIGNAL>
+
+<SIGNAL>
+<NAME>CalClient::obj-removed</NAME>
+<RETURNS>void</RETURNS>
+CalClient *calclient
+GtkString  arg1
+</SIGNAL>
+
diff --git a/doc/devel/calendar/cal-client/evolution-cal-client.types b/doc/devel/calendar/cal-client/evolution-cal-client.types
new file mode 100644
index 0000000000..84d65a6637
--- /dev/null
+++ b/doc/devel/calendar/cal-client/evolution-cal-client.types
@@ -0,0 +1,4 @@
+#include <gnome.h>
+#include <cal-client/cal-client.h>
+
+cal_client_get_type
diff --git a/doc/devel/calendar/cal-client/tmpl/cal-client.sgml b/doc/devel/calendar/cal-client/tmpl/cal-client.sgml
new file mode 100644
index 0000000000..7fdc69bfdc
--- /dev/null
+++ b/doc/devel/calendar/cal-client/tmpl/cal-client.sgml
@@ -0,0 +1,205 @@
+<!-- ##### SECTION Title ##### -->
+CalClient
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO CAL_CLIENT ##### -->
+<para>
+
+</para>
+
+@obj: 
+
+
+<!-- ##### ENUM CalClientLoadStatus ##### -->
+<para>
+
+</para>
+
+@CAL_CLIENT_LOAD_SUCCESS: 
+@CAL_CLIENT_LOAD_ERROR: 
+@CAL_CLIENT_LOAD_IN_USE: 
+@CAL_CLIENT_LOAD_METHOD_NOT_SUPPORTED: 
+
+<!-- ##### ENUM CalClientGetStatus ##### -->
+<para>
+
+</para>
+
+@CAL_CLIENT_GET_SUCCESS: 
+@CAL_CLIENT_GET_NOT_FOUND: 
+@CAL_CLIENT_GET_SYNTAX_ERROR: 
+
+<!-- ##### FUNCTION cal_client_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION cal_client_load_calendar ##### -->
+<para>
+
+</para>
+
+@client: 
+@str_uri: 
+@Returns: 
+
+
+<!-- ##### FUNCTION cal_client_create_calendar ##### -->
+<para>
+
+</para>
+
+@client: 
+@str_uri: 
+@Returns: 
+
+
+<!-- ##### FUNCTION cal_client_get_n_objects ##### -->
+<para>
+
+</para>
+
+@client: 
+@type: 
+@Returns: 
+
+
+<!-- ##### FUNCTION cal_client_get_object ##### -->
+<para>
+
+</para>
+
+@client: 
+@uid: 
+@ico: 
+@Returns: 
+
+
+<!-- ##### FUNCTION cal_client_get_uid_by_pilot_id ##### -->
+<para>
+
+</para>
+
+@client: 
+@pilot_id: 
+@uid: 
+@Returns: 
+
+
+<!-- ##### FUNCTION cal_client_update_pilot_id ##### -->
+<para>
+
+</para>
+
+@client: 
+@uid: 
+@pilot_id: 
+@pilot_status: 
+
+
+<!-- ##### FUNCTION cal_client_get_uids ##### -->
+<para>
+
+</para>
+
+@client: 
+@type: 
+@Returns: 
+
+
+<!-- ##### FUNCTION cal_client_get_events_in_range ##### -->
+<para>
+
+</para>
+
+@client: 
+@start: 
+@end: 
+@Returns: 
+
+
+<!-- ##### FUNCTION cal_client_get_alarms_in_range ##### -->
+<para>
+
+</para>
+
+@client: 
+@start: 
+@end: 
+@Returns: 
+
+
+<!-- ##### FUNCTION cal_client_get_alarms_for_object ##### -->
+<para>
+
+</para>
+
+@client: 
+@uid: 
+@start: 
+@end: 
+@alarms: 
+@Returns: 
+
+
+<!-- ##### FUNCTION cal_client_update_object ##### -->
+<para>
+
+</para>
+
+@client: 
+@ico: 
+@Returns: 
+
+
+<!-- ##### FUNCTION cal_client_remove_object ##### -->
+<para>
+
+</para>
+
+@client: 
+@uid: 
+@Returns: 
+
+
+<!-- ##### SIGNAL CalClient::cal-loaded ##### -->
+<para>
+
+</para>
+
+@calclient: the object which received the signal.
+@arg1: 
+
+<!-- ##### SIGNAL CalClient::obj-updated ##### -->
+<para>
+
+</para>
+
+@calclient: the object which received the signal.
+@arg1: 
+
+<!-- ##### SIGNAL CalClient::obj-removed ##### -->
+<para>
+
+</para>
+
+@calclient: the object which received the signal.
+@arg1: 
+
diff --git a/doc/devel/calendar/cal-client/tmpl/evolution-cal-client-unused.sgml b/doc/devel/calendar/cal-client/tmpl/evolution-cal-client-unused.sgml
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/doc/devel/calendar/cal-client/tmpl/evolution-cal-client-unused.sgml
diff --git a/doc/devel/calendar/evolution-calendar.sgml b/doc/devel/calendar/evolution-calendar.sgml
new file mode 100644
index 0000000000..f3936d9bbc
--- /dev/null
+++ b/doc/devel/calendar/evolution-calendar.sgml
@@ -0,0 +1,51 @@
+  <part>
+    <docinfo>
+      <authorgroup>
+	<author>
+	  <firstname>Federico</firstname>
+	  <surname>Mena Quintero</surname>
+	  <affiliation>
+	    <address>
+	      <email>federico@helixcode.com</email>
+	    </address>
+	  </affiliation>
+	</author>
+      </authorgroup>
+    </docinfo>
+
+    <title>Developing Applications for the Evolution Calendar</title>
+
+    <partintro>
+      <para>
+	This part of the Evolution Developer's Guide describes how to
+	write applications for the Evolution Calendar by using its
+	public interfaces.  The Evolution Calendar exports its
+	functionality through a number of interfaces, including CORBA,
+	GTK+ wrappers for Bonobo objects, and other utility libraries.
+      </para>
+
+      <para>
+	You should read this part of the Evolution Developer's guide
+	if you intend to write client applications that use the
+	functionality of the Evolution Calendar.
+      </para>
+
+      <para>
+	This part does not describe the internal interfaces of the
+	Evolution Calendar; for that you should read the Evolution
+	Internals Guide.  You should only need to read that guide if
+	you are interested in the way the calendar works internally or
+	if you want to make changes directly to the Evolution Calendar
+	code.
+      </para>
+    </partintro>
+
+    &calendar-architecture;
+  </part>
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../evolution-devel-guide.sgml" "book" "book" "")
+End:
+-->
diff --git a/doc/devel/calendar/public-reference.sgml b/doc/devel/calendar/public-reference.sgml
new file mode 100644
index 0000000000..afe3b85628
--- /dev/null
+++ b/doc/devel/calendar/public-reference.sgml
@@ -0,0 +1,20 @@
+  <reference>
+    <title>Calendar Public API Reference</title>
+
+    <partintro>
+      <para>
+	This part presents the class and function reference for the
+	public APIs of the different components of the Evolution
+	Calendar.
+      </para>
+    </partintro>
+
+    &CalClient;
+  </reference>
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../evolution-devel-guide.sgml" "book" "part" "")
+End:
+-->
diff --git a/doc/devel/calendar/reference.sgml b/doc/devel/calendar/reference.sgml
new file mode 100644
index 0000000000..afe3b85628
--- /dev/null
+++ b/doc/devel/calendar/reference.sgml
@@ -0,0 +1,20 @@
+  <reference>
+    <title>Calendar Public API Reference</title>
+
+    <partintro>
+      <para>
+	This part presents the class and function reference for the
+	public APIs of the different components of the Evolution
+	Calendar.
+      </para>
+    </partintro>
+
+    &CalClient;
+  </reference>
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../evolution-devel-guide.sgml" "book" "part" "")
+End:
+-->