<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
- <copyright>
- <year>2006</year>
- <holder>Nokia Corporation</holder>
- </copyright>
+<!ENTITY ModestAccountKeys SYSTEM "xml/modest-account-keys.xml">
+<!ENTITY ModestAccountMgr SYSTEM "xml/modest-account-mgr.xml">
+<!ENTITY ModestConfKeys SYSTEM "xml/modest-conf-keys.xml">
+<!ENTITY ModestConf SYSTEM "xml/modest-conf.xml">
+<!ENTITY ModestError SYSTEM "xml/modest-error.xml">
+<!ENTITY ModestFormatter SYSTEM "xml/modest-formatter.xml">
+<!ENTITY ModestIconFactory SYSTEM "xml/modest-icon-factory.xml">
+<!ENTITY ModestIconNames SYSTEM "xml/modest-icon-names.xml">
+<!ENTITY ModestMailOperation SYSTEM "xml/modest-mail-operation.xml">
+<!ENTITY ModestMailOperationQueue SYSTEM "xml/modest-mail-operation-queue.xml">
+<!ENTITY ModestMarshal SYSTEM "xml/modest-marshal.xml">
+<!ENTITY ModestPair SYSTEM "xml/modest-pair.xml">
+<!ENTITY ModestPresets SYSTEM "xml/modest-presets.xml">
+<!ENTITY ModestProtocolMgr SYSTEM "xml/modest-protocol-mgr.xml">
+<!ENTITY ModestProto SYSTEM "xml/modest-proto.xml">
+<!ENTITY ModestTextUtils SYSTEM "xml/modest-text-utils.xml">
+<!ENTITY ModestTnyAccountStore SYSTEM "xml/modest-tny-account-store.xml">
+<!ENTITY ModestTnyAttachment SYSTEM "xml/modest-tny-attachment.xml">
+<!ENTITY ModestTnyMsgActions SYSTEM "xml/modest-tny-msg-actions.xml">
+<!ENTITY ModestTnyPlatformFactory SYSTEM "xml/modest-tny-platform-factory.xml">
+<!ENTITY ModestTnyStoreActions SYSTEM "xml/modest-tny-store-actions.xml">
+<!ENTITY ModestTnyStreamGtkhtml SYSTEM "xml/modest-tny-stream-gtkhtml.xml">
+<!ENTITY ModestWidgetFactory SYSTEM "xml/modest-widget-factory.xml">
+<!ENTITY ModestWidgetMemory SYSTEM "xml/modest-widget-memory.xml">
+<!ENTITY widgets-ModestAccountView SYSTEM "xml/modest-account-view.xml">
+<!ENTITY widgets-ModestComboBox SYSTEM "xml/modest-combo-box.xml">
+<!ENTITY widgets-ModestFolderView SYSTEM "xml/modest-folder-view.xml">
+<!ENTITY widgets-ModestHeaderView SYSTEM "xml/modest-header-view.xml">
+<!ENTITY widgets-ModestMsgView SYSTEM "xml/modest-msg-view.xml">
+<!ENTITY widgets-modestToolbar SYSTEM "xml/modest-toolbar.xml">
+
+<!ENTITY gtk-ModestAccountViewWindow SYSTEM "xml/modest-account-view-window.xml">
+<!ENTITY gtk-ModestAccountAssistant SYSTEM "xml/modest-account-assistant.xml">
+<!ENTITY gtk-ModestEditMsgWindow SYSTEM "xml/modest-edit-msg-window.xml">
+<!ENTITY gtk-ModestMainWindow SYSTEM "xml/modest-main-window.xml">
+<!ENTITY gtk-ModestStoreWidget SYSTEM "xml/modest-store-widget.xml">
+<!ENTITY gtk-modestTransportWidget SYSTEM "xml/modest-transport-widget.xml">
+<!ENTITY gtk-modestUi SYSTEM "xml/modest-ui.xml">
+
+<!ENTITY index-Object-Tree SYSTEM "xml/tree_index.sgml">
+
+]>
+
+<!--<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">-->
+<book id="index">
<bookinfo>
<title>modest technical documentation</title>
+ <copyright>
+ <year>2006</year>
+ <holder>Nokia Corporation</holder>
+ </copyright>
</bookinfo>
<preface>
</para>
<para>To summarize the goals for <application>modest</application>:
- <itemizedlist>
- <listitem>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);</listitem>
- <listitem>target Linux/Unix-like environments with GLib/GTK+-based
- support;</listitem>
- <listitem>support multiple user-interface (UIs) with as much code
- sharing as possible between the different UIs.</listitem>
+ <itemizedlist>
+ <listitem>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);</listitem>
+ <listitem>target Linux/Unix-like environments with GLib/GTK+-based
+ support;</listitem>
+ <listitem>support multiple user-interface (UIs) with as much code
+ sharing as possible between the different UIs.</listitem>
</itemizedlist></para>
<para>Like <application>tinymail</application>
- and <application>libcamel</application>, <application>modest</application>
- is programmed in C, using the <package>GObject</package>-system for
- object-oriented (OO) features. For now, it specifically targets \gtk based
- UIs (and derivatives like 'Hildon').</para>
+ and <application>libcamel</application>, <application>modest</application>
+ is programmed in C, using the <package>GObject</package>-system for
+ object-oriented (OO) features. For now, it specifically targets \gtk based
+ UIs (and derivatives like 'Hildon').</para>
</preface>
For <application>modest</application>, the following:
<itemizedlist>
<listitem><application>modest</application> is a e-mail program
- using the <package>tinymail</package> and <package>camel</package>
- libraries;</listitem>
+ using the <package>tinymail</package> and <package>camel</package>
+ libraries;</listitem>
<listitem><application>modest</application> targets gtk and
gconf-based user-interfaces, including the Hildon
environment;</listitem>
<listitem><application>modest</application> main use-case is in
small, mobile device such as the <productname>Nokia 770 Internet
- Tablet</productname>;</listitem>
+ Tablet</productname>;</listitem>
<listitem>However, effort is made also to
make <application>modest</application> usable as a general-purpose
e-mail client on normal desktop computer.</listitem>
</para>
</partintro>
</part>
-
+
<part>
<title>Design</title>
<partintro>
<para>In this part, we'll discuss the design of various parts of
<application>modest</application>. We'll not go into the details of
- various APIs in this chapter. Please consul the documentation generated
- from the source code (<systemitem>gtk-doc</systemitem>) for that.</para>
+ various APIs in this chapter. Please consult the documentation generated
+ from the source code (<systemitem>gtk-doc</systemitem>) for that.
+ </para>
</partintro>
<chapter>
<listitem>An <emphasis>account</emphasis> is a named entity
consisting of a <emphasis>store</emphasis> and
a <emphasis>transport</emphasis>. Note: For our mobile use-cases,
- the <emphasis>transport</emphasis> cannot be a static entity, but
- may depend on the network connection. That is however not part of
- Account Management, so not discussed here</listitem>
+ the <emphasis>transport</emphasis> cannot be a static entity, but
+ may depend on the network connection. That is however not part of
+ Account Management, so not discussed here</listitem>
<listitem>A <emphasis>server account</emphasis> is account
describing the connection with a specific server. Server accounts
come in two type:
</listitem>
</itemizedlist>
</sect1>
-
+
<sect1>
<title>Code</title>
<para>The functions to deal with account and server accounts are
over all smtp-servers and find the right one.
</para>
</sect1>
- </chapter>
-
- <sec1>
- <title>Account Management and Tinymail</title>
- <para>
- Tinymail needs the information about all configured accounts - and the
- mechanism that it uses for that
- is <interface>TnyAccountStoreIface</interface>. We don't want to use
- the tinymail-provided <classname>TnyAccountStore</classname>, but
- provide our own implementation
- instead: <classname>ModestTnyAccountStore</classname>. This class
- implements the <interface>TnyAccountStoreIface</interface>-interace in
- terms of the aforementioned <classname>ModestAccountMgr</classname>.
- </para>
+ <sect1>
+ <title>Account Management and Tinymail</title>
+ <para>
+ Tinymail needs the information about all configured accounts - and the
+ mechanism that it uses for that
+ is <interface>TnyAccountStoreIface</interface>. We don't want to use
+ the tinymail-provided <classname>TnyAccountStore</classname>, but
+ provide our own implementation
+ instead: <classname>ModestTnyAccountStore</classname>. This class
+ implements the <interface>TnyAccountStoreIface</interface>-interace in
+ terms of the aforementioned <classname>ModestAccountMgr</classname>.
+ </para>
+
+ <para>
+ One unexpected function
+ that <classname>ModestTnyAccountStore</classname> needs to implement
+ is <symbol>tny account_store get_session</symbol> (to get the
+ Camel-session). This function must be provided as a public function,
+ with that exact name.
+ </para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Finding the right transport</title>
<para>
- One unexpected function
- that <classname>ModestTnyAccountStore</classname> needs to implement
- is <symbol>tny account_store get_session</symbol> (to get the
- Camel-session). This function must be provided as a public function,
- with that exact name.
+ One of the interesting topics in designing a mobile e-mail client is
+ to deal with transports (in
+ particular, <acronym>SMTP</acronym>). The reason for that is that
+ the majority of <acronym>SMTP</acronym>-servers only allow e-mail
+ from the same network. That means that for example <systemitem>
+ smtp.some-isp.com</systemitem> will only accept mail from
+ (<command>MAIL FROM:</command>) <systemitem>
+ user@some-isp.com</systemitem>, and refuse mail
+ from <systemitem>user@some-other-isp.com</systemitem>, unless the
+ recipient (<command>RCPT TO:</command>) is on the same network.
</para>
- </sec1>
- </chapter>
-
-
-
-
- <chapter>
- <title>Finding the right transport</title>
- <para>
- One of the interesting topics in designing a mobile e-mail client is
- to deal with transports (in
- particular, <acronym>SMTP</acronym>). The reason for that is that
- the majority of <acronym>SMTP</acronym>-servers only allow e-mail
- from the same network. That means that for example <systemitem>
- smtp.some-isp.com</systemitem> will only accept mail from
- (<command>MAIL FROM:</command>) <systemitem>
- user@some-isp.com</systemitem>, and refuse mail
- from <systemitem>user@some-other-isp.com</systemitem>, unless the
- recipient (<command>RCPT TO:</command>) is on the same network.
- </para>
- </chapter>
+ </chapter>
</part>
-
-
<chapter>
<title>Coding guidelines</title>
<para>
<para>
Here are only some additional notes.
</para>
-
+
<para>
Your editor may help you with this, for example for <application>emacs</application>:
<programlisting>
- (c-set-style "K&R")
- (setq tab-width 8)
- (setq indent-tabs-mode t)
- (setq c-basic-offset 8)
+ (c-set-style "K&R")
+ (setq tab-width 8)
+ (setq indent-tabs-mode t)
+ (setq c-basic-offset 8)
</programlisting>
Or the equivalent in your favourite editor.
<para>
Lines must not exceed 100 characters.
</para>
-
+
<para>
Functions should do one thing, and do it well. In general, functions
should not be much longer than 20-30 lines (except for, say, handling
many different cases in a 'switch'-statement). Files should not get to
- big either; if there's more than, say, 800 lines, it probably shows the
- codes needs to be refactored a bit.
+ big either; if there are more than, say, 800 lines, it's a sign that
+ some refactoring should take place.
</para>
-
+
<para>
Code should compile cleanly
with <command>gcc</command>'s <symbol>-Wall</symbol> compile option. Of
course this might not always be possible due to problems in dependent
libraries and/or compiler version. Therefore, do not
- include <symbol>-Werror</symbol> in the standard compile options.
+ include <symbol>-Werror</symbol> in the standard compile options; but
+ do use it when building / testing things yourself.
</para>
- <para>Global functions (the ones in <filename>.h</filename>-files) should
- be commented using
- <systemitem>gtk-doc</systemitem>.
+ <para>
+ Code should also run cleanly. GTK+/GLib warnings and errors must be
+ taken very seriously. If you run <application>modest</application> with
+ the <symbol>-d</symbol>-flag, it will <symbol>abort</symbol> whenever
+ there is such a warning. This can be useful when running inside the
+ debugger.
</para>
-
-
-
+ <para>Global functions (the ones in <filename>.h</filename>-files) must
+ be commented using <systemitem>gtk-doc</systemitem>. This way, we
+ generate nice documentation. After installing
+ (under <filename>/usr/local</filename>), we can browse the results
+ with <application>DevHelp</application>. Just
+ add <systemitem>/usr/local/share/gtk-doc/html</systemitem> to the
+ <systemitem>DEVHELP_SEARCH_PATH</systemitem>-environment variable.
+ </para>
<para>
- Furthermore, please follow 'conventional wisdom' for programming with
- GLib/GTK+/GObject. Some things to remember:
- <itemizedlist>
- <listitem> <function>g_new</function>, <function>g_malloc</function> and
- friends <emphasis>never</emphasis> return <function>NULL</function>. They terminate
- the application if it happens (normally). No need to check
- for <function>NULL</function> returns;</listitem>
- <listitem> <function>g_return_if_fail</function> and friends may be
- 'turned off', ie. they are to be used for error checking,
- but <emphasis>not</emphasis> for your programming logic
- </listitem>
- </itemizedlist>
+ Furthermore, please follow 'conventional wisdom' for programming with
+ GLib/GTK+/GObject. Some things to remember:
+ <itemizedlist>
+ <listitem> <function>g_new</function>, <function>g_malloc</function> and
+ friends <emphasis>never</emphasis> return <function>NULL</function>. They terminate
+ the application if it happens (normally). No need to check
+ for <function>NULL</function> returns;</listitem>
+ <listitem> <function>g_return_if_fail</function> and friends may be
+ 'turned off', ie. they are to be used for error checking,
+ but <emphasis>not</emphasis> for your programming logic
+ </listitem>
+ </itemizedlist>
</para>
</chapter>
<chapter>
<title>Object Index</title>
</chapter>
-
+
<chapter>
<title>API Reference</title>
- <xi:include href="xml/modest-ui.xml"/>
- <xi:include href="xml/modest-tny-header-tree-view.xml"/>
- <xi:include href="xml/modest-tny-msg-view.xml"/>
- <xi:include href="xml/modest-account-mgr.xml"/>
- <xi:include href="xml/modest-conf.xml"/>
- <xi:include href="xml/modest-window-mgr.xml"/>
- <xi:include href="xml/modest-tny-folder-tree-view.xml"/>
- <xi:include href="xml/modest-tny-account-store.xml"/>
- <xi:include href="xml/modest-tny-transport-actions.xml"/>
- <xi:include href="xml/modest-main-window.xml"/>
- <xi:include href="xml/modest-editor-window.xml"/>
- <xi:include href="xml/modest-viewer-window.xml"/>
- <xi:include href="xml/modest-proto.xml"/>
- <xi:include href="xml/modest-account-keys.xml"/>
- <xi:include href="xml/modest-conf-keys.xml"/>
+ <chapter id="src">
+ <title>Modest</title>
+ &ModestAccountKeys;
+ &ModestAccountMgr;
+ &ModestConfKeys;
+ &ModestConf;
+ &ModestError;
+ &ModestFormatter;
+ &ModestIconFactory;
+ &ModestIconNames;
+ &ModestMailOperation;
+ &ModestMailOperationQueue;
+ &ModestMarshal;
+ &ModestPair;
+ &ModestPresets;
+ &ModestProtocolMgr;
+ &ModestProto;
+ &ModestTextUtils;
+ &ModestTnyAccountStore;
+ &ModestTnyAttachment;
+ &ModestTnyMsgActions;
+ &ModestTnyPlatformFactory;
+ &ModestTnyStoreActions;
+ &ModestTnyStreamGtkhtml;
+ &ModestWidgetFactory;
+ &ModestWidgetMemory;
+ </chapter>
+ <chapter id="gtk">
+ <title>Gtk</title>
+ </chapter>
+ <chapter id="widgets">
+ <title>Widgets</title>
+ </chapter>
</chapter>
</book>
projects / modest / blobdiff