diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst deleted file mode 100644 index d4670c5..0000000 --- a/docs/INSTALL.rst +++ /dev/null @@ -1,161 +0,0 @@ -.. -*- coding: utf-8 -*- -.. _OfflineIMAP: https://github.com/OfflineIMAP/offlineimap -.. _OLI_git_repo: git://github.com/OfflineIMAP/offlineimap.git - -============ -Installation -============ - -.. contents:: -.. .. sectnum:: - ------------------ -Development state ------------------ - -Since several months, the official maintainers Nicolas Sebrecht and Sebatian -Spaeth are too much busy to actively contribute to this project. - -In order to preserve contributions, a team of official maintainers have been -promoted to have write access to the official repository at `OfflineIMAP`_. -OfflineIMAP is now maintained by occasional contributors and the official -maintainers. All the documentation links might not be up-to-date to reflect -this change. - -The best place to get the latest news about the development state is at the -mailing list. - -------------- -Prerequisites -------------- - -In order to use `OfflineIMAP`_, you need to have these conditions satisfied: - -1. Your mail server must support IMAP. Mail access via POP is not - supported. A special Gmail mailbox type is available to interface - with Gmail's IMAP front-end, although Gmail has a very peculiar and - non-standard implementation of its IMAP interface. - -2. You must have Python version 2.6 or above installed. If you are - running on Debian GNU/Linux, this requirement will automatically be - taken care of for you. If you intend to use the SSL interface, - your Python must have been built with SSL support. - -3. If you use OfflineImap as an IMAP<->Maildir synchronizer, you will - obviously need to have a mail reader that supports the Maildir - mailbox format. Most modern mail readers have this support built-in, - so you can choose from a wide variety of mail servers. This format - is also known as the "qmail" format, so any mail reader compatible - with it will work with `OfflineIMAP`_. - - ------------- -Installation ------------- - -Installing OfflineImap should usually be quite easy, as you can simply unpack -and run OfflineImap in place if you wish to do so. There are a number of options -though: - -#. system-wide :ref:`installation via your distribution package manager ` -#. system-wide or single user :ref:`installation from the source package ` -#. system-wide or single user :ref:`installation from a git checkout ` - -Having installed OfflineImap, you will need to configure it, to be actually -useful. Please check the :ref:`Configuration` section in the :doc:`MANUAL` for -more information on the configuration step. - -.. _inst_pkg_man: - -System-Wide Installation via distribution -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The easiest way to install OfflineIMAP is via your distribution's package -manager. OfflineImap is available under the name `offlineimap` in most Linux and -BSD distributions. - - -.. _inst_src_tar: - -Installation from source package -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Download the latest source archive from our `download page -`_. Simply click the "Download -as .zip" or "Download as .tar.gz" buttons to get the latest "stable" code from -the master branch. If you prefer command line, you will want to use: wget -https://github.com/spaetz/offlineimap/tarball/master - -Unpack and continue with the :ref:`system-wide installation ` -or the :ref:`single-user installation ` section. - - -.. _inst_git: - -Installation from git checkout -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Get your own copy of the `official git repository `_ at `OfflineIMAP`_:: - - git clone https://github.com/OfflineIMAP/offlineimap.git - -This will download the source with history. By default, git sets up the -`master` branch up, which is most likely what you want. If not, you can -checkout a particular release like this:: - - cd offlineimap - git checkout v6.5.2.1 - -You have now a source tree available and proceed with either the -:ref:`system-wide installation ` or the :ref:`single-user -installation `. - - -.. _system_wide_inst: - -System-wide installation -++++++++++++++++++++++++ - -Then run these commands, to build the python package:: - - make clean - make - -Finally, install the program (as root):: - - python setup.py install - -Next, proceed to below. Type `offlineimap` to invoke the program. - - -.. _single_user_inst: - -Single-user installation -++++++++++++++++++++++++ - -Download the git repository as described above. Instead of installing the -program as root, you type `./offlineimap.py`; there is no installation step -necessary. - ---------- -Uninstall ---------- - -If you installed a system-wide installation via "python setup.py -install", there are a few files to purge to cleanly uninstall -`OfflineImap`_ again. Assuming that `/usr/local` is the standard prefix of -your system and that you use python 2.7, you need to: - -#) Delete the OfflineImap installation itself:: - - /usr/local/lib/python2.7/dist-packages/offlineimap-6.4.4.egg-info - /usr/local/lib/python2.7/dist-packages/offlineimap - - In case, you did the single-user installation, simply delete your - offlineimap directory. - -#) Delete all files that OfflineImap creates during its operation. - - The cache at (default location) ~/.offlineimap - - Your manually created (default loc) ~/.offlineimaprc - (It is possible that you created those in different spots) - -That's it. Have fun without OfflineImap. diff --git a/docs/doc-src/FAQ.rst b/docs/doc-src/FAQ.rst deleted file mode 100644 index 49fa140..0000000 --- a/docs/doc-src/FAQ.rst +++ /dev/null @@ -1,516 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. NOTE TO MAINTAINERS: Please add new questions to the end of their - sections, so section/question numbers remain stable. - -.. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project -.. _OfflineIMAP: https://github.com/OfflineIMAP/offlineimap -.. _ssl.wrap_socket: http://docs.python.org/library/ssl.html#ssl.wrap_socket -.. _Advanced Git: https://github.com/OfflineIMAP/offlineimap/blob/next/docs/doc-src/GitAdvanced.rst -.. _FAQ: https://github.com/OfflineIMAP/offlineimap/blob/next/docs/doc-src/FAQ.rst -.. _Contributing: https://github.com/OfflineIMAP/offlineimap/blob/next/CONTRIBUTING.rst - - - - -============================================= - OfflineIMAP FAQ (Frequently Asked Questions) -============================================= - -:Web site: https://github.com/nicolas33/offlineimap -:Copyright: This document is licensed under GPLv2. - -.. contents:: -.. sectnum:: - - -Please feel free to ask questions and/or provide answers; send email to the -`mailing list`_. - -Most recent `FAQ`_. - - -OfflineIMAP -=========== - -Where do I get OfflineIMAP? ---------------------------- - -See the information on the Home page `OfflineIMAP`_. - -How fast is it? ---------------- - -OfflineIMAP has a multithreaded sync, so it should have very nice performance. - -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. - -See the Performance section in the MANUAL for some tips. - -What platforms does OfflineIMAP support? ----------------------------------------- - -It should run on most platforms supported by Python, with one exception: we do not support Windows, but some have made it work there. - -The following has been reported by OfflineIMAP users. We do not test -OfflineIMAP on Windows, so we 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. The Windows - filesystem is not powerful enough to accomodate Maildir by itself. - - Next, you’ll need to mount your Maildir directory in a special - way. There is information for doing that at - http://barnson.org/node/295. 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. - - -Does OfflineIMAP supports XDG Base Directory specification? ------------------------------------------------------------ - -Yes. We are trying to use `$XDG_CONFIG_HOME/offlineimap/config` -as the primary configuration file, falling back to `~/.offlineimaprc` -if configuration file location was not explicitely specified at the -command line. - - -Does OfflineIMAP support mbox, mh, or anything else other than Maildir? ------------------------------------------------------------------------ - -Not directly. Maildir was the easiest to implement. We are not planning -to write an mbox-backend, though if someone sent me well-written mbox -support and pledged to support it, it would be committed it to the tree. - -However, OfflineIMAP can directly sync accounts on two different IMAP servers -together. So you could install an IMAP server on your local machine that -supports mbox, sync to it, and then instruct your mail readers to use the -mboxes. - -Or you could install whatever IMAP server you like on the local machine, and -point your mail readers to that IMAP server on localhost. - -What is the UID validity problem for folder? --------------------------------------------- - -IMAP servers use a folders UIDVALIDITY value in combination with a -unique ID (UID) to refer to a specific message. This is guaranteed to -be unique to a particular message forever. No other message in the same -folder will ever get the same UID as long as UIDVALIDITY remains -unchanged. UIDs are an integral part of `OfflineIMAP`_'s -synchronization scheme; they are used to match up messages on your -computer to messages on the server. - -Sometimes, the UIDs on the server might get reset. Usually this will -happen if you delete and then recreate a folder. When you create a -folder, the server will often start the UID back from 1. But -`OfflineIMAP`_ might still have the UIDs from the previous folder by the -same name stored. `OfflineIMAP`_ will detect this condition because of -the changed UIDVALIDITY value and skip the folder. This is GOOD, -because it prevents data loss. - -In the IMAP<->Maildir case, you can fix it by removing your local folder -and cache data. For instance, if your folders are under `~/Folders` and -the folder with the problem is INBOX, you'd type this:: - - rm -r ~/Folders/INBOX - rm -r ~/.offlineimap/Account-AccountName/LocalStatus/INBOX - rm -r ~/.offlineimap/Repository-RemoteRepositoryName/FolderValidity/INBOX - -(Of course, replace AccountName and RemoteRepositoryName with the names as -specified in `~/.offlineimaprc`). - -Next time you run `OfflineIMAP`_, it will re-download the folder with the new -UIDs. Note that the procedure specified above will lose any local changes made -to the folder. - -Some IMAP servers are broken and do not support UIDs properly. If you continue -to get this error for all your folders even after performing the above -procedure, it is likely that your IMAP server falls into this category. -`OfflineIMAP`_ is incompatible with such servers. Using `OfflineIMAP`_ with -them will not destroy any mail, but at the same time, it will not actually -synchronize it either. (`OfflineIMAP`_ will detect this condition and abort -prior to synchronization.) - - -This question comes up frequently on the `mailing list`_. You can find a detailed -discussion of the problem there -http://lists.complete.org/offlineimap@complete.org/2003/04/msg00012.html.gz. - -How do I automatically delete a folder? ---------------------------------------- - -OfflineIMAP does not currently provide this feature. You will have to delete folders manually. See next entry too. - -May I delete local folders? ---------------------------- - -`OfflineIMAP`_ does a two-way synchronization. That is, if you make a change -to the mail on the server, it will be propagated to your local copy, and -vise-versa. Some people might think that it would be wise to just delete all -their local mail folders periodically. If you do this with `OfflineIMAP`_, -remember to also remove your local status cache (`~/.offlineimap` by default). -Otherwise, `OfflineIMAP`_ will take this as an intentional deletion of many -messages and will interpret your action as requesting them to be deleted from -the server as well. (If you don't understand this, don't worry; you probably -won't encounter this situation.) - -Can I run multiple instances? ------------------------------ - -`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, you'll probably -find autorefresh settings more convenient than cron. Alternatively, you can -set a separate metadata directory for each instance. -In the future, we will lock each account individually rather than having one global lock. - -Can I copy messages between folders? ---------------------------------------- - -Normally, when you copy a message between folders or add a new message to a -folder locally, `OfflineIMAP`_ will just do the right thing. However, -sometimes this can be tricky ― if your IMAP server does not provide the SEARCH -command, or does not return something useful, `OfflineIMAP`_ cannot determine -the new UID of the message. So, in these rare instances, OfflineIMAP will -upload the message to the IMAP server and delete it from your local folder. -Then, on your next sync, the message will be re-downloaded with the proper UID. -`OfflineIMAP`_ makes sure that the message was properly uploaded before -deleting it, so there should be no risk of data loss. - -But if you try to sync between two IMAP servers, where both are unable to -provide you with UID of the new message, then this will lead to infinite loop. -`OfflineIMAP`_ will upload the message to one server and delete on second. On -next run it will upload the message to second server and delete on first, etc. - -Does OfflineIMAP support POP? ------------------------------ - -No. - -How is OfflineIMAP conformance? -------------------------------- - -* Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as specified in - `2060`:RFC: and `3501`:RFC: -* CRAM-MD5 as specified in `2195`:RFC: -* Maildir as specified in the Maildir manpage and the qmail website. -* Standard Python 2.7 as implemented on POSIX-compliant systems. - -Can I force OfflineIMAP to sync a folder right now? ---------------------------------------------------- - -Yes: - -1) if you use the `Blinkenlights` UI. That UI shows the active -accounts as follows:: - - 4: [active] *Control: . - 3: [ 4:36] personal: - 2: [ 3:37] work: . - 1: [ 6:28] uni: - - Simply press the appropriate digit (`3` for `personal`, etc.) to - resync that account immediately. This will be ignored if a resync is - already in progress for that account. - -2) While in sleep mode, you can also send a SIGUSR1. See the :ref:`UNIX - signals` section in the MANUAL for details. - - -I get a "Mailbox already exists" error --------------------------------------- - -**Q:** When synchronizing, I receive errors such as:: - - Folder 'sent'[main-remote] could not be created. Server responded: - ('NO', ['Mailbox already exists.']) - -**A:** IMAP folders are usually case sensitive. But some IMAP servers seem - to treat "special" folders as case insensitive (e.g. the initial - INBOX. part, or folders such as "Sent" or "Trash"). If you happen to - have a folder "sent" on one side of things and a folder called "Sent" - on the other side, OfflineIMAP will try to create those folders on - both sides. If you server happens to treat those folders as - case-insensitive you can then see this warning. - - You can solve this by excluding the "sent" folder by filtering it from - the repository settings:: - - folderfilter= lambda f: f not in ['sent'] - - -Configuration Questions -======================= - -Can I synchronize multiple accounts with OfflineIMAP? ------------------------------------------------------ - -Of course! - -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. - -You can also optionally use the -a option when you run OfflineIMAP to request -that it only operate upon a subset of the accounts for a particular run. - -How do I specify the names of 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 only -certain folders and rename them as they come in if you like. - -Also you can configure OfflineImap to only synchronize "subscribed" folders. - -How do I prevent certain folders from being synced? ---------------------------------------------------- - -Use the folderfilter option. See the MANUAL for details and examples. - -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. - -Does OfflineIMAP verify SSL certificates? ------------------------------------------ - -You can verify an imapserver's certificate by specifying the CA -certificate on a per-repository basis by setting the `sslcacertfile` -option in the config file. (See the example offlineimap.conf for -details.) If you do not specify any CA certificate, you will be presented with the server's certificate fingerprint and add that to the configuration file, to make sure it remains unchanged. -No verification happens if connecting via STARTTLS. - -How do I generate an `sslcacertfile` file? ------------------------------------------- - -The `sslcacertfile` file must contain an SSL certificate (or a concatenated -certificates chain) in PEM format. (See the documentation of -`ssl.wrap_socket`_'s `certfile` parameter for the gory details.) You can use either openssl or gnutls to create a certificate file in the required format. - -#. via openssl:: - - openssl s_client -CApath /etc/ssl/certs -connect ${hostname}:imaps -showcerts \ - | perl -ne 'print if /BEGIN/../END/; print STDERR if /return/' > $sslcacertfile - ^D - - -#. via gnutls:: - gnutls-cli --print-cert -p imaps ${host} $sslcacertfile - - -The path `/etc/ssl/certs` is not standardized; your system may store -SSL certificates elsewhere. (On some systems it may be in -`/usr/local/share/certs/`.) - -Before using the resulting file, ensure that openssl verified the certificate -successfully. In case of problems, you can test the certificate using a command such as (credits to Daniel Shahaf for this) to verify the certificate:: - - % openssl s_client -CAfile $sslcacertfile -connect ${hostname}:imaps 2>&1 ` for those interested in modifying the source code -or otherwise peek into the OfflineImap internals in a second part. - - -If you just want to get started with minimal fuzz, have a look at our `online -quick start guide `_. Do note though, -that our configuration options are many and powerful. Perusing our precious -documentation does often pay off! - -More information on specific topics can be found on the following pages: - -**User documentation** - * :doc:`Overview and features ` - * :doc:`installation/uninstall ` +Welcome to OfflineIMAP's documentation +====================================== **Configuration** * :doc:`user manual/Configuration ` * :doc:`Folder filtering & name transformation guide ` - * :doc:`maxage ` * :doc:`command line options ` - * :doc:`Frequently Asked Questions ` **Developer documentation** - * :doc:`Contributing ` * :doc:`Advanced Git ` * :doc:`API documentation ` for internal details on the :mod:`offlineimap` module +**OfflineIMAP APIs** + .. toctree:: - :hidden: - - features - INSTALL - MANUAL - nametrans - advanced_config - offlineimap - FAQ - - CONTRIBUTING - GitAdvanced API repository ui diff --git a/docs/doc-src/nametrans.rst b/docs/doc-src/nametrans.rst deleted file mode 100644 index f802c05..0000000 --- a/docs/doc-src/nametrans.rst +++ /dev/null @@ -1,233 +0,0 @@ -.. _folder_filtering_and_name_translation: - -Folder filtering and Name translation -===================================== - -OfflineImap provides advanced and potentially complex possibilities for -filtering and translating folder names. If you don't need any of this, you can -safely skip this section. - -.. warning:: - Starting with v6.4.0, OfflineImap supports the creation of folders on the remote repostory. This change means that people that only had a nametrans option on the remote repository (everyone) will need to have a nametrans setting on the local repository too that will reverse the name transformation. See section `Reverse nametrans`_ for details. - -folderfilter ------------- - -If you do not want to synchronize all your folders, 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. - -The only parameter to that function is the folder name. If the filter -function returns True, the folder will be synced, if it returns False, -it. will be skipped. The folderfilter operates on the *UNTRANSLATED* -name (before any `nametrans`_ fudging takes place). Consider the -examples below to get an idea of what they do. - -Example 1: synchronizing only INBOX and Sent:: - - folderfilter = lambda folder: folder in ['INBOX', 'Sent'] - -Example 2: synchronizing everything except Trash:: - - folderfilter = lambda folder: folder not in ['Trash'] - -Example 3: Using a regular expression to exclude Trash and all folders -containing the characters "Del":: - - folderfilter = lambda folder: not re.search('(^Trash$|Del)', folder) - -.. note:: - 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'] - -Usually it suffices to put a `folderfilter`_ setting in the remote repository -section. You might want to put 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 in this case, folder filters on the remote repository will -prevent that) - -folderincludes --------------- - -You can specify `folderincludes`_ to manually include additional folders to be -synced, even if they had been filtered out by a folderfilter setting. -`folderincludes`_ should return a Python list. - -This can be used to 1) add a folder that was excluded by your -folderfilter rule, 2) to include a folder that your server does not specify -with its LIST option, or 3) 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'] - -This will add the "debian.user" and "debian.personal" folders even if you -have filtered out everything starting with "debian" in your folderfilter -settings. - - -createfolders -------------- - -By default OfflineImap propagates new folders in both -directions. Sometimes this is not what you want. E.g. you might want -new folders on your IMAP server to propagate to your local MailDir, -but not the other way around. The 'readonly' setting on a repository -will not help here, as it prevents any change from occuring on that -repository. This is what the `createfolders` setting is for. By -default it is `True`, meaning that new folders can be created on this -repository. To prevent folders from ever being created on a -repository, set this to `False`. If you set this to False on the -REMOTE repository, you will not have to create the `Reverse -nametrans`_ rules on the LOCAL repository. - - -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. We suggest a lambda function, but it could be any python -function really. If you use nametrans rules, you will need to set them both on -the remote and the local repository, see `Reverse nametrans`_ just below for -details. The following examples are thought to be put in the remote repository -section. - -The below will remove "INBOX." from the leading edge of folders (great -for Courier IMAP users):: - - nametrans = lambda folder: re.sub('^INBOX\.', '', folder) - -Using Courier remotely and want to duplicate its mailbox naming -locally? Try this:: - - nametrans = lambda folder: re.sub('^INBOX\.*', '.', folder) - -.. 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 :ref:`pitfalls` section. - - -Reverse nametrans -+++++++++++++++++ - -Since 6.4.0, OfflineImap supports the creation of folders on the remote -repository and that complicates things. Previously, only one nametrans setting -on the remote repository was needed and that transformed a remote to a local -name. However, nametrans transformations are one-way, and OfflineImap has no way -using those rules on the remote repository to back local names to remote names. - -Take a remote nametrans rule `lambda f: re.sub('^INBOX/','',f)` which cuts off -any existing INBOX prefix. Now, if we parse a list of local folders, finding -e.g. a folder "Sent", is it supposed to map to "INBOX/Sent" or to "Sent"? We -have no way of knowing. This is why **every nametrans setting on a remote -repository requires an equivalent nametrans rule on the local repository that -reverses the transformation**. - -Take the above examples. If your remote nametrans setting was:: - - nametrans = lambda folder: re.sub('^INBOX\.', '', folder) - -then you will want to have this in your local repository, prepending "INBOX." to -any local folder name:: - - nametrans = lambda folder: 'INBOX.' + folder - -Failure to set the local nametrans rule will lead to weird-looking error -messages of -for instance- this type:: - - ERROR: Creating folder moo.foo on repository remote - Folder 'moo.foo'[remote] could not be created. Server responded: ('NO', ['Unknown namespace.']) - -(This indicates that you attempted to create a folder "Sent" when all remote -folders needed to be under the prefix of "INBOX."). - -OfflineImap will make some sanity checks 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). - -You can probably already see now that creating nametrans rules can be a pretty -daunting and complex endeavour. Check out the Use cases in the manual. If you -have some interesting use cases that we can present as examples here, please let -us know. - -Debugging folderfilter and nametrans ------------------------------------- - -Given the complexity of the functions and regexes involved, it is easy to -misconfigure things. One way to test your configuration without danger to -corrupt anything or to create unwanted folders is to invoke offlineimap with the -`--info` option. - -It will output a list of folders and their transformations on the screen (save -them to a file with -l info.log), and will help you to tweak your rules as well -as to understand your configuration. It also provides good output for bug -reporting. - -FAQ on nametrans ----------------- - -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) - diff --git a/docs/doc-src/offlineimap.rst b/docs/doc-src/offlineimap.rst deleted file mode 100644 index 37d78dc..0000000 --- a/docs/doc-src/offlineimap.rst +++ /dev/null @@ -1,92 +0,0 @@ -The offlineimap 'binary' command line options -============================================= - -Offlineimap is invoked with the following pattern: `offlineimap [args...]`. - -Where [args...] are as follows: - -Options: - --dry-run This mode protects us from performing any actual action. - It will not precisely give the exact information what - will happen. If e.g. it would need to create a folder, - it merely outputs "Would create folder X", but not how - many and which mails it would transfer. - --info Output information on the configured email - repositories. Useful for debugging and bug reporting. - Use in conjunction with the -a option to limit the - output to a single account. - --version show program's version number and exit - -h, --help show this help message and exit - -1 Disable all multithreading operations and use solely a - single-thread sync. This effectively sets the - maxsyncaccounts and all maxconnections configuration - file variables to 1. - -P DIR Sets OfflineIMAP into profile mode. The program will - create DIR (it must not already exist). As it runs, - Python profiling information about each thread is - logged into profiledir. Please note: This option is - present for debugging and optimization only, and - should NOT be used unless you have a specific reason - to do so. It will significantly slow program - performance, may reduce reliability, and can generate - huge amounts of data. This option implies the - singlethreading option (-1). - -a ACCOUNTS Overrides the accounts section in the config file. - Lets you specify a particular account or set of - accounts to sync without having to edit the config - file. You might use this to exclude certain accounts, - or to sync some accounts that you normally prefer not - to. - -c FILE Specifies a configuration file to use in lieu of - ~/.offlineimaprc. - - -d type1,[type2...] Enables debugging for OfflineIMAP. This is useful if - you are trying to track down a malfunction or figure - out what is going on under the hood. I suggest that - you use this with -1 in order to make the results more - sensible. This option requires one or more debugtypes, - separated by commas. These define what exactly will - be debugged, and so far include the options: imap, - thread,maildir or ALL. The imap option will enable - IMAP protocol stream and parsing debugging. Note that - the output may contain passwords, so take care to - remove that from the debugging output before sending - it to anyone else. The maildir option will enable - debugging for certain Maildir operations. - - -l FILE Log to FILE - - -f folder1,[folder2...] - Only sync the specified folders. The 'folder's 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". - - -o Run only once, ignoring any autorefresh setting in the - configuration file. - -q Run only quick synchronizations. Ignore any flag - updates on IMAP servers. - -u INTERFACE Specifies an alternative user interface to use. This - overrides the default specified in the configuration - file. The UI specified with -u will be forced to be - used, even if checks determine that it is not usable. - Possible interface choices are: Curses.Blinkenlights, - TTY.TTYUI, Noninteractive.Basic, Noninteractive.Quiet, - Machine.MachineUI - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`search` -