README: deep cleanup

Documentation refactorized.

Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>
This commit is contained in:
Nicolas Sebrecht 2015-03-10 04:01:22 +01:00
parent d5cea50370
commit f46f08ecf8

263
README.md
View File

@ -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 ## Description
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.
OfflineIMAP does not require additional python dependencies beyond python >=2.6 OfflineIMAP is a software to dispose your e-mail mailbox(es) as a local Maildir.
(although python-sqlite is strongly recommended).
OfflineIMAP is a Free Software project licensed under the GNU General For example, this allows reading the mails while offline without the need for your mail reader (MUA) to support disconnected operations.
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.
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. The documentation is included (in .rst format) in the `docs` directory.
Read it directly or generate nice html docs (python-sphinx needed) and/or 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 The resulting user documentation will be in `docs/html`. The full user
docs are also at: http://docs.offlineimap.org. Please see there for docs are also at: http://docs.offlineimap.org. Please see there for
detailed information on how to install and configure OfflineImap. detailed information on how to install and configure OfflineImap.
Quick Start
===========
First, install OfflineIMAP. See `docs/INSTALL.rst` or read
<http://docs.offlineimap.org/en/latest/INSTALL.html>
(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
<http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project>. 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
<https://github.com/OfflineIMAP/offlineimap/issues>.
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.