From 1c29a7206e7697e0b0cda13ff4836a0b2bc017d2 Mon Sep 17 00:00:00 2001
From: jgoerzen <jgoerzen>
Date: Fri, 9 Aug 2002 22:25:28 +0100
Subject: [PATCH] /offlineimap/head: changeset 232

Added documentation for Tommi's patch.
---
 offlineimap/head/debian/changelog |  4 ++
 offlineimap/head/offlineimap.1    | 66 +++++++++++++++++++++++++++----
 offlineimap/head/offlineimap.conf |  8 ++--
 3 files changed, 68 insertions(+), 10 deletions(-)

diff --git a/offlineimap/head/debian/changelog b/offlineimap/head/debian/changelog
index 027eddf..5fa7532 100644
--- a/offlineimap/head/debian/changelog
+++ b/offlineimap/head/debian/changelog
@@ -2,6 +2,10 @@ offlineimap (3.2.5) unstable; urgency=low
 
   * Now handles uploading messages without Message-Id headers.
     Closes: #156022.
+  * Applied patch from Tommi Virtanen that adds two new config file
+    options: pythonfile and foldersort.  Fixes [complete.org #29], and
+    for Debian, Closes: #155637.
+  * Added documentation for the above features.
 
  -- John Goerzen <jgoerzen@complete.org>  Fri,  9 Aug 2002 17:54:01 -0500
 
diff --git a/offlineimap/head/offlineimap.1 b/offlineimap/head/offlineimap.1
index 5d31ad7..c54100f 100644
--- a/offlineimap/head/offlineimap.1
+++ b/offlineimap/head/offlineimap.1
@@ -418,35 +418,37 @@ passwords must be specified using one of the configuration file options.
 .\".TP
 .\".B \-v, \-\-version
 .\"Show version of program.
+.\"**********************************************************************
 .SH EXAMPLES
 Here is an example configuration for a particularly complex situation;
 more examples will be added later.
+.\"********************
 .SS MULTIPLE ACCOUNTS WITH MUTT
 This example shows you how to set up
 .B OfflineIMAP
 to synchronize multiple accounts with the mutt mail reader.
-.PP
+
 Start by creating a directory to hold your folders:
 .br
 .B mkdir ~/Mail
-.PP
+
 In your
 .I ~/.offlineimaprc,
 specify this:
 .br
 .B accounts = Personal, Work
-.PP
+
 Make sure that you have both a
 .B [Personal]
 and a
 .B [Work]
 section, with different localfolder pathnames and enable
 .B [mbnames].
-.PP
+
 In each account section, do something like this:
 .br
 .B localfolders = ~/Mail/Personal
-.PP
+
 Add these lines to your
 .I ~/.muttrc:
 .br
@@ -461,8 +463,9 @@ Add these lines to your
 .B set folder=$HOME/Mail
 .br
 .B set spoolfile=+Personal/INBOX
-.PP
+
 That's it!
+.\"********************
 .SS UW-IMAPD AND REFERENCES
 Some users with a UW-IMAPD server need to use
 .B OfflineIMAP's
@@ -472,7 +475,7 @@ configuration 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.
-.PP
+
 .B [Gerf]
 .br
 .B localfolders = ~/Mail
@@ -508,6 +511,55 @@ limits the folders synced to just three.
 .B maxconnections = 1
 .br
 .B holdconnectionopen = no
+.\"********************
+.SS 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 \fI~/.offlineimap.rc\fP, he adds these options:
+
+.B [general]
+.br
+.B pythonfile=~/.offlineimap.py
+.br
+.br
+.B [foo]
+.br
+.B foldersort=mycmp
+
+Then, the \fI~/.offlineimap.py\fP file will contain:
+
+.B prioritized = ['INBOX', 'personal', 'announce', 'list']
+
+.B def mycmp(x, y):
+.br
+.B "   for prefix in prioritized:"
+.br
+.B "       if x.startswith(prefix):"
+.br
+.B "           return -1"
+.br
+.B "       elif y.startswith(prefix):"
+.br
+.B "           return +1"
+.br
+.B "   return cmp(x, y)"
+
+.B def test_mycmp():
+.br
+.B "   import os, os.path"
+.br
+.B "   folders=os.listdir(os.path.expanduser('~/data/mail/tv@hq.yok.utu.fi'))"
+.br
+.B "   folders.sort(mycmp)"
+.br
+.B "   print folders"
+
+This code snippet illustrates how the \fBfoldersort\fP option can be
+customized with a Python function from the \fBpythonfile\fP to always
+synchronize certain folders first.
+.\"**********************************************************************
 .SH ERRORS
 If you get one of some frequently-encountered or confusing errors,
 please check this section.
diff --git a/offlineimap/head/offlineimap.conf b/offlineimap/head/offlineimap.conf
index c893ea9..cfdf9f9 100644
--- a/offlineimap/head/offlineimap.conf
+++ b/offlineimap/head/offlineimap.conf
@@ -80,7 +80,8 @@ ignore-readonly = no
 # You can give a Python source filename here and all config file
 # python snippets will be evaluated in the context of that file.
 # This allows you to e.g. define helper functions in the Python
-# source file and call them from this config file.
+# source file and call them from this config file.  You can find
+# an example of this in the manual.
 #
 # pythonfile = ~/.offlineimap.py
 #
@@ -263,13 +264,14 @@ remoteuser = username
 
 # You can specify foldersort to determine how folders are sorted.
 # This affects order of synchronization and mbnames. The expression
-# should return -1, 0, or 1, as the default Python cmp() does.
+# should return -1, 0, or 1, as the default Python cmp() does.  The
+# two arguments, x and y, are strings representing the names of the folders
+# to be sorted.  The sorting is applied *AFTER* nametrans, if any.
 #
 # To reverse the sort:
 #
 # foldersort = lambda x, y: -cmp(x, y)
 
-
 # OfflineIMAP can use multiple connections to the server in order
 # to perform multiple synchronization actions simultaneously.
 # This may place a higher burden on the server.  In most cases,