From eeb05129383b802b8e9b98ecaa592ce90e3d2be4 Mon Sep 17 00:00:00 2001
From: Guilhem Moulin <guilhem@fripost.org>
Date: Tue, 9 Jul 2019 05:21:26 +0200
Subject: Improve presentation of interimap config.

---
 doc/getting-started.md | 94 ++++++++++++++++++++++++++++++++++++--------------
 tests/run              |  2 +-
 2 files changed, 69 insertions(+), 27 deletions(-)

diff --git a/doc/getting-started.md b/doc/getting-started.md
index d8f92d5..bc23b3a 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -163,34 +163,71 @@ Create directories for the InterIMAP configuration and data files:
 
     $ 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
-		list-select-opts = SUBSCRIBED
-		# ignore the mailbox named 'virtual' and its descendants
-		# WARN: for <=0.4 it should be: ^virtual(?:/|$)
-		ignore-mailbox = ^virtual(?:\x00|$)
-
-		[local]
-		type = tunnel
-		command = exec ~/.local/bin/dovecot-imap
-
-		[remote]
-		type = imaps
-		host = imap.example.net
-		username = myname
-		password = xxxxxxxx
-	EOF
 
-Create the database:
+Create the configuration file.  The included sample file
+`/usr/share/doc/interimap/interimap.sample` can be used as baseline, but
+for the sake of clarity we start from an empty file here.
+
+    $ install -m0600 /dev/null ${XDG_CONFIG_HOME:-~/.config}/interimap/config
+
+ 1. The file is in [INI format][INI file].  First, set general options
+    in the default section:
+
+        $ cat >${XDG_CONFIG_HOME:-~/.config}/interimap/config <<-EOF
+			# only consider subscribed mailboxes
+			list-select-opts = SUBSCRIBED
+			#list-mailbox = "*"
+
+			# ignore the mailbox named 'virtual' and its descendants
+			# WARN: for <=0.4 it should be: ^virtual(?:/|$)
+			ignore-mailbox = ^virtual(?:\x00|$)
+
+		EOF
+
+ 2. Next, append a `[local]` section pointing to the wrapper defined
+    above:
+
+        $ cat >>${XDG_CONFIG_HOME:-~/.config}/interimap/config <<-EOF
+			[local]
+			type = tunnel
+			command = exec ~/.local/bin/dovecot-imap
+
+		EOF
+
+ 3. And finally append a `[remote]` section with your account
+    information at `imap.example.org` (adapt the values accordingly):
+
+        $ cat >>${XDG_CONFIG_HOME:-~/.config}/interimap/config <<-EOF
+			[remote]
+			type = imaps
+			host = imap.example.net
+			username = myname
+			password = xxxxxxxx
+		EOF
+
+At this point running [`interimap`(1)] should create the database and
+copy the entire remote mail store locally.  (If `~/Mail` was not empty,
+it will also copy its content remotely, possibly *yielding duplicates*.)
+Depending on the volume of messages this might take a while.
 
     $ interimap
-    Creating new schema in database file …/interimap.db
+    Creating new schema in database file …/imap.example.net.db
     database: Created mailbox INBOX
     […]
 
-Override systemd unit if desired, for instance to reduce the interval
-between synchronization runs to 20s:
+A user unit for systemd is provided.  To enable and start the service,
+simply run the following command:
+
+    $ systemctl --user enable --now interimap
+
+By default the connection to the IMAP servers remains open, and a status
+update is requested every minute.  Thanks to the [`QRESYNC`][RFC 7162]
+IMAP extension a status update scales linearly with the number of
+mailboxes (not to the number of messages like [OfflineIMAP]).  And
+thanks to the `COMPRESS` extension, the typical volume of data exchanged
+is rather small (*TODO* metrics).  You may want to override the default
+settings, and for instance reduce the interval between status updates to
+20s:
 
     $ mkdir -p ${XDG_CONFIG_HOME:-~/.config}/systemd/user/interimap.service.d
 <!-- -->
@@ -201,10 +238,8 @@ between synchronization runs to 20s:
 	EOF
 <!-- -->
     $ systemctl --user daemon-reload
-
-Enable unit and start it:
-
-    $ systemctl --user enable --now interimap
+<!-- -->
+    $ systemctl --user restart interimap
 
 
 Configure email client
@@ -221,7 +256,14 @@ Put in your mutt configuration (XXX):
     $ mutt -n -F /tmp/muttrc
 
 
+Further Reading and Resources
+=============================
+
+Manual, links to other use-case, benchmarks, etc.
+
+
 [IMAP4rev1]: https://tools.ietf.org/html/rfc3501
+[INI file]: https://en.wikipedia.org/wiki/INI_file
 [`interimap`(1)]: interimap.1.html
 [LMTP server]: https://wiki.dovecot.org/LMTP
 [Maildir]: https://en.wikipedia.org/wiki/Maildir
diff --git a/tests/run b/tests/run
index ee11757..a01300e 100755
--- a/tests/run
+++ b/tests/run
@@ -99,7 +99,7 @@ prepare() {
         fi
         cat >>"$HOME_local/.config/interimap/config$cfg" <<-EOF
 			database = $u.db
- 
+
 			[local]
 			type = tunnel
 			command = exec ${HOME_local@Q}/.local/bin/doveadm exec imap
-- 
cgit v1.2.3