<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY app "<application>Mail Notification</application>">
  <!ENTITY appversion "5.4">
  <!ENTITY manrevision "2.25">
  <!ENTITY date "Thursday, May 22, 2008">

  <!ENTITY project "The Mail Notification Project">

  <!ENTITY documentation-license SYSTEM "documentation-license.xml">
  <!ENTITY software-license SYSTEM "software-license.xml">

  <!ENTITY aka "<acronym>aka</acronym>">
  <!ENTITY uri "<link linkend=&#34;uri&#34;>URI</link>">
  <!ENTITY maildir "<link linkend=&#34;maildir&#34;>Maildir</link>">
  <!ENTITY mbox "<link linkend=&#34;mbox&#34;>mbox</link>">
  <!ENTITY mh "<link linkend=&#34;mh&#34;>MH</link>">
  <!ENTITY pop3 "<link linkend=&#34;pop3&#34;>POP3</link>">
  <!ENTITY imap "<link linkend=&#34;imap&#34;>IMAP</link>">
  <!ENTITY sasl "<link linkend=&#34;sasl&#34;>SASL</link>">
  <!ENTITY ssl "<link linkend=&#34;pop3&#34;>SSL</link>">
  <!ENTITY tls "<link linkend=&#34;pop3&#34;>TLS</link>">
  <!ENTITY mozilla "<link linkend=&#34;mozilla&#34;>Mozilla</link>">
  <!ENTITY sylpheed "<link linkend=&#34;sylpheed&#34;>Sylpheed</link>">
  <!ENTITY gnomevfs "<link linkend=&#34;gnomevfs&#34;>GnomeVFS</link>">
]>

<!-- $Id: mail-notification.xml,v 1.187 2008-05-22 15:44:32 jylefort Exp $ -->
<!-- Mail Notification Manual -->

<!-- Copyright (C) 2003-2008 Jean-Yves Lefort -->
<!-- All rights reserved. -->

<!-- See documentation-license.xml for licensing information. -->

<!-- This document does its best to adhere to the -->
<!-- GNOME Documentation Style Guide V1.3 -->
<!-- (http://developer.gnome.org/documents/style-guide) -->

<article id="index" lang="en">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
  <articleinfo>
    <title>&app; Manual V&manrevision;</title>

    <copyright>
      <year>2004</year>
      <year>2005</year>
      <year>2006</year>
      <year>2007</year>
      <year>2008</year>
      <holder>Jean-Yves Lefort</holder>
    </copyright>
<!-- translators: uncomment this:

  <copyright>
   <year>2002</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

   -->
    <publisher>
      <publishername>&project;</publishername>
    </publisher>

    &documentation-license;

    <authorgroup>
      <author>
	<firstname>Jean-Yves</firstname>
	<surname>Lefort</surname>
	<affiliation>
	  <orgname>&project;</orgname>
	  <address><email>jylefort@brutele.be</email></address>
	</affiliation>
      </author>
      
<!-- This is appropriate place for other contributors: translators,
     maintainers,  etc. Commented out by default.
     
      <othercredit role="translator">
		<firstname>Latin</firstname> 
		<surname>Translator 1</surname> 
		<affiliation> 
	  		<orgname>Latin Translation Team</orgname> 
	  		<address> <email>translator@gnome.org</email> </address> 
		</affiliation>
		<contrib>Latin translation</contrib>
      </othercredit>
-->
    </authorgroup>

<!-- The revision numbering system for GNOME manuals is as follows: -->
<!-- * the revision number consists of two components -->
<!-- * the first component of the revision number reflects the release version of the GNOME desktop. -->
<!-- * the second component of the revision number is a decimal unit that is incremented with each revision of the manual. -->
<!-- For example, if the GNOME desktop release is V2.x, the first version of the manual that -->
<!-- is written in that desktop timeframe is V2.0, the second version of the manual is V2.1, etc. -->
<!-- When the desktop release version changes to V3.x, the revision number of the manual changes -->
<!-- to V3.0, and so on. -->  
    <revhistory>
      <revision>
	<revnumber>Mail Notification Manual V&manrevision;</revnumber>
	<date>&date;</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.24</revnumber>
	<date>Sunday, April 27, 2008</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.23</revnumber>
	<date>Thursday, March 20, 2008</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.22</revnumber>
	<date>Thursday, March 20, 2008</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.21</revnumber>
	<date>Friday, January 4, 2008</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.20</revnumber>
	<date>Tuesday, November 27, 2007</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.19</revnumber>
	<date>Tuesday, June 26, 2007</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.18</revnumber>
	<date>Wednesday, January 17, 2007</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.17</revnumber>
	<date>Thursday, December 7, 2006</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.16</revnumber>
	<date>Monday, November 27, 2006</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.15</revnumber>
	<date>Wednesday, June 14, 2006</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.14</revnumber>
	<date>Thursday, May 18, 2006</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.13</revnumber>
	<date>Tuesday, May 16, 2006</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.12</revnumber>
	<date>Tuesday, August 9, 2005</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.11</revnumber>
	<date>Sunday, March 6, 2005</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.10</revnumber>
	<date>Thursday, November 25, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.9</revnumber>
	<date>Monday, November 15, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.8</revnumber>
	<date>Thursday, November 4, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.7</revnumber>
	<date>Sunday, October 31, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.6</revnumber>
	<date>Monday, October 25, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.5</revnumber>
	<date>Wednesday, October 6, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.4</revnumber>
	<date>Thursday, September 9, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.3</revnumber>
	<date>Thursday, August 19, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.2</revnumber>
	<date>Monday, August 16, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.1</revnumber>
	<date>Wednesday, July 21, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>Mail Notification Manual V2.0</revnumber>
	<date>Tuesday, June 29, 2004</date>
	<revdescription>
	  <para role="author">
	    Jean-Yves Lefort
	    <email>jylefort@brutele.be</email>
	  </para>
	  <para role="publisher">&project;</para>
	</revdescription>
      </revision>
    </revhistory>

    <releaseinfo>
      This manual describes version &appversion; of Mail Notification.
    </releaseinfo>
    <legalnotice>
      <title>Feedback</title>
      <para>To report a bug or make a suggestion regarding the &app;
	application or this manual, follow the directions in
	<xref linkend="problem-reports"/>.
      </para>
      <!-- Translators may also add here feedback address for translations -->
    </legalnotice>
  </articleinfo>

  <indexterm zone="index">
    <primary>Mail Notification</primary>
  </indexterm>

  <sect1 id="introduction">
    <title>Introduction</title>
    <para>
      &app; is a status icon (&aka; tray icon) that informs you if you
      have new mail.
    </para>
    <para>
      It works with system trays implementing the freedesktop.org
      <ulink url="http://www.freedesktop.org/Standards/systemtray-spec" type="http">System Tray Specification</ulink>, such as the
      GNOME Panel Notification Area, the Xfce Notification Area and the KDE System Tray.
    </para>
    <para>
      &app; features include:
    </para>
    <itemizedlist>
      <listitem><para>multiple mailbox support</para></listitem>
      <listitem><para>Evolution, Gmail, &imap;, &maildir;, &mbox;, &mh;, &mozilla; products (Mozilla, SeaMonkey, Thunderbird, &hellip;), &pop3;, &sylpheed;, Windows Live Hotmail and Yahoo! Mail support</para></listitem>
      <listitem><para>&sasl; authentication support</para></listitem>
      <listitem><para>APOP authentication support</para></listitem>
      <listitem><para>&ssl;/&tls; support</para></listitem>
      <listitem><para>automatic detection of mailbox format</para></listitem>
      <listitem><para><link linkend="immediate-notification">immediate notification</link> (the status icon is updated immediately or within seconds after a mailbox changes)</para></listitem>
      <listitem><para>message popups</para></listitem>
      <listitem><para><ulink url="http://developer.gnome.org/projects/gup/hig" type="http">HIG</ulink> 2.0 compliance</para></listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="getting-started">
    <title>Getting Started</title>

    <sect2 id="to-start">
    <title>To Start &app;</title>
      <para>
	You can start &app; in the following ways:
      </para>
      <variablelist>
    	<varlistentry>
	  <term><guimenu>System</guimenu> menu</term>
	  <listitem>
	    <para>Choose
	      <menuchoice>
    		<guisubmenu>Preferences</guisubmenu>
    		<guimenuitem>&app;</guimenuitem>
	      </menuchoice> (this location may vary across systems).</para>
	  </listitem>
    	</varlistentry>

    	<varlistentry>
	  <term>Command line</term>
	  <listitem>
	    <para>
	      To start &app; from a command line, type the following
	      command in a terminal:
	    </para>
	    <para>
	      <command>mail-notification</command>
	      <replaceable>options</replaceable>
	    </para>
	    <para>
	      where <replaceable>options</replaceable> is one or more options
	      from the following non-exhaustive list:
	    </para>
	    <variablelist>
	      <varlistentry>
		<term>-v, --version</term>
		<listitem><para>Show version information and compiled-in features</para></listitem>
	      </varlistentry>

	      <varlistentry>
		<term>-i, --enable-info</term>
		<listitem>
		  <para>Enable informational output</para>
		  <warning>
		    <title>Security</title>
		    <para>
		      The output of --enable-info may contain
		      sensitive information such as passwords and
		      session transcripts.
		    </para>
		  </warning>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term>-p, --display-properties</term>
		<listitem><para>Display the properties dialog</para></listitem>
	      </varlistentry>

	      <varlistentry>
		<term>-a, --display-about</term>
		<listitem><para>Display the about dialog</para></listitem>
	      </varlistentry>

	      <varlistentry>
		<term>-r, --consider-new-mail-as-read</term>
		<listitem><para>Consider new mail as read</para></listitem>
	      </varlistentry>

	      <varlistentry>
		<term>-u, --update</term>
		<listitem><para>Update the mail status</para></listitem>
	      </varlistentry>

	      <varlistentry>
		<term>-s, --print-summary</term>
		<listitem><para>Print a XML mail summary</para></listitem>
	      </varlistentry>

	      <varlistentry>
		<term>--unset-obsolete-configuration</term>
		<listitem><para>Unset obsolete <application>GConf</application> configuration</para></listitem>
	      </varlistentry>

	      <varlistentry>
		<term>-q, --quit</term>
		<listitem><para>Quit &app;</para></listitem>
	      </varlistentry>

	      <varlistentry>
		<term>-?, --help</term>
		<listitem><para>Show help</para></listitem>
	      </varlistentry>
	    </variablelist>
	  </listitem>
    	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="when-start">
      <title>When You Start &app;</title>
      <para>
	When you start &app;, it puts itself in the background and
	monitors the status of your mailboxes.
      </para>
      <para>
	When new mail arrives, an icon similar to the following one is
	displayed in the notification area (&aka; system tray). The
	number of new messages is displayed over the icon.
      </para>
      <figure id="no-mail-fig">
	<title>&app; when there is new mail</title>
	<screenshot>
	  <mediaobject> 
	    <imageobject>
	      <imagedata fileref="figures/mail.png" format="PNG"/>
	    </imageobject>
	    <textobject>
	      <phrase>Shows the &app; status icon.</phrase>
	    </textobject>
	  </mediaobject>
	</screenshot>
      </figure>
      <para>
	Additionally:
      </para>
      <itemizedlist>
	<listitem>
	  <para>
	    if the <link
	    linkend="play-a-sound-when-new-mail-arrives">Play a sound
	    when new mail arrives</link> setting is enabled, that sound
	    is played
	  </para>
	</listitem>
	<listitem>
	  <para>
	    if the <link linkend="enable-message-popups">Enable
	    message popups</link> setting is enabled, information
	    about each new message is popped up on your desktop
	  </para>
	</listitem>
      </itemizedlist>
      <para>
	If an error is detected, the icon blinks.
      </para>
      <para>
	Leaving your mouse over the icon will reveal more details
	about the status of your mailboxes. Clicking on the
	icon will perform the action specified in the
	<link linkend="click-action">Click Action</link> setting.
      </para>
    </sect2>
  </sect1>

  <sect1 id="properties"> 
    <title>Properties</title> 
    <para>To configure &app;, choose
      <menuchoice>
	<guimenu>System</guimenu>
	<guisubmenu>Preferences</guisubmenu>
	<guimenuitem>Mail Notification</guimenuitem>
      </menuchoice> (this location may vary across systems).
    </para>
    <para>
      The <guilabel>Properties</guilabel> dialog contains the
      following tabbed sections:
    </para>
    <itemizedlist>
      <listitem>
	<para><link linkend="properties-general">General</link></para>
      </listitem>
      <listitem>
	<para><link linkend="properties-status-icon">Status Icon</link></para>
      </listitem>
      <listitem>
	<para><link linkend="properties-message-popups">Message Popups</link></para>
      </listitem>
    </itemizedlist>
    <para>
      In addition, at the bottom of the dialog, the <guilabel>Display
      test messages</guilabel> setting can be used to test the various
      settings against test messages.
    </para>

    <sect2 id="properties-general">
      <title>General</title>
      <variablelist>
	<varlistentry>
	  <term><guilabel>General</guilabel></term>
	  <listitem>
	    <variablelist>
	      <varlistentry id="play-a-sound-when-new-mail-arrives">
		<term><guilabel>Play a sound when new mail arrives</guilabel></term>
		<listitem>
		  <para>
		    If this setting is enabled, the selected sound
		    will be played when new mail arrives.
		  </para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </listitem>
	</varlistentry>
	<varlistentry id="mailbox-list">
	  <term><guilabel>Mailbox List</guilabel></term>
	  <listitem>
	    <para>
	      This is the list of mailboxes to monitor for new
	      mail. Selecting <guibutton>Add</guibutton> or
	      <guibutton>Properties</guibutton> will display the <link linkend="mailbox-properties">Mailbox Properties</link>
	      dialog.
	      <tip>
		<para>
		  You can drag a file or folder into this list.
		</para>
	      </tip>
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
    
    <sect2 id="properties-status-icon">
      <title>Status Icon</title>
      <variablelist>
	<varlistentry id="click-action">
	  <term><guilabel>Click Action</guilabel></term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term><guilabel>Launch the mail reader</guilabel></term>
		<listitem>
		  <para>
		    Launches the GNOME mail reader. To specify your
		    preferred mail reader, choose
		    <menuchoice>
		      <guimenu>System</guimenu>
		      <guisubmenu>Preferences</guisubmenu>
		      <guimenuitem>Preferred Applications</guimenuitem>
		    </menuchoice> (this location may vary across systems).
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term><guilabel>Open the latest message</guilabel></term>
		<listitem>
		  <para>
		    Opens the most recent message, if supported.
		  </para>
		  <para>
		    This is equivalent to clicking on the
		    <guilabel>Open</guilabel> button in the message
		    popup. See the <link
		    linkend="message-actions">Message Actions</link>
		    section for more details.
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term><guilabel>Consider new mail as read</guilabel></term>
		<listitem>
		  <para>
		    Hides the messages received so far. This action
		    has no permanent effects: your mailboxes will not
		    be modified, and the messages will no longer be
		    hidden the next time &app; is started.
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term><guilabel>Update the mail status</guilabel></term>
		<listitem>
		  <para>
		    Checks for new mail in all mailboxes which do not
		    support <link
		    linkend="immediate-notification">immediate
		    notification</link>.
		  </para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="properties-message-popups">
      <title>Message Popups</title>
      <variablelist>
	<varlistentry>
	  <term><guilabel>General</guilabel></term>
	  <listitem>
	    <variablelist>
	      <varlistentry id="enable-message-popups">
		<term><guilabel>Enable message popups</guilabel></term>
		<listitem>
		  <para>
		    If this setting is enabled, an information window
		    will be popped up on your desktop whenever a new
		    message arrives.
		  </para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guilabel>Position</guilabel></term>
	  <listitem>
	    <para>
	      The location of the message popups on the screen.
	    </para>
	    <variablelist>
	      <varlistentry>
		<term><guilabel>Attached to the status icon</guilabel></term>
		<listitem>
		  <para>
		    Message popups will be placed next to the status icon.
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term><guilabel>In the popup stack</guilabel></term>
		<listitem>
		  <para>
		    Message popups will be stacked together in one
		    corner of your screen.
		  </para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guilabel>Expiration</guilabel></term>
	  <listitem>
	    <para>
	      You can choose to have message popups stay on the screen
	      until you click on them, or have them disappear after a
	      delay has elapsed.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
  </sect1>

  <sect1 id="mailbox-properties">
    <title>Mailbox Properties</title>
    <para>
      The <guilabel>Mailbox Properties</guilabel> dialog is displayed
      when you add a new mailbox or when you edit an existing one. It
      may contain the following tabbed sections:
    </para>
    <itemizedlist>
      <listitem>
	<para><link linkend="mailbox-properties-general">General</link></para>
      </listitem>
      <listitem>
	<para><link linkend="mailbox-properties-connection">Connection</link></para>
      </listitem>
      <listitem>
	<para><link linkend="mailbox-properties-details">Details</link></para>
      </listitem>
    </itemizedlist>

    <sect2 id="mailbox-properties-general">
      <title>General</title>
      <variablelist>
	<varlistentry>
	  <term><guilabel>General</guilabel></term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term><guilabel>Mailbox type</guilabel></term>
		<listitem>
		  <para>
		    This is the type of the mailbox. If you select
		    <guilabel>autodetect</guilabel>, the type will be
		    autodetected using the mailbox &uri; and/or
		    contents.
		  </para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <guilabel>Location</guilabel>
	    (<guilabel>Autodetect</guilabel> and <guilabel>System
	      mailbox</guilabel> only)
	  </term>
	  <listitem>
	    <para>
	      This is the &uri; of the mailbox.
	    </para>
	    <note>
	      <para>
		&app; abstracts file operations by using &gnomevfs;.
		All the schemes (http, ftp, sftp, &hellip;) supported by
		&gnomevfs; are therefore supported by &app;.
	      </para>
	    </note>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <guilabel>Account</guilabel> (<guilabel>Gmail</guilabel>,
	    <guilabel>IMAP</guilabel>, <guilabel>POP3</guilabel>,
	    <guilabel>Windows Live Hotmail</guilabel> and
	    <guilabel>Yahoo! Mail</guilabel> only)
	  </term>
	  <listitem>
	    <variablelist>
	      <varlistentry>
		<term>
		  <guilabel>Server</guilabel>
		  (<guilabel>IMAP</guilabel> and
		  <guilabel>POP3</guilabel> only)
		</term>
		<listitem>
		  <para>
		    This is the hostname or IP address of the &imap; or
		    &pop3; server.
		  </para>
		  <note>
		    <para>
		      Symbolic names as well as IPv4 and IPv6
		      addresses are supported.
		    </para>
		  </note>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term><guilabel>Username</guilabel></term>
		<listitem>
		  <para>
		    This is your username on the mail server.
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term><guilabel>Password</guilabel></term>
		<listitem>
		  <para>
		    This is your password on the mail server. If the
		    password is filled in, it will be stored in your
		    default keyring. If it is left out, a password
		    prompt will appear when needed.
		  </para>
		  <warning>
		    <title>IMAP and POP3 Security</title>
		    <para>
		      To avoid sending your password over the network
		      in clear text, you must either use a SSL/TLS
		      connection or select a secure authentication
		      mechanism. See the <link
		      linkend="authentication-mechanism">Authentication
		      Mechanism</link> setting for more details.
		    </para>
		    <!-- simplified on purpose: actually, a weak SSL/TLS -->
		    <!-- algorithm could be used, but this is beyond the -->
		    <!-- scope of this document -->
		  </warning>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <guilabel>IMAP Mailbox</guilabel> (<guilabel>IMAP</guilabel> only)
	  </term>
	  <listitem>
	    <para>
	      This is the &imap; mailbox to use.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <guilabel>Folder</guilabel> (<guilabel>Evolution</guilabel> only)
	  </term>
	  <listitem>
	    <para>
	      This is the Evolution folder to monitor for changes.
	    </para>
	    <note>
	      <para>
		For the folder selector to be available and for
		monitoring an Evolution mailbox, Evolution must be
		running and the Evolution <guilabel>Jean-Yves Lefort's
		Mail Notification</guilabel> plugin must be loaded.
	      </para>
	    </note>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="mailbox-properties-connection">
      <title>Connection (<guilabel>IMAP</guilabel> and <guilabel>POP3</guilabel> only)</title>
      <variablelist>
	<varlistentry>
	  <term><guilabel>Connection type</guilabel></term>
	  <listitem>
	    <para>
	      This is the type of connection to use and the port
	      number to connect to.
	    </para>
	    <para>
	      <guilabel>In-band SSL/TLS</guilabel> refers to a
	      &ssl;/&tls; connection negotiated inside of the
	      protocol (using the <literal>STARTTLS</literal> &imap;
	      command or the <literal>STLS</literal> &pop3;
	      command).
	    </para>
	    <para>
	      <guilabel>SSL/TLS on separate port</guilabel> refers to
	      the most widespread method for establishing a
	      &ssl;/&tls; connection: using a separate port.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><guilabel>Authentication</guilabel></term>
	  <listitem>
	    <variablelist>
	      <varlistentry id="authentication-mechanism">
		<term><guilabel>Mechanism</guilabel></term>
		<listitem>
		  <para>
		    This is the authentication mechanism to use.
		    If you select <guilabel>autodetect</guilabel>,
		    all the authentication mechanisms supported by the &imap;
		    or &pop3; server will be tried, in descending order of
		    security. Otherwise, the selected mechanism (and
		    <emphasis>only</emphasis> the selected mechanism) will
		    be used.
		  </para>
		  <warning>
		    <title>Security</title>
		    <para>
		      If <guilabel>autodetect</guilabel> is selected and
		      secure authentication fails, your credentials may
		      be sent over the network in clear text (unless you
		      use a &ssl;/&tls; connection).
		    </para>
		    <para>
		      If this is a concern, select the appropriate
		      secure authentication mechanism from the drop-down
		      list.
		    </para>
		  </warning>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <guilabel>Use the IDLE extension</guilabel>
	    (<guilabel>IMAP</guilabel> only)
	  </term>
	  <listitem>
	    <para>
	      The IDLE extension (as defined by <ulink url="http://www.ietf.org/rfc/rfc2177.txt" type="http">RFC 2177</ulink>)
	      allows &app; to stay connected to the server and provide
	      <link linkend="immediate-notification">immediate notification</link> of changes.
	    </para>
	    <para>
	      If <guilabel>never</guilabel> is selected, &app;
	      will never use the IDLE extension, not even if the
	      server supports it. Use this setting if it appears
	      that &app; does not detect changes to an &imap;
	      mailbox while the IDLE extension is in use. If using
	      this setting fixes the issue, please also send the
	      &imap; session transcript (obtained by running &app;
	      using the --enable-info option) to Jean-Yves Lefort
	      <email>jylefort@brutele.be</email>.
	    </para>
	    <para>
	      If <guilabel>autodetect</guilabel> is selected,
	      &app; will use the IDLE extension if the server
	      supports it, unless the server software is known to
	      have a broken IDLE implementation (currently, the
	      only such software known to &app; is the University
	      of Washington imapd). This is the recommended
	      choice.
	    </para>
	    <para>
	      If <guilabel>always</guilabel> is selected, &app;
	      will use the IDLE extension if the server supports
	      it, regardless of the server software. Use this
	      setting if you want to force &app; to use the IDLE
	      extension, even if it has detected a bogus
	      implementation.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="mailbox-properties-details">
      <title>Details</title>
      <variablelist>
	<varlistentry>
	  <term><guilabel>Mailbox Name</guilabel></term>
	  <listitem>
	    <para>
	      You can choose to assign a custom name to the
	      mailbox. The mailbox name has informative purposes
	      only, and is displayed in various parts of
	      &app;.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry id="delay-between-mail-checks">
	  <term><guilabel>Delay Between Mail Checks</guilabel></term>
	  <listitem>
	    <para>
	      This is the amount of time to wait between mail checks.
	    </para>
	    <note>
	      <para>
		This delay is only used if the mailbox does
		not support <link
		  linkend="immediate-notification">immediate
		  notification</link> of changes.
	      </para>
	    </note>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
  </sect1>

  <sect1 id="advanced-configuration">
    <title>Advanced Configuration</title>

    <sect2 id="message-actions">
      <title>Message Actions</title>
      <para>
	Message popups support the following actions:
      </para>
      <itemizedlist>
	<listitem><para><guilabel>Open</guilabel></para></listitem>
	<listitem><para><guilabel>Mark as Read</guilabel></para></listitem>
	<listitem><para><guilabel>Mark as Spam</guilabel></para></listitem>
	<listitem><para><guilabel>Delete</guilabel></para></listitem>
      </itemizedlist>
      <para>
	Note that the <guilabel>Delete</guilabel> action is disabled
	by default. It can be enabled by modifying the <database
	class="field">/apps/mail-notification/popups/actions</database>
	<application>GConf</application> key. See the <link
	linkend="gconf-settings">GConf Settings</link> section
	for more details about the <application>GConf</application>
	database.
      </para>

      <sect3 id="built-in-actions">
	<title>Built-in Actions</title>
	<para>
	  The following table summarizes the currently implemented
	  built-in actions for each mailbox type.
	</para>
	<table>
	  <title>Built-in Actions</title>
	  <tgroup cols="4">
	    <thead>
	      <row>
		<entry>Mailbox Type</entry>
		<entry><guilabel>Open</guilabel></entry>
		<entry><guilabel>Mark as Read</guilabel></entry>
		<entry><guilabel>Mark as Spam</guilabel></entry>
		<entry><guilabel>Delete</guilabel></entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry>Evolution</entry>
		<entry>yes</entry>
		<entry>yes</entry>
		<entry>yes</entry>
		<entry>yes</entry>
	      </row>
	      <row>
		<entry>Gmail</entry>
		<entry>yes</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
	      </row>
	      <row>
		<entry>&imap;</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
	      </row>
	      <row>
		<entry>&maildir;</entry>
		<entry>yes</entry>
		<entry>yes</entry>
		<entry>no</entry>
		<entry>yes</entry>
	      </row>
	      <row>
		<entry>&mbox;</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
	      </row>
	      <row>
		<entry>&mh;</entry>
		<entry>yes</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
	      </row>
	      <row>
		<entry>&mozilla;</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
	      </row>
	      <row>
		<entry>&sylpheed;</entry>
		<entry>yes</entry>
		<entry>yes</entry>
		<entry>no</entry>
		<entry>no</entry>
	      </row>
	      <row>
		<entry>&pop3;</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
	      </row>
	      <row>
		<entry>Windows Live Hotmail</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
	      </row>
	      <row>
		<entry>Yahoo! Mail</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
		<entry>no</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
      </sect3>

      <sect3 id="custom-actions">
	<title>Custom Actions</title>
	<para>
	  To define a custom action for a particular mailbox, edit the
	  <filename>~/.gnome2/mail-notification/mailboxes.xml</filename>
	  file and specify a command to be executed when the action
	  button is clicked.
	</para>
	<note>
	  <para>
	    If both a built-in action and a custom action exists, the
	    custom action overrides the built-in action.
	  </para>
	</note>
	<para>
	  XML attributes should be added to the
	  <sgmltag>mailbox</sgmltag> element of the mailbox you want the
	  actions to be available for. The following table specifies
	  which XML attribute should be used for a particular action.
	</para>
	<table>
	  <title>Action Attributes</title>
	  <tgroup cols="2">
	    <thead>
	      <row>
		<entry>Action</entry>
		<entry>XML Attribute</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry><guilabel>Open</guilabel></entry>
		<entry><parameter>open-command</parameter></entry>
	      </row>
	      <row>
		<entry><guilabel>Mark as Read</guilabel></entry>
		<entry><parameter>mark-as-read-command</parameter></entry>
	      </row>
	      <row>
		<entry><guilabel>Mark as Spam</guilabel></entry>
		<entry><parameter>mark-as-spam-command</parameter></entry>
	      </row>
	      <row>
		<entry><guilabel>Delete</guilabel></entry>
		<entry><parameter>delete-command</parameter></entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
	<para>
	  Before executing a command, some strings will be
	  substituted. The following table summarizes the available
	  substitutions.
	</para>
	<table>
	  <title>Command String Substitutions</title>
	  <tgroup cols="2">
	    <thead>
	      <row>
		<entry>String</entry>
		<entry>Substitution</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry><literal>%%</literal></entry>
		<entry>a single percent character</entry>
	      </row>
	      <row>
		<entry><literal>%sent-time</literal></entry>
		<entry>
		  the message timestamp expressed in seconds since the
		  Epoch (00:00:00 UTC, January 1, 1970)
		</entry>
	      </row>
	      <row>
		<entry><literal>%id</literal></entry>
		<entry>
		  the message unique identifier
		</entry>
	      </row>
	      <row>
		<entry><literal>%from</literal></entry>
		<entry>
		  the message sender
		</entry>
	      </row>
	      <row>
		<entry><literal>%subject</literal></entry>
		<entry>
		  the message subject, if any
		</entry>
	      </row>
	      <row>
		<entry><literal>%uri</literal></entry>
		<entry>
		  the message &uri;, if any
		</entry>
	      </row>
	      <row>
		<entry><literal>%filename</literal></entry>
		<entry>
		  if the message has an &uri; and that &uri; points to a
		  local filename, that filename
		</entry>
	      </row>
	      <row>
		<entry><literal>%uid</literal></entry>
		<entry>
		  the Evolution message UID, if any
		</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
	<note>
	  <itemizedlist>
	    <listitem>
	      <para>
		Substitutions will be shell-quoted as appropriate, you
		therefore must not quote the percent strings.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Keywords can be enclosed in braces, as in
		<literal>%{from}</literal>.
	      </para>
	    </listitem>
	  </itemizedlist>
	</note>
	<para>
	  Example:
	</para>
	<programlisting>
&lt;?xml version="1.0"?&gt;
&lt;mailboxes&gt;
  &lt;mailbox
    type="custom-vfs"
    uri="file:///home/jylefort/Mail/misc"
    open-command="my-open-script %filename"
    mark-as-spam-command="my-spam-script %filename"/&gt;
&lt;/mailboxes&gt;</programlisting>
      </sect3>
    </sect2>

    <sect2 id="modifying-appearance">
      <title>Modifying the Appearance of &app;</title>
      <para>
	&app; sets names for several widgets and icons, so that they
	can easily be matched in a GTK+ resource file.
      </para>
      <para>
	More information about GTK+ resource files, including a
	description of their format, can be found in the <ulink	url="http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html" type="http">Resource Files</ulink>
	section of the GTK+ Reference Manual.
      </para>

      <table><title>Widget Names</title>
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>Widget</entry>
	      <entry>Name</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>mail icon and message count</entry>
	      <entry>mn-mail-icon</entry>
	    </row>
	    <row>
	      <entry>tooltip section title</entry>
	      <entry>mn-tooltip-section-title</entry>
	    </row>
	    <row>
	      <entry>tooltip section body (except mail summary)</entry>
	      <entry>mn-tooltip-section-body</entry>
	    </row>
	    <row>
	      <entry>tooltip mail summary</entry>
	      <entry>mn-message-view</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

      <table><title>Icon Names</title>
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>Icon</entry>
	      <entry>Name</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>status icon when there is new mail</entry>
	      <entry>mn-mail</entry>
	    </row>
	    <row>
	      <entry>status icon when there is no new mail</entry>
	      <entry>mn-no-mail</entry>
	    </row>
	    <row>
	      <entry>local mailbox</entry>
	      <entry>mn-local</entry>
	    </row>
	    <row>
	      <entry>remote mailbox</entry>
	      <entry>mn-remote</entry>
	    </row>
	    <row>
	      <entry>autodetect (in the <guilabel>Mailbox type</guilabel> drop-down menu)</entry>
	      <entry>mn-unknown</entry>
	    </row>
	    <row>
	      <entry>mailbox error</entry>
	      <entry>mn-error</entry>
	    </row>
	    <row>
	      <entry>Gmail mailbox</entry>
	      <entry>mn-gmail</entry>
	    </row>
	    <row>
	      <entry>Yahoo! Mail mailbox</entry>
	      <entry>mn-yahoo</entry>
	    </row>
	    <row>
	      <entry>Windows Live Hotmail mailbox</entry>
	      <entry>mn-hotmail</entry>
	    </row>
	    <row>
	      <entry>system mailbox</entry>
	      <entry>mn-system-mailbox</entry>
	    </row>
	    <row>
	      <entry>Evolution mailbox</entry>
	      <entry>mn-evolution-mailbox</entry>
	    </row>
	    <row>
	      <entry>mail reader</entry>
	      <entry>mn-mail-reader</entry>
	    </row>
	    <row>
	      <entry>open message</entry>
	      <entry>mn-open-message</entry>
	    </row>
	    <row>
	      <entry>consider new mail as read</entry>
	      <entry>mn-consider-new-mail-as-read</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

      <sect3>
	<title>Examples</title>
	<para>
	  You can modify the appearance of &app; by editing the
	  <filename>~/.gtkrc-2.0</filename> file.
	</para>
	<para>
	  To use a larger font for the message count of the mail icon,
	  and display it on a yellow background:
	</para>
	<programlisting>style "mn-mail-icon"
{
  font_name = "Sans 12"
  bg[NORMAL] = "#FFFF00"
}

widget "*.mn-mail-icon" style "mn-mail-icon"</programlisting>
	<para>
	  To use a smaller font for the mail summary tooltip messages:
	</para>
	<programlisting>style "mn-mail-summary-tooltip-messages"
{
  font_name = "Sans 8"
}

widget "gtk-tooltips.*.mn-message-view"
  style "mn-mail-summary-tooltip-messages"</programlisting>
	<para>
	  To use some custom icons:
	</para>
	<programlisting>pixmap_path "/home/myaccount/icons"

style "mn-icons"
{
  stock["mn-mail"] =
  {
    { "my-mail-icon.png" }
  }
  stock["mn-no-mail"] =
  {
    { "my-no-mail-icon.png" }
  }
}

widget "*" style "mn-icons"</programlisting>
      </sect3>
    </sect2>

    <sect2 id="gconf-settings">
      <title>GConf Settings</title>
      <para>
	A number of advanced settings are available in the
	<database>/apps/mail-notification</database> namespace of the
	<application>GConf</application> database. To modify these
	settings, type the following command in a terminal:
      </para>
      <para>
	<command>gconf-editor /apps/mail-notification</command>
      </para>
    </sect2>
  </sect1>

  <sect1 id="troubleshooting">
    <title>Troubleshooting</title>
    <para>
      If &app; does not work as expected, remember that you can obtain
      more details by leaving your mouse over its icon.
    </para>
    <para>
      Additionally, a very efficient way to identify and solve
      problems is to run &app; using the --enable-info option and
      examine the output.
      <warning>
	<title>Security</title>
	<para>
	  The output of --enable-info may contain sensitive
	  information such as passwords and session transcripts.
	</para>
      </warning>
    </para>
  </sect1>
  
  <sect1 id="technical-information">
    <title>Technical Information</title>
    
    <sect2 id="immediate-notification">
      <title>Immediate Notification</title>
      <para>
	Immediate notification is the ability to detect changes to a
	mailbox without needing to check it periodically. It allows
	the status icon to be updated immediately (or within seconds)
	after a mailbox changes.
      </para>
      <para>
	Requirements for immediate notification to be enabled:
      </para>
      <variablelist>
	<varlistentry>
	  <term>&maildir;, &mbox;, &mh;, &mozilla; and &sylpheed; mailboxes:</term>
	  <listitem>
	    <para>
	      &gnomevfs; must support monitoring (it usually does).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>&imap; mailboxes:</term>
	  <listitem>
	    <para>
	      The &imap; server must support the IDLE extension, as defined by
	      <ulink url="http://www.ietf.org/rfc/rfc2177.txt" type="http">RFC 2177</ulink>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Evolution mailboxes:</term>
	  <listitem>
	    <para>
	      There is no requirement. Immediate notification is
	      always enabled.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Gmail, &pop3;, Windows Live Hotmail and Yahoo! Mail mailboxes:</term>
	  <listitem>
	    <para>
	      Immediate notification is not supported by these mailbox types.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <note>
	<para>
	  If immediate notification cannot be enabled for a mailbox
	  (either because that type of mailbox does not support it or
	  because the requirements are not met), the mailbox will be
	  checked periodically according to its <link
	  linkend="delay-between-mail-checks">Delay Between Mail
	  Checks</link> setting.
	</para>
      </note>
    </sect2>

    <sect2>
      <title>POP3 Implementation</title>
      <para>
	The &app; &pop3; implementation strictly conforms to
	<ulink url="http://www.ietf.org/rfc/rfc1939.txt" type="http">RFC 1939</ulink>,
	<ulink url="http://www.ietf.org/rfc/rfc2449.txt" type="http">RFC 2449</ulink>,
	<ulink url="http://www.ietf.org/rfc/rfc1734.txt" type="http">RFC 1734</ulink>,
	<ulink url="http://www.ietf.org/rfc/rfc2595.txt" type="http">RFC 2595</ulink> and
	<ulink url="http://www.ietf.org/rfc/rfc2384.txt" type="http">RFC 2384</ulink>.
      </para>
      <para>
	The AUTH, APOP and USER/PASS authentication mechanisms are
	supported, and the LOGIN-DELAY capability is honoured. The TOP
	optional command is supported.
      </para>
      <para>
	The authentication logic can be represented with the following
	pseudo-code:
      </para>
      <programlisting>success = false;

if (mailbox.config.authmech != autodetect) {
  if (mailbox.config.authmech in server.supported_authmechs) {
    success = server.authenticate(mailbox.config.authmech);
  }
} else {
  if (has_sasl_support &amp;&amp; server.supports_sasl) {
    foreach authmech in server.supported_authmechs {
      if (server.ssl_connection || ! authmech.plaintext) {
        success = server.authenticate(authmech);
        if (success)
          break;
      }
    }
    if (! success &amp;&amp; server.supports_apop) {
      success = server.authenticate(apop);
    }
    if (! success) {
      success = server.authenticate(userpass);
    }
  }
}

if (! success) {
  mailbox.error = "authentication failed";
}</programlisting>
    </sect2>

    <sect2>
      <title>IMAP Implementation</title>
      <para>
	The &app; &imap; implementation strictly conforms to
	<ulink url="http://www.ietf.org/rfc/rfc3501.txt" type="http">RFC 3501</ulink>,
	<ulink url="http://www.ietf.org/rfc/rfc2177.txt" type="http">RFC 2177</ulink> and
	<ulink url="http://www.ietf.org/rfc/rfc2192.txt" type="http">RFC 2192</ulink>.
      </para>
      <para>
	The AUTHENTICATE and LOGIN authentication mechanisms are
	supported, and the IDLE extension is implemented.
      </para>
      <para>
	The authentication logic can be represented with the following
	pseudo-code:
      </para>
      <programlisting>success = false;

if (mailbox.config.authmech != autodetect) {
  if (mailbox.config.authmech in server.supported_authmechs) {
    success = server.authenticate(mailbox.config.authmech);
  }
} else {
  if (has_sasl_support &amp;&amp; server.supports_sasl) {
    foreach authmech in server.supported_authmechs {
      if (server.ssl_connection || ! authmech.plaintext) {
        success = server.authenticate(authmech);
        if (success)
          break;
      }
    }
    if (! success &amp;&amp; server.supports_login) {
      server.authenticate(login);
    }
  }
}

if (! success) {
  mailbox.error = "authentication failed";
}</programlisting>
    </sect2>
  </sect1>
    
  <sect1 id="faq">
    <title>Frequently Asked Questions</title>
    <qandaset defaultlabel="number">
      <qandaentry>
	<question>
	  <para>
	    How can I access the <link
	    linkend="properties">Properties</link> dialog?
	  </para>
	</question>
	<answer>
	  <para>
	    Choose
	    <menuchoice>
	      <guimenu>System</guimenu>
	      <guisubmenu>Preferences</guisubmenu>
	      <guimenuitem>Mail Notification</guimenuitem>
	    </menuchoice> (this location may vary across systems) or type
	    <command>mail-notification -p</command> in a terminal.
	  </para>
	</answer>
      </qandaentry>
      <qandaentry>
	<question>
	  <para>
	    You say that &app; supports &lt;mailbox type&gt;, but
	    there is no such entry in the <link
	    linkend="mailbox-properties">Mailbox Properties</link>
	    dialog.
	  </para>
	</question>
	<answer>
	  <para>
	    &app; was built without support for &lt;mailbox type&gt;.
	  </para>
	  <para>
	    If you have installed &app; from a package, contact the
	    package maintainer and ask him to enable &lt;mailbox
	    type&gt; support.
	  </para>
	  <para>
	    If you have built &app; yourself, install the &lt;mailbox
	    type&gt; prerequisites (they are listed in the
	    <filename>INSTALL</filename> file), then rebuild &app;.
	  </para>
	</answer>
      </qandaentry>
      <qandaentry>
	<question>
	  <para>
	    I need &ssl;/&tls; for connecting to my &pop3; or &imap;
	    server, but the &ssl;/&tls; settings are greyed out.
	  </para>
	</question>
	<answer>
	  <para>
	    &app; was built without &ssl;/&tls; support.
	  </para>
	  <para>
	    If you have installed &app; from a package, contact the
	    package maintainer and ask him to enable &ssl;/&tls;
	    support.
	  </para>
	  <para>
	    If you have built &app; yourself, install the &ssl;/&tls;
	    prerequisites (they are listed in the
	    <filename>INSTALL</filename> file), then rebuild &app;.
	  </para>
	</answer>
      </qandaentry>
      <qandaentry>
	<question>
	  <para>
	    When monitoring a &pop3; mailbox, &app; reports all
	    messages as new.
	  </para>
	</question>
	<answer>
	  <para>
	    This is caused by limitations in the &pop3; protocol. You
	    should configure your mail reader so that it deletes mail
	    from the server after downloading it.
	  </para>
	</answer>
      </qandaentry>
      <qandaentry>
	<question>
	  <para>
	    How can I monitor multiple &imap; folders?
	  </para>
	</question>
	<answer>
	  <para>
	    Add each folder as a separate &app; mailbox.
	  </para>
	</answer>
      </qandaentry>
      <qandaentry>
	<question>
	  <para>
	    Can I monitor a &lt;webmail provider&gt; account?
	  </para>
	</question>
	<answer>
	  <para>
	    &app; has no native support for &lt;webmail provider&gt;
	    mailboxes. However, &app; supports the &pop3; and &imap;
	    protocols; you can therefore use a separate application
	    for providing &pop3; or &imap; access to the &lt;webmail
	    provider&gt; account.
	  </para>
	</answer>
      </qandaentry>
      <qandaentry>
	<question>
	  <para>
	    How can I access message data from the new mail command?
	  </para>
	</question>
	<answer>
	  <para>
	    Parse the output of <command>mail-notification --print-summary</command>.
	  </para>
	</answer>
      </qandaentry>
      <qandaentry>
	<question>
	  <para>
	    I do not use &app; but I am presented with the properties
	    dialog each time I log in. How can I disable it?
	  </para>
	</question>
	<answer>
	  <orderedlist>
	    <listitem>
	      <para>
		Choose
		<menuchoice>
		  <guimenu>System</guimenu>
		  <guisubmenu>Preferences</guisubmenu>
		  <guimenuitem>Sessions</guimenuitem>
		</menuchoice> (this location may vary across systems).
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Select the <guilabel>Startup Programs</guilabel> tab.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Uncheck the <guilabel>Mail Notification</guilabel> entry.
	      </para>
	    </listitem>
	  </orderedlist>
	</answer>
      </qandaentry>
    </qandaset>
  </sect1>

  <sect1 id="about">
    <title>About &app;</title>
    <para>
      &app; was written by Jean-Yves Lefort
      <email>jylefort@brutele.be</email>. To find more information
      about &app;, visit the
      <ulink url="http://www.nongnu.org/mailnotify" type="http">Mail Notification web site</ulink>.
    </para>
    
    <sect2 id="problem-reports">
      <title>Reporting Bugs and Other Feedback</title>
      <para>
	Bug reports and feature requests should be filed in the
	<ulink url="https://bugs.launchpad.net/mail-notification/" type="http">Mail Notification bug tracker</ulink>.
	Other feedback can be sent to Jean-Yves Lefort <email>jylefort@brutele.be</email>.
      </para>
    </sect2>

    <sect2 id="acknowledgements">
      <title>Acknowledgements</title>
      <itemizedlist>
	<!-- We don't use <firstname> and <surname> because we can't -->
	<!-- unambiguously split some names. -->
	<listitem><para>Claudio André</para></listitem>
	<listitem><para>Hendrik Brandt</para></listitem>
	<listitem><para>Kim Briggs</para></listitem>
	<listitem><para>Hiroshi Hasebe</para></listitem>
	<listitem><para>Duarte Henriques</para></listitem>
	<listitem><para>Nacho Hermoso de Mendoza</para></listitem>
	<listitem><para>Dan Korostelev</para></listitem>
	<listitem><para>Pav Lucistnik</para></listitem>
	<listitem><para>Filip Miletic</para></listitem>
	<listitem><para>Phil Nelson</para></listitem>
	<listitem><para>Daniel Nylander</para></listitem>
	<listitem><para>Lorenzo Orlandini</para></listitem>
	<listitem><para>Maurycy Pawłowski-Wieroński</para></listitem>
	<listitem><para>Vladimir Petkov</para></listitem>
	<listitem><para>Benoît Rouits</para></listitem>
	<listitem><para>Tomasz Sarota-Raczek</para></listitem>
	<listitem><para>Tomasz Sałaciński</para></listitem>
	<listitem><para>Edwin Shin</para></listitem>
	<listitem><para>Topi</para></listitem>
	<listitem><para>Marcel J. Zwiebel</para></listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="licensing-terms">
      <title>Licensing Terms</title>
      &software-license;
    </sect2>
  </sect1>

  <glossary id="glossary">
    <title>Glossary</title>

    <glossdiv><title>G</title>
      <glossentry id="gnomevfs">
	<glossterm>GnomeVFS</glossterm>
	<glossdef>
	  <para>
	    A filesystem abstraction library allowing applications to access
	    local, remote and virtual resources in a transparent fashion.
	    <ulink url="http://developer.gnome.org/doc/API/2.0/gnome-vfs-2.0" type="http">GnomeVFS</ulink>
	    is part of the <ulink url="http://www.gnome.org" type="http">GNOME Desktop Environment</ulink>.
	  </para>
	</glossdef>
      </glossentry>
    </glossdiv>

    <glossdiv><title>I</title>
      <glossentry>
	<glossterm>IMAP</glossterm>
	<glosssee otherterm="imap"/>
      </glossentry>

      <glossentry id="imap">
	<glossterm>Internet Message Access Protocol</glossterm>
	<acronym>IMAP</acronym>
	<glossdef>
	  <para>
	    A protocol allowing a client to access and manipulate
	    electronic mail messages on a server. &app; implements
	    version 4rev1 of the protocol, as defined by
	    <ulink url="http://www.ietf.org/rfc/rfc3501.txt" type="http">RFC 3501</ulink>.
	  </para>
	</glossdef>
      </glossentry>
    </glossdiv>

    <glossdiv><title>M</title>
      <glossentry id="maildir">
	<glossterm>Maildir</glossterm>
	<glossdef>
	  <para>
	    A mailbox format popularised by the <ulink url="http://www.qmail.org" type="http">qmail</ulink> mail transfer agent.
	    Messages are stored in a structure of directories for reliability.
	  </para>
	</glossdef>
      </glossentry>

      <glossentry id="mbox">
	<glossterm>mbox</glossterm>
	<glossdef>
	  <para>
	    The traditional UNIX mailbox format. Messages are
	    stored in a single file.
	  </para>
	</glossdef>
      </glossentry>

      <glossentry id="mh">
	<glossterm>MH</glossterm>
	<glossdef>
	  <para>
	    A mailbox format popularised by the
	    <ulink url="http://www.ics.uci.edu/~mh" type="http">MH</ulink> mail user agent.
	    Messages are stored as separate files for flexibility and performance.
	  </para>
	</glossdef>
      </glossentry>

      <glossentry id="mozilla">
	<glossterm>Mozilla</glossterm>
	<glossdef>
	  <para>
	    In this manual, a Mozilla mailbox refers to a mailbox
	    produced by a Mozilla-based mail reader (Mozilla,
	    SeaMonkey, Thunderbird, &hellip;). This mailbox format only
	    differs from the &mbox; format by the fact that message
	    status information is stored in the
	    <literal>X-Mozilla-Status</literal> header instead of the
	    <literal>Status</literal> header.
	  </para>
	</glossdef>
      </glossentry>
    </glossdiv>

    <glossdiv><title>P</title>
      <glossentry>
	<glossterm>POP3</glossterm>
	<glosssee otherterm="pop3"/>
      </glossentry>

      <glossentry id="pop3">
	<glossterm>Post Office Protocol Version 3</glossterm>
	<acronym>POP3</acronym>
	<glossdef>
	  <para>
	    A protocol allowing a workstation to dynamically access
	    a maildrop on a server host, as defined by
	    <ulink url="http://www.ietf.org/rfc/rfc1939.txt" type="http">RFC 1939</ulink>.
	  </para>
	</glossdef>
      </glossentry>
    </glossdiv>

    <glossdiv><title>S</title>
      <glossentry>
	<glossterm>SASL</glossterm>
	<glosssee otherterm="sasl"/>
      </glossentry>

      <glossentry id="ssl">
	<glossterm>Secure Sockets Layer</glossterm>
	<acronym>SSL</acronym>
	<glossdef>
	  <para>
	    A protocol securing a connection through the use of
	    cryptographic techniques.
	  </para>
	</glossdef>
      </glossentry>

      <glossentry id="sasl">
	<glossterm>Simple Authentication and Security Layer</glossterm>
	<acronym>SASL</acronym>
	<glossdef>
	  <para>
	    A method for adding authentication support to
	    connection-based protocols, as defined by
	    <ulink url="http://www.ietf.org/rfc/rfc2222.txt" type="http">RFC 2222</ulink>.
	  </para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm>SSL</glossterm>
	<glosssee otherterm="ssl"/>
      </glossentry>

      <glossentry id="sylpheed">
	<glossterm>Sylpheed</glossterm>
	<glossdef>
	  <para>
	    The mailbox format used by the <ulink url="http://sylpheed.good-day.net" type="http">Sylpheed</ulink>
	    mail user agent. The Sylpheed format adds a binary cache to MH folders
	    for faster indexing.
	  </para>
	</glossdef>
      </glossentry>
    </glossdiv>

    <glossdiv><title>T</title>
      <glossentry>
	<glossterm>TLS</glossterm>
	<glosssee otherterm="tls"/>
      </glossentry>

      <glossentry id="tls">
	<glossterm>Transport Layer Security</glossterm>
	<acronym>TLS</acronym>
	<glossdef>
	  <para>
	    A protocol securing a connection through the use of
	    cryptographic techniques, as defined by
	    <ulink url="http://www.ietf.org/rfc/rfc2246.txt" type="http">RFC 2246</ulink>.
	    TLS is the successor of &ssl;.
	  </para>
	</glossdef>
      </glossentry>
    </glossdiv>

    <glossdiv><title>U</title>
      <glossentry id="uri">
	<glossterm>Uniform Resource Identifier</glossterm>
	<acronym>URI</acronym>
	<glossdef>
	  <para>
	    A <quote>compact string of characters for identifying an
	      abstract or physical resource</quote>, as defined
	    by <ulink url="http://www.ietf.org/rfc/rfc2396.txt" type="http">RFC 2396</ulink>.
	  </para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm>URI</glossterm>
	<glosssee otherterm="uri"/>
      </glossentry>
    </glossdiv>
  </glossary>
</article>
