README.rst: Major overhaul and cleanup after switching to ReStructuredText.

1 files changed, 278 insertions, 112 deletions

diff --git a/README.rst b/README.rst
index e962f6f..249b5ab 100644
--- a/README.rst
+++ b/README.rst
@@ -1,195 +1,361 @@
-# uenv
-## About
-**uenv** - as in *"useful environments"* - is a collection of scripts, systemd service and timer units and configuration that go along with it.  
-A couple of them might only be useful, when using window managers like [Awesome](http://awesome.naquadah.org/), that stem from a minimalistic approach...
-Some of the functionalities implemented here can be found in desktop environments like [KDE](https://www.kde.org/) or [Gnome](https://www.gnome.org/).
-
-## Features
-
-* modified/ added systemd system services for
-  * autossh
-  * cpupower
-  * rtorrent
-  * update-mirrorlist
-
-* modified/ added systemd user services for
-  * compton
-  * gpg-agent
-  * irssi
-  * jack
-  * mpd
-  * rtorrent
-  * ssh-agent
-  * syndaemon
-  * systemd-analyze
-  * tmux
-  * weechat
-
-* special systemd user services
-  * monitoring
-  * postpone-screensaver
-
-## HOWTO & Info
-Here are some short HOWTOs and infos on using some of the special or modified systemd services.  
-
-### Real-time kernel command line option
-Some services are dependant or anti-dependant on the kernel command line option *"systemd.setenv=REALTIME=true"*. The option itself sets nothing but an Environment for systemd.  
-This is pretty useful when wanting to enable or disable certain services using *ConditionKernelCommandLine* in their **[Unit]** sections,
-
-### Separate tmux environment
-[tmux](https://tmux.github.io/) is used for a couple of services to start an environment in which other command line interface programs can run. To achieve this and not get in conflict with the standard [tmux](https://tmux.github.io/) environment, some modifications might be needed.  
-In some services the following Environment will be set:
-    
+uenv
+####
+
+| *uenv* - as in `*u*seful *env*ironments` - is a collection of scripts, |systemd| |systemd.service| and |systemd.timer| units and configuration that go along with it.  
+| It is meant to help organizing your workflow and hiding away user and system services in neat little separate environments.
+| Arguably a couple of the |systemd.unit| might only be useful, when using window managers like |awesome|, that stem from a minimalistic approach.
+| Some of the functionalities implemented here can be found in desktop environments like |kde| or |gnome|.
+| *uenv* and all of its components are licensed under the GPLv3.
+
+Separate tmux environments
+--------------------------
+| |tmux| is a very useful tool to multiplex your terminals. It offers tiling and a high configurability.
+| Here it is used for a couple of services to start an environment in which other |cli| programs can run.
+| In those services the following |systemd.exec| is set:
+
+  .. code:: systemd
+
     Environment=TMUX_TMPDIR=%t/tmux
 
-This will store the [tmux](https://tmux.github.io/) server socket in the users run directory. If after starting this service one wants to connect to that special [tmux](https://tmux.github.io/) session, it is necessary to either define the absolute path to the socket  
+| This will store the |tmux| server socket in the users' *XDG_RUNTIME_DIR*. Therefore it will be necessary to set your *TMUX_TMPDIR* |environment_variable| for your |bash| or |zsh| (or whatever you run) to the following:
 
-    tmux -S /run/user/<your-user-id>/tmux/<name-of-socket> attach
+  .. code:: bash
 
-or to just set your *"$TMUX\_TMPDIR"* variable to the same directoy in your shells configuration files and then just attach to it, like so:  
+    export TMUX_TMPDIR="$XDG_RUNTIME_DIR/tmux/"
+
+| Afterwards a simple
+
+  .. code:: bash
 
     tmux -L <name-of-socket> attach
 
-### compton
-The [compton](https://github.com/chjj/compton/) user service will need a properly exported **$DISPLAY** variable to work. You can set this in */etc/systemd/user.conf*:  
+| will attach you to that separate environment.
+| *Note*: All of these separate environments are dependant on your login. If there is no login, |systemd| will kill all of your user services! You can get around this by using |loginctl| to set *enable-linger* for your user.
+
+"REALTIME" kernel parameter
+-----------------------------------------
+| Some services are dependant or anti-dependant on the |kernel_parameter| *"systemd.setenv=REALTIME=true"*. The option itself sets nothing but an Environment for systemd.  
+| This is pretty useful when wanting to enable or disable certain services using *ConditionKernelCommandLine* in their *[Unit]* sections, when you're on a |real-time_kernel|.
+| Simply add this to your kernel parameters, using |grub|, |syslinux|, or |systemd-boot|:
+
+  .. code:: bash
+
+    systemd.setenv=REALTIME=true
+
+Services
+--------
+
+compton --user
+______________
+| The |compton| user service needs a properly exported *$DISPLAY* variable to work. You can set this in your |systemd-user.conf|:
+
+  .. code:: systemd
 
-    ...
     DefaultEnvironment=DISPLAY=:0
-    ...
 
-The compton user service is anti-dependent on the real-time kernel command line option. It will not start, when booting into a kernel with that option set.  
-You can start and enable it like any other systemd user service:  
+| The compton user service is anti-dependent on the `REALTIME kernel parameter` (i.e. it will not start, when booting into a kernel with that option set).
+| You can start and enable it like any other systemd user service:  
+
+  .. code:: systemd
 
      systemctl --user start compton
      systemctl --user enable compton
 
-### cpupower
-The cpupower package (on Archlinux) has some [limitations](https://bugs.archlinux.org/task/44270?project=5&cat[0]=33&string=cpupower), that make it quite hard to apply CPU settings based on profiles.  
-At least in a real-time environment, the modified version of cpupower - called cpupower-rt - makes it easy to apply differing settings **after** the usual cpupower settings have been applied.  
-Once the above mentioned feature request is resolved, it will be as easy as just copying the *cpupower.service* file and modify it slightly in */etc/systemd/sytem/*.  
-For now, there needs to be a separate config file **and** a separate script. For setting it up, just modify */etc/default/cpupower-rt* as you would for */etc/default/cpupower*.
+cpupower-rt
+___________
+| The cpupower package on |arch_linux| has some [limitations](https://bugs.archlinux.org/task/44270?project=5&cat[0]=33&string=cpupower), which make it quite hard to apply CPU settings based on profiles.  
+| At least in a real-time environment, the modified version of cpupower - called cpupower-rt - makes it easy to apply differing settings **after** the usual cpupower settings have been applied.  
+| jOnce the above mentioned feature request is resolved, it will be as easy as just copying the *cpupower.service* file and modify it slightly in */etc/systemd/sytem/*.
 
-This service is dependant on the real-time kernel command line option. It will only start, if that condition is met.  
-You can start and enable it like any other systemd service:  
+| For now, there needs to be a separate config file *and* a separate script. For setting it up, just modify */etc/default/cpupower-rt* as you would for */etc/default/cpupower*.
+
+| The *cpupower-rt.service* is dependant on the `REALTIME kernel parameter`. It will only start, if that condition is met.  
+| You can start and enable it like any other systemd service:
+
+  .. code:: systemd
 
     systemctl start cpupower-rt
     systemctl enable cpupower-rt
 
-### irssi
-The systemd user service *irssi.service* starts the [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) client [irssi](http://irssi.org/) in a separate [tmux](https://tmux.github.io/) environment for the current user.
-To connect to it after starting the service, just do  
+irssi --user
+____________
+| The systemd user service *irssi.service* starts the |irc| client |irssi| in a separate |tmux| environment for the current user.
+| To connect to it after starting the service, just do
 
-    tmux -S /run/user/<your-user-id>/tmux/irssi attach
-
-or (if you've setup *$TMUX_TMPDIR* properly in your shell)  
+  .. code:: systemd
 
     tmux -L irssi attach
 
-### JACK
+jack@ --user
+____________
 JACK2 comes with a dbus interface. Unfortunately systemd's efforts regarding [kdbus](https://en.wikipedia.org/wiki/Kdbus) and integrating kernel CPU [cgroups](https://www.kernel.org/doc/Documentation/cgroups/) (and thereby also real-time scheduling) is still somewhat in limbo.  
-The included jack@.service starts JACK using */usr/bin/jackd"* (so no dbus), according to a profile. The name of that profile follows after the *@* on starting/ activating the unit.  
+The included jack@.service starts JACK using */usr/bin/jackd"* (so no dbus), according to a profile. The name of that profile follows after the *@* on starting/ activating the unit and must be found in either `/etc/jack/` or `~/.config/jack/`.  
 
     systemctl --user start jack@fw1
     systemctl --user enable jack@fw1
 
 This service is dependant on the real-time kernel command line option. It will only start, if that condition is met.  
 
-### Monitoring
-The systemd user service *monitoring.service* is just a useful tool, that's hopefully going to expand in features in the near future. It starts htop, glances and a *"loginctl user-status"* for the current user in a separate [tmux](https://tmux.github.io/) environment.  
-To connect to it after starting the service, just do  
-
-    tmux -S /run/user/<your-user-id>/tmux/mon attach
+monitoring --user
+_________________
+| The systemd user service *monitoring.service* is just a useful tool for monitoring.
+| Currently it starts |htop|, |glances| and asks loginctl for the current user processes in a `separate |tmux| environment`.
+| To connect to it after starting the service, just do  
 
-or (if you've setup *$TMUX_TMPDIR* properly in your shell)  
+  .. code:: systemd
 
     tmux -L mon attach
 
-### MPD
-The specialized systemd user service *mpd@.service* starts MPD with a separate configuration located in *~/.config/mpd/mpd-<name-of-server>.conf*. It will also use [pax11publish](http://linux.die.net/man/1/pax11publish) to connect pulseaudio to that server!
-Start and enable it like any other systemd user service:
+mpd@ --user
+___________
+| The specialized systemd user service *mpd@.service* starts |mpd| with a separate configuration located in *~/.config/mpd/mpd-<name-of-server>.conf*. It will also use |pax11publish| to connect pulseaudio to that server!
+| Start and enable it like any other systemd user service:
+
+  .. code:: bash
 
     systemctl --user start mpd@myserver
     systemctl --user enable mpd@myserver
 
-The systemd user service mpd-new.service is a drop-in replacement for mpd.service. It properly starts MPD with a real-time budget and will remain in this repository as long as [upstream decides to ship a version broken for newer systems](http://bugs.musicpd.org/view.php?id=4227).  
-You can use it instead of mpd.service, if you want to use real-time scheduling on newer systemd (>205) based systems.  
+mpd-new --user
+______________
+| The systemd user service *mpd-new.service* is a drop-in replacement for *mpd.service*. It properly starts |mpd| with a real-time budget and will remain in this repository as long as upstream decides to ship a |mpd_bug|.
+| You can use it instead of *mpd.service*, if you want to use real-time scheduling on newer systemd (>205) based systems.
+
+  .. code:: bash
 
     systemctl --user start mpd-new
     systemctl --user enable mpd-new
 
-### postpone-screensaver
-With the systemd user service and timer *postpone-screensaver.{service,timer}* one can - as the name implies - postpone one's screensaver from blanking the screen. The script checks for programs set in *~/.config/postpone-screensaver* and can be started and activated like any other timer/service:  
+postpone-screensaver --user
+___________________________
+| With the systemd user service and timer *postpone-screensaver.{service,timer}* one can - as the name implies - postpone one's screensaver from blanking the screen. The script checks for programs set in *~/.config/postpone-screensaver* and can be started and activated like any other timer/service:
+
+  .. code:: bash
 
     systemctl --user start postpone-screensaver.timer 
     systemctl --user enable postpone-screensaver.timer 
 
-### rtorrent
-rtorrent doesn't really come with any systemd service. Here it is started within a separate [tmux](https://tmux.github.io/) environment. It will automatically create *~/Downloads/rtorrent/{tmp,session}*, if non-existent, set its working directory to *~/Downloads*.  
-The systemd user service is started/ enabled like this:  
+rtorrent --user
+_______________
+| rtorrent doesn't really come with any systemd service. Here it is started within a `separate |tmux| environment`. It will automatically create *~/Downloads/rtorrent/{tmp,session}*, if non-existent and set its working directory to *~/Downloads*.
+| The systemd user service is started/ enabled like this:
+
+  .. code:: bash
 
     systemctl --user start rtorrent
     systemctl --user enable rtorrent
 
-The systemd system service is quite similar in functionality, but on top offers the possibility of dependency to a system service - like [OpenVPN](http://openvpn.net/). The default is a OpenVPN profile called *ipredator*.   
-**Note:** In a separate configuration file (*"/etc/conf.d/rtorrent@.conf"*), the *TMUX_TMPDIR* should be set, as it otherwise defaults to using *"/tmp/"*!   
-The system service can be started and enabled like this:  
+rtorrent
+________
+| The systemd system service rtorrent.service is quite similar in functionality, but on top offers the possibility of dependency to a system service - like |openvpn| (the default being a profile called *secure*).
+| **Note:** In a separate configuration file (*"/etc/conf.d/rtorrent@.conf"*), the *TMUX_TMPDIR* should be set, as it otherwise defaults to using *"/tmp/"*!
+| The system service can be started and enabled like this:
+
+  .. code:: bash
 
     systemctl start rtorrent@<your-user-name>
     systemctl enable rtorrent@<your-user-name>
 
-To connect to the user and system service after starting the service, just do  
-
-    tmux -S /run/user/<your-user-id>/tmux/rt attach
+| To connect to the user and system service after starting the service, just do
 
-or (if you've setup *$TMUX_TMPDIR* properly in your shell and for the **rtorrent@.service**, too)  
+  .. code:: bash
 
     tmux -L rt attach
 
-### syndaemon
-The [xf86-input-synaptics](https://www.archlinux.org/packages/extra/x86_64/xf86-input-synaptics/) package comes with */usr/bin/syndaemon*. This tool is used to disable the touchpad while typing. While desktop environments like KDE and Gnome use it integrated, it can also be started as a systemd user service:  
+syndaemon
+_________
+The |xf86-input-synaptics| package comes with */usr/bin/syndaemon*. This tool is used to disable the touchpad while typing. While desktop environments like |kde| and |gnome| use it integrated, it can also be started as a systemd user service:  
+
+  .. code:: bash
 
     systemctl --user start syndaemon
     systemctl --user enable syndaemon
 
-### systemd-analyze-plot
-Systemd comes with a functionality to plot the system's boot up process in svg and other file formats. This user service uses */usr/bin/systemd-analyze* to plot a svg to a predefined directory. Configuration takes place in *~/.config/systemd/plot.conf*.  
-To start/enable the service afterwards just do:  
+systemd-analyze-plot
+____________________
+| Systemd comes with a functionality to plot the system's boot up process in svg and other file formats. This user service uses */usr/bin/systemd-analyze* to plot a svg to a predefined directory. Configuration takes place in *~/.config/systemd/plot.conf*.
+| To start/enable the service afterwards just do:  
+
+  .. code:: bash
 
     systemctl --user start systemd-analyze-plot
     systemctl --user enable systemd-analyze-plot
 
-### tmux
-[tmux](https://tmux.github.io/) is a very useful tool to multiplex your terminals. It offers tiling and a high configurability.  
-The systemd user service for tmux starts it in a separate environment (set in *$TMUX\_TMPDIR*). This way it is started as soon as the *user@.service* starts, but will also close, when your last session closes!  
-To start/enable it, just do:  
+tmux --user
+___________
+| The systemd user service *tmux.service* starts a `separate |tmux| environment`.
+| To start/enable it, just do:
+
+  .. code:: bash
 
     systemctl --user start tmux
     systemctl --user enable tmux
 
-To connect to the user service after starting it, just do  
+| To connect to the user service after starting it, just do
 
-    tmux -S /run/user/<your-user-id>/tmux/default attach
-
-or (if you've setup *$TMUX_TMPDIR* properly in your shell)  
+  .. code:: bash
 
     tmux attach
 
-## update-mirrorlist
-[Udpate-mirrorlist](https://github.com/ushis/update-mirrorlist) is a program to update the system's pacman mirrorlist according to some predefined settings. Here it is started on a weekly basis according to a timer unit.
-To start/enable it, just do:  
+update-mirrorlist
+_________________
+| |update-mirrorlist| is a script to update the system's |pacman| mirrorlist according to some predefined settings. Here it is started on a weekly basis according to a timer unit.
+| To start/enable it, just do:
+
+  .. code:: bash
 
     systemctl start update-mirrorlist.timer
     systemctl enable update-mirrorlist.timer
 
-### weechat
-The systemd user service *weechat.service* starts the [IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) client [weechat](http://irssi.org/) in a separate [tmux](https://tmux.github.io/) environment for the current user.
-To connect to it after starting the service, just do  
+weechat --user
+______________
+| The systemd user service *weechat.service* starts the |irc| client |weechat| in a `separate |tmux| environment` for the current user.
+| To start/enable it, just do:
 
-    tmux -S /run/user/<your-user-id>/tmux/weechat attach
+  .. code:: bash
 
-or (if you've setup *$TMUX_TMPDIR* properly in your shell)  
+    systemctl --user start weechat
+    systemctl --user enable weechat
+| To connect to it after starting the service, just do
+
+  .. code:: bash
 
     tmux -L weechat attach
 
-## LICENSE
-**uenv** and all of its components are licensed under the GPLv3.
+.. |systemd| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/Systemd" target="_blank">systemd</a>
+
+.. |awesome| raw:: html
+
+  <a href="http://awesome.naquadah.org/" target="_blank">awesome</a>
+
+.. |gnome| raw:: html
+
+  <a href="https://gnome.org" target="_blank">Gnome</a>
+
+.. |kde| raw:: html
+
+  <a href="https://kde.org" target="_blank">KDE</a>
+
+.. |systemd.unit| raw:: html
+
+  <a href="http://www.freedesktop.org/software/systemd/man/systemd.unit.html" target="_blank">units</a>
+
+.. |systemd.service| raw:: html
+
+  <a href="http://www.freedesktop.org/software/systemd/man/systemd.service.html" target="_blank">service</a>
+
+.. |systemd.timer| raw:: html
+
+  <a href="http://www.freedesktop.org/software/systemd/man/systemd.timer.html" target="_blank">timer</a>
+
+.. |systemd.exec| raw:: html
+
+  <a href="http://www.freedesktop.org/software/systemd/man/systemd.exec.html" target="_blank">Environment</a>
+
+.. |tmux| raw:: html
+
+  <a href="https://tmux.github.io/" target="_blank">tmux</a>
+
+.. |cli| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/Command-line_interface" target="_blank">cli</a>
+
+.. |environment_variable| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/Environment_variable" target="_blank">environment variable</a>
+
+.. |bash| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29" target="_blank">bash</a>
+
+.. |zsh| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/Z_shell" target="_blank">zsh</a>
+
+.. |systemd-user.conf| raw:: html
+
+  <a href="http://www.freedesktop.org/software/systemd/man/systemd-user.conf.html" target="_blank">/etc/systemd/user.conf</a>
+
+.. |compton| raw:: html
+
+  <a href="https://github.com/chjj/compton/" target="_blank">compton</a>
+
+.. |real-time_kernel| raw:: html
+
+  <a href="https://www.kernel.org/pub/linux/kernel/projects/rt/" target="_blank">real-time kernel</a>
+
+.. |kernel_parameter| raw:: html
+
+  <a href="https://www.kernel.org/doc/Documentation/kernel-parameters.txt" target="_blank">kernel parameter</a>
+
+.. |grub| raw:: html
+
+  <a href="https://wiki.archlinux.org/index.php/Kernel_parameters#GRUB" target="_blank">GRUB</a>
+
+.. |syslinux| raw:: html
+
+  <a href="https://wiki.archlinux.org/index.php/Kernel_parameters#Syslinux" target="_blank">syslinux</a>
+
+.. |systemd-boot| raw:: html
+
+  <a href="https://wiki.archlinux.org/index.php/Kernel_parameters#systemd-boot" target="_blank">systemd-boot</a>
+
+.. |arch_linux| raw:: html
+
+  <a href="https://www.archlinux.org/" target="_blank">Arch Linux</a>
+
+.. |htop| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/Htop" target="_blank">htop</a>
+
+.. |irc| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/Internet_Relay_Chat" target="_blank">IRC</a>
+
+.. |irssi| raw:: html
+
+  <a href="http://irssi.org/" target="_blank">Irssi</a>
+
+.. |glances| raw:: html
+
+  <a href="https://github.com/nicolargo/glances" target="_blank">glances</a>
+
+.. |openvpn| raw:: html
+
+  <a href="https://github.com/nicolargo/glances" target="_blank">OpenVPN</a>
+
+.. |mpd_bug| raw:: html
+
+  <a href="http://bugs.musicpd.org/view.php?id=4413" target="_blank">broken version</a>
+
+.. |mpd| raw:: html
+
+  <a href="http://www.musicpd.org/" target="_blank">MPD</a>
+
+.. |pax11publish| raw:: html
+
+  <a href="http://linux.die.net/man/1/pax11publish" target="_blank">pax11publish</a>
+
+.. |xf86-input-synaptics| raw:: html
+
+  <a href="https://www.archlinux.org/packages/extra/x86_64/xf86-input-synaptics/" target="_blank">xf86-input-synaptics</a>
+
+.. |loginctl| raw:: html
+
+  <a href="http://www.freedesktop.org/software/systemd/man/loginctl.html" target="_blank">loginctl</a>
+
+.. |update-mirrorlist| raw:: html
+
+  <a href="https://github.com/ushis/update-mirrorlist" target="_blank">update-mirrorlist</a>
+
+.. |pacman| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/Arch_Linux#Pacman" target="_blank">pacman</a>
+
+.. |weechat| raw:: html
+
+  <a href="http://weechat.org/" target="_blank">weechat</a>
+
+