/head: changeset 111

Updated documentation; absorbed readme into new manual
2002-07-12 07:43:07 +01:00 · 2002-07-12 07:43:07 +01:00 · ec4b5cde6f
commit ec4b5cde6f
parent f4966e3a40
7 changed files with 2581 additions and 328 deletions
--- a/head/Makefile
+++ b/head/Makefile
@ -14,6 +14,7 @@
 #    You should have received a copy of the GNU General Public License
 #    along with this program; if not, write to the Free Software
 #    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 SHELL=/bin/bash
 clean:
 	-python2.2 setup.py clean --all
@ -28,3 +29,9 @@ changelog:
 	cvs2cl
 	cvs commit ChangeLog
 	rm ChangeLog.bak
 docs:
 	man -t -l offlineimap.1 > manual.ps
 	ps2pdf manual.ps
 	groff -Tascii -man offlineimap.1 | sed $$'s/.\b//g' > manual.txt
 	groff -Thtml -man offlineimap.1 > manual.html
--- a/head/README
+++ b/head/README
@ -1,298 +0,0 @@
 OfflineIMAP
 Copyright (C) 2002 John Goerzen <jgoerzen@complete.org>
 This software comes with ABSOLUTELY NO WARRANTY; see the file
 COPYING for details.  This is free software, and you are welcome
 to distribute it under the conditions laid out in COPYING.
 gopher://quux.org/1/devel/offlineimap
 http://quux.org/devel/offlineimap
 ==================================================
 Welcome
 ==================================================
 OfflineIMAP is a tool to simplify your e-mail reading.  With
 OfflimeIMAP, you can:
 * Read the same mailbox from multiple computers, and have your
   changes (deletions, etc.) be automatically reflected on
   all computers
 * Use various mail clients to read a single mail box
 * Read mail while offline (on a laptop) and have all changes
   synchronized when you get connected again
 * Read IMAP mail with mail readers that do not support IMAP
 * Use SSL (secure connections) to read IMAP mail even if your reader
   doesn't support SSL
 * Synchronize your mail using a completely safe and fault-tolerant
   algorithm.  (At least I think it is!)
 * Customize which mailboxes to synchronize with regular expressions
   or lists.
 * Synchronize your mail two to four times faster than with other tools
   or other mail readers' internal IMAP support.
 In short, OfflineIMAP is a tool to let you read mail how YOU want to.
 ==================================================
 Requirements
 ==================================================
 To use OfflineIMAP, you must:
 1. Have your mail delivered to a server that supports IMAP
 2. Have Python 2.2 or above installed
 3. Have a mail reader that supports Maildirs (most modern ones do)
 These requirements are easy to meet, and most people will have met
 them already without even being aware of it.
 If you do not have Python already, check your operating system vendor
 or download it from http://www.python.org/
 ==================================================
 Installation
 ==================================================
 Basic installation for a single user requires only these steps:
 1. Copy offlineimap.conf to ~/.offlineimaprc and edit that file
   for your accounts.  Full instructions are in it.
 2. Make the directory that you will store your folders in.
   (~/Test in the example)
 You can then just run "python2.2 offlineimap.py" to synchronize your
 mail.
 ------------------------------
 Systemwide
 If you wish to install OfflineIMAP for all users on your system:
 1. Either install the Debian package or run "python2.2 setup.py" and
   follow the prompts
 2. Advise users to perform steps 1 and 2 above
 3. Run OfflineIMAP by typing "offlineimap"
 That's it!
 ==================================================
 Frequently Asked Questions
 ==================================================
 Q. I get a message saying "UID validity problem for folder; skipping".
 What does this mean and how do I fix it?
 A. IMAP servers use a unique ID (UID) to refer to a specific message.
 This number is guaranteed to be unique to a particular message
 FOREVER.  No other message in the same folder will ever get the same
 UID.  UIDs are an integral part of OfflineIMAP's synchronization
 scheme; they are used to match up messages on your computer to
 messages on the server.
 Sometimes, the UIDs on the server might get reset.  Usually this will
 happen if you delete and then recreate a folder.  When you create a
 folder, the server will often start the UID back from 1.  But
 OfflineIMAP might still have the UIDs from the previous folder by the
 same name stored.  OfflineIMAP will detect this condition and skip the
 folder.  This is GOOD, because it prevents data loss.
 You can fix it by removing your local folder and cache data.  For
 instance, if your folders are under ~/Folders and the folder with the
 problem is INBOX, you'd type this:
 rm -r ~/Folders/INBOX
 rm ~/.offlineimap/AccountName/INBOX
 (replacing AccountName with the account name as specified in
 ~/.offlineimaprc)
 Next time you run OfflineIMAP, it will re-download the folder with the
 new UIDs.  Note that the procedure specified above will lose any local
 changes made to the folder.
 Some IMAP servers are broken and do not support UIDs properly.  If you
 continue to get this error for all your folders even after performing
 the above procedure, it is likely that your IMAP server falls into
 this category.  OfflineIMAP is incompatible with such servers.  Using
 OfflineIMAP with them will not destroy any mail, but at the same time,
 it will not actually synchronize it either.  (OfflineIMAP will detect
 this condition and abort prior to synchronization)
 --------------------------------------------------
 Q. What platforms does OfflineIMAP run on?
 A. It should run on most platforms supported by Python, which are
 quite a few.
 --------------------------------------------------
 Q. I'm using Mutt.  Other IMAP synchronization programs require me to
 "set maildir_trash=yes".  Do I need to do that with OfflineIMAP?
 A. No.  OfflineIMAP is smart enough to figure out message deletion
 without this extra crutch.  You'll get the best results if you don't
 use that setting, in fact.
 --------------------------------------------------
 Q. How do I specify the names of my folders?
 A. You do not need to.  OfflineIMAP is smart enough to automatically
 figure out what folders are present on the IMAP server and synchronize
 them.
 --------------------------------------------------
 Q. How can I prevent certain folders from being synced?
 A. This feature will be introduced in a future version of OfflineIMAP.
 --------------------------------------------------
 Q. How can I add or delete a folder?
 A. OfflineIMAP does not currently provide this feature.
 --------------------------------------------------
 Q. Are there any specific warnings or things I should be aware of
 before using OfflineIMAP?
 A. Yes.  OfflineIMAP does a two-way synchronization.  That is, if you
 make a change to the mail on the server, it will be propogated to your
 local copy, and vise-versa.  Some people might think that it would be
 wise to just delete all their local mail folders periodically.  If you
 do this with OfflineIMAP, remember to also remove your local status
 cache (~/.offlineimap by default).  Otherwise, OfflineIMAP will take
 this as an intentional deletion of many messages and will interpret
 your action as requesting them to be deleted from the server as well.
 (If you don't understand this, don't worry; you probably won't
 encounter this situation)
 --------------------------------------------------
 Q. What's thie Mailbox name recorder (mbnames) thing all about?
 A. The Mutt mail reader is not capable of automatically determining
 the names of your mailboxes.  OfflineIMAP can help it (or many other)
 programs out be writing these names out in a format you specify.  See
 the example offlineimap.conf file for details.
 --------------------------------------------------
 Q. Can I synchronize multiple accounts with OfflineIMAP?
 A. Sure.  Just name them all in the accounts line in the general
 section of the config file, and add a per-account section for each one.
 --------------------------------------------------
 Q. Do you support POP?
 A. No.  POP is not robust enough to do a completely reliable
 multi-machine synchronization like OfflineIMAP can do.  OfflineIMAP
 will not support it.
 --------------------------------------------------
 Q. Do you support mailbox formats other than Maildir?
 A. Not at present.  There is no technical reason not to; just no
 demand yet.  Maildir is a superior format anyway.
 --------------------------------------------------
 Q. [technical] Why are your Maildir message filenames so huge?
 A. OfflineIMAP has two relevant principles: 1) never modifying your
 messages in any way and 2) ensuring 100% reliable synchronizations.
 In order to do a reliable sync, OfflineIMAP must have a way to
 uniquely identify each e-mail.  Three pieces of information are
 required to do this: your account name, the folder name, and the
 message UID.  The account name can be calculated from the path in
 which your messages are.  The folder name can usually be as well, BUT
 some mail clients move messages between folders by simply moving the
 file, leaving the name intact.
 So, OfflineIMAP must store both a UID folder ID.  The folder ID is
 necessary so OfflineIMAP can detect a message moved to a different
 folder.  OfflineIMAP stores the UID (U= number) and an md5sum of the
 foldername (FMD5= number) to facilitate this.
 --------------------------------------------------
 Q. Can you provide an example of using OfflineIMAP with Mutt and
 multiple accounts?
 A. Sure.  I set it up to have a single Mail directory with additional
 directories under that for each account.  So, mkdir ~/Mail.  Then, 
 in your ~/.offlineimaprc:
 Set "accounts = Personal, Work"
 Make sure you have a [Personal] and a [Work] section, with different
 pathnames.  Enable [mbnames].
 In each account section, do something like this:
 localfolders = ~/Mail/Personal
 or
 localfolders = ~/Mail/Work
 In Mutt:
 add lines like this to your ~/.muttrc:
 source ~/path-to-mbnames-muttrc-mailboxes
 folder-hook Personal set from="youremail@personal.com"
 folder-hook Work set from="youremail@work.com"
 set mbox_type=Maildir
 set folder=$HOME/Mail
 set spoolfile=+Personal/INBOX
 That's it!
 --------------------------------------------------
 Q. What about the speed of the sync?
 A. OfflineIMAP 2.0 contains a multithreaded system.  A good way to
 experiment is by setting maxsyncaccounts to 3 and maxconnections to 3
 in each account clause.
 This lets OfflineIMAP open up multiple connections simultaneously.
 That will let it process multiple folders and messages at once.  In
 most cases, this will increase performance of the sync.
 Don't set the number too high.  If you do that, things might actually
 slow down as your link gets saturated.  Also, too many connections can
 cause mail servers to have excessive load.  Administrators might take
 unkindly to this, and the server might bog down.  There are many
 variables in the optimal setting; experimentation may help.
 An informal benchmark yields these results for my setup:
 OfflineIMAP 2.0 sync with multitreading:  9 seconds
 OfflineIMAP 1.x sync w/o multithreading: 20 seconds
 GNUS sync:                                5 minutes
 MacOS X Mail.app "manual cache" method:  10 minutes
 OfflineIMAP's default configuration example does not have
 multithreading enabled.  You must configure it yourself to gain these
 performance benefits.  This decision was taken to provide a "works out
 of the box" experience.
--- a/head/manual.html
+++ b/head/manual.html
@ -0,0 +1,960 @@
 <html>
 <head>
 <meta name="generator" content="groff -Thtml, see www.gnu.org">
 <meta name="Content-Style" content="text/css">
 <title>OFFLINEIMAP</title>
 </head>
 <body>
 <h1 align=center>OFFLINEIMAP</h1>
 <a href="#NAME">NAME</a><br>
 <a href="#SYNOPSIS">SYNOPSIS</a><br>
 <a href="#DESCRIPTION">DESCRIPTION</a><br>
 <a href="#INSTALLATION">INSTALLATION</a><br>
 <a href="#CONFIGURATION">CONFIGURATION</a><br>
 <a href="#OPTIONS">OPTIONS</a><br>
 <a href="#EXAMPLES">EXAMPLES</a><br>
 <a href="#ERRORS">ERRORS</a><br>
 <a href="#OTHER FREQUENTLY ASKED QUESTIONS">OTHER FREQUENTLY ASKED QUESTIONS</a><br>
 <a href="#CONFORMING TO">CONFORMING TO</a><br>
 <a href="#NOTES">NOTES</a><br>
 <a href="#BUGS">BUGS</a><br>
 <a href="#COPYRIGHT">COPYRIGHT</a><br>
 <a href="#AUTHOR">AUTHOR</a><br>
 <a href="#SEE ALSO">SEE ALSO</a><br>
 <hr>
 <!-- Creator     : groff version 1.17.2 -->
 <!-- CreationDate: Thu Jul 11 15:42:24 2002 -->
 <a name="NAME"></a>
 <h2>NAME</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 OfflineIMAP - Powerful IMAP/Maildir synchronization and reader support</td></table>
 <a name="SYNOPSIS"></a>
 <h2>SYNOPSIS</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>offlineimap</b> [ <b>-1</b> ] [ <b>-a</b>
 <i>accountlist</i> ] [ <b>-c</b> <i>configfile</i> ]<br>
 [ <b>-d</b> ] [ <b>-u</b> <i>interface</i> ]</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>offlineimap -h</b> | <b>--help</b></td></table>
 <a name="DESCRIPTION"></a>
 <h2>DESCRIPTION</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>OfflineIMAP</b> is a tool to simplify your e-mail
 reading. With <b>OfflineIMAP,</b> you can read the same
 mailbox from multiple computers. You get a current copy of
 your messages on each computer, and changes you make one
 place will be visible on all other systems. For instance,
 you can delete a message on your home computer, and it will
 appear deleted on your work computer as well.
 <b>OfflineIMAP</b> is also useful if you want to use a mail
 reader that does not have IMAP support, has poor IMAP
 support, or does not provide disconnected
 operation.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>OfflineIMAP</b> is <i>FAST;</i> it synchronizes my two
 accounts with over 50 folders in 3 seconds. Other similar
 tools might take over a minute, and achieve a less-reliable
 result. Some mail readers can take over 10 minutes to do the
 same thing, and some don't even support it at all. Unlike
 other mail tools, <b>OfflineIMAP</b> features a
 multi-threaded synchronization algorithm that can
 dramatically speed up performance in many situations by
 synchronizing several different things
 simultaneously.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>OfflineIMAP</b> is <i>FLEXIBLE;</i> you can customize
 which folders are synced via regular expressions, lists, or
 Python expressions; a versatile and comprehensive
 configuration file is used to control behavior; two user
 interfaces are built-in; fine-tuning of synchronization
 performance is possible; internal or external automation is
 supported; SSL and PREAUTH tunnels are both supported;
 offline (or &quot;unplugged&quot;) reading is supported; and
 esoteric IMAP features are supported to ensure compatibility
 with the widest variety of IMAP servers.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>OfflineIMAP</b> is <i>SAFE;</i> it uses an algorithm
 designed to prevent mail loss at all costs. Because of the
 design of this algorithm, even programming errors should not
 result in loss of mail. I am so confident in the algorithm
 that I use my own personal and work accounts for testing of
 <b>OfflineIMAP</b> pre-release, development, and beta
 releases.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="4%"></td><td width="96%">
 <b>METHOD OF OPERATION</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>OfflineIMAP</b> operates by maintaining a hierarchy of
 mail folders in Maildir format locally. Your own mail reader
 will read mail from this tree, and need never know that the
 mail comes from IMAP. <b>OfflineIMAP</b> will detect changes
 to the mail folders on your IMAP server and your own
 computer and bi-directionally synchronize them, copying,
 marking, and deleting messages as necessary.</td></table>
 <a name="INSTALLATION"></a>
 <h2>INSTALLATION</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 If you are reading this document via the &quot;man&quot;
 command, it is likely that you have no installation tasks to
 perform; your system administrator has already installed it.
 If you need to install it yourself, you have three options:
 a system-wide installation with Debian, system-wide
 installation with other systems, and a single-user
 installation. You can download the latest version of
 OfflineIMAP from
 http://quux.org/devel/offlineimap/.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="4%"></td><td width="96%">
 <b>PREREQUISITES</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 In order to use OfflineIMAP, you need to have these
 conditions satisfied:</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Your mail server must support IMAP. Most Internet Service
 Providers and corporate networks do, and most operating
 systems have an IMAP implementation readily
 available.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 You must have Python version 2.2.1 or above installed. If
 you are running on Debian GNU/Linux, this requirement will
 automatically be taken care of for you. If you do not have
 Python already, check with your system administrator or
 operating system vendor; or, download it from
 http://www.python.org/. If you intend to use the Tk
 interface, you must have Tkiner (python-tk) installed. If
 you intend to use the SSL interface, your Python must have
 been built with SSL support.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Have a mail reader that supports the Maildir mailbox format.
 Most modern mail readers have this support built-in, so you
 can choose from a wide variety of mail servers. This format
 is also known as the &quot;qmail&quot; format, so any mail
 reader compatible with it will work with
 OfflineIMAP.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="4%"></td><td width="96%">
 <b>DEBIAN SYSTEM-WIDE INSTALLATION</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 If you are tracking Debian unstable, you may install
 <b>OfflineIMAP</b> by simply running the following command
 as root:</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>apt-get install offlineimap</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 If you are not tracking Debian unstable, download the Debian
 .deb package from the OfflineIMAP website and then run
 <b>dpkg -i</b> to install the downloaded package. Then, go
 to CONFIGURATION below. You will type <b>offlineimap</b> to
 invoke the program.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="4%"></td><td width="96%">
 <b>OTHER SYSTEM-WIDE INSTALLATION</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Download the tar.gz version of the package from the website.
 Then run these commands:</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>tar -zxvf offlineimap-x.y.z.tar.gz<br>
 cd offlineimap-x.y.z<br>
 python2.2 setup.py</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Some systems will need to use <b>python</b> instead of
 <b>python2.2.</b> Next, proceed to configuration. You will
 type <b>offlineimap</b> to invoke the program.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="4%"></td><td width="96%">
 <b>SINGLE-ACCOUNT INSTALLATION</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Download the tar.gz version of the package from the website.
 Then run these commands:</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>tar -zxvf offlineimap-x.y.z.tar.gz<br>
 cd offlineimap-x.y.z</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 When you want to run <b>OfflineIMAP,</b> you will issue the
 <b>cd</b> command as above and then type
 <b>./offlineimap;</b> there is no installation step
 necessary.</td></table>
 <a name="CONFIGURATION"></a>
 <h2>CONFIGURATION</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>OfflineIMAP</b> is regulated by a configuration file that
 is normally stored in <i>~/.offlineimaprc.</i>
 <b>OfflineIMAP</b> ships with a file named
 <i>offlineimap.conf</i> that you should copy to that
 location and then edit. This file is vital to proper
 operation of the system; it sets everything you need to run
 <b>OfflineIMAP.</b> Full documentation for the configuration
 file is included within the sample file.</td></table>
 <a name="OPTIONS"></a>
 <h2>OPTIONS</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Most configuration is done via the configuration file.
 Nevertheless, there are a few options that you may set for
 <b>OfflineIMAP.</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>-1</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Disable all multithreading operations and use solely a
 single-thread sync. This effectively sets the
 <b>maxsyncaccounts</b> and all <b>maxconnections</b>
 configuration file variables to 1.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>-a</b> <i>accountlist</i></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Overrides the <b>accounts</b> section in the config file.
 Lets you specify a particular account or set of accounts to
 sync without having to edit the config file. You might use
 this to exclude certain accounts, or to sync some accounts
 that you normally prefer not to.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>-c</b> <i>configfile</i></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Specifies a configuration file to use in lieu of the
 default, <i>~/.offlineimaprc.</i></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>-d</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Enables IMAP protocol stream and parsing debugging. This is
 useful if you are trying to track down a malfunction or
 figure out what is going on under the hood. I suggest that
 you use this with <b>-1</b> in order to make the results
 more sensible. Note that this output will contain full IMAP
 protocol in plain text, including passwords, so take care to
 remove that from the debugging output before sending it to
 anyone else.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>-h, --help</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Show summary of options.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>-u</b> <i>interface</i></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Specifies an alternative user interface module to use. This
 overrides the default specified in the configuration file.
 The UI specified with <b>-u</b> will be forced to be used,
 even if its <b>isuable()</b> method states that it cannot
 be. Use this option with care.</td></table>
 <a name="EXAMPLES"></a>
 <h2>EXAMPLES</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Here is an example configuration for a particularly complex
 situation; more examples will be added later.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="4%"></td><td width="96%">
 <b>MULTIPLE ACCOUNTS WITH MUTT</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 This example shows you how to set up <b>OfflineIMAP</b> to
 synchronize multiple accounts with the mutt mail
 reader.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Start by creating a directory to hold your folders:<b><br>
 mkdir ~/Mail</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 In your <i>~/.offlineimaprc,</i> specify this:<b><br>
 accounts = Personal, Work</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Make sure that you have both a <b>[Personal]</b> and a
 <b>[Work]</b> section, with different localfolder pathnames
 and enable <b>[mbnames].</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 In each account section, do something like this:<b><br>
 localfolders = ~/Mail/Personal</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Add these lines to your <i>~/.muttrc:</i><b><br>
 source ~/path-to-mbnames-muttrc-mailboxes<br>
 folder-hook Personal set
 from=&quot;youremail@personal.com&quot;<br>
 folder-hook Work set from=&quot;youremail@work.com&quot;<br>
 set mbox_type=Maildir<br>
 set folder=$HOME/Mail<br>
 set spoolfile=+Personal/INBOX</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 That's it!</td></table>
 <a name="ERRORS"></a>
 <h2>ERRORS</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 If you get one of some frequently-encountered or confusing
 errors, please check this section.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="4%"></td><td width="96%">
 <b>UID validity problem for folder</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 IMAP servers use a unique ID (UID) to refer to a specific
 message. This number is guaranteed to be unique to a
 particular message FOREVER. No other message in the same
 folder will ever get the same UID. UIDs are an integral part
 of OfflineIMAP's synchronization scheme; they are used to
 match up messages on your computer to messages on the
 server.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Sometimes, the UIDs on the server might get reset. Usually
 this will happen if you delete and then recreate a folder.
 When you create a folder, the server will often start the
 UID back from 1. But <b>OfflineIMAP</b> might still have the
 UIDs from the previous folder by the same name stored.
 <b>OfflineIMAP</b> will detect this condition and skip the
 folder. This is GOOD, because it prevents data
 loss.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 You can fix it by removing your local folder and cache data.
 For instance, if your folders are under <i>~/Folders</i> and
 the folder with the problem is INBOX, you'd type
 this:</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>rm -r ~/Folders/INBOX<br>
 rm ~/.offlineimap/AccountName/INBOX</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 (replacing AccountName with the account name as specified in
 <i>~/.offlineimaprc)</i></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Next time you run <b>OfflineIMAP,</b> it will re-download
 the folder with the new UIDs. Note that the procedure
 specified above will lose any local changes made to the
 folder.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Some IMAP servers are broken and do not support UIDs
 properly. If you continue to get this error for all your
 folders even after performing the above procedure, it is
 likely that your IMAP server falls into this category.
 <b>OfflineIMAP</b> is incompatible with such servers. Using
 <b>OfflineIMAP</b> with them will not destroy any mail, but
 at the same time, it will not actually synchronize it
 either. (OfflineIMAP will detect this condition and abort
 prior to synchronization)</td></table>
 <a name="OTHER FREQUENTLY ASKED QUESTIONS"></a>
 <h2>OTHER FREQUENTLY ASKED QUESTIONS</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 There are some other FAQs that might not fit into another
 section of this document, and they are enumerated
 here.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>What platforms does OfflineIMAP run on?</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 It should run on most platforms supported by Python, which
 are quite a few.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>I'm using Mutt. Other IMAP sync programs require me to
 use set maildir_trash=yes . Do I need to do that with
 OfflineIMAP?</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 No. <b>OfflineIMAP</b> is smart enough to figure out message
 deletion without this extra crutch. You'll get the best
 results if you don't use this setting, in fact.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>How do I specify the names of my
 folders?</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 You do not need to. <b>OfflineIMAP</b> is smart enough to
 automatically figure out what folders are present on the
 IMAP server and synchronize them. You can use the
 <b>folderfilter</b> and <b>foldertrans</b> configuration
 file options to request certain folders and rename them as
 they come in if you like.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>How can I prevent certain folders from being
 synced?</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Use the <b>folderfilter</b> option in the configuration
 file.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>How can I add or delete a folder?</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 <b>OfflineIMAP</b> does not currently provide this feature,
 but if you create a new folder on the IMAP server, it will
 be created locally automatically.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>Are there any other warnings that I should be aware
 of?</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Yes; see the NOTES section below.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>What is the mailbox name recorder (mbnames)
 for?</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 The Mutt mail reader is not capable of automatically
 determining the names of your mailboxes. OfflineIMAP can
 help it (or many other) programs out be writing these names
 out in a format you specify. See the example
 offlineimap.conf file for details.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>Can I synchronize multiple accounts with
 OfflineIMAP?</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Sure. Just name them all in the accounts line in the general
 section of the config file, and add a per-account section
 for each one.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>Does OfflineIMAP support POP?</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 No. POP is not robust enough to do a completely reliable
 multi-machine synchronization like OfflineIMAP can do.
 OfflineIMAP will not support it.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>Do you support mailbox formats other than
 Maildir?</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Not at present. There is no technical reason not to; just no
 demand yet. Maildir is a superior format
 anyway.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>[technical] Why are your Maildir message filenames so
 huge?</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 <b>OfflineIMAP</b> has two relevant principles: 1) never
 modifying your messages in any way and 2) ensuring 100%
 reliable synchronizations. In order to do a reliable sync,
 <b>OfflineIMAP</b> must have a way to uniquely identify each
 e-mail. Three pieces of information are required to do this:
 your account name, the folder name, and the message UID. The
 account name can be calculated from the path in which your
 messages are. The folder name can usually be as well, BUT
 some mail clients move messages between folders by simply
 moving the file, leaving the name intact.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 So, <b>OfflineIMAP</b> must store both a UID folder ID. The
 folder ID is necessary so <b>OfflineIMAP</b> can detect a
 message moved to a different folder. <b>OfflineIMAP</b>
 stores the UID (U= number) and an md5sum of the foldername
 (FMD5= number) to facilitate this.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>What is the speed of OfflineIMAP's sync?</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 <b>OfflineIMAP</b> versions 2.0 and above contain a
 multithreaded system. A good way to experiment is by setting
 maxsyncaccounts to 3 and maxconnections to 3 in each account
 clause.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 This lets OfflineIMAP open up multiple connections
 simultaneously. That will let it process multiple folders
 and messages at once. In most cases, this will increase
 performance of the sync.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Don't set the number too high. If you do that, things might
 actually slow down as your link gets saturated. Also, too
 many connections can cause mail servers to have excessive
 load. Administrators might take unkindly to this, and the
 server might bog down. There are many variables in the
 optimal setting; experimentation may help.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 An informal benchmark yields these results for my
 setup:</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 10 minutes with MacOS X Mail.app &quot;manual
 cache&quot;<br>
 5 minutes with GNUS agent sync<br>
 20 seconds with OfflineIMAP 1.x<br>
 9 seconds with OfflineIMAP 2.x<br>
 3 seconds with OfflineIMAP 3.x &quot;cold start&quot;<br>
 2 seconds with OfflineIMAP 3.x &quot;held
 connection&quot;</td></table>
 <a name="CONFORMING TO"></a>
 <h2>CONFORMING TO</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Internet Message Access Protocol version 4rev1 (IMAP 4rev1)
 as specified in RFC2060</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Maildir as specified in
 http://www.qmail.org/qmail-manual-html/man5/maildir.html and
 http://cr.yp.to/proto/maildir.html.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="21%"></td><td width="79%">
 Standard Python 2.2.1 as implemented on POSIX-compliant
 systems.</td></table>
 <a name="NOTES"></a>
 <h2>NOTES</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="4%"></td><td width="96%">
 <b>DELETING LOCAL FOLDERS</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>OfflineIMAP</b> does a two-way synchronization. That is,
 if you make a change to the mail on the server, it will be
 propogated to your local copy, and vise-versa. Some people
 might think that it would be wise to just delete all their
 local mail folders periodically. If you do this with
 OfflineIMAP, remember to also remove your local status cache
 (~/.offlineimap by default). Otherwise, OfflineIMAP will
 take this as an intentional deletion of many messages and
 will interpret your action as requesting them to be deleted
 from the server as well. (If you don't understand this,
 don't worry; you probably won't encounter this
 situation)</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="4%"></td><td width="96%">
 <b>MAILING LIST</b></td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 There is an OfflineIMAP mailing list available.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 To subscribe, send the text &quot;Subscribe&quot; in the
 subject of a mail to offlineimap-request@complete.org. To
 post, send the message to
 offlineimap@complete.org.</td></table>
 <a name="BUGS"></a>
 <h2>BUGS</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Should be reported to the author at the address specified
 below.</td></table>
 <a name="COPYRIGHT"></a>
 <h2>COPYRIGHT</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 OfflineIMAP is Copyright (C) 2002 John Goerzen.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 This program is free software; you can redistribute it
 and/or modify it under the terms of the GNU General Public
 License as published by the Free Software Foundation; either
 version 2 of the License, or (at your option) any later
 version.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 This program is distributed in the hope that it will be
 useful, but WITHOUT ANY WARRANTY; without even the implied
 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 PURPOSE. See the GNU General Public License for more
 details.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 You should have received a copy of the GNU General Public
 License along with this program; if not, write
 to:</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 Free Software Foundation, Inc.<br>
 59 Temple Place<br>
 Suite 330<br>
 Boston, MA 02111-1307<br>
 USA</td></table>
 <a name="AUTHOR"></a>
 <h2>AUTHOR</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>OfflineIMAP,</b> its libraries, documentation, and all
 included files, except where noted, was written by John
 Goerzen &lt;jgoerzen@complete.org&gt; and copyright is held
 as stated in the COPYRIGHT section.</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 OfflineIMAP may be downloaded, and information found, from
 its homepage via either Gopher or HTTP:</td></table>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 gopher://quux.org/1/devel/offlineimap<br>
 http://quux.org/devel/offlineimap</td></table>
 <a name="SEE ALSO"></a>
 <h2>SEE ALSO</h2>
 <table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">
 <td width="10%"></td><td width="90%">
 <b>mutt</b>(1), <b>python</b>(1).</td></table>
 <hr>
 </body>
 </html>
--- a/head/manual.pdf
+++ b/head/manual.pdf
--- a/head/manual.ps
+++ b/head/manual.ps
@ -0,0 +1,704 @@
 %!PS-Adobe-3.0
 %%Creator: groff version 1.17.2
 %%CreationDate: Thu Jul 11 15:42:22 2002
 %%DocumentNeededResources: font Times-Roman
 %%+ font Times-Bold
 %%+ font Times-Italic
 %%DocumentSuppliedResources: procset grops 1.17 2
 %%Pages: 6
 %%PageOrder: Ascend
 %%Orientation: Portrait
 %%EndComments
 %%BeginProlog
 %%BeginResource: procset grops 1.17 2
 /setpacking where{
 pop
 currentpacking
 true setpacking
 }if
 /grops 120 dict dup begin
 /SC 32 def
 /A/show load def
 /B{0 SC 3 -1 roll widthshow}bind def
 /C{0 exch ashow}bind def
 /D{0 exch 0 SC 5 2 roll awidthshow}bind def
 /E{0 rmoveto show}bind def
 /F{0 rmoveto 0 SC 3 -1 roll widthshow}bind def
 /G{0 rmoveto 0 exch ashow}bind def
 /H{0 rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def
 /I{0 exch rmoveto show}bind def
 /J{0 exch rmoveto 0 SC 3 -1 roll widthshow}bind def
 /K{0 exch rmoveto 0 exch ashow}bind def
 /L{0 exch rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def
 /M{rmoveto show}bind def
 /N{rmoveto 0 SC 3 -1 roll widthshow}bind def
 /O{rmoveto 0 exch ashow}bind def
 /P{rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def
 /Q{moveto show}bind def
 /R{moveto 0 SC 3 -1 roll widthshow}bind def
 /S{moveto 0 exch ashow}bind def
 /T{moveto 0 exch 0 SC 5 2 roll awidthshow}bind def
 /SF{
 findfont exch
 [exch dup 0 exch 0 exch neg 0 0]makefont
 dup setfont
 [exch/setfont cvx]cvx bind def
 }bind def
 /MF{
 findfont
 [5 2 roll
 0 3 1 roll
 neg 0 0]makefont
 dup setfont
 [exch/setfont cvx]cvx bind def
 }bind def
 /level0 0 def
 /RES 0 def
 /PL 0 def
 /LS 0 def
 /MANUAL{
 statusdict begin/manualfeed true store end
 }bind def
 /PLG{
 gsave newpath clippath pathbbox grestore
 exch pop add exch pop
 }bind def
 /BP{
 /level0 save def
 1 setlinecap
 1 setlinejoin
 72 RES div dup scale
 LS{
 90 rotate
 }{
 0 PL translate
 }ifelse
 1 -1 scale
 }bind def
 /EP{
 level0 restore
 showpage
 }bind def
 /DA{
 newpath arcn stroke
 }bind def
 /SN{
 transform
 .25 sub exch .25 sub exch
 round .25 add exch round .25 add exch
 itransform
 }bind def
 /DL{
 SN
 moveto
 SN
 lineto stroke
 }bind def
 /DC{
 newpath 0 360 arc closepath
 }bind def
 /TM matrix def
 /DE{
 TM currentmatrix pop
 translate scale newpath 0 0 .5 0 360 arc closepath
 TM setmatrix
 }bind def
 /RC/rcurveto load def
 /RL/rlineto load def
 /ST/stroke load def
 /MT/moveto load def
 /CL/closepath load def
 /FL{
 currentgray exch setgray fill setgray
 }bind def
 /BL/fill load def
 /LW/setlinewidth load def
 /RE{
 findfont
 dup maxlength 1 index/FontName known not{1 add}if dict begin
 {
 1 index/FID ne{def}{pop pop}ifelse
 }forall
 /Encoding exch def
 dup/FontName exch def
 currentdict end definefont pop
 }bind def
 /DEFS 0 def
 /EBEGIN{
 moveto
 DEFS begin
 }bind def
 /EEND/end load def
 /CNT 0 def
 /level1 0 def
 /PBEGIN{
 /level1 save def
 translate
 div 3 1 roll div exch scale
 neg exch neg exch translate
 0 setgray
 0 setlinecap
 1 setlinewidth
 0 setlinejoin
 10 setmiterlimit
 []0 setdash
 /setstrokeadjust where{
 pop
 false setstrokeadjust
 }if
 /setoverprint where{
 pop
 false setoverprint
 }if
 newpath
 /CNT countdictstack def
 userdict begin
 /showpage{}def
 }bind def
 /PEND{
 clear
 countdictstack CNT sub{end}repeat
 level1 restore
 }bind def
 end def
 /setpacking where{
 pop
 setpacking
 }if
 %%EndResource
 %%IncludeResource: font Times-Roman
 %%IncludeResource: font Times-Bold
 %%IncludeResource: font Times-Italic
 grops begin/DEFS 1 dict def DEFS begin/u{.001 mul}bind def end/RES 72
 def/PL 792 def/LS false def/ENC0[/asciicircum/asciitilde/Scaron/Zcaron
 /scaron/zcaron/Ydieresis/trademark/quotesingle/.notdef/.notdef/.notdef
 /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef
 /.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef
 /.notdef/.notdef/space/exclam/quotedbl/numbersign/dollar/percent
 /ampersand/quoteright/parenleft/parenright/asterisk/plus/comma/hyphen
 /period/slash/zero/one/two/three/four/five/six/seven/eight/nine/colon
 /semicolon/less/equal/greater/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N/O
 /P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash/bracketright/circumflex
 /underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y
 /z/braceleft/bar/braceright/tilde/.notdef/quotesinglbase/guillemotleft
 /guillemotright/bullet/florin/fraction/perthousand/dagger/daggerdbl
 /endash/emdash/ff/fi/fl/ffi/ffl/dotlessi/dotlessj/grave/hungarumlaut
 /dotaccent/breve/caron/ring/ogonek/quotedblleft/quotedblright/oe/lslash
 /quotedblbase/OE/Lslash/.notdef/exclamdown/cent/sterling/currency/yen
 /brokenbar/section/dieresis/copyright/ordfeminine/guilsinglleft
 /logicalnot/minus/registered/macron/degree/plusminus/twosuperior
 /threesuperior/acute/mu/paragraph/periodcentered/cedilla/onesuperior
 /ordmasculine/guilsinglright/onequarter/onehalf/threequarters
 /questiondown/Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE
 /Ccedilla/Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex
 /Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis
 /multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute/Thorn
 /germandbls/agrave/aacute/acircumflex/atilde/adieresis/aring/ae/ccedilla
 /egrave/eacute/ecircumflex/edieresis/igrave/iacute/icircumflex/idieresis
 /eth/ntilde/ograve/oacute/ocircumflex/otilde/odieresis/divide/oslash
 /ugrave/uacute/ucircumflex/udieresis/yacute/thorn/ydieresis]def
 /Times-Italic@0 ENC0/Times-Italic RE/Times-Bold@0 ENC0/Times-Bold RE
 /Times-Roman@0 ENC0/Times-Roman RE
 %%EndProlog
 %%Page: 1 1
 %%BeginPageSetup
 BP
 %%EndPageSetup
 /F0 10/Times-Roman@0 SF 111.22(OFFLINEIMAP\(1\) Of)72 48 R
 (\215ineIMAP manual)-.25 E(OFFLINEIMAP\(1\))113.72 E/F1 10.95
 /Times-Bold@0 SF -.219(NA)72 84 S(ME).219 E F0(Of)108 96 Q
 (\215ineIMAP \255 Po)-.25 E
 (werful IMAP/Maildir synchronization and reader support)-.25 E F1
 (SYNOPSIS)72 112.8 Q/F2 10/Times-Bold@0 SF(of\215ineimap)108 124.8 Q F0
 ([)2.5 E F2<ad31>2.5 E F0 2.5(][)2.5 G F2<ad61>A/F3 10/Times-Italic@0 SF
 (accountlist)2.5 E F0 2.5(][)2.5 G F2<ad63>A F3(con\214g\214le)2.5 E F0
 (])2.5 E([)108 136.8 Q F2<ad64>2.5 E F0 2.5(][)2.5 G F2<ad75>A F3
 (interface)2.5 E F0(])2.5 E F2(of\215ineimap \255h)108 160.8 Q F0(|)2.5
 E F2(\255\255help)2.5 E F1(DESCRIPTION)72 177.6 Q F2(Of\215ineIMAP)108
 189.6 Q F0 .019(is a tool to simplify your e-mail reading.)2.519 F -.4
 (Wi)5.019 G(th).4 E F2(Of\215ineIMAP)2.519 E(,)-.92 E F0 .018
 (you can read the same mailbox)2.519 F 1.115(from multiple computers.)
 108 201.6 R -1.1(Yo)6.115 G 3.615(ug)1.1 G 1.115(et a current cop)-3.615
 F 3.616(yo)-.1 G 3.616(fy)-3.616 G 1.116(our messages on each computer)
 -3.616 F 3.616(,a)-.4 G 1.116(nd changes you)-3.616 F(mak)108 213.6 Q
 2.915(eo)-.1 G .414(ne place will be visible on all other systems.)
 -2.915 F -.15(Fo)5.414 G 2.914(ri).15 G .414
 (nstance, you can delete a message on your home)-2.914 F(computer)108
 225.6 Q 3.5(,a)-.4 G 1(nd it will appear deleted on your w)-3.5 F 1
 (ork computer as well.)-.1 F F2(Of\215ineIMAP)6 E F0 1
 (is also useful if you)3.5 F -.1(wa)108 237.6 S .827
 (nt to use a mail reader that does not ha).1 F 1.127 -.15(ve I)-.2 H
 .827(MAP support, has poor IMAP support, or does not pro).15 F(vide)-.15
 E(disconnected operation.)108 249.6 Q F2(Of\215ineIMAP)108 266.4 Q F0
 (is)3.216 E F3 -1.15(FA)3.216 G(ST)1.15 E(;)-.65 E F0 .716
 (it synchronizes my tw)3.216 F 3.216(oa)-.1 G .716(ccounts with o)-3.216
 F -.15(ve)-.15 G 3.216(r5).15 G 3.216(0f)-3.216 G .717
 (olders in 3 seconds.)-3.216 F .717(Other similar)5.717 F .26
 (tools might tak)108 278.4 R 2.76(eo)-.1 G -.15(ve)-2.91 G 2.76(ram).15
 G .26(inute, and achie)-2.76 F .56 -.15(ve a l)-.25 H .259
 (ess-reliable result.).15 F .259(Some mail readers can tak)5.259 F 2.759
 (eo)-.1 G -.15(ve)-2.909 G 2.759(r1).15 G 2.759(0m)-2.759 G(in-)-2.759 E
 .157(utes to do the same thing, and some don')108 290.4 R 2.657(te)-.18
 G -.15(ve)-2.907 G 2.657(ns).15 G .157(upport it at all.)-2.657 F(Unlik)
 5.158 E 2.658(eo)-.1 G .158(ther mail tools,)-2.658 F F2(Of\215ineIMAP)
 2.658 E F0(fea-)2.658 E .321(tures a multi-threaded synchronization alg\
 orithm that can dramatically speed up performance in man)108 302.4 R
 2.82(ys)-.15 G(itu-)-2.82 E(ations by synchronizing se)108 314.4 Q -.15
 (ve)-.25 G(ral dif).15 E(ferent things simultaneously)-.25 E(.)-.65 E F2
 (Of\215ineIMAP)108 331.2 Q F0(is)3.065 E F3(FLEXIBLE;)3.065 E F0 .566
 (you can customize which folders are synced via re)3.065 F .566(gular e)
 -.15 F .566(xpressions, lists, or)-.15 F .734(Python e)108 343.2 R .734
 (xpressions; a v)-.15 F .734(ersatile and comprehensi)-.15 F 1.034 -.15
 (ve c)-.25 H .733(on\214guration \214le is used to control beha).15 F
 .733(vior; tw)-.2 F 3.233(ou)-.1 G(ser)-3.233 E(interf)108 355.2 Q .535
 (aces are b)-.1 F .535(uilt-in; \214ne-tuning of synchronization perfor\
 mance is possible; internal or e)-.2 F .535(xternal automa-)-.15 F .441
 (tion is supported; SSL and PREA)108 367.2 R .441
 (UTH tunnels are both supported; of)-.55 F .44
 (\215ine \(or "unplugged"\) reading is sup-)-.25 F .543(ported; and eso\
 teric IMAP features are supported to ensure compatibility with the wide\
 st v)108 379.2 R .544(ariety of IMAP)-.25 F(serv)108 391.2 Q(ers.)-.15 E
 F2(Of\215ineIMAP)108 408 Q F0(is)4.065 E F3(SAFE;)4.065 E F0 1.565
 (it uses an algorithm designed to pre)4.065 F -.15(ve)-.25 G 1.565
 (nt mail loss at all costs.).15 F 1.564(Because of the)6.564 F .01
 (design of this algorithm, e)108 420 R -.15(ve)-.25 G 2.51(np).15 G .01
 (rogramming errors should not result in loss of mail.)-2.51 F 2.511(Ia)
 5.011 G 2.511(ms)-2.511 G 2.511(oc)-2.511 G .011(on\214dent in the)
 -2.511 F .448(algorithm that I use my o)108 432 R .448
 (wn personal and w)-.25 F .448(ork accounts for testing of)-.1 F F2
 (Of\215ineIMAP)2.948 E F0 .448(pre-release, de)2.948 F -.15(ve)-.25 G
 (lop-).15 E(ment, and beta releases.)108 444 Q F2(METHOD OF OPERA)87
 460.8 Q(TION)-.95 E(Of\215ineIMAP)108 472.8 Q F0 .07
 (operates by maintaining a hierarch)2.57 F 2.57(yo)-.05 G 2.57(fm)-2.57
 G .07(ail folders in Maildir format locally)-2.57 F 5.07(.Y)-.65 G .07
 (our o)-6.17 F .07(wn mail)-.25 F .618
 (reader will read mail from this tree, and need ne)108 484.8 R -.15(ve)
 -.25 G 3.118(rk).15 G(no)-3.118 E 3.118(wt)-.25 G .617
 (hat the mail comes from IMAP)-3.118 F(.)-1.11 E F2(Of\215ineIMAP)5.617
 E F0 .849(will detect changes to the mail folders on your IMAP serv)108
 496.8 R .849(er and your o)-.15 F .849(wn computer and bi-directionally)
 -.25 F(synchronize them, cop)108 508.8 Q
 (ying, marking, and deleting messages as necessary)-.1 E(.)-.65 E F1
 (INST)72 525.6 Q(ALLA)-.986 E(TION)-1.04 E F0 .491
 (If you are reading this document via the "man" command, it is lik)108
 537.6 R .49(ely that you ha)-.1 F .79 -.15(ve n)-.2 H 2.99(oi).15 G .49
 (nstallation tasks to)-2.99 F .043
 (perform; your system administrator has already installed it.)108 549.6
 R .044(If you need to install it yourself, you ha)5.043 F .344 -.15
 (ve t)-.2 H(hree).15 E .39(options: a system-wide installation with Deb\
 ian, system-wide installation with other systems, and a single-)108
 561.6 R 12.823(user installation.)108 573.6 R -1.1(Yo)17.823 G 15.323
 (uc)1.1 G 12.823(an do)-15.323 F 12.823(wnload the latest v)-.25 F
 12.823(ersion of Of)-.15 F 12.823(\215ineIMAP from)-.25 F
 (http://quux.or)108 585.6 Q(g/de)-.18 E -.15(ve)-.25 G(l/of).15 E
 (\215ineimap/.)-.25 E F2(PREREQ)87 602.4 Q(UISITES)-.1 E F0
 (In order to use Of)108 614.4 Q(\215ineIMAP)-.25 E 2.5(,y)-1.11 G
 (ou need to ha)-2.5 E .3 -.15(ve t)-.2 H(hese conditions satis\214ed:)
 .15 E 32.5<8359>108 631.2 S .197(our mail serv)-33.6 F .197
 (er must support IMAP)-.15 F 5.197(.M)-1.11 G .197
 (ost Internet Service Pro)-5.197 F .197(viders and corporate netw)-.15 F
 .196(orks do,)-.1 F(and most operating systems ha)144 643.2 Q .3 -.15
 (ve a)-.2 H 2.5(nI).15 G(MAP implementation readily a)-2.5 E -.25(va)-.2
 G(ilable.).25 E 32.5<8359>108 660 S .085(ou must ha)-33.6 F .385 -.15
 (ve P)-.2 H .085(ython v).15 F .085(ersion 2.2.1 or abo)-.15 F .385 -.15
 (ve i)-.15 H 2.585(nstalled. If).15 F .086
 (you are running on Debian GNU/Linux,)2.585 F .813
 (this requirement will automatically be tak)144 672 R .813
 (en care of for you.)-.1 F .812(If you do not ha)5.812 F 1.112 -.15
 (ve P)-.2 H .812(ython already).15 F(,)-.65 E 3.88
 (check with your system administrator or operating system v)144 684 R
 3.88(endor; or)-.15 F 6.38(,d)-.4 G -.25(ow)-6.38 G 3.88(nload it from)
 .25 F(http://www)144 696 Q(.p)-.65 E(ython.or)-.1 E 3.378(g/. If)-.18 F
 .878(you intend to use the Tk interf)3.378 F .877(ace, you must ha)-.1 F
 1.177 -.15(ve T)-.2 H .877(kiner \(p).15 F(ython-tk\))-.1 E 2.859
 (installed. If)144 708 R .359(you intend to use the SSL interf)2.859 F
 .359(ace, your Python must ha)-.1 F .66 -.15(ve b)-.2 H .36(een b).15 F
 .36(uilt with SSL sup-)-.2 F(port.)144 720 Q(John Goerzen)72 768 Q
 (July 11, 2002)151.655 E(1)201.915 E EP
 %%Page: 2 2
 %%BeginPageSetup
 BP
 %%EndPageSetup
 /F0 10/Times-Roman@0 SF 111.22(OFFLINEIMAP\(1\) Of)72 48 R
 (\215ineIMAP manual)-.25 E(OFFLINEIMAP\(1\))113.72 E 32.5<8348>108 84 S
 -2.25 -.2(av e)-32.5 H 2.784(am)2.984 G .284
 (ail reader that supports the Maildir mailbox format.)-2.784 F .284
 (Most modern mail readers ha)5.284 F .584 -.15(ve t)-.2 H(his).15 E .111
 (support b)144 96 R .112(uilt-in, so you can choose from a wide v)-.2 F
 .112(ariety of mail serv)-.25 F 2.612(ers. This)-.15 F .112
 (format is also kno)2.612 F(wn)-.25 E(as the "qmail" format, so an)144
 108 Q 2.5(ym)-.15 G(ail reader compatible with it will w)-2.5 E
 (ork with Of)-.1 E(\215ineIMAP)-.25 E(.)-1.11 E/F1 10/Times-Bold@0 SF
 (DEBIAN SYSTEM-WIDE INST)87 124.8 Q(ALLA)-.9 E(TION)-.95 E F0 .708
 (If you are tracking Debian unstable, you may install)108 136.8 R F1
 (Of\215ineIMAP)3.208 E F0 .708(by simply running the follo)3.208 F .708
 (wing com-)-.25 F(mand as root:)108 148.8 Q F1
 (apt-get install of\215ineimap)108 165.6 Q F0 .339
 (If you are not tracking Debian unstable, do)108 182.4 R .34
 (wnload the Debian .deb package from the Of)-.25 F .34
 (\215ineIMAP website)-.25 F .39(and then run)108 194.4 R F1 .39(dpkg -i)
 2.89 F F0 .389(to install the do)2.89 F .389(wnloaded package.)-.25 F
 .389(Then, go to CONFIGURA)5.389 F .389(TION belo)-1.11 F 4.189 -.65
 (w. Y)-.25 H .389(ou will)-.45 F(type)108 206.4 Q F1(of\215ineimap)2.5 E
 F0(to in)2.5 E -.2(vo)-.4 G .2 -.1(ke t).2 H(he program.).1 E F1 -.4(OT)
 87 223.2 S(HER SYSTEM-WIDE INST).4 E(ALLA)-.9 E(TION)-.95 E F0(Do)108
 235.2 Q(wnload the tar)-.25 E(.gz v)-.55 E
 (ersion of the package from the website.)-.15 E
 (Then run these commands:)5 E F1(tar -zxvf of\215ineimap-x.y)108 252 Q
 (.z.tar)-.7 E(.gz)-1 E(cd of\215ineimap-x.y)108 264 Q(.z)-.7 E
 (python2.2 setup.py)108 276 Q F0 1.272(Some systems will need to use)108
 292.8 R F1(python)3.773 E F0 1.273(instead of)3.773 F F1(python2.2.)
 3.773 E F0(Ne)6.273 E 1.273(xt, proceed to con\214guration.)-.15 F -1.1
 (Yo)6.273 G 3.773(uw)1.1 G(ill)-3.773 E(type)108 304.8 Q F1
 (of\215ineimap)2.5 E F0(to in)2.5 E -.2(vo)-.4 G .2 -.1(ke t).2 H
 (he program.).1 E F1(SINGLE-A)87 321.6 Q(CCOUNT INST)-.55 E(ALLA)-.9 E
 (TION)-.95 E F0(Do)108 333.6 Q(wnload the tar)-.25 E(.gz v)-.55 E
 (ersion of the package from the website.)-.15 E
 (Then run these commands:)5 E F1(tar -zxvf of\215ineimap-x.y)108 350.4 Q
 (.z.tar)-.7 E(.gz)-1 E(cd of\215ineimap-x.y)108 362.4 Q(.z)-.7 E F0 .149
 (When you w)108 379.2 R .149(ant to run)-.1 F F1(Of\215ineIMAP)2.648 E
 (,)-.92 E F0 .148(you will issue the)2.648 F F1(cd)2.648 E F0 .148
 (command as abo)2.648 F .448 -.15(ve a)-.15 H .148(nd then type).15 F F1
 (./of\215ineimap;)2.648 E F0(there is no installation step necessary)108
 391.2 Q(.)-.65 E/F2 10.95/Times-Bold@0 SF(CONFIGURA)72 408 Q(TION)-1.04
 E F1(Of\215ineIMAP)108 420 Q F0 .508(is re)3.008 F .508
 (gulated by a con\214guration \214le that is normally stored in)-.15 F
 /F3 10/Times-Italic@0 SF(~/.of)3.009 E(\215ineimapr)-.18 E(c.)-.37 E F1
 (Of\215ineIMAP)5.509 E F0 .004(ships with a \214le named)108 432 R F3
 (of)2.503 E(\215ineimap.conf)-.18 E F0 .003(that you should cop)2.503 F
 2.503(yt)-.1 G 2.503(ot)-2.503 G .003(hat location and then edit.)-2.503
 F .003(This \214le is vital)5.003 F .255
 (to proper operation of the system; it sets e)108 444 R -.15(ve)-.25 G
 .256(rything you need to run).15 F F1(Of\215ineIMAP)2.756 E(.)-1.1 E F0
 .256(Full documentation for)5.256 F
 (the con\214guration \214le is included within the sample \214le.)108
 456 Q F2(OPTIONS)72 472.8 Q F0 .061
 (Most con\214guration is done via the con\214guration \214le.)108 484.8
 R(Ne)5.061 E -.15(ve)-.25 G .061(rtheless, there are a fe).15 F 2.561
 (wo)-.25 G .061(ptions that you may set)-2.561 F(for)108 496.8 Q F1
 (Of\215ineIMAP)2.5 E(.)-1.1 E<ad31>108 513.6 Q F0 .281(Disable all mult\
 ithreading operations and use solely a single-thread sync.)25.3 F .281
 (This ef)5.281 F(fecti)-.25 E -.15(ve)-.25 G .281(ly sets the).15 F F1
 (maxsyncaccounts)144 525.6 Q F0(and all)2.5 E F1(maxconnections)2.5 E F0
 (con\214guration \214le v)2.5 E(ariables to 1.)-.25 E F1<ad61>108 542.4
 Q F3(accountlist)2.5 E F0(Ov)144 554.4 Q .84(errides the)-.15 F F1
 (accounts)3.34 E F0 .84(section in the con\214g \214le.)3.34 F .84
 (Lets you specify a particular account or set of)5.84 F 1.647
 (accounts to sync without ha)144 566.4 R 1.647
 (ving to edit the con\214g \214le.)-.2 F -1.1(Yo)6.648 G 4.148(um)1.1 G
 1.648(ight use this to e)-4.148 F 1.648(xclude certain)-.15 F
 (accounts, or to sync some accounts that you normally prefer not to.)144
 578.4 Q F1<ad63>108 595.2 Q F3(con\214g\214le)2.5 E F0
 (Speci\214es a con\214guration \214le to use in lieu of the def)144
 607.2 Q(ault,)-.1 E F3(~/.of)2.5 E(\215ineimapr)-.18 E(c.)-.37 E F1
 <ad64>108 624 Q F0 1.139(Enables IMAP protocol stream and parsing deb)
 24.74 F 3.639(ugging. This)-.2 F 1.138
 (is useful if you are trying to track)3.639 F(do)144 636 Q .081
 (wn a malfunction or \214gure out what is going on under the hood.)-.25
 F 2.582(Is)5.082 G .082(uggest that you use this with)-2.582 F F1<ad31>
 144 648 Q F0 .336(in order to mak)2.836 F 2.836(et)-.1 G .335
 (he results more sensible.)-2.836 F .335
 (Note that this output will contain full IMAP proto-)5.335 F 1.7
 (col in plain te)144 660 R 1.7(xt, including passw)-.15 F 1.7
 (ords, so tak)-.1 F 4.2(ec)-.1 G 1.7(are to remo)-4.2 F 2 -.15(ve t)-.15
 H 1.7(hat from the deb).15 F 1.7(ugging output)-.2 F
 (before sending it to an)144 672 Q(yone else.)-.15 E F1
 (\255h, \255\255help)108 688.8 Q F0(Sho)144 700.8 Q 2.5(ws)-.25 G
 (ummary of options.)-2.5 E(John Goerzen)72 768 Q(July 11, 2002)151.655 E
 (2)201.915 E EP
 %%Page: 3 3
 %%BeginPageSetup
 BP
 %%EndPageSetup
 /F0 10/Times-Roman@0 SF 111.22(OFFLINEIMAP\(1\) Of)72 48 R
 (\215ineIMAP manual)-.25 E(OFFLINEIMAP\(1\))113.72 E/F1 10/Times-Bold@0
 SF<ad75>108 84 Q/F2 10/Times-Italic@0 SF(interface)2.5 E F0 1.133
 (Speci\214es an alternati)144 96 R 1.433 -.15(ve u)-.25 H 1.133
 (ser interf).15 F 1.133(ace module to use.)-.1 F 1.133(This o)6.133 F
 -.15(ve)-.15 G 1.133(rrides the def).15 F 1.132(ault speci\214ed in the)
 -.1 F .28(con\214guration \214le.)144 108 R .28(The UI speci\214ed with)
 5.28 F F1(-u)2.78 E F0 .281(will be forced to be used, e)2.78 F -.15(ve)
 -.25 G 2.781(ni).15 G 2.781(fi)-2.781 G(ts)-2.781 E F1(isuable\(\))2.781
 E F0(method)2.781 E(states that it cannot be.)144 120 Q
 (Use this option with care.)5 E/F3 10.95/Times-Bold@0 SF(EXAMPLES)72
 136.8 Q F0(Here is an e)108 148.8 Q
 (xample con\214guration for a particularly comple)-.15 E 2.5(xs)-.15 G
 (ituation; more e)-2.5 E(xamples will be added later)-.15 E(.)-.55 E F1
 (MUL)87 165.6 Q(TIPLE A)-.92 E(CCOUNTS WITH MUTT)-.55 E F0 .514(This e)
 108 177.6 R .514(xample sho)-.15 F .514(ws you ho)-.25 F 3.014(wt)-.25 G
 3.014(os)-3.014 G .514(et up)-3.014 F F1(Of\215ineIMAP)3.014 E F0 .513
 (to synchronize multiple accounts with the mutt mail)3.014 F(reader)108
 189.6 Q(.)-.55 E(Start by creating a directory to hold your folders:)108
 206.4 Q F1(mkdir ~/Mail)108 218.4 Q F0(In your)108 235.2 Q F2(~/.of)2.5
 E(\215ineimapr)-.18 E(c,)-.37 E F0(specify this:)2.5 E F1(accounts = P)
 108 247.2 Q(ersonal, W)-.2 E(ork)-.75 E F0(Mak)108 264 Q 2.82(es)-.1 G
 .32(ure that you ha)-2.82 F .62 -.15(ve b)-.2 H .32(oth a).15 F F1([P)
 2.821 E(ersonal])-.2 E F0 .321(and a)2.821 F F1([W)2.821 E(ork])-.75 E
 F0 .321(section, with dif)2.821 F .321(ferent localfolder pathnames and)
 -.25 F(enable)108 276 Q F1([mbnames].)2.5 E F0
 (In each account section, do something lik)108 292.8 Q 2.5(et)-.1 G
 (his:)-2.5 E F1(localf)108 304.8 Q(olders = ~/Mail/P)-.25 E(ersonal)-.2
 E F0(Add these lines to your)108 321.6 Q F2(~/.muttr)2.5 E(c:)-.37 E F1
 (sour)108 333.6 Q(ce ~/path-to-mbnames-muttr)-.18 E(c-mailboxes)-.18 E
 -.25(fo)108 345.6 S(lder).25 E(-hook P)-.37 E(ersonal set fr)-.2 E
 (om="y)-.18 E(our)-.25 E(email@personal.com")-.18 E -.25(fo)108 357.6 S
 (lder).25 E(-hook W)-.37 E(ork set fr)-.75 E(om="y)-.18 E(our)-.25 E
 (email@w)-.18 E(ork.com")-.1 E(set mbox_type=Maildir)108 369.6 Q(set f)
 108 381.6 Q(older=$HOME/Mail)-.25 E(set spool\214le=+P)108 393.6 Q
 (ersonal/INBO)-.2 E(X)-.4 E F0(That')108 410.4 Q 2.5(si)-.55 G(t!)-2.5 E
 F3(ERR)72 427.2 Q(ORS)-.329 E F0(If you get one of some frequently-enco\
 untered or confusing errors, please check this section.)108 439.2 Q F1
 (UID v)87 456 Q(alidity pr)-.1 E(oblem f)-.18 E(or f)-.25 E(older)-.25 E
 F0 1.638(IMAP serv)108 468 R 1.637
 (ers use a unique ID \(UID\) to refer to a speci\214c message.)-.15 F
 1.637(This number is guaranteed to be)6.637 F 1.109
 (unique to a particular message FOREVER.)108 480 R 1.109
 (No other message in the same folder will e)6.109 F -.15(ve)-.25 G 3.61
 (rg).15 G 1.11(et the same)-3.61 F 2.874(UID. UIDs)108 492 R .373
 (are an inte)2.874 F .373(gral part of Of)-.15 F(\215ineIMAP')-.25 E
 2.873(ss)-.55 G .373(ynchronization scheme; the)-2.873 F 2.873(ya)-.15 G
 .373(re used to match up mes-)-2.873 F
 (sages on your computer to messages on the serv)108 504 Q(er)-.15 E(.)
 -.55 E .107(Sometimes, the UIDs on the serv)108 520.8 R .108
 (er might get reset.)-.15 F .108
 (Usually this will happen if you delete and then recreate)5.108 F 3.743
 (af)108 532.8 S(older)-3.743 E 6.243(.W)-.55 G 1.243
 (hen you create a folder)-6.243 F 3.742(,t)-.4 G 1.242(he serv)-3.742 F
 1.242(er will often start the UID back from 1.)-.15 F(But)6.242 E F1
 (Of\215ineIMAP)3.742 E F0 .302(might still ha)108 544.8 R .602 -.15
 (ve t)-.2 H .302(he UIDs from the pre).15 F .302
 (vious folder by the same name stored.)-.25 F F1(Of\215ineIMAP)5.303 E
 F0 .303(will detect this)2.803 F(condition and skip the folder)108 556.8
 Q 5(.T)-.55 G(his is GOOD, because it pre)-5 E -.15(ve)-.25 G
 (nts data loss.).15 E -1.1(Yo)108 573.6 S 2.827(uc)1.1 G .327
 (an \214x it by remo)-2.827 F .327
 (ving your local folder and cache data.)-.15 F -.15(Fo)5.327 G 2.827(ri)
 .15 G .327(nstance, if your folders are under)-2.827 F F2(~/F)2.826 E
 (old-)-1.05 E(er)108 585.6 Q(s)-.1 E F0
 (and the folder with the problem is INBO)2.5 E(X, you')-.4 E 2.5(dt)-.5
 G(ype this:)-2.5 E F1(rm -r ~/F)108 602.4 Q(olders/INBO)-.25 E(X)-.4 E
 (rm ~/.of\215ineimap/AccountName/INBO)108 614.4 Q(X)-.4 E F0
 (\(replacing AccountName with the account name as speci\214ed in)108
 631.2 Q F2(~/.of)2.5 E(\215ineimapr)-.18 E(c\))-.37 E F0(Ne)108 648 Q
 .801(xt time you run)-.15 F F1(Of\215ineIMAP)3.301 E(,)-.92 E F0 .802
 (it will re-do)3.302 F .802(wnload the folder with the ne)-.25 F 3.302
 (wU)-.25 G 3.302(IDs. Note)-3.302 F .802(that the proce-)3.302 F
 (dure speci\214ed abo)108 660 Q .3 -.15(ve w)-.15 H(ill lose an).15 E
 2.5(yl)-.15 G(ocal changes made to the folder)-2.5 E(.)-.55 E .523
 (Some IMAP serv)108 676.8 R .522(ers are brok)-.15 F .522
 (en and do not support UIDs properly)-.1 F 5.522(.I)-.65 G 3.022(fy)
 -5.522 G .522(ou continue to get this error for all)-3.022 F .066
 (your folders e)108 688.8 R -.15(ve)-.25 G 2.566(na).15 G .066
 (fter performing the abo)-2.566 F .366 -.15(ve p)-.15 H .066
 (rocedure, it is lik).15 F .066(ely that your IMAP serv)-.1 F .066(er f)
 -.15 F .067(alls into this cat-)-.1 F -.15(eg)108 700.8 S(ory).15 E(.)
 -.65 E F1(Of\215ineIMAP)5.984 E F0 .984(is incompatible with such serv)
 3.484 F 3.484(ers. Using)-.15 F F1(Of\215ineIMAP)3.484 E F0 .984
 (with them will not destro)3.484 F(y)-.1 E(an)108 712.8 Q 2.769(ym)-.15
 G .269(ail, b)-2.769 F .269
 (ut at the same time, it will not actually synchronize it either)-.2 F
 5.27(.\()-.55 G(Of)-5.27 E .27(\215ineIMAP will detect this con-)-.25 F
 (dition and abort prior to synchronization\))108 724.8 Q(John Goerzen)72
 768 Q(July 11, 2002)151.655 E(3)201.915 E EP
 %%Page: 4 4
 %%BeginPageSetup
 BP
 %%EndPageSetup
 /F0 10/Times-Roman@0 SF 111.22(OFFLINEIMAP\(1\) Of)72 48 R
 (\215ineIMAP manual)-.25 E(OFFLINEIMAP\(1\))113.72 E/F1 10.95
 /Times-Bold@0 SF -.438(OT)72 84 S(HER FREQ).438 E(UENTL)-.11 E 2.738(YA)
 -1.007 G(SKED Q)-2.738 E(UESTIONS)-.11 E F0 .684(There are some other F)
 108 96 R -.55(AQ)-.74 G 3.184(st).55 G .684
 (hat might not \214t into another section of this document, and the)
 -3.184 F 3.183(ya)-.15 G .683(re enumer)-3.183 F(-)-.2 E(ated here.)108
 108 Q/F2 10/Times-Bold@0 SF(What platf)108 124.8 Q
 (orms does Of\215ineIMAP run on?)-.25 E F0(It should run on most platfo\
 rms supported by Python, which are quite a fe)144 136.8 Q -.65(w.)-.25 G
 F2 .688(I'm using Mutt. Other IMAP sync pr)108 153.6 R .689(ograms r)
 -.18 F(equir)-.18 E 3.189(em)-.18 G 3.189(et)-3.189 G 3.189(ou)-3.189 G
 .689(se set maildir_trash=y)-3.189 F .689(es . Do I need to)-.1 F
 (do that with Of\215ineIMAP?)108 165.6 Q F0(No.)144 177.6 Q F2
 (Of\215ineIMAP)7.27 E F0 2.27
 (is smart enough to \214gure out message deletion without this e)4.77 F
 2.27(xtra crutch.)-.15 F -1.1(Yo)144 189.6 S(u')1.1 E
 (ll get the best results if you don')-.1 E 2.5(tu)-.18 G
 (se this setting, in f)-2.5 E(act.)-.1 E F2(Ho)108 206.4 Q 2.5(wd)-.1 G
 2.5(oIs)-2.5 G(pecify the names of my f)-2.5 E(olders?)-.25 E F0 -1.1
 (Yo)144 218.4 S 3.55(ud)1.1 G 3.55(on)-3.55 G 1.05(ot need to.)-3.55 F
 F2(Of\215ineIMAP)6.05 E F0 1.05
 (is smart enough to automatically \214gure out what folders are)3.55 F
 .678(present on the IMAP serv)144 230.4 R .678(er and synchronize them.)
 -.15 F -1.1(Yo)5.679 G 3.179(uc)1.1 G .679(an use the)-3.179 F F2 -.25
 (fo)3.179 G(lder\214lter).25 E F0(and)3.179 E F2 -.25(fo)3.179 G
 (ldertrans).25 E F0(con\214guration \214le options to request certain f\
 olders and rename them as the)144 242.4 Q 2.5(yc)-.15 G
 (ome in if you lik)-2.5 E(e.)-.1 E F2(Ho)108 259.2 Q 2.5(wc)-.1 G
 (an I pr)-2.5 E -2.3 -.15(ev e)-.18 H(nt certain f).15 E(olders fr)-.25
 E(om being synced?)-.18 E F0(Use the)144 271.2 Q F2 -.25(fo)2.5 G
 (lder\214lter).25 E F0(option in the con\214guration \214le.)2.5 E F2
 (Ho)108 288 Q 2.5(wc)-.1 G(an I add or delete a f)-2.5 E(older?)-.25 E
 (Of\215ineIMAP)144 300 Q F0 .504(does not currently pro)3.004 F .504
 (vide this feature, b)-.15 F .504(ut if you create a ne)-.2 F 3.003(wf)
 -.25 G .503(older on the IMAP)-3.003 F(serv)144 312 Q(er)-.15 E 2.5(,i)
 -.4 G 2.5(tw)-2.5 G(ill be created locally automatically)-2.5 E(.)-.65 E
 F2(Ar)108 328.8 Q 2.5(et)-.18 G(her)-2.5 E 2.5(ea)-.18 G(ny other war)
 -2.5 E(nings that I should be awar)-.15 E 2.5(eo)-.18 G(f?)-2.5 E F0 -1
 (Ye)144 340.8 S(s; see the NO)1 E(TES section belo)-.4 E -.65(w.)-.25 G
 F2(What is the mailbox name r)108 357.6 Q(ecorder \(mbnames\) f)-.18 E
 (or?)-.25 E F0 1.019(The Mutt mail reader is not capable of automatical\
 ly determining the names of your mailbox)144 369.6 R(es.)-.15 E(Of)144
 381.6 Q .266(\215ineIMAP can help it \(or man)-.25 F 2.765(yo)-.15 G
 .265(ther\) programs out be writing these names out in a format you)
 -2.765 F(specify)144 393.6 Q 5(.S)-.65 G(ee the e)-5 E(xample of)-.15 E
 (\215ineimap.conf \214le for details.)-.25 E F2(Can I synchr)108 410.4 Q
 (onize multiple accounts with Of\215ineIMAP?)-.18 E F0 3.344(Sure. Just)
 144 422.4 R .845(name them all in the accounts line in the general sect\
 ion of the con\214g \214le, and add a)3.344 F(per)144 434.4 Q
 (-account section for each one.)-.2 E F2
 (Does Of\215ineIMAP support POP?)108 451.2 Q F0 4.077(No. POP)144 463.2
 R 1.576(is not rob)4.077 F 1.576(ust enough to do a completely reliable\
 multi-machine synchronization lik)-.2 F(e)-.1 E(Of)144 475.2 Q
 (\215ineIMAP can do.)-.25 E(Of)5 E(\215ineIMAP will not support it.)-.25
 E F2(Do y)108 492 Q(ou support mailbox f)-.25 E
 (ormats other than Maildir?)-.25 E F0 .409(Not at present.)144 504 R
 .409(There is no technical reason not to; just no demand yet.)5.409 F
 .41(Maildir is a superior for)5.41 F(-)-.2 E(mat an)144 516 Q(yw)-.15 E
 (ay)-.1 E(.)-.65 E F2([technical] Wh)108 532.8 Q 2.5(ya)-.15 G .36 -.18
 (re y)-2.5 H(our Maildir message \214lenames so huge?)-.07 E
 (Of\215ineIMAP)144 544.8 Q F0 .959(has tw)3.459 F 3.459(or)-.1 G(ele)
 -3.459 E -.25(va)-.25 G .959(nt principles: 1\) ne).25 F -.15(ve)-.25 G
 3.459(rm).15 G .958(odifying your messages in an)-3.459 F 3.458(yw)-.15
 G .958(ay and 2\))-3.558 F .493
 (ensuring 100% reliable synchronizations.)144 556.8 R .493
 (In order to do a reliable sync,)5.493 F F2(Of\215ineIMAP)2.993 E F0
 .494(must ha)2.993 F -.15(ve)-.2 G 3.095(aw)144 568.8 S .595
 (ay to uniquely identify each e-mail.)-3.195 F .594
 (Three pieces of information are required to do this: your)5.594 F .537
 (account name, the folder name, and the message UID.)144 580.8 R .538
 (The account name can be calculated from)5.537 F 1.082
 (the path in which your messages are.)144 592.8 R 1.082
 (The folder name can usually be as well, B)6.082 F 1.081(UT some mail)
 -.1 F(clients mo)144 604.8 Q .3 -.15(ve m)-.15 H
 (essages between folders by simply mo).15 E(ving the \214le, lea)-.15 E
 (ving the name intact.)-.2 E(So,)144 621.6 Q F2(Of\215ineIMAP)3.2 E F0
 .7(must store both a UID folder ID.)3.2 F .7
 (The folder ID is necessary so)5.7 F F2(Of\215ineIMAP)3.2 E F0 .456
 (can detect a message mo)144 633.6 R -.15(ve)-.15 G 2.956(dt).15 G 2.955
 (oad)-2.956 G(if)-2.955 E .455(ferent folder)-.25 F(.)-.55 E F2
 (Of\215ineIMAP)5.455 E F0 .455(stores the UID \(U= number\) and)2.955 F
 (an md5sum of the foldername \(FMD5= number\) to f)144 645.6 Q
 (acilitate this.)-.1 E F2(What is the speed of Of\215ineIMAP')108 662.4
 Q 2.5(ss)-.37 G(ync?)-2.5 E(Of\215ineIMAP)144 674.4 Q F0 -.15(ve)2.89 G
 .39(rsions 2.0 and abo).15 F .691 -.15(ve c)-.15 H .391
 (ontain a multithreaded system.).15 F 2.891(Ag)5.391 G .391(ood w)-2.891
 F .391(ay to e)-.1 F(xperiment)-.15 E(is by setting maxsyncaccounts to \
 3 and maxconnections to 3 in each account clause.)144 686.4 Q .382
 (This lets Of)144 703.2 R .382
 (\215ineIMAP open up multiple connections simultaneously)-.25 F 5.381
 (.T)-.65 G .381(hat will let it process mul-)-5.381 F
 (tiple folders and messages at once.)144 715.2 Q
 (In most cases, this will increase performance of the sync.)5 E
 (John Goerzen)72 768 Q(July 11, 2002)151.655 E(4)201.915 E EP
 %%Page: 5 5
 %%BeginPageSetup
 BP
 %%EndPageSetup
 /F0 10/Times-Roman@0 SF 111.22(OFFLINEIMAP\(1\) Of)72 48 R
 (\215ineIMAP manual)-.25 E(OFFLINEIMAP\(1\))113.72 E(Don')144 84 Q 3.103
 (ts)-.18 G .603(et the number too high.)-3.103 F .603
 (If you do that, things might actually slo)5.603 F 3.104(wd)-.25 G -.25
 (ow)-3.104 G 3.104(na).25 G 3.104(sy)-3.104 G .604(our link gets)-3.104
 F 2.633(saturated. Also,)144 96 R .133(too man)2.633 F 2.633(yc)-.15 G
 .132(onnections can cause mail serv)-2.633 F .132(ers to ha)-.15 F .432
 -.15(ve ex)-.2 H(cessi).15 E .432 -.15(ve l)-.25 H 2.632
 (oad. Administra-).15 F .506(tors might tak)144 108 R 3.006(eu)-.1 G
 .506(nkindly to this, and the serv)-3.006 F .507(er might bog do)-.15 F
 3.007(wn. There)-.25 F .507(are man)3.007 F 3.007(yv)-.15 G .507
 (ariables in the)-3.257 F(optimal setting; e)144 120 Q
 (xperimentation may help.)-.15 E
 (An informal benchmark yields these results for my setup:)144 136.8 Q
 (10 minutes with MacOS X Mail.app "manual cache")144 153.6 Q 2.5(5m)144
 165.6 S(inutes with GNUS agent sync)-2.5 E(20 seconds with Of)144 177.6
 Q(\215ineIMAP 1.x)-.25 E 2.5(9s)144 189.6 S(econds with Of)-2.5 E
 (\215ineIMAP 2.x)-.25 E 2.5(3s)144 201.6 S(econds with Of)-2.5 E
 (\215ineIMAP 3.x "cold start")-.25 E 2.5(2s)144 213.6 S(econds with Of)
 -2.5 E(\215ineIMAP 3.x "held connection")-.25 E/F1 10.95/Times-Bold@0 SF
 (CONFORMING T)72 230.4 Q(O)-.197 E F0 32.5<8349>108 242.4 S
 (nternet Message Access Protocol v)-32.5 E(ersion 4re)-.15 E
 (v1 \(IMAP 4re)-.25 E(v1\) as speci\214ed in RFC2060)-.25 E 32.5<834d>
 108 259.2 S 8.92(aildir as speci\214ed in http://www)-32.5 F(.qmail.or)
 -.65 E(g/qmail-manual-html/man5/maildir)-.18 E 8.92(.html and)-.55 F
 (http://cr)144 271.2 Q(.yp.to/proto/maildir)-.55 E(.html.)-.55 E 32.5
 <8353>108 288 S
 (tandard Python 2.2.1 as implemented on POSIX-compliant systems.)-32.5 E
 F1(NO)72 304.8 Q(TES)-.438 E/F2 10/Times-Bold@0 SF
 (DELETING LOCAL FOLDERS)87 316.8 Q(Of\215ineIMAP)108 328.8 Q F0 .532
 (does a tw)3.032 F(o-w)-.1 E .532(ay synchronization.)-.1 F .532
 (That is, if you mak)5.532 F 3.032(eac)-.1 G .532
 (hange to the mail on the serv)-3.032 F(er)-.15 E 3.033(,i)-.4 G(t)
 -3.033 E .897(will be propog)108 340.8 R .897(ated to your local cop)
 -.05 F 2.197 -.65(y, a)-.1 H .897(nd vise-v).65 F 3.397(ersa. Some)-.15
 F .896(people might think that it w)3.397 F .896(ould be wise to)-.1 F
 1.59(just delete all their local mail folders periodically)108 352.8 R
 6.59(.I)-.65 G 4.09(fy)-6.59 G 1.59(ou do this with Of)-4.09 F
 (\215ineIMAP)-.25 E 4.09(,r)-1.11 G 1.59(emember to also)-4.09 F(remo)
 108 364.8 Q 1.67 -.15(ve y)-.15 H 1.37(our local status cache \(~/.of)
 .15 F 1.37(\215ineimap by def)-.25 F 3.87(ault\). Otherwise,)-.1 F(Of)
 3.87 E 1.37(\215ineIMAP will tak)-.25 F 3.87(et)-.1 G 1.37(his as an)
 -3.87 F .415(intentional deletion of man)108 376.8 R 2.915(ym)-.15 G
 .416(essages and will interpret your action as requesting them to be de\
 leted from)-2.915 F(the serv)108 388.8 Q(er as well.)-.15 E
 (\(If you don')5 E 2.5(tu)-.18 G(nderstand this, don')-2.5 E 2.5(tw)-.18
 G(orry; you probably w)-2.6 E(on')-.1 E 2.5(te)-.18 G
 (ncounter this situation\))-2.5 E F2(MAILING LIST)87 405.6 Q F0
 (There is an Of)108 417.6 Q(\215ineIMAP mailing list a)-.25 E -.25(va)
 -.2 G(ilable.).25 E 2.448 -.8(To s)108 434.4 T .847
 (ubscribe, send the te).8 F .847
 (xt "Subscribe" in the subject of a mail to of)-.15 F
 (\215ineimap-request@complete.or)-.25 E 3.347(g. T)-.18 F(o)-.8 E
 (post, send the message to of)108 446.4 Q(\215ineimap@complete.or)-.25 E
 (g.)-.18 E F1 -.11(BU)72 463.2 S(GS).11 E F0
 (Should be reported to the author at the address speci\214ed belo)108
 475.2 Q -.65(w.)-.25 G F1(COPYRIGHT)72 492 Q F0(Of)108 504 Q
 (\215ineIMAP is Cop)-.25 E(yright \(C\) 2002 John Goerzen.)-.1 E .286
 (This program is free softw)108 520.8 R .286(are; you can redistrib)-.1
 F .287(ute it and/or modify it under the terms of the GNU General)-.2 F
 .766(Public License as published by the Free Softw)108 532.8 R .766
 (are F)-.1 F .766(oundation; either v)-.15 F .766
 (ersion 2 of the License, or \(at your)-.15 F(option\) an)108 544.8 Q
 2.5(yl)-.15 G(ater v)-2.5 E(ersion.)-.15 E .579(This program is distrib)
 108 561.6 R .579(uted in the hope that it will be useful, b)-.2 F .58
 (ut WITHOUT ANY W)-.2 F(ARRANTY)-1.2 E 3.08(;w)-.92 G(ithout)-3.08 E
 -2.15 -.25(ev e)108 573.6 T 2.73(nt).25 G .23(he implied w)-2.73 F .229
 (arranty of MERCHANT)-.1 F .229(ABILITY or FITNESS FOR A P)-.93 F(AR)
 -.92 E .229(TICULAR PURPOSE.)-.6 F(See)5.229 E
 (the GNU General Public License for more details.)108 585.6 Q -1.1(Yo)
 108 602.4 S 2.77(us)1.1 G .27(hould ha)-2.77 F .57 -.15(ve r)-.2 H(ecei)
 .15 E -.15(ve)-.25 G 2.77(dac).15 G(op)-2.77 E 2.77(yo)-.1 G 2.77(ft)
 -2.77 G .27
 (he GNU General Public License along with this program; if not, write)
 -2.77 F(to:)108 614.4 Q(Free Softw)108 631.2 Q(are F)-.1 E
 (oundation, Inc.)-.15 E(59 T)108 643.2 Q(emple Place)-.7 E(Suite 330)108
 655.2 Q(Boston, MA)108 667.2 Q(02111-1307)5 E(USA)108 679.2 Q F1 -.548
 (AU)72 696 S(THOR).548 E F2(Of\215ineIMAP)108 708 Q(,)-.92 E F0 .488
 (its libraries, documentation, and all included \214les, e)2.988 F .488
 (xcept where noted, w)-.15 F .487(as written by John)-.1 F
 (Goerzen <jgoerzen@complete.or)108 720 Q(g> and cop)-.18 E
 (yright is held as stated in the COPYRIGHT section.)-.1 E(John Goerzen)
 72 768 Q(July 11, 2002)151.655 E(5)201.915 E EP
 %%Page: 6 6
 %%BeginPageSetup
 BP
 %%EndPageSetup
 /F0 10/Times-Roman@0 SF 111.22(OFFLINEIMAP\(1\) Of)72 48 R
 (\215ineIMAP manual)-.25 E(OFFLINEIMAP\(1\))113.72 E(Of)108 84 Q
 (\215ineIMAP may be do)-.25 E(wnloaded, and information found, from its\
 homepage via either Gopher or HTTP:)-.25 E(gopher://quux.or)108 100.8 Q
 (g/1/de)-.18 E -.15(ve)-.25 G(l/of).15 E(\215ineimap)-.25 E
 (http://quux.or)108 112.8 Q(g/de)-.18 E -.15(ve)-.25 G(l/of).15 E
 (\215ineimap)-.25 E/F1 10.95/Times-Bold@0 SF(SEE ALSO)72 141.6 Q/F2 10
 /Times-Bold@0 SF(mutt)108 153.6 Q F0(\(1\),)A F2(python)2.5 E F0(\(1\).)
 A(John Goerzen)72 768 Q(July 11, 2002)151.655 E(6)201.915 E EP
 %%Trailer
 end
 %%EOF
--- a/head/manual.txt
+++ b/head/manual.txt
@ -0,0 +1,456 @@
 OFFLINEIMAP(1)          OfflineIMAP manual         OFFLINEIMAP(1)
 NAME
       OfflineIMAP  -  Powerful  IMAP/Maildir synchronization and
       reader support
 SYNOPSIS
       offlineimap [ -1 ] [ -a accountlist ] [ -c configfile ]
       [ -d ] [ -u interface ]
       offlineimap -h | --help
 DESCRIPTION
       OfflineIMAP is a tool to  simplify  your  e-mail  reading.
       With  OfflineIMAP, you can read the same mailbox from mul-
       tiple computers.  You get a current copy of your  messages
       on  each  computer, and changes you make one place will be
       visible on all  other  systems.   For  instance,  you  can
       delete a message on your home computer, and it will appear
       deleted on your work computer  as  well.   OfflineIMAP  is
       also useful if you want to use a mail reader that does not
       have IMAP support, has poor IMAP support, or does not pro-
       vide disconnected operation.
       OfflineIMAP  is FAST; it synchronizes my two accounts with
       over 50 folders in 3 seconds.  Other similar  tools  might
       take  over  a  minute, and achieve a less-reliable result.
       Some mail readers can take over 10 minutes to do the  same
       thing,  and  some  don't  even  support it at all.  Unlike
       other mail tools, OfflineIMAP  features  a  multi-threaded
       synchronization  algorithm  that can dramatically speed up
       performance in many situations  by  synchronizing  several
       different things simultaneously.
       OfflineIMAP  is  FLEXIBLE; you can customize which folders
       are synced  via  regular  expressions,  lists,  or  Python
       expressions;  a  versatile and comprehensive configuration
       file is used to control behavior; two user interfaces  are
       built-in;  fine-tuning  of  synchronization performance is
       possible; internal or external  automation  is  supported;
       SSL  and  PREAUTH  tunnels are both supported; offline (or
       "unplugged") reading is supported; and esoteric IMAP  fea-
       tures  are  supported  to  ensure  compatibility  with the
       widest variety of IMAP servers.
       OfflineIMAP is SAFE; it uses an algorithm designed to pre-
       vent  mail  loss  at  all costs.  Because of the design of
       this algorithm, even programming errors should not  result
       in  loss of mail.  I am so confident in the algorithm that
       I use my own personal and work  accounts  for  testing  of
       OfflineIMAP pre-release, development, and beta releases.
   METHOD OF OPERATION
       OfflineIMAP  operates  by  maintaining a hierarchy of mail
       folders in Maildir format locally.  Your own  mail  reader
       will  read  mail  from this tree, and need never know that
       the mail comes from IMAP.  OfflineIMAP will detect changes
       to  the mail folders on your IMAP server and your own com-
       puter  and  bi-directionally  synchronize  them,  copying,
       marking, and deleting messages as necessary.
 INSTALLATION
       If you are reading this document via the "man" command, it
       is likely that you have no installation tasks to  perform;
       your  system  administrator  has already installed it.  If
       you need to install it yourself, you have three options: a
       system-wide  installation with Debian, system-wide instal-
       lation with other systems, and a single-user installation.
       You  can  download  the latest version of OfflineIMAP from
       http://quux.org/devel/offlineimap/.
   PREREQUISITES
       In order to use OfflineIMAP, you need to have these condi-
       tions satisfied:
       o      Your  mail server must support IMAP.  Most Internet
              Service Providers and corporate  networks  do,  and
              most  operating systems have an IMAP implementation
              readily available.
       o      You  must  have  Python  version  2.2.1  or   above
              installed.  If you are running on Debian GNU/Linux,
              this requirement will automatically be  taken  care
              of  for  you.   If  you do not have Python already,
              check with your system administrator  or  operating
              system     vendor;    or,    download    it    from
              http://www.python.org/.  If you intend to  use  the
              Tk  interface,  you  must  have  Tkiner (python-tk)
              installed.  If you intend to use the SSL interface,
              your  Python must have been built with SSL support.
       o      Have a mail reader that supports the Maildir  mail-
              box  format.   Most  modern  mail readers have this
              support built-in, so you can  choose  from  a  wide
              variety of mail servers.  This format is also known
              as the "qmail" format, so any mail reader  compati-
              ble with it will work with OfflineIMAP.
   DEBIAN SYSTEM-WIDE INSTALLATION
       If  you  are  tracking  Debian  unstable,  you may install
       OfflineIMAP by simply running  the  following  command  as
       root:
       apt-get install offlineimap
       If  you  are  not  tracking  Debian unstable, download the
       Debian .deb package from the OfflineIMAP website and  then
       run  dpkg  -i to install the downloaded package.  Then, go
       to CONFIGURATION below.   You  will  type  offlineimap  to
       invoke the program.
   OTHER SYSTEM-WIDE INSTALLATION
       Download  the  tar.gz version of the package from the web-
       site.  Then run these commands:
       tar -zxvf offlineimap-x.y.z.tar.gz
       cd offlineimap-x.y.z
       python2.2 setup.py
       Some systems will need to use python instead of python2.2.
       Next, proceed to configuration.  You will type offlineimap
       to invoke the program.
   SINGLE-ACCOUNT INSTALLATION
       Download the tar.gz version of the package from  the  web-
       site.  Then run these commands:
       tar -zxvf offlineimap-x.y.z.tar.gz
       cd offlineimap-x.y.z
       When  you  want  to run OfflineIMAP, you will issue the cd
       command as above and then type ./offlineimap; there is  no
       installation step necessary.
 CONFIGURATION
       OfflineIMAP  is  regulated by a configuration file that is
       normally stored in  ~/.offlineimaprc.   OfflineIMAP  ships
       with a file named offlineimap.conf that you should copy to
       that location and then edit.  This file is vital to proper
       operation  of  the  system; it sets everything you need to
       run OfflineIMAP.  Full documentation for the configuration
       file is included within the sample file.
 OPTIONS
       Most  configuration  is  done  via the configuration file.
       Nevertheless, there are a few options that you may set for
       OfflineIMAP.
       -1     Disable   all  multithreading  operations  and  use
              solely a single-thread sync.  This effectively sets
              the maxsyncaccounts and all maxconnections configu-
              ration file variables to 1.
       -a accountlist
              Overrides the accounts section in the config  file.
              Lets  you  specify  a  particular account or set of
              accounts to sync without having to edit the  config
              file.   You  might  use  this  to  exclude  certain
              accounts, or to sync some accounts  that  you  nor-
              mally prefer not to.
       -c configfile
              Specifies  a  configuration  file to use in lieu of
              the default, ~/.offlineimaprc.
       -d     Enables IMAP protocol stream and parsing debugging.
              This  is  useful  if you are trying to track down a
              malfunction or figure out what is  going  on  under
              the  hood.   I suggest that you use this with -1 in
              order to make the results more sensible.  Note that
              this  output  will  contain  full  IMAP protocol in
              plain text, including passwords, so  take  care  to
              remove  that from the debugging output before send-
              ing it to anyone else.
       -h, --help
              Show summary of options.
       -u interface
              Specifies an alternative user interface  module  to
              use.   This  overrides the default specified in the
              configuration file.  The UI specified with -u  will
              be  forced to be used, even if its isuable() method
              states that it cannot be.   Use  this  option  with
              care.
 EXAMPLES
       Here  is  an example configuration for a particularly com-
       plex situation; more examples will be added later.
   MULTIPLE ACCOUNTS WITH MUTT
       This example shows you how to set up OfflineIMAP  to  syn-
       chronize multiple accounts with the mutt mail reader.
       Start by creating a directory to hold your folders:
       mkdir ~/Mail
       In your ~/.offlineimaprc, specify this:
       accounts = Personal, Work
       Make  sure  that  you  have both a [Personal] and a [Work]
       section, with different localfolder pathnames  and  enable
       [mbnames].
       In each account section, do something like this:
       localfolders = ~/Mail/Personal
       Add these lines to your ~/.muttrc:
       source ~/path-to-mbnames-muttrc-mailboxes
       folder-hook Personal set from="youremail@personal.com"
       folder-hook Work set from="youremail@work.com"
       set mbox_type=Maildir
       set folder=$HOME/Mail
       set spoolfile=+Personal/INBOX
       That's it!
 ERRORS
       If you get one of some frequently-encountered or confusing
       errors, please check this section.
   UID validity problem for folder
       IMAP servers use a unique ID (UID) to refer to a  specific
       message.  This number is guaranteed to be unique to a par-
       ticular message FOREVER.  No other  message  in  the  same
       folder  will  ever get the same UID.  UIDs are an integral
       part of OfflineIMAP's  synchronization  scheme;  they  are
       used  to match up messages on your computer to messages on
       the server.
       Sometimes, the UIDs on the server might get  reset.   Usu-
       ally  this  will  happen if you delete and then recreate a
       folder.  When you create a folder, the server  will  often
       start  the  UID  back from 1.  But OfflineIMAP might still
       have the UIDs from the previous folder by  the  same  name
       stored.   OfflineIMAP  will detect this condition and skip
       the folder.  This is GOOD, because it prevents data  loss.
       You  can  fix  it  by removing your local folder and cache
       data.  For instance, if your folders are  under  ~/Folders
       and the folder with the problem is INBOX, you'd type this:
       rm -r ~/Folders/INBOX
       rm ~/.offlineimap/AccountName/INBOX
       (replacing AccountName with the account name as  specified
       in ~/.offlineimaprc)
       Next  time  you  run  OfflineIMAP, it will re-download the
       folder with the new UIDs.  Note that the procedure  speci-
       fied above will lose any local changes made to the folder.
       Some IMAP servers are broken and do not support UIDs prop-
       erly.   If  you  continue  to  get this error for all your
       folders even after performing the above procedure,  it  is
       likely  that  your  IMAP  server falls into this category.
       OfflineIMAP is  incompatible  with  such  servers.   Using
       OfflineIMAP  with  them  will not destroy any mail, but at
       the same time, it will not actually synchronize it either.
       (OfflineIMAP will detect this condition and abort prior to
       synchronization)
 OTHER FREQUENTLY ASKED QUESTIONS
       There are some other FAQs that might not fit into  another
       section of this document, and they are enumerated here.
       What platforms does OfflineIMAP run on?
              It  should  run  on  most  platforms  supported  by
              Python, which are quite a few.
       I'm using Mutt. Other IMAP sync programs require me to use
       set  maildir_trash=yes  .  Do  I  need  to  do  that  with
       OfflineIMAP?
              No.  OfflineIMAP is smart enough to figure out mes-
              sage  deletion  without  this extra crutch.  You'll
              get the best results if you don't use this setting,
              in fact.
       How do I specify the names of my folders?
              You do not need to.  OfflineIMAP is smart enough to
              automatically figure out what folders  are  present
              on  the  IMAP server and synchronize them.  You can
              use the folderfilter and foldertrans  configuration
              file  options to request certain folders and rename
              them as they come in if you like.
       How can I prevent certain folders from being synced?
              Use the folderfilter option  in  the  configuration
              file.
       How can I add or delete a folder?
              OfflineIMAP  does  not  currently provide this fea-
              ture, but if you create a new folder  on  the  IMAP
              server, it will be created locally automatically.
       Are there any other warnings that I should be aware of?
              Yes; see the NOTES section below.
       What is the mailbox name recorder (mbnames) for?
              The  Mutt  mail  reader is not capable of automati-
              cally determining  the  names  of  your  mailboxes.
              OfflineIMAP  can  help  it (or many other) programs
              out be writing these names  out  in  a  format  you
              specify.  See the example offlineimap.conf file for
              details.
       Can I synchronize multiple accounts with OfflineIMAP?
              Sure.  Just name them all in the accounts  line  in
              the  general  section of the config file, and add a
              per-account section for each one.
       Does OfflineIMAP support POP?
              No.  POP is not robust enough to  do  a  completely
              reliable    multi-machine    synchronization   like
              OfflineIMAP can do.  OfflineIMAP will  not  support
              it.
       Do you support mailbox formats other than Maildir?
              Not  at  present.  There is no technical reason not
              to; just no demand yet.  Maildir is a superior for-
              mat anyway.
       [technical]  Why  are  your  Maildir  message filenames so
       huge?
              OfflineIMAP  has  two relevant principles: 1) never
              modifying your messages in any way and 2)  ensuring
              100%  reliable  synchronizations.  In order to do a
              reliable sync,  OfflineIMAP  must  have  a  way  to
              uniquely  identify  each  e-mail.   Three pieces of
              information are required to do this:  your  account
              name,  the  folder  name, and the message UID.  The
              account name can be calculated  from  the  path  in
              which  your messages are.  The folder name can usu-
              ally be as well, BUT some mail  clients  move  mes-
              sages  between  folders  by simply moving the file,
              leaving the name intact.
              So, OfflineIMAP must store both a  UID  folder  ID.
              The  folder  ID  is  necessary  so  OfflineIMAP can
              detect a  message  moved  to  a  different  folder.
              OfflineIMAP  stores  the  UID  (U=  number)  and an
              md5sum of the foldername (FMD5= number) to  facili-
              tate this.
       What is the speed of OfflineIMAP's sync?
              OfflineIMAP versions 2.0 and above contain a multi-
              threaded system.  A good way to  experiment  is  by
              setting  maxsyncaccounts to 3 and maxconnections to
              3 in each account clause.
              This lets OfflineIMAP open up multiple  connections
              simultaneously.   That will let it process multiple
              folders and messages at once.  In most cases,  this
              will increase performance of the sync.
              Don't  set  the  number  too high.  If you do that,
              things might actually slow down as your  link  gets
              saturated.   Also,  too  many connections can cause
              mail servers to have excessive  load.   Administra-
              tors  might  take  unkindly to this, and the server
              might bog down.  There are many  variables  in  the
              optimal setting; experimentation may help.
              An  informal  benchmark yields these results for my
              setup:
              10 minutes with MacOS X Mail.app "manual cache"
              5 minutes with GNUS agent sync
              20 seconds with OfflineIMAP 1.x
              9 seconds with OfflineIMAP 2.x
              3 seconds with OfflineIMAP 3.x "cold start"
              2 seconds with OfflineIMAP 3.x "held connection"
 CONFORMING TO
       o      Internet  Message  Access  Protocol  version  4rev1
              (IMAP 4rev1) as specified in RFC2060
       o      Maildir as specified in http://www.qmail.org/qmail-
              manual-html/man5/maildir.html                   and
              http://cr.yp.to/proto/maildir.html.
       o      Standard  Python 2.2.1 as implemented on POSIX-com-
              pliant systems.
 NOTES
   DELETING LOCAL FOLDERS
       OfflineIMAP does a two-way synchronization.  That  is,  if
       you  make  a  change to the mail on the server, it will be
       propogated to your local copy, and vise-versa.  Some  peo-
       ple  might  think that it would be wise to just delete all
       their local mail folders periodically.   If  you  do  this
       with  OfflineIMAP, remember to also remove your local sta-
       tus  cache  (~/.offlineimap   by   default).    Otherwise,
       OfflineIMAP  will  take this as an intentional deletion of
       many messages and will interpret your action as requesting
       them to be deleted from the server as well.  (If you don't
       understand this, don't worry; you probably won't encounter
       this situation)
   MAILING LIST
       There is an OfflineIMAP mailing list available.
       To  subscribe, send the text "Subscribe" in the subject of
       a mail to offlineimap-request@complete.org.  To post, send
       the message to offlineimap@complete.org.
 BUGS
       Should  be reported to the author at the address specified
       below.
 COPYRIGHT
       OfflineIMAP is Copyright (C) 2002 John Goerzen.
       This program is free software;  you  can  redistribute  it
       and/or modify it under the terms of the GNU General Public
       License as published  by  the  Free  Software  Foundation;
       either  version  2 of the License, or (at your option) any
       later version.
       This program is distributed in the hope that  it  will  be
       useful, but WITHOUT ANY WARRANTY; without even the implied
       warranty of MERCHANTABILITY or FITNESS  FOR  A  PARTICULAR
       PURPOSE.   See  the  GNU  General  Public License for more
       details.
       You should have received a copy of the GNU General  Public
       License along with this program; if not, write to:
       Free Software Foundation, Inc.
       59 Temple Place
       Suite 330
       Boston, MA  02111-1307
       USA
 AUTHOR
       OfflineIMAP,   its   libraries,   documentation,  and  all
       included files, except where noted, was  written  by  John
       Goerzen  <jgoerzen@complete.org>  and copyright is held as
       stated in the COPYRIGHT section.
       OfflineIMAP may be downloaded, and information found, from
       its homepage via either Gopher or HTTP:
       gopher://quux.org/1/devel/offlineimap
       http://quux.org/devel/offlineimap
 SEE ALSO
       mutt(1), python(1).
 John Goerzen              July 11, 2002            OFFLINEIMAP(1)
--- a/head/offlineimap.1
+++ b/head/offlineimap.1
@ -2,7 +2,7 @@
 .\" First parameter, NAME, should be all caps
 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
 .\" other parameters are allowed: see man(7), man(1)
-.TH OFFLINEIMAP 1 "July 11, 2002" "quux.org" "OfflineIMAP manual"
+.TH OFFLINEIMAP 1 "July 11, 2002" "John Goerzen" "OfflineIMAP manual"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
@ -16,31 +16,33 @@
 .\" .sp <n>    insert n+1 empty lines
 .\" for manpage-specific macros, see man(7)
 .SH NAME
-OfflineIMAP \- IMAP/Maildir synchronization and reader support
+OfflineIMAP \- Powerful IMAP/Maildir synchronization and reader support
 .SH SYNOPSIS
 .B offlineimap
 [
-.BI -1
+.BI \-1
 ]
 [
-.BI -a \ accountlist
+.BI \-a \ accountlist
 ]
 [
-.BI -c \ configfile
+.BI \-c \ configfile
 ]
 .br
 [
-.BI -d
+.BI \-d
 ]
 [
-.BI -u " interface"
+.BI \-u " interface"
 ]
 .\".RI [ -c \ foo ]
 .\".RI [ options ] " files" ...
 .br
 .B offlineimap
-.B -h
+.B \-h 
 |
 .B \-\-help
 .\".RI [ options ] " files" ...
 .SH DESCRIPTION
 .B OfflineIMAP
@ -90,38 +92,460 @@ should not result in loss of mail.  I am so confident in the algorithm
 that I use my own personal and work accounts for testing of
 .B OfflineIMAP
 pre-release, development, and beta releases.
 .SS "METHOD OF OPERATION"
 .B OfflineIMAP
 operates by maintaining a hierarchy of mail folders in Maildir format
 locally.  Your own mail reader will read mail from this tree, and need
 never know that the mail comes from IMAP.
 .B OfflineIMAP
 will detect changes to the mail folders on your IMAP server and your
 own computer and bi-directionally synchronize them, copying, marking,
 and deleting messages as necessary.
 .SH INSTALLATION
 If you are reading this document via the "man" command, it is likely
 that you have no installation tasks to perform; your system
 administrator has already installed it.  If you need to install it
 yourself, you have three options: a system-wide installation with
 Debian, system-wide installation with other systems, and a single-user
 installation.  You can download the latest version of OfflineIMAP from
 .UR http://quux.org/devel/offlineimap/
 http://quux.org/devel/offlineimap/.
 .UE
 .SS PREREQUISITES
 In order to use OfflineIMAP, you need to have these conditions
 satisfied:
 .IP \(bu
 Your mail server must support IMAP.  Most Internet Service Providers
 and corporate networks do, and most operating systems have an IMAP
 implementation readily available.
 .IP \(bu
 You must have Python version 2.2.1 or above installed.  If you are
 running on Debian GNU/Linux, this requirement will automatically be
 taken care of for you.  If you do not have Python already, check with
 your system administrator or operating system vendor; or, download it
 from
 .UR http://www.python.org/
 http://www.python.org/.
 .UE
 If you intend to use the Tk interface, you must have Tkiner
 (python-tk) installed.  If you intend to use the SSL interface, your
 Python must have been built with SSL support.
 .IP \(bu
 Have a mail reader that supports the Maildir mailbox format.  Most
 modern mail readers have this support built-in, so you can choose from
 a wide variety of mail servers.  This format is also known as the
 "qmail" format, so any mail reader compatible with it will work with
 OfflineIMAP.
 .SS DEBIAN SYSTEM-WIDE INSTALLATION
 If you are tracking Debian unstable, you may install
 .B OfflineIMAP
 by simply running the following command as root:
 .PP
-This manual page documents briefly the
+.B apt-get install offlineimap
 .PP
 If you are not tracking Debian unstable, download the Debian .deb
 package from the OfflineIMAP website
 and then run
 .B dpkg -i
 to install the downloaded package.  Then, go to CONFIGURATION below.
 You will type
 .B offlineimap
-and
+to invoke the program.
-.B bar
+.SS OTHER SYSTEM-WIDE INSTALLATION
-commands.
+Download the tar.gz version of the package from the website.  Then run
-This manual page was written for the Debian distribution
+these commands:
 because the original program does not have a manual page.
 Instead, it has documentation in the GNU Info format; see below.
 .PP
 .B tar -zxvf offlineimap-x.y.z.tar.gz
 .br
 .B cd offlineimap-x.y.z
 .br
 .B python2.2 setup.py
 .PP
 Some systems will need to use
 .B python
 instead of
 .B python2.2.
 Next, proceed to configuration.  You will type
 .B offlineimap
 to invoke the program.
 .SS SINGLE-ACCOUNT INSTALLATION
 Download the tar.gz version of the package from the website.  Then run
 these commands:
 .PP
 .B tar -zxvf offlineimap-x.y.z.tar.gz
 .br
 .B cd offlineimap-x.y.z
 .PP
 When you want to run
 .B OfflineIMAP,
 you will issue the
 .B cd
 command as above and then type
 .B ./offlineimap;
 there is no installation step necessary.
 .\"##################################################
 .SH CONFIGURATION
 .B OfflineIMAP
 is regulated by a configuration file that is normally stored in
 .I ~/.offlineimaprc.
 .B OfflineIMAP
 ships with a file named
 .I offlineimap.conf
 that you should copy to that location and then edit.  This file is
 vital to proper operation of the system; it sets everything you need
 to run
 .B OfflineIMAP.
 Full documentation for the configuration file is included within the
 sample file.
 .\"##################################################
 .\" TeX users may be more comfortable with the \fB<whatever>\fP and
 .\" \fI<whatever>\fP escape sequences to invode bold face and italics, 
 .\" respectively.
-\fBofflineimap\fP is a program that...
+.\"\fBofflineimap\fP is a program that...
 .SH OPTIONS
-These programs follow the usual GNU command line syntax, with long
+Most configuration is done via the configuration file.  Nevertheless,
-options starting with two dashes (`-').
+there are a few options that you may set for
-A summary of options is included below.
+.B OfflineIMAP.
-For a complete description, see the Info files.
+.TP
 .B \-1
 Disable all multithreading operations and use solely a single-thread
 sync.  This effectively sets the
 .B maxsyncaccounts
 and all
 .B maxconnections
 configuration file variables to 1.
 .TP
 .BI \-a \ accountlist
 Overrides the
 .B accounts
 section in the config file.  Lets you specify a particular account or
 set of accounts to sync without having to edit the config file.  You
 might use this to exclude certain accounts, or to sync some accounts
 that you normally prefer not to.
 .TP
 .BI \-c \ configfile
 Specifies a configuration file to use in lieu of the default,
 .I ~/.offlineimaprc.
 .TP
 .BI \-d
 Enables IMAP protocol stream and parsing debugging.  This is useful if
 you are trying to track down a malfunction or figure out what is going
 on under the hood.  I suggest that you use this with
 .BI \-1
 in order to make the results more sensible.  Note that this output
 will contain full IMAP protocol in plain text, including passwords, so
 take care to remove that from the debugging output before sending it
 to anyone else.
 .TP
 .B \-h, \-\-help
 Show summary of options.
 .TP
-.B \-v, \-\-version
+.BI \-u \ interface
-Show version of program.
+Specifies an alternative user interface module to use.  This overrides
-.SH SEE ALSO
+the default specified in the configuration file.  The UI specified
-.BR bar (1),
+with
-.BR baz (1).
+.B -u
 will be forced to be used, even if its
 .B isuable()
 method states that it cannot be.  Use this option with care.
 .\".TP
 .\".B \-v, \-\-version
 .\"Show version of program.
 .SH EXAMPLES
 Here is an example configuration for a particularly complex situation;
 more examples will be added later.
 .SS MULTIPLE ACCOUNTS WITH MUTT
 This example shows you how to set up
 .B OfflineIMAP
 to synchronize multiple accounts with the mutt mail reader.
 .PP
 Start by creating a directory to hold your folders:
 .br
-The programs are documented fully by
+.B mkdir ~/Mail
-.IR "The Rise and Fall of a Fooish Bar" ,
+.PP
-available via the Info system.
+In your
 .I ~/.offlineimaprc,
 specify this:
 .br
 .B accounts = Personal, Work
 .PP
 Make sure that you have both a
 .B [Personal]
 and a
 .B [Work]
 section, with different localfolder pathnames and enable
 .B [mbnames].
 .PP
 In each account section, do something like this:
 .br
 .B localfolders = ~/Mail/Personal
 .PP
 Add these lines to your
 .I ~/.muttrc:
 .br
 .B source ~/path-to-mbnames-muttrc-mailboxes
 .br
 .B folder-hook Personal set from="youremail@personal.com"
 .br
 .B folder-hook Work set from="youremail@work.com"
 .br
 .B set mbox_type=Maildir
 .br
 .B set folder=$HOME/Mail
 .br
 .B set spoolfile=+Personal/INBOX
 .PP
 That's it!
 .SH ERRORS
 If you get one of some frequently-encountered or confusing errors,
 please check this section.
 .SS UID validity problem for folder
 IMAP servers use a unique ID (UID) to refer to a specific message.
 This number is guaranteed to be unique to a particular message
 FOREVER.  No other message in the same folder will ever get the same
 UID.  UIDs are an integral part of OfflineIMAP's synchronization
 scheme; they are used to match up messages on your computer to
 messages on the server.
 .PP
 Sometimes, the UIDs on the server might get reset.  Usually this will
 happen if you delete and then recreate a folder.  When you create a
 folder, the server will often start the UID back from 1.  But
 .B OfflineIMAP
 might still have the UIDs from the previous folder by the
 same name stored.
 .B OfflineIMAP
 will detect this condition and skip the
 folder.  This is GOOD, because it prevents data loss.
 .PP
 You can fix it by removing your local folder and cache data.  For
 instance, if your folders are under
 .I ~/Folders
 and the folder with the
 problem is INBOX, you'd type this:
 .PP
 .B rm -r ~/Folders/INBOX
 .br
 .B rm ~/.offlineimap/AccountName/INBOX
 .PP
 (replacing AccountName with the account name as specified in
 .I ~/.offlineimaprc)
 .PP
 Next time you run
 .B OfflineIMAP,
 it will re-download the folder with the
 new UIDs.  Note that the procedure specified above will lose any local
 changes made to the folder.
 .PP
 Some IMAP servers are broken and do not support UIDs properly.  If you
 continue to get this error for all your folders even after performing
 the above procedure, it is likely that your IMAP server falls into
 this category.
 .B OfflineIMAP
 is incompatible with such servers.  Using
 .B OfflineIMAP
 with them will not destroy any mail, but at the same time,
 it will not actually synchronize it either.  (OfflineIMAP will detect
 this condition and abort prior to synchronization)
 .SH OTHER FREQUENTLY ASKED QUESTIONS
 There are some other FAQs that might not fit into another section of
 this document, and they are enumerated here.
 .TP
 .B What platforms does OfflineIMAP run on?
 It should run on most platforms supported by Python, which are quite a
 few.
 .TP
 .B I'm using Mutt.  Other IMAP sync programs require me to use "set maildir_trash=yes".  Do I need to do that with OfflineIMAP?
 No.
 .B OfflineIMAP
 is smart enough to figure out message deletion without this extra
 crutch.  You'll get the best results if you don't use this setting, in
 fact.
 .TP
 .B How do I specify the names of my folders?
 You do not need to.
 .B OfflineIMAP
 is smart enough to automatically figure out what folders are present
 on the IMAP server and synchronize them.  You can use the
 .B folderfilter
 and
 .B foldertrans
 configuration file options to request certain folders and rename them
 as they come in if you like.
 .TP
 .B How can I prevent certain folders from being synced?
 Use the
 .B folderfilter
 option in the configuration file.
 .TP
 .B How can I add or delete a folder?
 .B OfflineIMAP
 does not currently provide this feature, but if you create a new
 folder on the IMAP server, it will be created locally automatically.
 .TP
 .B Are there any other warnings that I should be aware of?
 Yes; see the NOTES section below.
 .TP
 .B What is the mailbox name recorder (mbnames) for?
 The Mutt mail reader is not capable of automatically determining
 the names of your mailboxes.  OfflineIMAP can help it (or many other)
 programs out be writing these names out in a format you specify.  See
 the example offlineimap.conf file for details.
 .TP
 .B Can I synchronize multiple accounts with OfflineIMAP?
 Sure.  Just name them all in the accounts line in the general
 section of the config file, and add a per-account section for each one.
 .TP
 .B Does OfflineIMAP support POP?
 No.  POP is not robust enough to do a completely reliable
 multi-machine synchronization like OfflineIMAP can do.  OfflineIMAP
 will not support it.
 .TP
 .B Do you support mailbox formats other than Maildir?
 Not at present.  There is no technical reason not to; just no
 demand yet.  Maildir is a superior format anyway.
 .TP
 .B [technical] Why are your Maildir message filenames so huge?
 .B OfflineIMAP
 has two relevant principles: 1) never modifying your
 messages in any way and 2) ensuring 100% reliable synchronizations.
 In order to do a reliable sync,
 .B OfflineIMAP
 must have a way to
 uniquely identify each e-mail.  Three pieces of information are
 required to do this: your account name, the folder name, and the
 message UID.  The account name can be calculated from the path in
 which your messages are.  The folder name can usually be as well, BUT
 some mail clients move messages between folders by simply moving the
 file, leaving the name intact.
 .IP
 So,
 .B OfflineIMAP
 must store both a UID folder ID.  The folder ID is
 necessary so
 .B OfflineIMAP
 can detect a message moved to a different
 folder.
 .B OfflineIMAP
 stores the UID (U= number) and an md5sum of the
 foldername (FMD5= number) to facilitate this.
 .TP
 .B What is the speed of OfflineIMAP's sync?
 .B OfflineIMAP
 versions 2.0 and above contain a multithreaded system.  A good way to
 experiment is by setting maxsyncaccounts to 3 and maxconnections to 3
 in each account clause.
 .IP
 This lets OfflineIMAP open up multiple connections simultaneously.
 That will let it process multiple folders and messages at once.  In
 most cases, this will increase performance of the sync.
 .IP
 Don't set the number too high.  If you do that, things might actually
 slow down as your link gets saturated.  Also, too many connections can
 cause mail servers to have excessive load.  Administrators might take
 unkindly to this, and the server might bog down.  There are many
 variables in the optimal setting; experimentation may help.
 .IP
 An informal benchmark yields these results for my setup:
 .IP
 10 minutes with MacOS X Mail.app "manual cache"
 .br
 5 minutes with GNUS agent sync
 .br
 20 seconds with OfflineIMAP 1.x
 .br
 9 seconds with OfflineIMAP 2.x
 .br
 3 seconds with OfflineIMAP 3.x "cold start"
 .br
 2 seconds with OfflineIMAP 3.x "held connection"
 .SH CONFORMING TO
 .IP \(bu
 Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as
 specified in RFC2060
 .IP \(bu
 Maildir as specified in
 .UR http://www.qmail.org/qmail-manual-html/man5/maildir.html
 http://www.qmail.org/qmail-manual-html/man5/maildir.html
 .UE
 and
 .UR http://cr.yp.to/proto/maildir.html
 http://cr.yp.to/proto/maildir.html.
 .UE
 .IP \(bu
 Standard Python 2.2.1 as implemented on POSIX-compliant systems.
 .SH NOTES
 .SS DELETING LOCAL FOLDERS
 .B OfflineIMAP
 does a two-way synchronization.  That is, if you
 make a change to the mail on the server, it will be propogated to your
 local copy, and vise-versa.  Some people might think that it would be
 wise to just delete all their local mail folders periodically.  If you
 do this with OfflineIMAP, remember to also remove your local status
 cache (~/.offlineimap by default).  Otherwise, OfflineIMAP will take
 this as an intentional deletion of many messages and will interpret
 your action as requesting them to be deleted from the server as well.
 (If you don't understand this, don't worry; you probably won't
 encounter this situation)
 .SS MAILING LIST
 There is an OfflineIMAP mailing list available.
 .PP
 To subscribe, send the text "Subscribe" in the subject of a mail to
 offlineimap-request@complete.org.  To post, send the message to
 offlineimap@complete.org.
 .SH BUGS
 Should be reported to the author at the address specified below.
 .SH COPYRIGHT
 OfflineIMAP is Copyright (C) 2002 John Goerzen.
 .PP
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.
 .PP
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 .PP
 You should have received a copy of the GNU General Public License
 along with this program; if not, write to:
 .PP
 Free Software Foundation, Inc.
 .br
 59 Temple Place
 .br
 Suite 330
 .br
 Boston, MA  02111-1307
 .br
 USA
 .SH AUTHOR
-This manual page was written by John Goerzen <jgoerzen@complete.org>,
+.B OfflineIMAP,
-for the Debian GNU/Linux system (but may be used by others).
+its libraries, documentation, and all included files, except where
 noted, was written by John Goerzen <jgoerzen@complete.org> and
 copyright is held as stated in the COPYRIGHT section.
 .PP
 OfflineIMAP may be downloaded, and information found, from its
 homepage via either Gopher or HTTP:
 .PP
 .UR gopher://quux.org/1/devel/offlineimap
 gopher://quux.org/1/devel/offlineimap
 .UE
 .br
 .UR http://quux.org/devel/offlineimap
 http://quux.org/devel/offlineimap
 .UE
 .SH SEE ALSO
 .BR mutt (1),
 .BR python (1).
 .\".BR bar (1),
 .\".BR baz (1).
 .\".br
 .\"The programs are documented fully by
 .\".IR "The Rise and Fall of a Fooish Bar" ,
 .\"available via the Info system.
 .\".SH AUTHOR
 .\"This manual page was written by John Goerzen <jgoerzen@complete.org>,
 .\"for the Debian GNU/Linux system (but may be used by others).