New option 'list-reference' to specify a reference name.

This is useful for synchronizing multiple remote servers against
different namespaces belonging to the same local IMAP server (using a
different InterIMAP instance for each local namespace ↔ remote
synchronization, for instance with the newy provided systemd template
unit file).

1 files changed, 17 insertions, 0 deletions

diff --git a/interimap.md b/interimap.md
index 2f064e1..50c1832 100644
--- a/interimap.md
+++ b/interimap.md
@@ -214,6 +214,23 @@ Valid options are:
     (Default: `HOST.db`, where *HOST* is taken from the `[remote]` or
     `[local]` sections, in that order.)
 
+*list-reference*
+
+:   An optional “reference name” to use for the initial `LIST` command,
+    indicating the context in which the *MAILBOX*es are interpreted.
+    For instance, by specifying `list-reference=perso/` in the `[local]`
+    section, *MAILBOX* names are interpreted relative to `perso/` on the
+    local server; in other words the remote mailbox hierarchy is mapped
+    to the `perso/` sub-hierarchy on the local server.  This is useful
+    for synchronizing multiple remote servers against different
+    namespaces belonging to the same local IMAP server (using a
+    different InterIMAP instance for each local namespace ↔ remote
+    synchronization).
+
+    (Note that if the reference name is not a level of mailbox hierarchy
+    and/or does not end with the hierarchy delimiter, by [RFC 3501] its
+    interpretation by the IMAP server is implementation-dependent.)
+
 *list-mailbox*
 
 :   A space separated list of mailbox patterns to use when issuing the