docs: refine tutorial and installation pages

docs/configuration/logging.rst

@@ -98,7 +98,7 @@ Formats
         ``encoding/json.Marshal()``, which is particularly useful for processing in
         log aggregation or when processing state dumps.
 
-Outlets are ... well ... outlets for log entries into the world.
+.. _logging-outlet-stdout:
 
 ``stdout`` Outlet
 -----------------

docs/installation.rst

@@ -5,7 +5,7 @@ Installation
 
 .. TIP::
 
-    Note: check out the [tutorial]({{< relref "tutorial/_index.md" >}}) if you want a first impression of zrepl.
+    Note: check out the :ref:`tutorial` if you want a first impression of zrepl.
 
 User Privileges
 ---------------
@@ -15,13 +15,32 @@ It is possible to run zrepl as an unprivileged user in combination with
 Also, there is the possibility to run it in a jail on FreeBSD by delegating a dataset to the jail.
 However, until we get around documenting those setups, you will have to run zrepl as root or experiment yourself :)
 
-Installation
+Packages
-------------
+--------
 
-zrepl is currently not packaged on any operating system. Signed & versioned releases are planned but not available yet.
+zrepl releases are signed & tagged by the author in the git repository.
+Your OS vendor may provide binary packages of zrepl through the package manager.
+The following list may be incomplete, feel free to submit a PR with an update:
 
-Check out the sources yourself, fetch dependencies using dep, compile and install to the zrepl user's `$PATH`.<br />
+.. list-table::
-**Note**: if the zrepl binary is not in `$PATH`, you will have to adjust the examples in the :ref:`tutorial`.
+    :header-rows: 1
+
+    * - OS / Distro
+      - Install Command
+      - Link
+    * - FreeBSD
+      - ``pkg install zrepl``
+      - `<https://www.freshports.org/sysutils/zrepl/>`_
+    * - Others
+      -
+      - Install from source, see below
+
+Compile From Source
+~~~~~~~~~~~~~~~~~~~
+
+Check out the sources yourself, fetch dependencies using ``dep``, compile and install to the zrepl user's ``$PATH``.
+You may want to switch to a tagged commit (we use `semver <http://semver.org>`_) although a checkout of ``master`` branch should generally work.
+**Note**: if the zrepl binary is not in ``$PATH``, the examples in the :ref:`tutorial` may need to be adjusted.
 
 ::
 
@@ -43,17 +62,20 @@ Configuration Files
 
 zrepl searches for its main configuration file in the following locations (in that order):
 
-* `/etc/zrepl/zrepl.yml`
+* ``/etc/zrepl/zrepl.yml``
-* `/usr/local/etc/zrepl/zrepl.yml`
+* ``/usr/local/etc/zrepl/zrepl.yml``
 
 Alternatively, use CLI flags to specify a config location.
+Copy a config from the :ref:`tutorial` or the ``cmd/sampleconf`` directory to one of these locations and customize it to your setup.
 
-Copy a config from the :ref:`tutorial` or the `cmd/sampleconf` directory to one of these locations and customize it to your setup.
+Runtime Directories
+-------------------
 
-## Runtime Directories
+zrepl requires ephemeral runtime directories where control sockets, etc are placed.
+Refer to the :ref:`configuration documentation <conf-runtime-directories>` for more information.
 
-Check the the :ref:`configuration documentation <conf-runtime-directories>` for more information.
+When installing from a package, the package maintainer should have taken care of setting them up through the init system.
-For default settings, the following should to the trick.
+Alternatively, for default settings, the following should to the trick.
 
 ::
 
@@ -65,20 +87,20 @@ Running the Daemon
 ------------------
 
 All actual work zrepl does is performed by a daemon process.
-
 Logging is configurable via the config file. Please refer to the :ref:`logging documention <logging>`.
 
-::
+When installating from a package, the package maintainer should have provided an init script / systemd.service file.
+You should thus be able to start zrepl daemon using your init system.
 
-    zrepl daemon
+Alternatively, or for running zrepl in the foreground, simply execute ``zrepl daemon``.
-
+Note that you won't see any output unless you configure :ref:`stdout logging outlet <logging-outlet-stdout>`.
-There are no *rc(8)* or *systemd.service(5)* service definitions yet. Note the *daemon(8)* utility on FreeBSD.
 
 .. ATTENTION::
 
-    Make sure to actually monitor the error level output of zrepl: some configuration errors will not make the daemon exit.<br />
+    Make sure to actually monitor the error level output of zrepl: some configuration errors will not make the daemon exit.
-    Example: if the daemon cannot create the [stdinserver]({{< relref "configuration/transports.md#stdinserver" >}}) sockets
+
-    in the runtime directory, it will emit an error message but not exit because other tasks such as periodic snapshots & pruning are of equal importance.
+    Example: if the daemon cannot create the :ref:`transport-ssh+stdinserver` sockets in the runtime directory,
+    it will emit an error message but not exit because other tasks such as periodic snapshots & pruning are of equal importance.
 
 .. _install-restarting:
 
@@ -86,7 +108,5 @@ Restarting
 ~~~~~~~~~~
 
 The daemon handles SIGINT and SIGTERM for graceful shutdown.
-
 Graceful shutdown means at worst that a job will not be rescheduled for the next interval.
-
 The daemon exits as soon as all jobs have reported shut down.

docs/tutorial.rst

@@ -168,7 +168,7 @@ If you like tmux, here is a handy script that works on FreeBSD:::
     tmux split-window "gnu-watch 'zfs list -t snapshot -o name,creation -s creation | grep zrepl_pull_backup_'"
     tmux select-layout tiled
 
-The Linux equivalent might look like this::
+The Linux equivalent might look like this: ::
 
     # make sure tmux is installed & let's assume you use systemd + journald
     tmux new-window