Merge branch 'master' into HEAD

1 files changed, 31 insertions, 9 deletions

diff --git a/interimap.md b/interimap.md
index 4d85eaf..50c1832 100644
--- a/interimap.md
+++ b/interimap.md
@@ -82,10 +82,10 @@ the *list-mailbox*, *list-select-opts* and *ignore-mailbox* options from
 the [configuration file](#configuration-file) can be used to shrink that
 list and save bandwidth.
 However if some extra argument are provided on the command line,
-`interimap` ignores said options and synchronizes the given
+`interimap` ignores these options and synchronizes the given
 *MAILBOX*es instead.  Note that each *MAILBOX* is taken “as is”; in
 particular, it must be [UTF-7 encoded][RFC 2152], unquoted, and the list
-wildcards ‘\*’ and ‘%’ are not expanded.
+wildcards ‘\*’ and ‘%’ are passed verbatim to the IMAP server.
 
 If the synchronization was interrupted during a previous run while some
 messages were being replicated (but before the `UIDNEXT` or
@@ -214,17 +214,38 @@ 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
     initial `LIST` command (overridden by the *MAILBOX*es given as
     command-line arguments).
-    Note that each pattern containing special characters such as spaces
-    or brackets (see [RFC 3501] for the exact syntax) must be quoted.
+    Names containing special characters such as spaces or brackets need
+    to be enclosed in double quotes.  Within double quotes C-style
+    backslash escape sequences can be used (‘\\t’ for an horizontal tab,
+    ‘\\n’ for a new line, ‘\\\\’ for a backslash, etc.), as well as
+    hexadecimal escape sequences ‘\\xHH’.
     Furthermore, non-ASCII names must be [UTF-7 encoded][RFC 2152].
-    Two wildcards are available: a ‘\*’ character matches zero or more
-    characters, while a ‘%’ character matches zero or more characters up
-    to the mailbox's hierarchy delimiter.
+    Two wildcards are available, and passed verbatim to the IMAP server:
+    a ‘\*’ character matches zero or more characters, while a ‘%’
+    character matches zero or more characters up to the hierarchy
+    delimiter.
     This option is only available in the default section.
     (The default pattern, `*`, matches all visible mailboxes on the
     server.)
@@ -261,8 +282,9 @@ Valid options are:
 :   One of `imap`, `imaps` or `tunnel`.
     `type=imap` and `type=imaps` are respectively used for IMAP and IMAP
     over SSL/TLS connections over a INET socket.
-    `type=tunnel` causes `interimap` to open a pipe to a *command*
-    instead of a raw socket.
+    `type=tunnel` causes `interimap` to create an unnamed pair of
+    connected sockets for interprocess communication with a *command*
+    instead of a opening a network socket.
     Note that specifying `type=tunnel` in the `[remote]` section makes
     the default *database* to be `localhost.db`.
     (Default: `imaps`.)