diff options
| -rw-r--r-- | doc/build.md | 13 | ||||
| -rw-r--r-- | doc/development.md | 51 |
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/ |