Improve wording.

1 files changed, 56 insertions, 51 deletions

diff --git a/doc/getting-started.md b/doc/getting-started.md
index 5b59f92..d8f92d5 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -2,10 +2,9 @@
 % [Guilhem Moulin](mailto:guilhem@fripost.org);
   [Gustav Eek](mailto:gustav.eek@fripost.org)
 
-This describes the setup of InterIMAP for a rather usual user-case, where
-messages on a remote IMAP server `imaps://imap.example.net` are
-synchronized locally.  Changes on either end is replicated on the other
-one.
+This document describes the setup of InterIMAP for a rather usual user-case,
+where messages on a remote IMAP server `imap.example.net` are synchronized
+locally.  Changes on either end is replicated on the other one.
 
 
 Local IMAP server
@@ -15,14 +14,14 @@ Background and rationale
 ------------------------
 
 On a workstation, one's mail storage is often found under `~/Maildir`
-(in [*Maildir* format](https://en.wikipedia.org/wiki/Maildir)) or in
-`/var/mail/$USER` (in [*mbox* format](https://en.wikipedia.org/wiki/Mbox)).
-Local mail clients typically access it directly, and maintain their own
-cache in order to speed up message header listing and searches.
+(in [*Maildir* format][Maildir]) or in `/var/mail/$USER` (in [*mbox*
+format][mbox]).  Local mail clients typically access it directly.  They
+also often maintain their own cache in order to speed up message header
+listing and searches.
 
 While bidirectional synchronisation software (such as [OfflineIMAP])
 is often able to handle a mail storage in Maildir format, *InterIMAP is
-not*.  Instead, InterIMAP needs an [IMAP4rev1] server on both ends to
+not*.  Instead, InterIMAP needs an [IMAP4rev1] server on *both* peers to
 synchronize.  This may sound like a severe limitation at first, but by
 seeing both local and remote mail storages though the same “IMAP lens”,
 InterIMAP is able to take advantage of the abstraction layer and do
@@ -33,33 +32,31 @@ extension for stateful synchronization, hence won't work on IMAP servers
 that don't advertize support for that extension.
 
 Installing an [IMAP4rev1] server on a single-user workstation may sound
-overkill, but we argue that Debian GNU/Linux systems generally come with a
-[Message Transfer Agent][MTA] installed, and not only on servers.  Just
-like one may use `/usr/sbin/sendmail` (or a compatible interface) in
-order to send mail out, we propose to use an `imap` binary to access
-them.
+overkill, but we argue that most systems, not only servers, come with a
+[Message Transfer Agent][MTA] preinstalled.  Just like one may use
+`/usr/sbin/sendmail` (or a compatible interface) in order to send mail
+out, we propose to use an `imap` binary to access them.
 
 In order to fully take advantage of the abstraction layer and
 InterIMAP's optimizations, one should *always* access the mail storage
 through the local [IMAP4rev1] server and *never directly*.  Otherwise
-the IMAP server will keep invalidating its cache when it notices
-inconsistencies, yielding a performance hit.  (*Or worse*: very likely
-many [IMAP4rev1] servers are not able to gracefuly deal with cache
-inconsistencies.)  As far as the mail client is concerned, the cost of
-abstraction seems to be negligible (*TODO* link to benchmark).
-Furthermore, we think that approach is in line with the [Unix
-philosophy]: the mail client only takes care of the rendering part,
-leaving the rest to the IMAP server (searches, sorting/threading, as
-well as storage and caching logic).
+the IMAP server will invalidate its cache each time it notices
+inconsistencies, thereby causing a servere performance hit.  (*Or
+worse*: very likely many [IMAP4rev1] servers are not able to gracefuly
+deal with cache inconsistencies.)  As far as the mail client is
+concerned, the cost of abstraction seems to be negligible (*TODO* link
+to benchmark).  Furthermore, we think that approach is in line with the
+[Unix philosophy]: the mail client only takes care of the rendering
+part, leaving the rest to the IMAP server (searches, sorting/threading,
+as well as storage and caching logic).
 
 Installation
 ------------
 
 While this document focuses on [Dovecot](https://dovecot.org), a popular
 [IMAP4rev1] server, any other [`QRESYNC`][RFC 7162]-capable server
-should work equally well.
-
-On Debian GNU/Linux systems, run the following command (as root):
+should work equally well.  Run the following command (as root) to
+install the Dovecot IMAP server on a Debian GNU/Linux system.
 
     $ apt install dovecot-imapd
 
@@ -77,22 +74,27 @@ it can spawn a command and use its standard input (resp. output) for
 is [Mutt], for which we propose a configuration snippet [below][todo
 link].
 
-Since we don't need the Dovecot services nor master process here, we
-simply disable it.  Run the following as root:
+Since we don't need the Dovecot services nor master process in this
+example, we disable them and create a local configuration file under
+`$XDG_CONFIG_HOME/dovecot`.  If you need to keep the system-wise
+services (for instance because your [MTA] uses the [LMTP server] for
+mailbox delivery) then don't disable them, and modify Dovecot's system
+wide configuration instead.  Same thing if your mail client isn't able
+to spawn a command for IMAP communication and insists on connecting to
+an `INET` socket (in that case you'll even need to configure [user
+authentication](https://wiki.dovecot.org/Authentication) for the IMAP
+service, which is out of scope for the present document).
+
+Run the following command (as root) to terminate and disable the
+system-wide Dovecot processes.
 
     $ systemctl mask --now dovecot.socket dovecot.service
 
-*Note*: If your mail client doesn't have this ability, and instead insists on
-connecting to a `INET` socket, then you may have to use `socat`(1) or
-similar to spawn the command; or alternatively, keep the Dovecot master
-process but edit the configuration so the IMAP daemon listens on the
-loopback interface.  This is however out of scope for the present
-document.  Consult the [Dovecot wiki](https://wiki.dovecot.org/) for
-details.
 
-We store the local Dovecot configuration under `$XDG_CONFIG_HOME/dovecot`:
+Create a new directory `$XDG_CONFIG_HOME/dovecot` holding the local
+Dovecot configuration:
 
-    $ mkdir -pvm 0700 ${XDG_CONFIG_HOME:-~/.config}/dovecot
+    $ install -m0700 -vd ${XDG_CONFIG_HOME:-~/.config}/dovecot
 <!-- -->
     $ cat >${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf <<-EOF
 		ssl = no
@@ -119,10 +121,10 @@ Some remarks on the above:
     change it later (on an existing mail store).  Popular hierarchy
     delimiters include `/` (slash) and `.` (period).
 
-Let's now test the configuration by starting a pre-authenticated
-[IMAP4rev1] session and issuing two command, first `` `LIST "" "*"` ``
-to recursively list all mailboxes (along with their hierarchy
-delimiter), then `` `LOGOUT` `` to… log out and exit.
+Now test the configuration by starting a pre-authenticated [IMAP4rev1]
+session and issuing two commands, first `` `LIST "" "*"` `` to
+recursively list all mailboxes (along with their hierarchy delimiter),
+then `` `LOGOUT` `` to… log out and exit.
 
     $ doveadm -c ${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf exec imap
     * PREAUTH [CAPABILITY IMAP4rev1 …] Logged in as myuser
@@ -134,7 +136,7 @@ delimiter), then `` `LOGOUT` `` to… log out and exit.
     q OK Logout completed (0.001 + 0.000 secs).
 
 Create a wrapper under `~/.local/bin` in order to avoid hard-coding the
-Dovecot configuration path:
+local Dovecot configuration path:
 
     $ install -Dm 0755 /dev/stdin ~/.local/bin/dovecot-imap <<-EOF
 		#!/bin/sh
@@ -145,22 +147,22 @@ Dovecot configuration path:
 		        exec imap
 	EOF
 
-You can now start a pre-authenticated [IMAP4rev1] session to your local
-mail store by simply running `` `~/.local/bin/dovecot-imap` ``.
+You can now start a pre-authenticated [IMAP4rev1] session like the one
+above by simply running `` `~/.local/bin/dovecot-imap` ``.
 
 
 InterIMAP
 ========
 
-On Debian 9 (codename Stretch) and later, installing the packange is one
-command away.  Simply run the following (as root):
+On Debian 10 (codename *Buster*) and later, installing the package is
+one command away.  Simply run the following (as root):
 
     $ apt install interimap
 
-Create config file:
+Create directories for the InterIMAP configuration and data files:
 
-    $ mkdir -pvm 0700 ${XDG_CONFIG_HOME:-~/.config}/interimap \
-        ${XDG_DATA_HOME:-~/.local/share}/interimap
+    $ install -m0700 -vd ${XDG_CONFIG_HOME:-~/.config}/interimap \
+                         ${XDG_DATA_HOME:-~/.local/share}/interimap
 <!-- -->
     $ install -m0600 /dev/stdin ${XDG_CONFIG_HOME:-~/.config}/interimap/config <<-EOF
 		# only consider subscribed mailboxes
@@ -192,7 +194,7 @@ between synchronization runs to 20s:
 
     $ mkdir -p ${XDG_CONFIG_HOME:-~/.config}/systemd/user/interimap.service.d
 <!-- -->
-    $ install -m 0644 /dev/stdin ${XDG_CONFIG_HOME:-~/.config}/systemd/user/interimap.service.d/override.conf" <<-EOF
+    $ cat >${XDG_CONFIG_HOME:-~/.config}/systemd/user/interimap.service.d/override.conf" <<-EOF
 		[Service]
 		ExecStart=
 		ExecStart=/usr/bin/interimap --watch=20
@@ -221,8 +223,11 @@ Put in your mutt configuration (XXX):
 
 [IMAP4rev1]: https://tools.ietf.org/html/rfc3501
 [`interimap`(1)]: interimap.1.html
-[OfflineIMAP]: https://www.offlineimap.org/
+[LMTP server]: https://wiki.dovecot.org/LMTP
+[Maildir]: https://en.wikipedia.org/wiki/Maildir
+[mbox]: https://en.wikipedia.org/wiki/Mbox
 [MTA]: https://en.wikipedia.org/wiki/Message_transfer_agent
 [Mutt]: http://mutt.org/
+[OfflineIMAP]: https://www.offlineimap.org/
 [RFC 7162]: https://tools.ietf.org/html/rfc7162
 [Unix philosophy]: https://en.wikipedia.org/wiki/Unix_philosophy