aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/benchmark.md4
-rw-r--r--doc/build.md65
-rw-r--r--doc/development.md12
-rw-r--r--doc/getting-started.md5
4 files changed, 54 insertions, 32 deletions
diff --git a/doc/benchmark.md b/doc/benchmark.md
index 72f51a4..f2f6cda 100644
--- a/doc/benchmark.md
+++ b/doc/benchmark.md
@@ -48,8 +48,8 @@ by placing packet counters on the interface.
[OfflineIMAP]: https://www.offlineimap.org/
[benchmark-script]: https://git.guilhem.org/interimap/plain/benchmark/run
[Dovecot]: https://dovecot.org
-[dbox]: https://wiki.dovecot.org/MailboxFormat/dbox
-[maildir]: https://wiki.dovecot.org/MailboxFormat/Maildir
+[dbox]: https://doc.dovecot.org/admin_manual/mailbox_formats/dbox/
+[maildir]: https://doc.dovecot.org/admin_manual/mailbox_formats/maildir/
-----------------------------------------------------------------------
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
============================
diff --git a/doc/development.md b/doc/development.md
index f4578b9..0fe54f4 100644
--- a/doc/development.md
+++ b/doc/development.md
@@ -136,7 +136,7 @@ and `remote` accounts.
Run [`interimap`(1)] without `--watch` in order to create the database.
- $ env -i PATH="$PATH" perl -I./lib -T ./interimap --config="$BASEDIR/interimap.conf"
+ $ env -i PATH="$PATH" perl -T ./interimap --config="$BASEDIR/interimap.conf"
Creating new schema in database file …/interimap.db
database: Created mailbox INBOX
[…]
@@ -144,7 +144,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 synchronization steps early.
- $ env -i PATH="$PATH" perl -I./lib -T ./interimap --config="$BASEDIR/interimap.conf" \
+ $ env -i PATH="$PATH" perl -T ./interimap --config="$BASEDIR/interimap.conf" \
--watch=1 --debug
Use instructions from the [previous section][Mail storage access]
@@ -168,12 +168,12 @@ Create a [`pullimap`(1)] configuration file with as section `[foo]`.
Run [`pullimap`(1)] without `--idle` in order to create the state file.
- $ env -i PATH="$PATH" perl -I./lib -T ./pullimap --config="$BASEDIR/pullimap.conf" \
+ $ env -i PATH="$PATH" perl -T ./pullimap --config="$BASEDIR/pullimap.conf" \
--no-delivery foo
You can now run [`pullimap`(1)] with `--idle` set.
- $ env -i PATH="$PATH" perl -I./lib -T ./pullimap --config="$BASEDIR/pullimap.conf" \
+ $ env -i PATH="$PATH" perl -T ./pullimap --config="$BASEDIR/pullimap.conf" \
--no-delivery --idle --debug foo
Use instructions from the [previous section][Mail storage access]
@@ -194,10 +194,10 @@ recursively remove the directory `$BASEDIR`.
[IMAP4rev1]: https://tools.ietf.org/html/rfc3501
[Dovecot]: https://dovecot.org
[Dovecot Logging]: https://doc.dovecot.org/admin_manual/logging/
-[Dovecot LDA]: https://wiki.dovecot.org/LDA
+[Dovecot LDA]: https://doc.dovecot.org/configuration_manual/protocols/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
+[Maildir]: https://doc.dovecot.org/configuration_manual/mail_location/Maildir/
[RFC 2342]: https://tools.ietf.org/html/rfc2342
[Dovecot Namespaces]: https://doc.dovecot.org/configuration_manual/namespace/
[`interimap`(1)]: interimap.1.html
diff --git a/doc/getting-started.md b/doc/getting-started.md
index 74fc8da..7a77a6b 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -84,7 +84,7 @@ 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 instead insists on
connecting to a network socket (in that case you'll even need to
-configure [user authentication](https://wiki.dovecot.org/Authentication)
+configure [user authentication](https://doc.dovecot.org/configuration_manual/authentication/)
for the IMAP service, which is out of scope for the present document).
Run the following command to terminate and disable the system-wide
@@ -113,7 +113,8 @@ Some remarks on the above:
running `` `doveconf -nc ${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf` ``.
* Messages will be stored in Maildir format under `~/Mail`. Ensure
the directory is either *empty* or *doesn't exist* before
- continuing! You may want to choose a different [format](https://wiki.dovecot.org/MailboxFormat)
+ continuing! You may want to choose a different
+ [format](https://doc.dovecot.org/admin_manual/mailbox_formats/)
here, or simply append `:LAYOUT=fs` to the `mail_location` value in
order to use a nicer (File System like) Maildir layout.
* The `separator` setting defines the IMAP hierarchy delimiter. This