Merge tag 'v0.5.7' into debian/latest

Release version 0.5.7

1 files changed, 43 insertions, 22 deletions

diff --git a/doc/build.md b/doc/build.md
index 2e4e511..b40760e 100644
--- a/doc/build.md
+++ b/doc/build.md
@@ -38,10 +38,10 @@ Additional packages are required in order to run the test suite:
 
     $ sudo apt install dovecot-imapd dovecot-lmtpd openssl procps sqlite3 xxd
 <!-- -->
-    $ make test
+    $ make check
 
-(The test suite also needs to bind to TCP ports 10024, 10143 and 10993
-on the loopback interface.)
+(Note also that the test suite needs to bind to TCP ports 10024, 10143
+and 10993 on the loopback interface.)
 
 Generate documentation
 ======================
@@ -51,32 +51,53 @@ Yet another set of packages is needed to generate the documentation:
     $ 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
--l doc/interimap.1` `` in order to read your copy of the [`interimap`(1)]
-manpage.
+manuals.  You'll find them at `build/doc/*.[1-9]`.  Then use for
+instance `` `man -l build/doc/interimap.1` `` to read your local copy of
+the [`interimap`(1)] manual.
 
-The HTML documentation can be built with `` `make html` ``.  HTML files
-are generated alongside their Markdown source by default, but you can
-choose another target directory using the `HTML_ROOTDIR` environment
-variable (the value of which defaults to `./doc`).  Moreover the
-[`libjs-bootstrap`](https://tracker.debian.org/libjs-bootstrap) is
-needed by default for the local CSS file; this can be controlled with
-the `CSS` environment variable (the value of which defaults to
-`/usr/share/javascript/bootstrap/css/bootstrap.min.css`).
+The HTML documentation can be built with `` `make html` ``.  By default
+HTML files are generated at `build/doc/*.html`, and a local CSS file is
+used — namely `/usr/share/javascript/bootstrap4/css/bootstrap.css`,
+shipped the by [`libjs-bootstrap`](https://tracker.debian.org/libjs-bootstrap)
+package.  But this is configurable: use for instance
 
-For instance, use
+    $ make html builddir="$XDG_RUNTIME_DIR/interimap" \
+		CSS="https://cdn.jsdelivr.net/npm/bootstrap@4.6.1/dist/css/bootstrap.min.css"
 
-    $ env CSS="https://guilhem.org/static/css/bootstrap.min.css" \
-		HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \
-		make html
+to generate the HTML documentation under `$XDG_RUNTIME_DIR/interimap/doc`
+using a remote CSS file.
 
-to generate the HTML documentation under directory `$XDG_RUNTIME_DIR/interimap`
-(which needs to exist) using a remote CSS file.
-
-The `doc` target generates all documentation, manpages as well as HTML
+The `doc` target generates all documentation, manuals as well as HTML
 pages.
 
 
+Installation without root privileges
+====================================
+
+By default `` `make install` `` installs [`interimap`(1)] under
+`/usr/local`, hence requires root privileges.  However another prefix
+can be used in order to perform the (un)installation as an unprivileged
+user.  For instance
+
+    $ install -m0700 -vd ${XDG_DATA_HOME:-~/.local/share}/interimap
+    $ make install-nodoc \
+		prefix=$HOME/.local \
+		sitelib=${XDG_DATA_HOME:-~/.local/share}/interimap/lib \
+		systemd_userunitdir=${XDG_DATA_HOME:-~/.local/share}/systemd/user
+
+skips documentation and installs
+
+  * executables into `~/.local/bin` (instead of `/usr/local/bin`);
+  * libraries into `$XDG_DATA_HOME/interimap/lib` or `~/.local/share/interimap/lib`
+    (instead of `/usr/local/lib/site_perl`); and
+  * [systemd user unit files][`systemd.unit`(5)] into `$XDG_DATA_HOME/systemd/user`
+    or `~/.local/share/systemd/user` (instead of `/usr/local/lib/systemd/user`).
+
+Note that for uninstallation one must call `` `make uninstall prefix=…` ``
+with the very same assignment(s) used for installation.
+
+[`systemd.unit`(5)]: https://www.freedesktop.org/software/systemd/man/systemd.unit.html
+
 Build custom Debian packages
 ============================