* Added documentation to ModestFormatter

[modest] / docs / reference / modest-docs.sgml

<?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" [

<!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>
    <title>Introduction</title>
    <para><application>modest</application> is a mail user agent
      (<abbrev>MUA</abbrev>) targetting small devices, in particular Nokia's
      <productname>Nokia 770 Internet Tablet</productname>. This document
      describes the design and implementation of this software.
    </para>
    
    <para><application>modest</application> lives at the top of a extensive
      stack of software. It is built on top
      of <application>tinymail</application>, 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) <productname>Nokia's 770 internet tablet</productname>. 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 <application>tinymail</application>, 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.
    </para>
    
    <para>
      <application>modest</application>, in turn, also tries to be efficient,
      fast and scalable. That means that the <abbrev>MUA</abbrev> should
      support multiple user-interfaces, perhaps making it even possible to
      switch between them during runtime.
    </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></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>

  </preface>

  <part>
    <title>Architecture</title>
    <partintro>
      <para><application>modest</application> tries to be quite flexible in its
        design. However, it's always important not to make things too
        generic. Both for reasons of time limitations and keeping the software
        understandable and 'modest', it's important to limit the scope.
      </para>
      
      <para>
        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>
          <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>
          <listitem>However, effort is made also to
            make <application>modest</application> usable as a general-purpose
            e-mail client on normal desktop computer.</listitem>
        </itemizedlist>
      </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 consult the documentation generated
        from the source code (<systemitem>gtk-doc</systemitem>) for that.
      </para>
    </partintro>
    
    <chapter>
      <title>Configuration</title>
      <para>Configuration is the part of <application>modest</application>
        that deals with storing all settings. While the design allows for
        alternative implementations, currently
        only <systemitem>GConf</systemitem> is supported as a backend.
      </para>
      
      <para>
        All dealing with configuration is done with
        the <classname>ModestConf</classname>-class. It is declared
        in <filename> modest-conf.h</filename>, and
        the <systemitem>GConf</systemitem>-based implementation in 
        <filename>modest-conf.c</filename>. As said, there could be
        different implementations --
        nothing <systemitem>GConf</systemitem>-specific is visible in the
        <classname>ModestConf</classname>-<abbrev>API</abbrev>.
      </para>
    </chapter>
    
    <chapter>
      <title>Account Management</title>
      <para>
        Account Management is the part of <application>modest</application>
        that deals with the setting related to sending and receiving of
        e-mail. We will follow the libcamel-convention of using the
        term <emphasis>store</emphasis> for an e-mail storage/retrieval
        server, and a <emphasis>transport</emphasis> for a server that
        transports mail to its destination.
      </para>
      
      <para>
        In practice, the following types are available:
        <itemizedlist>
          <listitem><emphasis>stores</emphasis>: <abbrev>POP</abbrev>
            and <abbrev>IMAP</abbrev>; </listitem>
          <listitem> <emphasis>transports</emphasis>: <systemitem>sendmail</systemitem>
            and <abbrev>SMTP</abbrev>.</listitem>
        </itemizedlist>
      </para>
      
      <sect1>
        <title>Definitions</title>
        <itemizedlist>
          <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>
          <listitem>A <emphasis>server account</emphasis> is account
            describing the connection with a specific server. Server accounts
            come in two type:
            <itemizedlist>
              <listitem>A <emphasis>transport</emphasis> describes the connection information
                (servername, username, password etc.) for a transport
                server;</listitem>
              <listitem>A <emphasis>store</emphasis> describes the connection information for
                a store server;</listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </sect1>
      
      <sect1>
        <title>Code</title>
        <para>The functions to deal with account and server accounts are
          located in <classname>ModestAccountMgr</classname>, ie. in 
          <filename>modest-account-mgr.[ch]</filename>. There function to add
          specific values for both, to list the available ones, etc. Please
          refer to the source code documentation for details.
        </para>
      </sect1>
      
      <sect1>
        <title>Location in configuration database</title>
        <para>
          <emphasis>Accounts</emphasis> can be found
          in <systemitem>/apps/modest/accounts</systemitem>,
          while <emphasis>server accounts</emphasis> can be found
          in <systemitem>/app/modest/server_accounts</systemitem>.
        </para>
        
        <para>
          The following image show an
          account <systemitem>accountstest</systemitem> with server accounts
          <systemitem>mystore</systemitem>
          and <systemitem>mytransport</systemitem>.
          <imagedata fileref="modest-account-mgr.png"/>
        </para>

        <para>
          For each of the stores, there are number of parameters specified:
          <itemizedlist>
            <listitem><emphasis>hostname</emphasis> - the place where the server resides;</listitem>
            <listitem><emphasis>username</emphasis> - the username;</listitem>
            <listitem><emphasis>password</emphasis> - the password;</listitem>
            <listitem><emphasis>proto</emphasis> - the protocal for communication with this server - for
              now these are the following valid values (literal strings):
              <itemizedlist>
                <listitem><emphasis>sendmail</emphasis>;</listitem>
                <listitem><emphasis>smtp</emphasis>;</listitem>
                <listitem><emphasis>pop</emphasis></listitem>
                <listitem><emphasis>imap</emphasis>.</listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </para>
        
        <para>In <filename>modest-proto.[ch]</filename> there are various
          functions to check whether something is a valid protocol, and
          whether it is a transport of a store.
        </para>
        
        <para>Note that server accounts and accounts are relatively independent. While
          accounts refer to two server accounts, these server accounts can be
          used by other accounts as well.
        </para>
        
        <para>The reason two keep accounts and server accounts separately, is a bit of
          flexibility. In mobile use-cases, quite often it's desirable to use a
          network-specific smtp-server. The chosen structure makes it easy to iterate
          over all smtp-servers and find the right one.
        </para>
      </sect1>
      
      <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 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>
  </part>
  
  <chapter>
    <title>Coding guidelines</title>
    <para>
      When hacking on modest, please honour these time-tested coding guidelines.
      First, please follow the <emphasis>Linux CodingStyle guidelines</emphasis>
      (<filename>/usr/src/linux/Documentation/CodingStyle</filename>).
    </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&amp;R")
        (setq tab-width 8)
        (setq indent-tabs-mode t)
        (setq c-basic-offset 8)
      </programlisting>
      
      Or the equivalent in your favourite editor.
    </para>
    
    <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 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; but
      do use it when building / testing things yourself.
    </para>

    <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>
    </para>
  </chapter>
  
  <chapter>
    <title>Object Index</title>
  </chapter>
  
  <chapter>
    <title>API Reference</title>
      <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>