Add scheme module

doc/riverguile.1

@@ -1,4 +1,4 @@
-.TH RIVERGUILE 1 2023-11-25 "git.sr.ht/~leon_plickat/riverguile" "General Commands Manual"
+.TH RIVERGUILE 1 2024-01-13 "git.sr.ht/~leon_plickat/riverguile" "General Commands Manual"
 .
 .SH NAME
 .P
@@ -62,24 +62,10 @@ terminal emulator:
 .EE
 .RE
 .P
-To make using this procedure more ergonomic you likely want to wrap it in a
-macro like this:
-.P
-.RS
-.EX
-(\fBdefine-syntax\fR R
-  (\fBsyntax-rules\fR ()
-    ((R first) (riverctl (\fBsymbol->string\fR 'first)))
-    ((R first . rest) (\fBapply\fR riverctl
-                             (\fBmap\fR \fBsymbol->string\fR
-                                  (\fBappend\fR '(first) 'rest))))))
-
-(R spawn foot)
-(R spawn \fB#{\fRnotify-send notification!\fB}#\fR)
-.EE
-.RE
-.P
-This macro can of course be further modified to suit your specific needs.
+Riverguile also provides a scheme module which exports macros that wrap this
+procedure in a more ergonomic interface.
+This module is documented in the \fBRIVERGUILE MODULE\fR section of this
+document.
 .
 .
 .SH EVENT HANDLERS
@@ -232,7 +218,110 @@ Here is an example which adds a message to the system log on exit:
 .EE
 .RE
 .RE
+.
+.
+.SH RIVERGUILE MODULE
+.P
+A complete installation of riverguile also provides a scheme module which
+exposes macros and procedures with the intention of exposing more ergonomic
+interfaces.
+.P
+.RS
+.EX
+(\fBuse-modules\fR (riverguile))
+.EE
+.RE
+.P
+This module is not necessary to use riverguile and also will not provide any
+of riverguiles functionality to any scheme script not executed by riverguile.
+.P
+The following documents all exported procedures and macros.
+.
+.P
+(\fBR\fR \fIarg\fR ...)
+.P
+.RS
+A direct wrapper for the \fBriverctl\fR procedure, however it also accepts 
+symbols and numbers in addition to strings.
+Any expressions you need evaluated must be unquoted.
+.P
+.RS
+.EX
+(R spawn foot)
+(R spawn "notify-send hello")
+ 
+(\fBfor-each\fR (\fBlambda\fR (cmd) (R spawn ,cmd))
+          '("foot" "firefox" "nautilus"))
+.EE
+.RE
+.RE
+.
+.P
+(\fBR:map\fR \fImode\fR (\fImod\fR \fIkey\fR \fIcmd\fR ...) ...)
+.P
+.RS
+This macro is intended to simplify defining keymaps.
+Please refer to the
+.BR riverctl (1)
+manual page for more details and specifics regarding rivers map mechanism.
+Any expressions you need evaluated must be unquoted.
+.P
+.RS
+.EX
+(R:map normal
+  (Super H focus-view left)
+  (Super Space spawn foot)
+  (-repeat None XF86AudioRaiseVolume spawn "volume.sh raise 5%"))
 
+(\fBfor-each\fR (\fBlambda\fR (mode)
+            (R:map ,mode
+              (None XF86MonBrightnessUp   spawn "light -A 5")
+              (None XF86MonBrightnessDown spawn "light -U 5")))
+          '("normal" "locked"))
+.EE
+.RE
+.RE
+.
+.P
+(\fBR:input\fR \fIname\fR (\fIval\fR \fIvar\fR ...) ...)
+.P
+.RS
+This macro is intended to simplify input device configuration.
+Please refer to the
+.BR riverctl (1)
+manual page for details and specifics regarding the input device configuration.
+Any expressions you need evaluated must be unquoted.
+.P
+.RS
+.EX
+(R:input pointer-1149-4128-Kensington_Expert_mouse
+  (accel-profile none)
+  (pointer-accel 0.6)
+  (scroll-method button)
+  (scroll-button BTN_SIDE))
+.EE
+.RE
+.RE
+.
+.P
+(\fBR:keyboard-group\fR \fIname\fR . \fIdevices\fR)
+.P
+.RS
+This macro is intended to simplify creation of keyboard groups.
+Please refer to the
+.BR riverctl (1)
+manual page for details and specifics regarding keyboard groups.
+Any expressions you need evaluated must be unquoted.
+.P
+.RS
+.EX
+(R:keyboard-group split
+  keyboard-XXXX-XXXX-Device-1
+  keyboard-XXXX-XXXX-Device-2
+  keyboard-XXXX-XXXX-Device-3)
+.EE
+.RE
+.RE
 .
 .
 .SH SEE ALSO