diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build.md | 18 | ||||
| -rw-r--r-- | doc/development.md | 18 | ||||
| -rw-r--r-- | doc/index.md | 4 | ||||
| -rw-r--r-- | doc/interimap.1.md | 55 | ||||
| -rw-r--r-- | doc/pullimap.1.md | 9 | ||||
| -rw-r--r-- | doc/template.html | 41 |
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">©</a> + <a href="https://git.guilhem.org/interimap/plain/COPYING">Copyright</a> © $for(author)$$author$$sep$, $endfor$ $endif$ </div> |