From 6658c0bd65117ee3d6410b6b57c43a56c2a42458 Mon Sep 17 00:00:00 2001 From: jgoerzen Date: Wed, 8 Jan 2003 23:12:49 +0100 Subject: [PATCH] /offlineimap/head: changeset 345 Finished first draft of doc conversion --- offlineimap/head/offlineimap.sgml | 287 +++++++++++++++++++++++++++++- 1 file changed, 283 insertions(+), 4 deletions(-) diff --git a/offlineimap/head/offlineimap.sgml b/offlineimap/head/offlineimap.sgml index 9433d4f..eca9cf6 100644 --- a/offlineimap/head/offlineimap.sgml +++ b/offlineimap/head/offlineimap.sgml @@ -11,7 +11,7 @@
jgoerzen@complete.org
JohnGoerzen - $Date: 2003-01-08 09:13:21 -0600 (Wed, 08 Jan 2003) $ + $Date: 2003-01-08 10:12:49 -0600 (Wed, 08 Jan 2003) $ @@ -290,7 +290,7 @@ cd offlineimap-x.y.z &OfflineIMAP;. - OfflineIMAP arguments + -1 Disable most multithreading operations and use solely a single-connection @@ -398,7 +398,7 @@ cd offlineimap-x.y.z is performing right now. The colors indicate what task the particular thread is performing, and are as follows: - Blinkenlights Colors + Black indicates that this light's thread has terminated; it will light up @@ -734,10 +734,289 @@ rm -r ~/.offlineimap/AccountName/INBOX + + Other Frequently Asked Questions + There are some other FAQs that might not fit into another section + of the document, so they are discussed 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 message 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 feature, 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? + Some mail readers, such as Mutt, are not capable + of automatically determining the names of your mailboxes. + &OfflineIMAP; can help these programs by writing the names + of the folders ni a format you specify. See the example + offlineimap.conf for details. + + + + Can I synchronize multiple accounts with &OfflineIMAP? + Sure. Just name them all in the + accounts line in the general + section of the configuration 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. + + + + Does &OfflineIMAP; 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. + + + + [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 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. + + + + What is the speed of &OfflineIMAP;'s sync? + 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. + + 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: + + + 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 + + Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as + specified in RFC2060 + CRAM-MD5 as specified in RFC2195 + Maildir as specified in + the Maildir manpage and + the qmail website. + Standard Python 2.2.1 as implemented on POSIX-compliant 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 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) + + + + + Copying Messages Between Folders + + Normally, when you copy a message between folders or add a new message + to a folder locally, &OfflineIMAP; + will just do the right thing. However, sometimes this can be tricky + -- if your IMAP server does not provide the SEARCH command, or does + not return something useful, &OfflineIMAP; + cannot determine the new UID of the message. So, in these rare + instances, OfflineIMAP will upload the message to the IMAP server and + delete it from your local folder. Then, on your next sync, the + message will be re-downloaded with the proper UID. + &OfflineIMAP; makes sure that the message was properly uploaded before deleting it, + so there should be no risk of data loss. + + + + + Use with Evolution + &OfflineIMAP; can work with Evolution. To do so, first configure + your &OfflineIMAP; account to have + in its configuration. Then, configure + Evolution with the + "Maildir-format mail directories" server type. For the path, you will need to + specify the name of the top-level folder + inside your &OfflineIMAP; storage location. + You're now set! + + + + + Use with KMail + At this time, I believe that &OfflineIMAP; is not compatible + with KMail. KMail cannot work in any mode other than to move + all messages out of all folders immediately, which (besides being annoying + and fundamentally broken) is incompatible with &OfflineIMAP;. + + + + + 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 + Reports of bugs should be sent via e-mail to the + &OfflineIMAP; bug-tracking system (BTS) at + offlineimap@bugs.complete.org or submitted online using + the web interface. + + + The Web site also lists all current bugs, where you can check their + status or contribute to fixing them. + + + + + + Copyright + OfflineIMAP, and this manual, are Copyright © 2002, 2003 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 the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + imaplib.py comes from the Python dev tree and is licensed under + the GPL-compatible PSF license as stated in the file + COPYRIGHT in the &OfflineIMAP; + distribution. + + + + + 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 is + hopepage via either Gopher + or HTTP. + + + + &OfflineIMAP; may also be downloaded using Subversion. Additionally, + the distributed tar.gz may be updated with a simple "svn update" + command; it is ready to go. For information on getting OfflineIMAP + with Subversion, please visit the + complete.org Subversion page. + + + See Also - This is also a test. Foo bar. + mutt(1), + python(1) +