Merge branch 'master' into debian

6 files changed, 97 insertions, 48 deletions

diff --git a/doc/build.md b/doc/build.md
index 38d1bfb..5c362f1 100644
--- a/doc/build.md
+++ b/doc/build.md
@@ -1,5 +1,5 @@
 % Build instructions
-% Guilhem Moulin <guilhem@fripost.org>
+% [Guilhem Moulin](mailto:guilhem@fripost.org)
 
 On Debian 9 (codename *Stretch*) and later, installing [`interimap`(1)]
 is a single command away:
@@ -33,9 +33,9 @@ On Debian GNU/Linux systems, the dependencies can be installed with the
 following command:
 
     $ apt install libconfig-tiny-perl \
-		libdbi-perl \
-		libdbd-sqlite3-perl \
-		libnet-ssleay-perl
+        libdbi-perl \
+        libdbd-sqlite3-perl \
+        libnet-ssleay-perl
 
 Additional packages are required in order to run the test suite:
 
@@ -68,8 +68,8 @@ the `CSS` environment variable (the value of which defaults to
 For instance, use
 
     $ CSS="https://guilhem.org/static/css/bootstrap.min.css" \
-		HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \
-		make html
+        HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \
+        make html
 
 to generate the HTML documentation under directory `$XDG_RUNTIME_DIR/interimap`
 (which needs to exist) using a remote CSS file.
@@ -78,12 +78,12 @@ The `doc` target generates all documentation, manpages as well as HTML
 pages.
 
 
-Build custom Debian package
-===========================
+Build custom Debian packages
+============================
 
 Debian GNU/Linux users can also use [`gbp`(1)] from
 [`git-buildpackage`](https://tracker.debian.org/pkg/git-buildpackage) in
-order to build their own package:
+order to build their own packages:
 
     $ git checkout debian
     $ gbp buildpackage
diff --git a/doc/development.md b/doc/development.md
index 406207a..49e8d74 100644
--- a/doc/development.md
+++ b/doc/development.md
@@ -1,5 +1,5 @@
-% Test environment setup for [`interimap`(1)] and [`pullimap`(1)]
-% Guilhem Moulin <guilhem@fripost.org>
+% Test environment setup
+% [Guilhem Moulin](mailto:guilhem@fripost.org)
 
 Introduction
 ============
@@ -83,7 +83,7 @@ pre-authenticated [IMAP4rev1] in the test environment for username
 `testuser`, list mailboxes, and exit, run:
 
     $ env -i PATH="/usr/bin:/bin" USER="testuser" \
-		doveadm -c "$BASEDIR/dovecot.conf" exec imap
+        doveadm -c "$BASEDIR/dovecot.conf" exec imap
     * PREAUTH [CAPABILITY IMAP4rev1 …] Logged in as testuser
     a LIST "" "*"
     * LIST (\HasNoChildren) "." INBOX
@@ -98,10 +98,10 @@ the latter to create a mailbox `foo`, add a sample message to it, and
 finally mark it as `\Seen`.
 
     $ env -i PATH="/usr/bin:/bin" USER="testuser" \
-		doveadm -c "$BASEDIR/dovecot.conf" mailbox create "foo"
+        doveadm -c "$BASEDIR/dovecot.conf" mailbox create "foo"
 <!-- -->
     $ env -i PATH="/usr/bin:/bin" USER="testuser" HOME="$BASEDIR/testuser" \
-		doveadm -c "$BASEDIR/dovecot.conf" exec dovecot-lda -e -m "foo" <<-EOF
+        doveadm -c "$BASEDIR/dovecot.conf" exec dovecot-lda -e -m "foo" <<-EOF
 			From: <sender@example.net>
 			To: <recipient@example.net>
 			Subject: Hello world!
@@ -112,7 +112,7 @@ finally mark it as `\Seen`.
 		EOF
 <!-- -->
     $ env -i PATH="/usr/bin:/bin" USER="testuser" \
-		doveadm -c "$BASEDIR/dovecot.conf" flags add "\\Seen" mailbox "foo" "*"
+        doveadm -c "$BASEDIR/dovecot.conf" flags add "\\Seen" mailbox "foo" "*"
 
 Normally [`dovecot-lda`(1)](https://wiki.dovecot.org/LDA) tries to do a
 userdb lookup in order to determine the user's home directory.  Since we
@@ -155,7 +155,7 @@ You can now run [`interimap`(1)] with `--watch` set, here to one second
 to observe synchronisation steps early.
 
     $ env -i PATH="$PATH" perl -I./lib -T ./interimap --config="$BASEDIR/interimap.conf" \
-		--watch=1 --debug
+        --watch=1 --debug
 
 Use instructions from the [previous section][Mail storage access]
 (substituting `testuser` with `local` or `remote`) in order to simulate
@@ -179,12 +179,12 @@ Create a [`pullimap`(1)] configuration file with as section `[foo]`.
 Run [`pullimap`(1)] without `--idle` in order to create the state file.
 
     $ env -i PATH="$PATH" perl -I./lib -T ./pullimap --config="$BASEDIR/pullimap.conf" \
-		--no-delivery foo
+        --no-delivery foo
 
 You can now run [`pullimap`(1)] with `--idle` set.
 
     $ env -i PATH="$PATH" perl -I./lib -T ./pullimap --config="$BASEDIR/pullimap.conf" \
-		--no-delivery --idle --debug foo
+        --no-delivery --idle --debug foo
 
 Use instructions from the [previous section][Mail storage access]
 in order to simulate activity on the “remote” server (in the relevant
diff --git a/doc/index.md b/doc/index.md
index 12de956..a403a3e 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -1,5 +1,5 @@
-% [`interimap`(1)] and [`pullimap`(1)] documentation
-% Guilhem Moulin <guilhem@fripost.org>
+% [`interimap`(1)] and [`pullimap`(1)]
+% [Guilhem Moulin](mailto:guilhem@fripost.org)
 
 Manuals (HTML versions)
 -----------------------
diff --git a/doc/interimap.1.md b/doc/interimap.1.md
index 387850a..ee92668 100644
--- a/doc/interimap.1.md
+++ b/doc/interimap.1.md
@@ -85,7 +85,10 @@ However if some extra argument are provided on the command line,
 `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 passed verbatim to the IMAP server.
+wildcards ‘\*’ and ‘%’ are passed verbatim to the IMAP server.  If the
+local and remote hierarchy delimiter differ, then within the *MAILBOX*
+names the *local* delimiter should be used (it is transparently
+substituted for remote commands and responses).
 
 If the synchronization was interrupted during a previous run while some
 messages were being replicated (but before the `UIDNEXT` or
@@ -175,10 +178,11 @@ Options
 
 `--debug`
 
-:   Turn on debug mode.  Debug messages are written to the given *logfile*.
-    Note that this include all IMAP traffic (except literals).
-    Depending on the chosen authentication mechanism, this might include
-    authentication credentials.
+:   Turn on debug mode.  Debug messages, which includes all IMAP traffic
+    besides literals, are written to the given *logfile*.  The `LOGIN`
+    and `AUTHENTICATE` commands are however redacted (in order to avoid
+    disclosing authentication credentials) unless the `--debug` flag is
+    set multiple times.
 
 `-h`, `--help`
 
@@ -245,7 +249,13 @@ Valid options are:
     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.
+    delimiter.  Hardcoding the hierarchy delimiter in this setting is
+    not advised because the server might silently change it at some
+    point. A null character should be used instead.  For instance, if
+    *list-mailbox* is set `"foo\x00bar"` then, assuming the hierarchy
+    delimiter is ‘/’, only the mailbox named `foo/bar` is considered for
+    synchronization.
+
     This option is only available in the default section.
     (The default pattern, `*`, matches all visible mailboxes on the
     server.)
@@ -266,7 +276,10 @@ Valid options are:
 :   An optional Perl Compatible Regular Expressions ([PCRE]) covering
     mailboxes to exclude: any ([UTF-7 encoded][RFC 2152] and unquoted)
     mailbox listed in the initial `LIST` responses is ignored if it
-    matches the given expression.
+    matches the given expression after trimming the reference names and
+    substituting the hierarchy delimiter with the null character.  For
+    instance, specifying `^virtual(?:\x00|$)` excludes the mailbox named
+    “virtual” as well as its descendants.
     Note that the *MAILBOX*es given as command-line arguments bypass the
     check and are always considered for synchronization.  This option is
     only available in the default section.
@@ -277,6 +290,19 @@ Valid options are:
     default these messages are written to the error output.)  This
     option is only available in the default section.
 
+*log-prefix*
+
+:   A `printf`(3)-like format string to use as prefix for each log
+    message.  Interpreted sequences are `%n` and `%m`, expanding
+    respectively to the component name (*local*/*remote*) and to the
+    name of the mailbox relevant for the log entry.  Conditions on a
+    specifier `%X` can be obtained with `%?X?then?` or `%?X?then&else?`,
+    which expands to *then* if the `%X` specifier expands to a non-empty
+    string, and to *else* (or the empty string if there is no else
+    condition) if it doesn't.  Literal `%` characters need to be escaped
+    as `%%`, while `&`, `?` and `\` characters need to be `\`-escaped.
+    (Default: `%?n?%?m?%n(%m)&%n?: ?`.)
+
 *type*
 
 :   One of `imap`, `imaps` or `tunnel`.
@@ -422,9 +448,10 @@ Known bugs and limitations
 
  * Using `interimap` on two identical servers with a non-existent or
    empty *database* will duplicate each message due to the absence of
-   local ↔ remote UID association.  Hence one needs to manually empty
-   the mail store on one end when migrating to `interimap` from another
-   synchronisation solution.
+   local ↔ remote UID association.  (Should they arise, an external tool
+   such as [`doveadm-deduplicate`(1)] can be used to weed them out.)
+   Hence one needs to manually empty the mail store on one end when
+   migrating to `interimap` from another synchronization solution.
 
  * `interimap` is single threaded and doesn't use IMAP command
    pipelining.  Synchronization could be boosted up by sending
@@ -439,6 +466,13 @@ Known bugs and limitations
    was deleted while another one (which is replicated again) was added
    to the other mailbox in the meantime.
 
+ * Because the [IMAP protocol][RFC 3501] doesn't provide a way for
+   clients to determine whether a disappeared mailbox was deleted or
+   renamed, `interimap` aborts when a known mailbox disappeared from one
+   server but not the other.  The `--delete` (resp. `rename`) command
+   should be used instead to delete (resp. rename) the mailbox on both
+   servers as well as within `interimap`'s internal database.
+
  * `PLAIN` and `LOGIN` are the only authentication mechanisms currently
    supported.
 
@@ -524,3 +558,4 @@ Standards
 [PCRE]: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions
 [`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/ciphers.html
 [`verify`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/verify.html
+[`doveadm-deduplicate`(1)]: https://wiki.dovecot.org/Tools/Doveadm/Deduplicate
diff --git a/doc/pullimap.1.md b/doc/pullimap.1.md
index 1b2e509..d40ece8 100644
--- a/doc/pullimap.1.md
+++ b/doc/pullimap.1.md
@@ -57,10 +57,11 @@ Options
 
 `--debug`
 
-:   Turn on debug mode.  Debug messages are written to the error output.
-    Note that this include all IMAP traffic (except literals).
-    Depending on the chosen authentication mechanism, this might include
-    authentication credentials.
+:   Turn on debug mode.  Debug messages, which includes all IMAP traffic
+    besides literals, are written to the given *logfile*.  The `LOGIN`
+    and `AUTHENTICATE` commands are however redacted (in order to avoid
+    disclosing authentication credentials) unless the `--debug` flag is
+    set multiple times.
 
 `-h`, `--help`
 
diff --git a/doc/template.html b/doc/template.html
index e17f0e3..2cd7cc9 100644
--- a/doc/template.html
+++ b/doc/template.html
@@ -15,12 +15,25 @@ $if(keywords)$
 $endif$
   <title>$if(title-prefix)$$title-prefix$ – $endif$$pagetitle$</title>
   <style type="text/css">
-      code{white-space: pre-wrap;}
-      span.smallcaps{font-variant: small-caps;}
-      span.underline{text-decoration: underline;}
-      div.column{display: inline-block; vertical-align: top; width: 50%;}
+    code{white-space: pre-wrap;}
+    span.smallcaps{font-variant: small-caps;}
+    span.underline{text-decoration: underline;}
+    div.column{display: inline-block; vertical-align: top; width: 50%;}
+    pre{tab-size: 4; -moz-tab-size: 4;}
+    @media only screen and (min-width: 600px) {
+      .parent {
+        float: right;
+        margin-left: 1em;
+      }
+      .content p {
+        text-align: justify;
+      }
+    }
+    @media(max-width: 1440px) { .container{ max-width: 1080px; } }
+    @media(max-width: 1280px) { .container{ max-width: 960px; } }
+    @media(max-width: 1024px) { .container{ max-width: 768px; } }
 $if(quotes)$
-      q { quotes: "“" "”" "‘" "’"; }
+    q { quotes: "“" "”" "‘" "’"; }
 $endif$
   </style>
 $if(highlighting-css)$
@@ -31,11 +44,6 @@ $endif$
 $for(css)$
   <link rel="stylesheet" href="$css$" />
 $endfor$
-  <style type="text/css">
-    @media(max-width: 1440px) { .container{ max-width: 1080px; } }
-    @media(max-width: 1280px) { .container{ max-width: 960px; } }
-    @media(max-width: 1024px) { .container{ max-width: 768px; } }
-  </style>
 $if(math)$
   $math$
 $endif$
@@ -48,21 +56,26 @@ $endfor$
 $for(include-before)$
 $include-before$
 $endfor$
-<div class="container text-justify">
+<div class="container">
   <div class="content">
 $if(title)$
-    <div class="page-header"><h1>$title$</h1></div>
+  <div class="page-header">
+$if(parent)$
+    <div class=parent><a href="$parent$"><span class="glyphicon glyphicon-circle-arrow-up" aria-hidden="true"></span> Parent</a></div>
+$endif$
+    <h1 style="">$title$</h1>
+  </div>
 $endif$
 
 $body$
-  </div>
+</div>
 
   <footer>
     <hr/>
     <div class="row">
       <div class="col-md-8 text-muted">
 $if(author)$
-        <a href="https://git.guilhem.org/interimap/plain/COPYING">&copy;</a>
+        <a href="https://git.guilhem.org/interimap/plain/COPYING">Copyright</a> &copy;
         $for(author)$$author$$sep$, $endfor$
 $endif$
       </div>