X-Git-Url: https://code.delx.au/offlineimap/blobdiff_plain/8dbfbb7ed96c30d08a5f3f00ae12b60d2bb398df..cd04e2e03ed92b0d2d41d32a279a82e28611ced4:/offlineimap.sgml diff --git a/offlineimap.sgml b/offlineimap.sgml index c8d7119..83f4ac0 100644 --- a/offlineimap.sgml +++ b/offlineimap.sgml @@ -32,6 +32,8 @@ -a accountlist -c configfile -d debugtype[,...] + -f foldername[,...] + -k [section:]option=value -l filename -o -u interface @@ -204,18 +206,19 @@ remoteuser = jgoerzen and corporate networks do, and most operating systems have an IMAP implementation readily available. + A special Gmail mailbox type is + available to interface with Gmail's IMAP front-end. - You must have Python version 2.2.1 or above installed. + You must have Python version 2.4 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 the Python website. - If you intend to use the Tk interface, you must have Tkinter - (python-tk) installed. If you intend to use the SSL interface, your + If you intend to use the SSL interface, your Python must have been built with SSL support. @@ -231,6 +234,7 @@ remoteuser = jgoerzen IMAP server and point both &OfflineIMAP; and your mail reader at it. + @@ -373,6 +377,26 @@ cd offlineimap-x.y.z will debug the threading model. + -f foldername[,foldername] + Only sync the specified folders. The + foldernames are the + untranslated foldernames. This command-line option + overrides any folderfilter + and folderincludes options in the + configuration file. + + + -k [section:]option=value + + Override configuration file option. If + "section" is omitted, it defaults + to general. Any underscores "_" in + the section name are replaced with spaces: for instance, + to override option autorefresh in + the "[Account Personal]" section in the config file one + would use "-k Account_Personal:autorefresh=30". + + -l filename @@ -389,6 +413,11 @@ cd offlineimap-x.y.z file. + -q + Run only quick synchronizations. Ignore any flag + updates on IMAP servers. + + -h --help Show summary of options. @@ -412,27 +441,22 @@ cd offlineimap-x.y.z option can override the configuration file setting. The available values for the configuration file or command-line are described in this section. + - Tk.Blinkenlights - Tk.Blinkenlights is an interface designed to be sleek, fun to watch, and + Curses.Blinkenlights + + Curses.Blinkenlights is an interface designed to be sleek, fun to watch, and informative of the overall picture of what &OfflineIMAP; is doing. I consider it to be the best general-purpose interface in &OfflineIMAP;. - Tk.Blinkenlights contains, by default, a small window with a row of - LEDs, a small log, and a row of command buttons. - The total size of the window is - very small, so it uses little desktop space, yet it is quite - functional. The optional, toggleable, log shows more + Curses.Blinkenlights contains a row of + "LEDs" with command buttons and a log. + The log shows more detail about what is happening and is color-coded to match the color of the lights. - - Tk.Blinkenlights is the only user interface that has configurable - parameters; see the example offlineimap.conf - for more details. - Each light in the Blinkenlights interface represents a thread of execution -- that is, a particular task that &OfflineIMAP; @@ -538,32 +562,6 @@ cd offlineimap-x.y.z - - Curses.Blinkenlights - - Curses.Blinkenlights is an interface very similar to Tk.Blinkenlights, - but is designed to be run in a console window (an xterm, Linux virtual - terminal, etc.) Since it doesn't have access to graphics, it isn't - quite as pretty, but it still gets the job done. - - Please see the Tk.Blinkenlights section above for more - information about the colors used in this interface. - - - - - Tk.VerboseUI - - Tk.VerboseUI (formerly known as Tk.TkUI) is a graphical interface - that presents a variable-sized window. In the window, each - currently-executing thread has a section where its name and current - status are displayed. This interface is best suited to people running - on slower connections, as you get a lot of detail, but for fast - connections, the detail may go by too quickly to be useful. People - with fast connections may wish to use Tk.Blinkenlights instead. - - - TTY.TTYUI @@ -598,6 +596,15 @@ cd offlineimap-x.y.z + + Machine.MachineUI + + Machine.MachineUI generates output in a machine-parsable format. + It is designed for other programs that will interface + to OfflineIMAP. + + + @@ -694,7 +701,7 @@ holdconnectionopen = no is based on one supplied by Tommi Virtanen for this feature. - In ~/.offlineimap.rc, he adds these options: + In ~/.offlineimaprc, he adds these options: [general] pythonfile=~/.offlineimap.py @@ -731,6 +738,24 @@ def test_mycmp(): + + + Signals + + OfflineIMAP writes its current PID into + ~/.offlineimap/pid when it is + running. It is not guaranteed that this file will + not exist when OfflineIMAP is not running. + + + Errors @@ -766,11 +791,11 @@ def test_mycmp(): rm -r ~/Folders/INBOX -rm -r ~/.offlineimap/Account-AccountName -rm -r ~/.offlineimap/Repository-RepositoryName +rm -r ~/.offlineimap/Account-AccountName/LocalStatus/INBOX +rm -r ~/.offlineimap/Repository-RemoteRepositoryName/FolderValidity/INBOX - (Of course, replace AccountName and RepositoryName + (Of course, replace AccountName and RemoteRepositoryName with the names as specified in ~/.offlineimaprc). @@ -801,145 +826,6 @@ rm -r ~/.offlineimap/Repository-RepositoryName - - Other Frequently Asked Questions - There are some other FAQs that might not fit into another section - of the document, so they are discussed here. - - - - 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. - - - - I've upgraded and now &OfflineIMAP; - crashes when I start it up! Why? - You need to upgrade your configuration - file. See at the end of this - manual. - - - - - 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 nametrans - 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 in 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. - However, &OfflineIMAP; can sync between two IMAP - servers, and some IMAP servers support other formats. You - could install an IMAP server on your local machine and have - &OfflineIMAP sync to that. - - - - [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 @@ -975,8 +861,8 @@ rm -r ~/.offlineimap/Repository-RepositoryName &OfflineIMAP; is not designed to have several instances (for instance, a cron job and an interactive invocation) run over the same mailbox simultaneously. It will perform a check on startup and abort if another &OfflineIMAP; is already running. If you need - to schedule synchronizations, please use the - autorefresh settings rather than cron. + to schedule synchronizations, you'll probably find + autorefresh settings more convenient than cron. Alternatively, you can set a separate metadata directory for each instance. @@ -999,35 +885,6 @@ rm -r ~/.offlineimap/Repository-RepositoryName - - 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; with Maildirs - 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;. - - - However, I have made KMail version 3 work well with - &OfflineIMAP; by installing an IMAP server on my local - machine, having &OfflineIMAP; sync to that, and pointing - KMail at the same server. - - Mailing List @@ -1041,9 +898,10 @@ rm -r ~/.offlineimap/Repository-RepositoryName Bugs - Reports of bugs should be sent via e-mail to the - &OfflineIMAP; mailing list at offlineimap at complete - dot org. Debian users are encouraged to instead use the + + Reports of bugs should be reported online at the + &OfflineIMAP; homepage. + Debian users are encouraged to instead use the Debian bug-tracking system. @@ -1128,14 +986,6 @@ rm -r ~/.offlineimap/Repository-RepositoryName homepage. - - &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. - -