doc: Add tutorial for REPL setup.

* doc/api.texi (Live Coding): New subsection.

1 files changed, 33 insertions, 0 deletions

diff --git a/doc/api.texi b/doc/api.texi
index beb9e44..3ea911b 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -350,6 +350,39 @@ The default behavior is to re-throw the error.
 
 @end deffn
 
+@subsection Live Coding
+
+One of the biggest appeals of any Lisp dialect is the ability to use
+the ``read-eval-print loop'' (REPL for short) to build programs
+iteratively and interactively while the program is running.  However,
+programs that run in an event loop and respond to user input (such as
+a video game) require special care for this workflow to be pleasant.
+Chickadee provides no built-in support for live coding, but it's
+fairly easy to hook up a special kind of REPL yourself.
+
+First, create a cooperative REPL server (It's important to use Guile's
+cooperative REPL server instead of the standard REPL server in
+@code{(system repl server)} to avoid thread synchronization issues):
+
+@example
+(use-modules (system repl coop-server))
+
+(define repl (spawn-coop-repl-server))
+@end example
+
+Then, in the game loop's update procedure, add this:
+
+@example
+(poll-coop-repl-server repl)
+@end example
+
+To use the REPL, connect to it via port 37146.  Telnet will do the
+trick, but using the @uref{https://www.nongnu.org/geiser/, Geiser}
+extension for Emacs is by far the best way to develop at the REPL with
+Guile.  Use @code{M-x connect-to-guile} to connect to the REPL server.
+
+Happy hacking!
+
 @node Math
 @section Math