doc: Reorganize and expand manual.

1 files changed, 50 insertions, 5 deletions

diff --git a/doc/chickadee.texi b/doc/chickadee.texi
index a65af9e..0585688 100644
--- a/doc/chickadee.texi
+++ b/doc/chickadee.texi
@@ -4,7 +4,7 @@
 @settitle The Chickadee Game Toolkit
 @c %**end of header
 @copying
-Copyright @copyright{} 2017-2020  David Thompson @email{davet@@gnu.org}
+Copyright @copyright{} 2017-2021  David Thompson @email{davet@@gnu.org}
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -53,8 +53,8 @@ The document was typeset with
 * Installation::                Installing Chickadee.
 * Getting Started::             Writing your first Chickadee program.
 * Command Line Interface::      Run Chickadee programs from the terminal.
+* Live Coding::                 Tips for building games from the REPL.
 * API Reference::               Chickadee API reference.
-
 * Copying This Manual::         The GNU Free Documentation License and you!
 * Index::
 @end menu
@@ -93,7 +93,6 @@ Chickadee depends on the following packages:
 @item libvorbisfile
 @end itemize
 
-
 @node Getting Started
 @chapter Getting Started
 
@@ -271,11 +270,57 @@ after each change.
 @item --repl-server[=@var{port}]
 
 Launch a REPL server on port @var{port}, or 37146 by default.
-Especially useful when paired with the
-@url{https://www.nongnu.org/geiser/, Geiser} extension for Emacs.
+
+@command{telnet localhost 37146} (or whatever port number was given)
+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.
 
 @end table
 
+@node Live Coding
+@chapter 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 game using the Chickadee library!) require special care for this
+workflow to be pleasant.
+
+If you are using the @command{chickadee play} command to run your
+game, then the @code{--repl} or @code{--repl-server} arguments are all
+you need to get a live coding environment running.
+
+If, however, you are using @code{run-game} to start the game loop then
+it's still fairly easy to hook up a special kind of REPL by 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).
+Then, in the game loop's update procedure, call
+@code{poll-coop-repl-server} and pass the REPL object.  Here is a
+template to follow:
+
+@example
+(use-modules (chickadee)
+             (system repl coop-server))
+
+(define repl (spawn-coop-repl-server))
+
+(define (update dt)
+  (poll-coop-repl-server repl)
+  ...)
+
+(run-game #:update update ...)
+@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.
+
 @node API Reference
 @chapter API Reference