Documented IMAP feature

2 files changed, 61 insertions, 5 deletions

diff --git a/mairix.1 b/mairix.1
index c243aed..28afc09 100644
--- a/mairix.1
+++ b/mairix.1
@@ -102,12 +102,18 @@ maildir
 MH (compatible with the MH folder formats used by xmh, sylpheed, claws-mail, nnml (Gnus) and evolution)
 .IP *
 mbox (including mboxes that have been compressed with gzip or bzip2)
+.IP *
+IMAP: remote folders on an IMAP server
 .PP
 If maildir or MH source folders are used, and a search outputs its matches to
 an mfolder in maildir or MH format, symbolic links are used to reference the
 original messages inside the mfolder.  However, if mbox folders are involved,
-copies of messages are made instead.
-
+copies of messages are made instead. If IMAP folders are used for both source
+results, IMAP server-side copies of messages are made. With IMAP source folders
+and any other type of results folder, messages are downloaded from the IMAP
+server to be written to the results folder. With an IMAP results folder and
+any other type of source folders, messages are uploaded to the IMAP server
+to be appended to the results folder.
 .SH OPTIONS
 
 .B mairix
@@ -233,7 +239,8 @@ paths on stdout.
 .br
 Instead of creating an mfolder containing the matched messages, display an
 excerpt from their headers on stdout.  The excerpt shows To, Cc, From, Subject
-and Date.
+and Date. With IMAP source folders, this requires downloading each matched
+message from the IMAP server.
 
 .TP
 .B -H, --force-hardlinks
diff --git a/mairixrc.5 b/mairixrc.5
index b25dead..4757739 100644
--- a/mairixrc.5
+++ b/mairixrc.5
@@ -61,6 +61,41 @@ If the path is relative, it is treated as relative to the location of the
 file.
 
 .TP
+.BI imap_server= hostname
+.br
+If any IMAP source folders are specified or the results folder is an IMAP
+folder, this defines the host name of the IMAP server. The port is
+currently always 143. This option is mutually exclusive with the
+'imap_pipe' option.
+
+.TP
+.BI imap_pipe= shell-command
+.br
+If any IMAP source folders are specified or the results folder is an IMAP
+folder, this defines a shell command that can be used to connect to the
+IMAP server and talk to it over UNIX pipes instead of a TCP/IP connection.
+This option is mutually exclusive with the 'imap_server' option.
+
+.TP
+.BI imap_username= username
+.br
+If any IMAP source folders are specified or the results folder is an IMAP
+folder, this defines the user name to use to log in to the IMAP server.
+This parameter is optional, but IMAP servers normally require clients to
+log in, so it is normally necessary to specify it. One example of a case
+where it is not required is if the 'imap_pipe' option is in use the the
+shell command established a connection with an IMAP server in
+pre-autenticated state.
+
+.TP
+.BI imap_password= password
+.br
+If any IMAP source folders are specified or the results folder is an IMAP
+folder, this defines the password to use to log in to the IMAP server.
+This parameter is optional, but IMAP servers normally require clients to
+log in, so it is normally necessary to specify it.
+
+.TP
 .BI maildir= list-of-folder-specifications
 This is a colon-separated list of the Maildir folders (relative to
 `base') that you want indexed.  Any entry that ends `...' is
@@ -245,6 +280,20 @@ can support a maximum of 65536 separate mboxes, and a
 maximum of 65536 messages within any one mbox.
 
 .TP
+.BI imap= list-of-folders
+.br
+This is a colon-separated list of the IMAP folders that you want indexed.
+
+These folders must all be located on the same account on the same IMAP
+server. The configuration options imap_server and imap_pipe specify
+how to connect to the IMAP server.
+
+More than one line starting with 'imap' can be included.  In this
+case, 
+.B mairix
+joins the lines together with colons as though a
+single list of folders had been given on a single very long line.
+.TP
 .BI omit= list-of-glob-patterns
 This is a colon-separated list of glob patterns for folders to be omitted from
 the indexing.  This allows wide wildcards and recursive elements to be used
@@ -321,9 +370,9 @@ folders.
 .TP
 .BI mformat= format
 This defines the type of folder used for the match folder where
-the search results go.  There are four valid settings for
+the search results go.  There are six valid settings for
 .IR format ,
-namely 'maildir', 'mh', 'mbox', 'raw' or 'excerpt'.  If the 'raw' setting is
+namely 'maildir', 'mh', 'mbox', 'imap', 'raw', or 'excerpt'.  If the 'raw' setting is
 used then
 .B mairix
 will just print out the path names of the files that match and no match folder