load script after initial registry burst

This makes the logic of installing idle handlers and layout handlers a bit
cleaner and allows us to send wayland request from the script in the future.

doc/riverguile.1

@@ -2,7 +2,7 @@
 .
 .SH NAME
 .P
-riverguile \- scheme powered layout generator for river
+riverguile \- scheme powered scripting layer for river
 .
 .
 .SH SYNOPSIS
@@ -12,16 +12,17 @@ riverguile \- scheme powered layout generator for river
 .
 .SH DESCRIPTION
 .P
-Layout generator for the
+Scripting layer for the
 .BR river (1)
-Wayland server which allows users to define layouts using guile scheme functions.
-.
+Wayland server.
+Allows the user to send commands to the Wayland server (probably river) and
+install handlers for events from a scheme script.
 .P
-The layout namespace is \fBriverguile\fB.
-.
+By default, riverguile will exit after the script has been loaded and evaluated.
+If certain handlers are installed it will run continously.
 .P
-Uppon launch, riverguile tries to eval a scheme script and checks the following
-paths for it in the given order:
+Uppon launch, riverguile tries to load the script from the following paths
+in the given order:
 .IP  \(bu 2
 \fBlayout.scm\fR
 .IP  \(bu 2
@@ -30,80 +31,153 @@ paths for it in the given order:
 \fB$HOME/.config/river/layout.scm\fR
 .IP  \(bu 2
 \fB/etc/riverguile/layout.scm\fR
-.
 .P
-In the context of this script, a special procedure
+.
+.
+.SH EVENT HANDLERS
+.P
+In the context of the script, a special procedure
 \fB(install-handler \fR\fIkey\fR \fIproc\fR\fB)\fR is available, which can be
-used to install handlers to certain events.
+used to install event handlers.
 The parameter \fIkey\fR is a symbol indicating for which event to install
 the procedure \fIproc\fR.
+The following keys are currently evailable:
+.
 .P
-The key \fBlayout-demand\fR installs a handler for layout demands, which must
-accept five required arguments, which are, in order: The amount of views in the
-layout (integer), the available width (integer), the available height (integer),
-the currently active tag set (integer representing a bitfield of size 32)
-and the global name of the output the layout is needed for (integer).
+\fBlayout-demand\fR
+.P
+.RS
+Installing a handler for this key allows the user to provide window layouts.
+All limitations of the river-layout-v3 protocol apply.
+The server will trigger this event when a new layout is required ("demanded").
+.P
+Installing a layout-demand handler will cause riverguile to run continously.
+.P
+The handler procedure must accept five required arguments, which are, in order:
+The amount of views in the layout (integer), the available width (integer), the
+available height (integer), the currently active tag set (integer representing a
+bitfield of size 32) and the global name of the output the layout is needed for
+(integer).
 The procedure must return a list containing exactly as many lists as there are
 views in the layout.
 Each of those sublists must contains exactly four numerical values, which are
 the x and y coordinates of the window as well as its width and height.
-Window positions and dimensions get applied to rivers window list top to bottom.
+Window positions and dimensions get applied to the window list top to bottom.
+.P
 Note that the numerical values do not need to be exact, riverguile takes care
 of rounding and casting for you.
-A layout demand handler must be installed, otherwise riverguile will exit.
 .P
-The key \fBuser-command\fR install a handler for user commands, which are the
-strings a user can send to layout generators.
-This handler procedure must accept three arguments, which are, in order:
-The command (string), the currently active tags (integer representing a
-bitfield of size 32) and the global name of the output (integer).
-This event can be used to change paramters of the layout.
-A new layout demand will be send right after this event.
-.P
-The key \fBidle:X\fR installs a handler which is called when the system has been
-idle for \fIX\fR seconds.
-As an example, use \fBidle:300\fR if you wish to be notified of your system
-being idle for five minutes.
-Idle in this case relates to user interaction;
-The system being idle for five minutes usually means there has been no input
-from the user in five minutes.
-Idle status however can also be influenced by other factors, for example by
-other programs inhibiting it (like video players), special sensors (user
-presence sensors) and is generally server-specific policy.
-The handler procedure must accept one argument, a symbol indicating the type
-of idle event.
-This symbol is either \fBidle\fR, indicating the system has been idle for the
-configured amount of time, or \fBresume\fR, indicating that the time intervall
-of the system being idle is over.
-Multiple idle handlers can be installed.
-Note: All idle events relate to the first advetised seat.
-As of now, river only supports a single seat anyway.
-.P
-The key \fBexit\fR installs a handler which is called when riverguile exits.
-The procedure takes no arguments.
-.
-.
-.SH EXAMPLE
-.P
-This is an example configuration, which installs a layout that simply assigns
-each window all usable space and a user command handler that tries to evaluate
-all send commands as scheme code.
-.
+Here is an example of a simple layout-demand handler which simply makes all
+windows use all available space:
 .P
 .RS
 .EX
-(install-handler 'user-command (lambda (cmd tags output)
-                                 (eval-string cmd)))
-
-(install-handler 'layout-demand (lambda (view-count width height tags output)
-                                  (letrec ((iter (lambda (n)
-                                                   (if (eq? 0 n)
-                                                       '()
-                                                       (append (list (list 0 0 width height))
-                                                               (iter (1- n)))))))
-                                    (iter view-count))))
+(\fBinstall-handler\fR 'layout-demand
+  (\fBlambda\fR (view-count width height tags output)
+    (\fBletrec\fR ((iter (\fBlambda\fR (n)
+                     (if (eq? 0 n)
+                         '()
+                         (\fBappend\fR (\fBlist\fR (\fBlist\fR 0 0 width height))
+                                 (iter (1- n)))))))
+      (iter view-count))))
 .EE
 .RE
+.RE
+.
+.P
+\fBuser-command\fR
+.P
+.RS
+User commands are intended to send commands to layout generators, allowing the
+user to update parameters of the layout live.
+Of course, nothing is stopping you from (ab-)using this event to trigger
+arbitrary scheme code on keypresses or on outside events, or from simply not
+using it at all.
+After a user-command has been received, the server can will trigger a
+layout-demand if there are visible windows.
+.P
+Installing a user-command handler will \fInot\fR cause riverguile to run continously.
+This event is an extension to the layout-demand event and as such it is invalid
+to install a user-command handler without also installing a layout-demant
+handler.
+.P
+The handler procedure must accept three arguments, which are, in order:
+The command (string), the currently active tags (integer representing a
+bitfield of size 32) and the global name of the output (integer).
+.P
+Here is an example of a simple user-command handler which simply evaluates the
+string as scheme code:
+.P
+.RS
+.EX
+(\fBinstall-handler\fR 'user-command
+  (\fBlambda\fR (cmd tags output)
+    (\fBeval-string\fR cmd)))
+.EE
+.RE
+.P
+Note that this is not necessarily good practice, but serves as a decent example.
+.RE
+.
+.P
+\fBidle:X\fR
+.P
+.RS
+A handler installed for this key will be triggered after the system has been
+idle for \fIX\fR seconds and once more once the system is no longer idle.
+.P
+Installing a layout-demand handler will cause riverguile to run continously.
+Multiple idle handlers can be installed.
+.P
+Idle state is server policy and may depend on a multitude of factors, but
+usually maps directly to the usage activity of input devices by the user.
+Certain programs may inhibit idle state, like for example video players.
+.P
+The handler procedure must accept one argument, a symbol indicating the type
+of idle event.
+This symbol is either \fBidle\fR, indicating the system has been idle for the
+configured amount of time, or \fBresume\fR, indicating that the system is no
+longer idle.
+.P
+Here is an example which will dim the screen after two minutes of inactiviy
+and lock it after fice:
+.P
+.RS
+.EX
+(\fBinstall-handler\fR 'idle:120
+  (\fBlambda\fR (event)
+    (\fBcond\fR ((\fBeq?\fR event 'idle) (\fBsystem\fR "light -S 20"))
+          ((\fBeq?\fR event 'resume) (\fBsystem\fR "light -S 100")))))
+
+(\fBinstall-handler\fR 'idle:300
+  (\fBlambda\fR (event)
+    (if (\fBeq?\fR event 'idle) (\fBsystem\fR "swaylock &"))))
+.EE
+.RE
+.P
+Note: All idle events relate to the first advetised seat.
+As of now, river only supports a single seat anyway.
+.RE
+.
+.P
+\fBexit\fR
+.RE
+.RS
+This key allows you to installs a handler which is called when riverguile exits.
+.P
+The procedure takes no arguments.
+.P
+Here is an example which adds a message to the system log on exit:
+.P
+.RS
+.EX
+(\fBinstall-handler\fR 'exit
+  (\fBlambda\fR ()
+    (\fBsystem\fR "logger 'goodbye from riverguile'")))
+.EE
+.RE
+.RE
+
 .
 .
 .SH SEE ALSO