X-Git-Url: https://code.delx.au/offlineimap/blobdiff_plain/90a72c71b69c7f81443133a1fc8b2d306b88795a..0c8e1922c62e0353104041c39cc44bcedab552eb:/offlineimap.sgml
diff --git a/offlineimap.sgml b/offlineimap.sgml
index 6575da0..83f4ac0 100644
--- a/offlineimap.sgml
+++ b/offlineimap.sgml
@@ -10,7 +10,6 @@
jgoerzen@complete.org
JohnGoerzen
- $Date: 2004-07-26 10:37:45 -0500 (Mon, 26 Jul 2004) $
@@ -33,6 +32,8 @@
-a accountlist
-c configfile
-d debugtype[,...]
+ -f foldername[,...]
+ -k [section:]option=value
-l filename
-o
-u interface
@@ -187,7 +188,7 @@ remoteuser = jgoerzen
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
- the &OfflineIMAP;
+ the &OfflineIMAP;
website.
@@ -205,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.
@@ -232,6 +234,7 @@ remoteuser = jgoerzen
IMAP server and point both &OfflineIMAP; and your mail
reader at it.
+
@@ -246,7 +249,7 @@ remoteuser = jgoerzen
If you are not tracking Debian unstable, download the Debian .deb
- package from the &OfflineIMAP; website
+ package from the &OfflineIMAP; website
and then run dpkg -i to install the downloaded
package. Then, skip to below. You will type offlineimap to
invoke the program.
@@ -257,7 +260,7 @@ remoteuser = jgoerzen
System-Wide Installation, Other
Download the tar.gz version of the package from the
- website.
+ website.
Then run
these commands, making sure that you are the "root" user first:
@@ -276,7 +279,7 @@ python2.2 setup.py install
Single-Account Installation
Download the tar.gz version of the package from the
- website.
+ website.
Then run these commands:
@@ -374,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
@@ -390,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.
@@ -413,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;
@@ -539,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
@@ -599,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.
+
+
+
@@ -695,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
@@ -732,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
@@ -767,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).
@@ -802,185 +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.
-
-
-
- What platforms does &OfflineIMAP; run on?
-
- It should run on most platforms supported by Python, which are quite a
- few. I do not support Windows myself, but some have made
- it work there; see the FAQ entry for that platform.
-
-
-
- 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 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 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"
-
-
- Can I use &OfflineIMAP; on Windows?
-
- These answers have been reported by &OfflineIMAP;
- users. I do not run &OfflineIMAP; on Windows myself, so
- I can't directly address their accuracy.
-
-
- The basic answer is that it's possible and doesn't
- require hacking &OfflineIMAP; source code. However,
- it's not necessarily trivial. The information below is
- based in instructions submitted by Chris Walker.
-
-
- First, you must run &OfflineIMAP; in the Cygwin
- environment.
-
-
- Next, you'll need to mount your Maildir directory in a
- special way. There is information for doing that at
- .
- That site gives this example:
-
-
-mount -f -s -b -o managed "d:/tmp/mail" "/home/of/mail"
-
-
- That URL also has more details on making OfflineIMAP
- work with Windows.
-
-
-
-
-
-
Conforming To
@@ -1016,8 +861,8 @@ mount -f -s -b -o managed "d:/tmp/mail" "/home/of/mail"
&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.
@@ -1040,35 +885,6 @@ mount -f -s -b -o managed "d:/tmp/mail" "/home/of/mail"
-
- 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
@@ -1082,9 +898,10 @@ mount -f -s -b -o managed "d:/tmp/mail" "/home/of/mail"
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.
@@ -1129,7 +946,7 @@ mount -f -s -b -o managed "d:/tmp/mail" "/home/of/mail"
Copyright
- OfflineIMAP, and this manual, are Copyright © 2002, 2003 John Goerzen.
+ OfflineIMAP, and this manual, are Copyright © 2002 - 2006 John Goerzen.
This program is free software; you can redistribute it and/or modify
@@ -1166,16 +983,7 @@ mount -f -s -b -o managed "d:/tmp/mail" "/home/of/mail"
&OfflineIMAP; may be downloaded, and information found, from its
- homepage 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.
+ homepage.