new API

and code cleanup

doc/riverguile.1

@@ -0,0 +1,97 @@
+.TH RIVERGUILE 1 2023-11-25 "git.sr.ht/~leon_plickat/riverguile" "General Commands Manual"
+.
+.SH NAME
+.P
+riverguile \- scheme powered layout generator for river
+.
+.
+.SH SYNOPSIS
+.SY riverguile
+.YS
+.
+.
+.SH DESCRIPTION
+.P
+Layout generator for the
+.BR river (1)
+Wayland server which allows users to define layouts using guile scheme functions.
+.
+.P
+The layout namespace is \fBriverguile\fB.
+.
+.P
+Uppon launch, riverguile tries to eval a scheme script and checks the following
+paths for it in the given order:
+.IP  \(bu 2
+\fBlayout.scm\fR
+.IP  \(bu 2
+\fB$XDG_CONFIG_HOME/river/layout.scm\fR
+.IP  \(bu 2
+\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
+\fB(install-handler \fR\fIkey\fR \fIproc\fR\fB)\fR is available, which can be
+used to install handlers to certain events.
+The parameter \fIkey\fR is a symbol indicating for which event to install
+the procedure \fIproc\fR.
+.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).
+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.
+Note that the numerical values do not need to be exact, riverguile takes care
+of rounding and casting for you.
+.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.
+.
+.
+.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.
+.
+.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))))
+.EE
+.RE
+.
+.
+.SH SEE ALSO
+.BR river (1),
+.BR riverctl (1),
+.BR rivertile (1),
+.BR guile (1)
+.
+.
+.SH AUTHOR
+.P
+.MT leonhenrik.plickat@stud.uni-goettingen.de
+Leon Henrik Plickat
+.ME