From 0b0d512054c942e25923292d82cf33ad880053e8 Mon Sep 17 00:00:00 2001 From: "Dirk-Jan C. Binnema" Date: Wed, 10 May 2006 10:21:03 +0000 Subject: [PATCH] * add documentation pmo-trunk-r23 --- docs/Makefile.am | 6 ++ docs/design/modest-design.tex | 200 ++++++++++++++++++++++++++++++++++++ docs/reference/Makefile.am | 75 ++++++++++++++ docs/reference/modest-docs.sgml | 43 ++++++++ docs/reference/modest-sections.txt | 180 ++++++++++++++++++++++++++++++++ 5 files changed, 504 insertions(+) create mode 100644 docs/Makefile.am create mode 100644 docs/design/modest-design.tex create mode 100644 docs/reference/Makefile.am create mode 100644 docs/reference/modest-docs.sgml create mode 100644 docs/reference/modest-overrides.txt create mode 100644 docs/reference/modest-sections.txt diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 0000000..8f1649b --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,6 @@ +# +# Makefile.am +# Time-stamp: <2006-04-17 13:23:36 (djcb)> +SUBDIRS=reference + +EXTRA_DIST=design diff --git a/docs/design/modest-design.tex b/docs/design/modest-design.tex new file mode 100644 index 0000000..f38a0fa --- /dev/null +++ b/docs/design/modest-design.tex @@ -0,0 +1,200 @@ +% +% modest-design.tex +% Time-stamp: <2006-05-04 17:21:51 (djcb)> + +% macros +\newcommand{\modest}{{\tt modest} } +\newcommand{\tinymail}{{\tt tinymail} } +\newcommand{\camel}{{\tt libcamel} } + +\newcommand{\djcbemail}{$<$dirk-jan.binnema@nokia.com$>$ } +\newcommand{\smtp}{{\sc SMTP} } +\newcommand{\pop}{{\sc POP3} } +\newcommand{\imap}{{\sc IMAP} } +\newcommand{\gtk}{{\sc GTK+} } +\newcommand{\gconf}{{\sc GConf} } + + +\documentclass{book} +\author{Dirk-Jan C. Binnema\\\djcbemail} +\title{{\huge \modest}\\ +an e-mail program for small devices\\ +architecture \& design} +\setlength{\parskip}{8pt} +\setlength{\parindent}{0pt} +\begin{document} +\maketitle +\tableofcontents +\chapter*{Introduction} +\modest is a mail user agent (MUA) targetting small devices, in particular +Nokia's {\em Nokia 770 Internet Tablet}. This document describes the design +and implementation of this software. + +\modest lives at the top of a extensive stack of software. It is built on +top of {\tt libtinymail}, and uses its libcamel backend. It strives to the be +a simple yet powerful program, geared towards small devices, for example (but +not limited to) Nokia's 770 internet tablet. An important goal is to minimize +memory usage while still being able to handle significant amounts of email +quickly; much of that is achieved simply by using \tinymail, which +uses a number of clever tricks for that, such as the proxy design pattern for +listing email headers, and not needing memory for headers which are not +currently visible. + +\modest, in turn, also tries to be efficient, fast and {\em scalable}. That +means that the MUA should support multiple user-interfaces, perhaps making it +even possible to switch between them during runtime. + +To summarize the goals for \modest: +\begin{itemize} +\item target devices with limited amounts of memory ("limited" in 2006 terms means + less than 64Mb, and of which only part can be used for e-mail); +\item target Linux/Unix-like environments with GLib/GTK+-based support; +\item support multiple user-interface (UIs) with as + much code sharing as possible between the different UIs. +\end{itemize} + +Like {\tt libtinymail} and {\tt libcamel}, \modest is programmed in C, using the +GObject-system for object-oriented (OO) features. For now, it specifically +targets \gtk based UIs (and derivatives like "Hildon"). + +\chapter{Architecture} +\modest tries to be quite flexible in its design. However, it's always +important not to make things {\em too} generic. Both for reasons of time +limitations and keeping the software understandable and ``modest'', it's +important to limit the scope. + +For \modest, the following: +\begin{itemize} + \item \modest is a e-mail program using the \tinymail and \camel libraries; + \item \modest targets \gtk and \gconf-based user-interfaces, including the Hildon + environment; + \item \modest main use-case is in small, mobile device such as Nokia's {\em 770 + Internet Tablet}; + \item However, effort is made also to make \modest usable as a + general-purpose e-mail client on normal desktop computer. +\end{itemize} + + + + + +\chapter{Design} +In this chapter, we'll discuss the design of various parts of \modest. We'll +not go into the details of various APIs. Please consult the documentation +generated from the source code ({\tt gtk-doc}) for that. + +\section {Configuration} +Configuration is the part of \modest that deals with storing all +settings. While the design allows for alternative implementations, currently +only {\tt gconf} is supported as a backend. + +All dealing with configuration is done with the {\tt ModestConf} GObject. This +object is declared in {\tt modest-conf.h}, and the GConf-based implementation in +{\tt modest-conf-gconf.c}. As said, there could be different implementations +{\tt modest-conf-myconf.c}, but we use the GConf-backed system. However, +nothing GConf-specific is visible in the ModestConf API. + +\section{Account Management} +Account Management is the part of \modest that deals with the setting related +to sending and receiving of e-mail. We will follow the libcamel-convention of +using the term {\em store} for a e-mail storage/retrieval server, and a {\em + transport} for a server that transports mail to its destination. + +In practice, the following types are available: +\begin{itemize} + \item {\bf stores}: \pop and \imap; + \item {\bf transports}: {\tt sendmail} and \smtp. +\end{itemize} + +\subsection{Definitions} +\begin{itemize} + \item A {\bf transport} describes the connection information (servername, + username, password etc.) for a transport server; + \item A {\bf store} describes the connection information for a store server; + \item An {\bf account} is a named entity consisting of a {\bf store} and a + {\bf transport}.\footnote{For our mobile use-cases, the {\em transport} + cannot be a static entity, but may depend on the network + connection. That is however not part of Account Management, so not + discussed here} +\end{itemize} + +\chapter{Finding the Transport} +One of the interesting topics in designing a mobile e-mail client is to deal +with transports (in particular, \smtp). The reason for that is that the +majority of \smtp-servers only allow e-mail from the same network. That means +that for example {\tt smtp.some-isp.com} will only accept mail from ({\tt MAIL + FROM:}) {\tt user@some-isp.com}, and refuse mail from {\tt + user@some-other-isp.com}, unless the recipient {\tt RCPT TO:} is on the same +network. + +To summarize: + +\footnote{Some smtp-servers {\bf will} accept mail + from} + + + +\chapter*{Coding guidelines} +When hacking on \modest, please honour these time-tested coding guidelines. +First, please follow the {\em Linux CodingStyle guidelines}:\\ + {\tt /usr/src/linux/Documentation/CodingStyle}\\ +Then, read the {\em OSSO Coding Style Guidelines}:\\ + {\tt http://foo} +Here are only some additional notes. + +Your editor may help you with this, for example for {\tt emacs}: +\begin{verbatim} + (c-set-style "K&R") + (setq tab-width 8) + (setq indent-tabs-mode t) + (setq c-basic-offset 8) +\end{verbatim} + +Or the equivalent in your favourite editor. + +Lines should not exceed 100 characters. + +Global functions (the ones in {\tt .h}-files) should be commented using +doxygen-style comments. + +Furthermore, please follow 'conventional wisdom' for programming with +GLib/GTK+/GObject. Some things to remember: +\begin{itemize} +\item {\tt g\_new}, {\tt g\_malloc} and friends {\bf never} return {\tt NULL}. They terminate + the application if it happens (normally). No need to check for {\tt NULL} returns. +\item {\tt g\_return\_if\_fail} and friends may be 'turned off', ie. they are + to be used for error checking, but {\bf not} for your programming logic +\end{itemize} + +To test for the validity of function parameters, +% g_return_if_fail / g_return_val_if_fail + +ie. +\begin{verbatim} +double +one_divided_by_x (double x) +{ + g_return_val_if_fail ((x != 0), -1); + return 1/x; +} +\end{verbatim} +This will give us a warning (and a wrong answer) in case we do +% one_divided_by_x (0); + +This is good for testing, but it's important to keep in mind that in +production code the check may be turned off. The caller should make +sure that the parameter is correct (ie. != 0 in this case). + +Now, if a similar check is actually part of the logic of a function, +then {\tt g\_return\_if\_fail} should not be used, but instead, e.g.: +\begin{verbatim} +int +stack_item_num (Stack *stack) +{ + if (!stack) + return 0; + + /* calculate item count */ +} +\end{verbatim} +\end{document} diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am new file mode 100644 index 0000000..31703d1 --- /dev/null +++ b/docs/reference/Makefile.am @@ -0,0 +1,75 @@ +## Process this file with automake to produce Makefile.in + +# This is a blank Makefile.am for using gtk-doc. +# Copy this to your project's API docs directory and modify the variables to +# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples +# of using the various options. + +# The name of the module, e.g. 'glib'. +DOC_MODULE=modest + +# The top-level SGML file. You can change this if you want to. +DOC_MAIN_SGML_FILE=modest-docs.sgml + +# The directory containing the source code. Relative to $(srcdir). +# gtk-doc will search all .c & .h files beneath here for inline comments +# documenting the functions and macros. +# e.g. DOC_SOURCE_DIR=../../../gtk +DOC_SOURCE_DIR=$(top_srcdir)/src + +# Extra options to pass to gtkdoc-scangobj. Not normally needed. +SCANGOBJ_OPTIONS= + +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS= + +# Extra options to supply to gtkdoc-mkdb. +# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml +MKDB_OPTIONS=--sgml-mode --output-format=xml + +# Extra options to supply to gtkdoc-mktmpl +# e.g. MKTMPL_OPTIONS=--only-section-tmpl +MKTMPL_OPTIONS= + +# Extra options to supply to gtkdoc-fixref. Not normally needed. +# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html +FIXXREF_OPTIONS= + +# Used for dependencies. The docs will be rebuilt if any of these change. +# e.g. HFILE_GLOB=$(top_srcdir)/*.h +# e.g. CFILE_GLOB=$(top_srcdir)/*.c +HFILE_GLOB=$(top_srcdir)/src/*.h +CFILE_GLOB=$(top_srcdir)/src/*.c + +# Header files to ignore when scanning. +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h +IGNORE_HFILES= + +# Images to copy into HTML directory. +# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png +HTML_IMAGES= + +# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). +# e.g. content_files=running.sgml building.sgml changes-2.0.sgml +content_files=#xml/tree_index.sgml + +# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded +# These files must be listed here *and* in content_files +# e.g. expand_content_files=running.sgml +expand_content_files= + +# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. +# Only needed if you are using gtkdoc-scangobj to dynamically query widget +# signals and properties. +# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) +INCLUDES=-I$(top_srcdir)/src $(MODEST_GSTUFF_CFLAGS) +GTKDOC_LIBS=$(MODEST_GSTUFF_LIBS) + +# This includes the standard gtk-doc make rules, copied by gtkdocize. +include $(top_srcdir)/gtk-doc.make + +# Other files to distribute +# e.g. EXTRA_DIST += version.xml.in +EXTRA_DIST += diff --git a/docs/reference/modest-docs.sgml b/docs/reference/modest-docs.sgml new file mode 100644 index 0000000..167deba --- /dev/null +++ b/docs/reference/modest-docs.sgml @@ -0,0 +1,43 @@ + + + + + +]> + + + + modest reference manual + + + + Introduction + modest is a lightweight e-mail program, built on top of + tinymail and libcamel + + + + Object Index + &index-Object-Index; + &index-Object-Tree; + + + + API Reference + + + modest general + &modest-ModestConf; + + + + + + Index + + + + diff --git a/docs/reference/modest-overrides.txt b/docs/reference/modest-overrides.txt new file mode 100644 index 0000000..e69de29 diff --git a/docs/reference/modest-sections.txt b/docs/reference/modest-sections.txt new file mode 100644 index 0000000..5857cc8 --- /dev/null +++ b/docs/reference/modest-sections.txt @@ -0,0 +1,180 @@ +
+modest-conf +ModestConf +ModestConf +modest_conf_new +modest_conf_get_string +modest_conf_get_int +modest_conf_get_bool +modest_conf_set_string +modest_conf_set_int +modest_conf_set_bool +modest_conf_list_subkeys +modest_conf_remove_key +modest_conf_key_exists + +MODEST_CONF +MODEST_IS_CONF +MODEST_TYPE_CONF +modest_conf_get_type +MODEST_CONF_CLASS +MODEST_IS_CONF_CLASS +MODEST_CONF_GET_CLASS +
+ +
+modest-account-mgr +ModestAccountMgr +ModestAccountMgr +modest_account_mgr_new +modest_account_mgr_add_account +modest_account_mgr_remove_account +modest_account_mgr_account_names +modest_account_mgr_account_exists +modest_account_mgr_get_account_string +modest_account_mgr_get_account_int +modest_account_mgr_get_account_bool +modest_account_mgr_set_account_string +modest_account_mgr_set_account_int +modest_account_mgr_set_account_bool + +MODEST_ACCOUNT_MGR +MODEST_IS_ACCOUNT_MGR +MODEST_TYPE_ACCOUNT_MGR +modest_account_mgr_get_type +MODEST_ACCOUNT_MGR_CLASS +MODEST_IS_ACCOUNT_MGR_CLASS +MODEST_ACCOUNT_MGR_GET_CLASS +
+ +
+modest-window-mgr +ModestWindowType +ModestOpenWindow +ModestWindowMgr +ModestWindowMgr +modest_window_mgr_new +modest_window_mgr_register +modest_window_mgr_unregister +modest_window_mgr_find_by_type +modest_window_mgr_find_by_id + +MODEST_WINDOW_MGR +MODEST_IS_WINDOW_MGR +MODEST_TYPE_WINDOW_MGR +modest_window_mgr_get_type +MODEST_WINDOW_MGR_CLASS +MODEST_IS_WINDOW_MGR_CLASS +MODEST_WINDOW_MGR_GET_CLASS +
+ +
+modest-ui +ModestUI +ModestUI +modest_ui_new +modest_ui_show_main_window +modest_ui_show_edit_window + +MODEST_UI +MODEST_IS_UI +MODEST_TYPE_UI +modest_ui_get_type +MODEST_UI_CLASS +MODEST_IS_UI_CLASS +MODEST_UI_GET_CLASS +
+ +
+modest-tny-account-store +ModestTnyAccountStore +ModestTnyAccountStore +modest_tny_account_store_new + +MODEST_TNY_ACCOUNT_STORE +MODEST_IS_TNY_ACCOUNT_STORE +MODEST_TYPE_TNY_ACCOUNT_STORE +modest_tny_account_store_get_type +MODEST_TNY_ACCOUNT_STORE_CLASS +MODEST_IS_TNY_ACCOUNT_STORE_CLASS +MODEST_TNY_ACCOUNT_STORE_GET_CLASS +
+ +
+modest-tny-folder-tree-view +ModestTnyFolderTreeView +ModestTnyFolderTreeView +modest_tny_folder_tree_view_new + +MODEST_TNY_FOLDER_TREE_VIEW +MODEST_IS_TNY_FOLDER_TREE_VIEW +MODEST_TYPE_TNY_FOLDER_TREE_VIEW +modest_tny_folder_tree_view_get_type +MODEST_TNY_FOLDER_TREE_VIEW_CLASS +MODEST_IS_TNY_FOLDER_TREE_VIEW_CLASS +MODEST_TNY_FOLDER_TREE_VIEW_GET_CLASS +
+ +
+modest-main-window +ModestMainWindow +ModestMainWindow +modest_main_window_new + +MODEST_MAIN_WINDOW +MODEST_IS_MAIN_WINDOW +MODEST_TYPE_MAIN_WINDOW +modest_main_window_get_type +MODEST_MAIN_WINDOW_CLASS +MODEST_IS_MAIN_WINDOW_CLASS +MODEST_MAIN_WINDOW_GET_CLASS +
+ +
+modest-edit-window +ModestEditWindow +ModestEditWindow +modest_edit_window_new + +MODEST_EDIT_WINDOW +MODEST_IS_EDIT_WINDOW +MODEST_TYPE_EDIT_WINDOW +modest_edit_window_get_type +MODEST_EDIT_WINDOW_CLASS +MODEST_IS_EDIT_WINDOW_CLASS +MODEST_EDIT_WINDOW_GET_CLASS +
+ +
+modest-conf-keys +MODEST_CONF_NAMESPACE +MODEST_CONF_USE_EXT_EDITOR +MODEST_CONF_EXT_EDITOR +MODEST_CONF_MAIN_WINDOW_HEIGHT +MODEST_CONF_MAIN_WINDOW_HEIGHT_DEFAULT +MODEST_CONF_MAIN_WINDOW_WIDTH +MODEST_CONF_MAIN_WINDOW_WIDTH_DEFAULT +MODEST_CONF_EDIT_WINDOW_HEIGHT +MODEST_CONF_EDIT_WINDOW_HEIGHT_DEFAULT +MODEST_CONF_EDIT_WINDOW_WIDTH +MODEST_CONF_EDIT_WINDOW_WIDTH_DEFAULT +
+ +
+modest-account-keys +MODEST_CONF_DEFAULT_ACCOUNT +MODEST_ACCOUNT_NAMESPACE +MODEST_ACCOUNT_DISPLAY_NAME +MODEST_ACCOUNT_DEFAULT +MODEST_ACCOUNT_TYPE +MODEST_ACCOUNT_TYPE_STORE +MODEST_ACCOUNT_TYPE_TRANSPORT +MODEST_ACCOUNT_PROTO +MODEST_ACCOUNT_PROTO_POP +MODEST_ACCOUNT_PROTO_IMAP +MODEST_ACCOUNT_PASSWORD +MODEST_ACCOUNT_SERVER +MODEST_ACCOUNT_USER +MODEST_ACCOUNT_LEAVE_ON_SERVER +
+ -- 1.7.9.5