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`.

2 files changed, 79 insertions, 29 deletions

diff --git a/nixos/modules/services/misc/weechat.nix b/nixos/modules/services/misc/weechat.nix
index 535a7f9ef91..1fcfb440485 100644
--- a/nixos/modules/services/misc/weechat.nix
+++ b/nixos/modules/services/misc/weechat.nix
@@ -9,28 +9,33 @@ in
 {
   options.services.weechat = {
     enable = mkEnableOption "weechat";
-    init = mkOption {
-      description = "Weechat commands applied at start, one command per line.";
-      example = ''
-        /set relay.network.password correct-horse-battery-staple
-        /relay add weechat 9001
-      '';
-      type = types.str;
-      default = "";
-    };
     root = mkOption {
       description = "Weechat state directory.";
       type = types.str;
       default = "/var/lib/weechat";
     };
+    sessionName = mkOption {
+      description = "Name of the `screen' session for weechat.";
+      default = "weechat-screen";
+      type = types.str;
+    };
+    binary = mkOption {
+      description = "Binary to execute (by default \${weechat}/bin/weechat).";
+      example = literalExample ''
+        ''${pkgs.weechat}/bin/weechat-headless
+      '';
+      default = "${pkgs.weechat}/bin/weechat";
+    };
   };
 
   config = mkIf cfg.enable {
     users = {
+      groups.weechat = {};
       users.weechat = {
         createHome = true;
         group = "weechat";
         home = cfg.root;
+        isSystemUser = true;
       };
     };
 
@@ -39,29 +44,13 @@ in
       serviceConfig = {
         User = "weechat";
         Group = "weechat";
+        RemainAfterExit = "yes";
       };
-      script = "exec ${pkgs.screen}/bin/screen -D -m ${pkgs.weechat}/bin/weechat";
+      script = "exec ${pkgs.screen}/bin/screen -Dm -S ${cfg.sessionName} ${cfg.binary}";
       wantedBy = [ "multi-user.target" ];
       wants = [ "network.target" ];
     };
-
-    systemd.paths.weechat-fifo = {
-      pathConfig = {
-        PathExists = "${cfg.root}/weechat_fifo";
-        Unit = "weechat-apply-init.service";
-      };
-      wantedBy = [ "multi-user.target" ];
-    };
-
-    systemd.services.weechat-apply-init = let
-      initFile = pkgs.writeText "weechat-init" cfg.init;
-    in {
-      script = "sed 's/^/*/' ${initFile} > ${cfg.root}/weechat_fifo";
-      serviceConfig = {
-        Type = "oneshot";
-        User = "weechat";
-        Group = "weechat";
-      };
-    };
   };
+
+  meta.doc = ./weechat.xml;
 }
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>