agent + IMAP

[Simon Josefsson <simon@josefsson.org>]

I've commited some Agent + IMAP fixes and the following documentation:

Agent and IMAP
--------------

   The Agent work with any Gnus backend, including nnimap.  However,
since there are some conceptual differences between NNTP and IMAP, this
section (should) provide you with some information to make Gnus Agent
work smoother as a IMAP Disconnected Mode client.

   The first thing to keep in mind is that all flags (read, ticked, etc)
are kept on the IMAP server, rather than in `.newsrc' as is the case
for nntp.  Thus Gnus need to remember flag changes when disconnected,
and synchronize these flags when you plug back in.

   Gnus keep track of flag changes when reading nnimap groups under the
Agent by default.  When you plug back in, by default Gnus will check if
you have any changed any flags and ask if you wish to synchronize theese
with the server.  This behaviour is customizable with
`gnus-agent-synchronize-flags'.

   If `gnus-agent-synchronize-flags' is `nil', the Agent will never
automatically synchronize flags.  If it is `ask', the default, the
Agent will check if you made any changes and if so ask if you wish to
synchronize these when you re-connect.  If it has any other value, all
flags will be synchronized automatically.

   If you do not wish to automatically synchronize flags when you
re-connect, this can be done manually with the
`gnus-agent-synchronize-flags' command that is bound to `J Y' in the
group buffer by default.

   Some things are currently not implemented in the Agent that you'd
might expect from a disconnected IMAP client, including:

   * Copying/moving articles into nnimap groups when unplugged.

   * Creating/deleting nnimap groups when unplugged.


   Technical note: the synchronization algorithm does not work by
"pushing" all local flags to the server, but rather incrementally
update the server view of flags by changing only those flags that were
changed by the user.  Thus, if you set one flag on a article, quit the
group and re-select the group and remove the flag; the flag will be set
and removed from the server when you "synchronize".  The queued flag
operations can be found in the per-server `flags' file in the Agent
directory.  It's emptied when you synchronize flags.