Improve nametrans user documentation
Fill in more details on nametrans and folder filtering. Also give them a separate section in our user documentation. Everything will be immediately online at docs.offlineimap.org. The main change is to describe the reverse nametrans settings that are needed since 6.4.0 to support remote folder creation. Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>
This commit is contained in:
Sebastian Spaeth
151
docs/MANUAL.rst
151
docs/MANUAL.rst
@ -328,18 +328,22 @@ Upgrading from plain text cache to SQLITE based cache
|
||||
|
||||
OfflineImap uses a cache to store the last know status of mails (flags etc). Historically that has meant plain text files, but recently we introduced sqlite-based cache, which helps with performance and CPU usage on large folders. Here is how to upgrade existing plain text cache installations to sqlite based one:
|
||||
|
||||
1) Sync to make sure things are reasonably similar
|
||||
3) Change the account section to status_backend = sqlite
|
||||
4) A new sync will convert your plain text cache to an sqlite cache (but
|
||||
leave the old plain text cache around for easy reverting)
|
||||
This should be quick and not involve any mail up/downloading.
|
||||
5) See if it works :-)
|
||||
6a) If it does not work, go back to the old version or set
|
||||
status_backend=plain
|
||||
6b) Or once you are sure it works, you can delete the
|
||||
.offlineimap/Account-foo/LocalStatus folder (the new cache will be in
|
||||
the LocalStatus-sqlite folder)
|
||||
1) Sync to make sure things are reasonably similar
|
||||
|
||||
2) Change the account section to status_backend = sqlite
|
||||
|
||||
3) A new sync will convert your plain text cache to an sqlite cache
|
||||
(but leave the old plain text cache around for easy reverting) This
|
||||
should be quick and not involve any mail up/downloading.
|
||||
|
||||
4) See if it works :-)
|
||||
|
||||
5) If it does not work, go back to the old version or set
|
||||
status_backend=plain
|
||||
|
||||
6) Or, once you are sure it works, you can delete the
|
||||
.offlineimap/Account-foo/LocalStatus folder (the new cache will be
|
||||
in the LocalStatus-sqlite folder)
|
||||
|
||||
Security and SSL
|
||||
================
|
||||
@ -399,128 +403,10 @@ accounts will abort any current sleep and will exit after a currently running
|
||||
synchronization has finished. This signal can be used to gracefully exit out of
|
||||
a running offlineimap "daemon".
|
||||
|
||||
Folder filtering and Name translation
|
||||
=====================================
|
||||
Folder filtering and nametrans
|
||||
==============================
|
||||
|
||||
OfflineImap provides advanced and potentially complex possibilities for
|
||||
filtering and translating folder names. If you don't need this, you can
|
||||
safely skip this section.
|
||||
|
||||
folderfilter
|
||||
------------
|
||||
|
||||
If you do not want to synchronize all your filters, you can specify a folderfilter function that determines which folders to include in a sync and which to exclude. Typically, you would set a folderfilter option on the remote repository only, and it would be a lambda or any other python function.
|
||||
|
||||
If the filter function returns True, the folder will be synced, if it
|
||||
returns False, it. The folderfilter operates on the *UNTRANSLATED* name
|
||||
(before any nametrans translation takes place).
|
||||
|
||||
Example 1: synchronizing only INBOX and Sent::
|
||||
|
||||
folderfilter = lambda foldername: foldername in ['INBOX', 'Sent']
|
||||
|
||||
Example 2: synchronizing everything except Trash::
|
||||
|
||||
folderfilter = lambda foldername: foldername not in ['Trash']
|
||||
|
||||
Example 3: Using a regular expression to exclude Trash and all folders
|
||||
containing the characters "Del"::
|
||||
|
||||
folderfilter = lambda foldername: not re.search('(^Trash$|Del)', foldername)
|
||||
|
||||
If folderfilter is not specified, ALL remote folders will be
|
||||
synchronized.
|
||||
|
||||
You can span multiple lines by indenting the others. (Use backslashes
|
||||
at the end when required by Python syntax) For instance::
|
||||
|
||||
folderfilter = lambda foldername: foldername in
|
||||
['INBOX', 'Sent Mail', 'Deleted Items',
|
||||
'Received']
|
||||
|
||||
You only need a folderfilter option on the local repository if you want to prevent some folders on the local repository to be created on the remote one.
|
||||
|
||||
Even if you filtered out folders, You can specify folderincludes to
|
||||
include additional folders. It should return a Python list. This might
|
||||
be used to include a folder that was excluded by your folderfilter rule,
|
||||
to include a folder that your server does not specify with its LIST
|
||||
option, or to include a folder that is outside your basic reference. The
|
||||
'reference' value will not be prefixed to this folder name, even if you
|
||||
have specified one. For example::
|
||||
|
||||
folderincludes = ['debian.user', 'debian.personal']
|
||||
|
||||
nametrans
|
||||
----------
|
||||
|
||||
Sometimes, folders need to have different names on the remote and the
|
||||
local repositories. To achieve this you can specify a folder name
|
||||
translator. This must be a eval-able Python expression that takes a
|
||||
foldername arg and returns the new value. I suggest a lambda. This
|
||||
example below will remove "INBOX." from the leading edge of folders
|
||||
(great for Courier IMAP users)::
|
||||
|
||||
nametrans = lambda foldername: re.sub('^INBOX\.', '', foldername)
|
||||
|
||||
Using Courier remotely and want to duplicate its mailbox naming
|
||||
locally? Try this::
|
||||
|
||||
nametrans = lambda foldername: re.sub('^INBOX\.*', '.', foldername)
|
||||
|
||||
|
||||
WARNING: you MUST construct nametrans rules such that it NEVER returns
|
||||
the same value for two folders, UNLESS the second values are
|
||||
filtered out by folderfilter below. That is, two filters on one side may never point to the same folder on the other side. Failure to follow this rule
|
||||
will result in undefined behavior. See also *Sharing a maildir with multiple IMAP servers* in the `PITFALLS & ISSUES`_ section.
|
||||
|
||||
Where to put nametrans rules, on the remote and/or local repository?
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
If you never intend to create new folders on the LOCAL repository that
|
||||
need to be synced to the REMOTE repository, it is sufficient to create a
|
||||
nametrans rule on the remote Repository section. This will be used to
|
||||
determine the names of new folder names on the LOCAL repository, and to
|
||||
match existing folders that correspond.
|
||||
|
||||
*IF* you create folders on the local repository, that are supposed to be
|
||||
automatically created on the remote repository, you will need to create
|
||||
a nametrans rule that provides the reverse name translation.
|
||||
|
||||
(A nametrans rule provides only a one-way translation of names and in
|
||||
order to know which names folders on the LOCAL side would have on the
|
||||
REMOTE side, you need to specify the reverse nametrans rule on the local
|
||||
repository)
|
||||
|
||||
OfflineImap will complain if it needs to create a new folder on the
|
||||
remote side and a back-and-forth nametrans-lation does not yield the
|
||||
original foldername (as that could potentially lead to infinite folder
|
||||
creation cycles).
|
||||
|
||||
What folder separators do I need to use in nametrans rules?
|
||||
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
**Q:** If I sync from an IMAP server with folder separator '/' to a
|
||||
Maildir using the default folder separator '.' which do I need to use
|
||||
in nametrans rules?::
|
||||
|
||||
nametrans = lambda f: "INBOX/" + f
|
||||
or::
|
||||
nametrans = lambda f: "INBOX." + f
|
||||
|
||||
**A:** Generally use the folder separator as defined in the repository
|
||||
you write the nametrans rule for. That is, use '/' in the above
|
||||
case. We will pass in the untranslated name of the IMAP folder as
|
||||
parameter (here `f`). The translated name will ultimately have all
|
||||
folder separators be replaced with the destination repositories'
|
||||
folder separator.
|
||||
|
||||
So if 'f' was "Sent", the first nametrans yields the translated name
|
||||
"INBOX/Sent" to be used on the other side. As that repository uses the
|
||||
folder separator '.' rather than '/', the ultimate name to be used will
|
||||
be "INBOX.Sent".
|
||||
|
||||
(As a final note, the smart will see that both variants of the above
|
||||
nametrans rule would have worked identically in this case)
|
||||
OfflineImap offers flexible (and complex) ways of filtering and transforming folder names. Please see the docs/dev-docs-src/folderfilters.rst document about details how to use folder filters and name transformations. The documentation will be autogenerated by a "make dev-doc" in the docs directory. It is also viewable at :ref:`folder_filtering_and_name_translation`.
|
||||
|
||||
KNOWN BUGS
|
||||
==========
|
||||
@ -566,6 +452,7 @@ KNOWN BUGS
|
||||
* Use cygwin managed mount (not tested)
|
||||
- not available anymore since cygwin 1.7
|
||||
|
||||
.. _pitfalls:
|
||||
|
||||
PITFALLS & ISSUES
|
||||
=================
|
||||
|
||||
Reference in New Issue
Block a user