nixos/weechat: cleanup module, add module documentation

This adds several improvements the previously introduced
`services.weechat` module:

* Dropped `services.weechat.init` as the initialization script can now
  be done on package-level since 2af41719bc using the `configure`
  function.

* Added `sessionName` option to explicitly configure a name for the
  `screen` session (by default: weechat-screen).

* Added `binary` option to configure the binary name (e.g.
  `weechat-headless`).

* Added docs regarding `screen` session and `weechat.service`.

1 files changed, 61 insertions, 0 deletions

diff --git a/nixos/modules/services/misc/weechat.xml b/nixos/modules/services/misc/weechat.xml
new file mode 100644
index 00000000000..de86dede2eb
--- /dev/null
+++ b/nixos/modules/services/misc/weechat.xml
@@ -0,0 +1,61 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         version="5.0"
+         xml:id="module-services-weechat">
+
+<title>WeeChat</title>
+<para><link xlink:href="https://weechat.org/">WeeChat</link> is a fast and extensible IRC client.</para>
+
+<section><title>Basic Usage</title>
+<para>
+By default, the module creates a
+<literal><link xlink:href="https://www.freedesktop.org/wiki/Software/systemd/">systemd</link></literal> unit
+which runs the chat client in a detached
+<literal><link xlink:href="https://www.gnu.org/software/screen/">screen</link></literal> session.
+
+</para>
+
+<para>
+This can be done by enabling the <literal>weechat</literal> service:
+
+<programlisting>
+{ ... }:
+
+{
+  <link linkend="opt-services.weechat.enable">services.weechat.enable</link> = true;
+}
+</programlisting>
+</para>
+<para>
+The service is managed by a dedicated user
+named <literal>weechat</literal> in the state directory
+<literal>/var/lib/weechat</literal>.
+</para>
+</section>
+<section><title>Re-attaching to WeeChat</title>
+<para>
+WeeChat runs in a screen session owned by a dedicated user. To explicitly
+allow your another user to attach to this session, the <literal>screenrc</literal> needs to be tweaked
+by adding <link xlink:href="https://www.gnu.org/software/screen/manual/html_node/Multiuser.html#Multiuser">multiuser</link> support:
+
+<programlisting>
+{
+  <link linkend="opt-programs.screen.screenrc">programs.screen.screenrc</link> = ''
+    multiuser on
+    acladd normal_user
+  '';
+}
+</programlisting>
+
+Now, the session can be re-attached like this:
+
+<programlisting>
+screen -r weechat-screen
+</programlisting>
+</para>
+<para>
+<emphasis>The session name can be changed using <link linkend="opt-services.weechat.sessionName">services.weechat.sessionName.</link></emphasis>
+</para>
+</section>
+</chapter>