diff --git a/README.md b/README.md index 7748f62..ef815c3 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,62 @@ -OfflineImap -=========== +[offlineimap]: https://github.com/OfflineIMAP/offlineimap +[website]: http://offlineimap.github.io +[wiki]: http://github.com/OfflineIMAP/offlineimap/wiki -Description ------------ +# OfflineImap -OfflineIMAP is a tool to simplify your e-mail reading. With OfflineIMAP, 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. 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 provide disconnected operation. It's homepage at -http://offlineimap.org contains more information, source code, and online -documentation. +## Description -OfflineIMAP does not require additional python dependencies beyond python >=2.6 -(although python-sqlite is strongly recommended). +OfflineIMAP is a software to dispose your e-mail mailbox(es) as a local Maildir. -OfflineIMAP is a Free Software project licensed under the GNU General -Public License version 2 (or later) with a special exception that allows -the OpenSSL library to be used. You can download it for free, and you -can modify it. In fact, you are encouraged to contribute to OfflineIMAP. +For example, this allows reading the mails while offline without the need for your mail reader (MUA) to support disconnected operations. -Documentation -------------- +OfflineIMAP will synchronize both sides via *IMAP*. + + +## License + +GNU General Public License v2. + + +## Why should I use OfflineIMAP? + +* It is **fast**. +* It is **reliable**. +* It is **flexible**. +* It is **safe**. + + +## Downloads + +You should first check if your distribution already package OfflineIMAP for you. +Downloads releases as [tarball or zipball](https://github.com/OfflineIMAP/offlineimap/tags). + + +## Feedbacks and contributions + +**The user discussions, development, announces and all the exciting stuff take +place in the mailing list.** While not mandatory to send emails, you can +[subscribe +here](http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project). + +Bugs, issues and contributions can be requested to both the mailing list or the +[official Github project][offlineimap]. + + +## The community + +* OfflineIMAP's main site is the [project page at Github][offlineimap]. +* There is the [OfflineIMAP community's website][website]. +* And finally, [the wiki][wiki]. + + +## Requirements + +* Python v2.7 +* Python SQlite (optional while recommended) + + +## Documentation The documentation is included (in .rst format) in the `docs` directory. Read it directly or generate nice html docs (python-sphinx needed) and/or @@ -36,191 +69,3 @@ the man page (python-docutils needed) while being in the `docs` dir via: The resulting user documentation will be in `docs/html`. The full user docs are also at: http://docs.offlineimap.org. Please see there for detailed information on how to install and configure OfflineImap. - -Quick Start -=========== - -First, install OfflineIMAP. See `docs/INSTALL.rst` or read - -(hint: `sudo python setup.py install`). - -Second, set up your configuration file and run it! The distribution -includes offlineimap.conf.minimal (Debian users may find this at -`/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal`) that -provides you with the bare minimum of setting up OfflineIMAP. You can -simply copy this file into your home directory and name it -`.offlineimaprc`. A command such as `cp offlineimap.conf.minimal -~/.offlineimaprc` will do it. Or, if you prefer, you can just copy -this text to `~/.offlineimaprc`: - - [general] - accounts = Test - - [Account Test] - localrepository = Local - remoterepository = Remote - - [Repository Local] - type = Maildir - localfolders = ~/Test - - [Repository Remote] - type = IMAP - remotehost = examplehost - remoteuser = jgoerzen - - -Now, edit the `~/.offlineimaprc` file with your favorite editor. All you have -to do is specify a directory for your folders to be in (on the `localfolders` -line), the host name of your IMAP server (on the `remotehost` line), and your -login name on the remote (on the `remoteuser` line). That's it! - -If you prefer to be compatible with the [XDG Base Directory -spec](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html), -then substitute the above `~/.offlineimaprc` with -`$XDG_CONFIG_HOME/offlineimap/config` and don't forget to set -`XDG_CONFIG_HOME` properly if you want it to be different from -the default `$HOME/.config` for any reason. - -To run OfflineIMAP, you just have to say `offlineimap` ― it will fire -up, ask you for a login password if necessary, synchronize your folders, -and exit. See? - -You can just throw away the rest of the finely-crafted, perfectly-honed user -manual! Of course, if you want to see how you can make OfflineIMAP -FIVE TIMES FASTER FOR JUST $19.95 (err, well, $0), you have to read on our -full user documentation and peruse the sample offlineimap.conf (which -includes all available options) for further tweaks! - - -Mailing list & bug reporting ----------------------------- - -The user discussion, development and all exciting stuff take place in the -OfflineImap mailing list at -. You do not -need to subscribe to send emails. - -Bugs, issues and contributions should be reported to the mailing list. Bugs can -also be reported in the issue tracker at -. - -Configuration Examples -====================== - -Here are some example configurations for various situations. Please e-mail any -other examples you have that may be useful to me. - - -Multiple Accounts with Mutt ---------------------------- - -This example shows you how to set up OfflineIMAP to synchronize multiple -accounts with the mutt mail reader. - -Start by creating a directory to hold your folders by running `mkdir ~/Mail`. -Then, in your `~/.offlineimaprc`, specify: - - accounts = Personal, Work - - -Make sure that you have both an `[Account Personal]` and an `[Account Work]` -section. The local repository for each account must have different `localfolder` -path names. Also, make sure to enable `[mbnames]`. - -In each local repository section, write something like this: - - localfolders = ~/Mail/Personal - - -Finally, 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 - spoolfile=+Personal/INBOX - - -That's it! - - -UW-IMAPD and References ------------------------ - -Some users with a UW-IMAPD server need to use OfflineIMAP's "reference" feature -to get at their mailboxes, specifying a reference of `~/Mail` or `#mh/` -depending on the configuration. The below configuration from (originally from -docwhat@gerf.org) shows using a reference of Mail, a `nametrans` that strips the -leading `Mail/` off incoming folder names, and a `folderfilter` that limits the -folders synced to just three: - - [Account Gerf] - localrepository = GerfLocal - remoterepository = GerfRemote - - [Repository GerfLocal] - type = Maildir - localfolders = ~/Mail - - [Repository GerfRemote] - type = IMAP - remotehost = gerf.org - ssl = yes - remoteuser = docwhat - reference = Mail - # Trims off the preceeding Mail on all the folder names. - nametrans = lambda foldername: \ - re.sub('^Mail/', '', foldername) - # Yeah, you have to mention the Mail dir, even though it - # would seem intuitive that reference would trim it. - folderfilter = lambda foldername: foldername in [ - 'Mail/INBOX', - 'Mail/list/zaurus-general', - 'Mail/list/zaurus-dev', - ] - maxconnections = 1 - holdconnectionopen = no - - -pythonfile Configuration File Option -------------------------------------- - -You can have OfflineIMAP load up a Python file before evaluating the -configuration file options that are Python expressions. This example is based -on one supplied by Tommi Virtanen for this feature. - - -In `~/.offlineimaprc`, he adds these options: - - [general] - pythonfile=~/.offlineimap.py - [Repository foo] - foldersort=mycmp - -Then, the `~/.offlineimap.py` file will contain: - - prioritized = ['INBOX', 'personal', 'announce', 'list'] - - def mycmp(x, y): - for prefix in prioritized: - xsw = x.startswith(prefix) - ysw = y.startswith(prefix) - if xsw and ysw: - return cmp(x, y) - elif xsw: - return -1 - elif ysw: - return +1 - return cmp(x, y) - - def test_mycmp(): - import os, os.path - folders=os.listdir(os.path.expanduser('~/data/mail/tv@hq.yok.utu.fi')) - folders.sort(mycmp) - print folders - - -This code snippet illustrates how the `foldersort` option can be customized with a -Python function from the `pythonfile` to always synchronize certain folders first.