aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/build.md13
-rw-r--r--doc/development.md51
2 files changed, 34 insertions, 30 deletions
diff --git a/doc/build.md b/doc/build.md
index 5c362f1..d704f71 100644
--- a/doc/build.md
+++ b/doc/build.md
@@ -4,7 +4,7 @@
On Debian 9 (codename *Stretch*) and later, installing [`interimap`(1)]
is a single command away:
- $ apt-get install interimap
+ $ sudo apt install interimap
This document is for those who are running other systems, and/or who
wish to install from [source](https://git.guilhem.org/interimap).
@@ -32,24 +32,23 @@ following Perl modules:
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
+ $ sudo apt install libconfig-tiny-perl libdbd-sqlite3-perl libnet-ssleay-perl
Additional packages are required in order to run the test suite:
- $ apt install dovecot-imapd procps sqlite3 xxd
+ $ sudo apt install dovecot-imapd dovecot-lmtpd openssl procps sqlite3 xxd
<!-- -->
$ make test
+(The test suite also needs to bind to TCP ports 10024, 10143 and 10993
+on the loopback interface.)
Generate documentation
======================
Yet another set of packages is needed to generate the documentation:
- $ apt install jq pandoc
+ $ sudo apt install jq pandoc
Run `` `make manual` `` (or just `` `make` ``) in order to generate the
manpages. You'll find them at `doc/*.[1-9]`. Use for instance `` `man
diff --git a/doc/development.md b/doc/development.md
index b5624f0..52ebf90 100644
--- a/doc/development.md
+++ b/doc/development.md
@@ -5,9 +5,8 @@ Introduction
============
This document describes how to create dummy mail storage for
-[`interimap`(1)] and/or [`pullimap`(1)] development, using
-[Dovecot](https://dovecot.org) as [IMAP4rev1] server. Start by creating
-a new temporary directory:
+[`interimap`(1)] and/or [`pullimap`(1)] development, using [Dovecot] as
+[IMAP4rev1] server. Start by creating a new temporary directory:
$ BASEDIR="$(mktemp --tmpdir --directory)"
@@ -30,9 +29,9 @@ Here are some details on the above:
`log_path`
- : Dovecot [logs to syslog](https://wiki.dovecot.org/Logging) by default.
- It's annoying to clutter syslog with test entries, so instead we make it
- log to a file under `$BASEDIR`.
+ : Dovecot [logs to syslog][Dovecot Logging] by default. It's annoying
+ to clutter syslog with test entries, so instead we make it log to a
+ file under `$BASEDIR`.
`mail_home`
@@ -42,13 +41,13 @@ Here are some details on the above:
can be used to determine the username. When this option is not set,
the username is taken from the `USER` environment variable. If that
environment variable is unset as well, then the return string of
- [`getlogin`(3)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/getlogin.html)
- is used.
+ [`getlogin`(3)] is used.
Similarly, the user's home directory is used in (`~`- and)
[`%`-variable] expansion. It's taken from the `HOME` environment
variable when the `mail_home` setting is left unset in the Dovecot
- configuration (and not overridden by the [user database](https://wiki.dovecot.org/UserDatabase)).
+ configuration (and not overridden by the [user database][User
+ Databases].
`mail_home` can therefore be left unset if the `HOME` environment
variable is consistently set to `$BASEDIR/$USER`. However it's
@@ -58,14 +57,12 @@ Here are some details on the above:
`mail_location`
- : The user's mail storage resides — in [Maildir](https://wiki.dovecot.org/MailLocation/Maildir)
- format — in a directory `Mail` under their home directory. This is
- enough if you're fine with the default IMAP hierarchy delimiter
- (which depends on the mail format) is used, and if you need a single
- [IMAP namespace](https://tools.ietf.org/html/rfc2342). For more
- complex setups you'll need one or more
- [`namespace {…}` block](https://wiki.dovecot.org/Namespaces).
-
+ : The user's mail storage resides — in [Maildir] format — in a directory
+ `Mail` under their home directory. This is enough if you're fine with
+ the default IMAP hierarchy delimiter (which depends on the mail format)
+ is used, and if you need a single [IMAP namespace][RFC 2342]. For more
+ complex setups you'll need one or more [`namespace {…}` block][Dovecot
+ Namespaces].
Mail storage access
===================
@@ -107,10 +104,10 @@ finally mark it as `\Seen`.
$ env -i PATH="/usr/bin:/bin" USER="testuser" \
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
-didn't configure a user database we need to explicitly set the `HOME`
-environment variable.
+Normally [`dovecot-lda`(1)][Dovecot LDA] tries to do a userdb lookup in
+order to determine the user's home directory. Since we didn't configure
+a user database we need to explicitly set the `HOME` environment
+variable.
InterIMAP configuration and test
@@ -145,7 +142,7 @@ Run [`interimap`(1)] without `--watch` in order to create the database.
[…]
You can now run [`interimap`(1)] with `--watch` set, here to one second
-to observe synchronisation steps early.
+to observe synchronization steps early.
$ env -i PATH="$PATH" perl -I./lib -T ./interimap --config="$BASEDIR/interimap.conf" \
--watch=1 --debug
@@ -195,7 +192,15 @@ recursively remove the directory `$BASEDIR`.
[IMAP4rev1]: https://tools.ietf.org/html/rfc3501
+[Dovecot]: https://dovecot.org
+[Dovecot Logging]: https://doc.dovecot.org/admin_manual/dovecot_logging/
+[Dovecot LDA]: https://wiki.dovecot.org/LDA
+[`getlogin`(3)]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getlogin.html
+[User Databases]: https://doc.dovecot.org/configuration_manual/authentication/user_databases_userdb/
+[Maildir]: https://wiki.dovecot.org/MailLocation/Maildir
+[RFC 2342]: https://tools.ietf.org/html/rfc2342
+[Dovecot Namespaces]: https://doc.dovecot.org/configuration_manual/namespace/
[`interimap`(1)]: interimap.1.html
[`pullimap`(1)]: pullimap.1.html
[`doveadm`(1)]: https://wiki.dovecot.org/Tools/Doveadm
-[`%`-variable]: https://wiki.dovecot.org/Variables
+[`%`-variable]: https://doc.dovecot.org/configuration_manual/config_file/config_variables/