More documentation

4 files changed, 65 insertions, 28 deletions

diff --git a/doc/fun.texi b/doc/fun.texi
index 1089dca..0b6e215 100644
--- a/doc/fun.texi
+++ b/doc/fun.texi
@@ -1,4 +1,4 @@
-@node Fun between the parens, Index, The REPL, Top
+@node Fun between the parens
 @chapter Fun between the parens
 
 A good @repl{} is a must, but just about half the story of a good Scheme
@@ -17,7 +17,8 @@ process giving you the @repl{}, make those Scheme buffers come to life.
 * Activating Geiser::
 * The source and the REPL::
 * Documentation helpers::
-* Evaluating Scheme code::
+* To eval or not to eval::
+* To err perchance to debug::
 * Jumping around::
 * Geiser writes for you::
 @end menu
@@ -199,7 +200,7 @@ Now that we have @code{geiser-mode} happily alive in our Scheme buffers
 and communicating with the right @repl{} instance, let us see what it
 can do for us, besides jumping to and fro.
 
-@node Documentation helpers, Evaluating Scheme code, The source and the REPL, Fun between the parens
+@node Documentation helpers, To eval or not to eval, The source and the REPL, Fun between the parens
 @section Documentation helpers
 
 @subsubheading Autodoc redux
@@ -216,7 +217,7 @@ identifier belongs to has been loaded in the running Scheme image. So it
 can be the case that, at first, no autodoc is shown for identifiers
 defined in the file you're editing. But as soon as you evaluate them
 (either individually or collectively using any of the devices described
-in @ref{Evaluating Scheme code}) their signatures will start appearing
+in @ref{To eval or not to eval}) their signatures will start appearing
 in the echo area.
 
 @cindex disabling autodoc
@@ -310,8 +311,8 @@ form of a list of its exported identifiers, using @kbd{C-c C-d C-m},
 exactly as you would do @ref{repl-mod,,in the REPL}. This commands works
 with all supported Schemes, no strings attached.
 
-@node Evaluating Scheme code, Jumping around, Documentation helpers, Fun between the parens
-@section Evaluating Scheme code
+@node To eval or not to eval, To err perchance to debug, Documentation helpers, Fun between the parens
+@section To eval or not to eval
 
 @cindex philosophy
 @cindex incremental development
@@ -360,12 +361,8 @@ region. Again, there's an @i{and go} version available,
 @code{geiser-eval-region-and-go}, bound to @kbd{C-c M-r}.
 
 For all the commands above, the result of the evaluation is displayed in
-the minibuffer, unless it causes a (scheme-side) error, in which case
-Geiser will report the problem by opening a debug buffer with
-information on what went wrong (Racket) or jump into the debugger when
-the REPL provides such a beast (Guile).
-
-@image{img/eval-error}
+the minibuffer, unless it causes a (scheme-side) error (@pxref{To err
+perchance to debug}).
 
 At the risk of repeating myself, i'll remember you that all these
 evaluations will take place in the namespace of the module corresponding
@@ -380,13 +377,52 @@ macro-expand them. The corresponding keybindings start with the prefix
 @kbd{C-r}. The result of the macro expansion always appears in a pop up
 buffer.
 
+@node To err perchance to debug, Jumping around, To eval or not to eval, Fun between the parens
+@section To err: perchance to debug
+
+@cindex to err is schemey
 @cindex backtraces
-When an error occurs during evaluation, you'll be presented with a
-backtrace, in a new buffer where file paths locating the origin of the
-error are clickable (you can navigate them using the @key{TAB} key, and
-use @key{RET} or the mouse to jump to the offending spot).
+When an error occurs during evaluation, it will be reported according to
+the capabilities of the underlying Scheme REPL.
+
+@cindex error buffer
+In Racket, you'll be presented with a backtrace, in a new buffer where
+file paths locating the origin of the error are clickable (you can
+navigate them using the @key{TAB} key, and use @key{RET} or the mouse to
+jump to the offending spot; or invoke Emacs' stock commands
+@code{next-error} and @code{previous-error}, bound to @kbd{M-g n} and
+@kbd{M-g p} by default).
+
+@image{img/eval-error}
 
-@node Jumping around, Geiser writes for you, Evaluating Scheme code, Fun between the parens
+The Racket backtrace also highlights the exception type, making it
+clickable. Following the link will open the documentation corresponding
+to said exception type. Both the error and exception link faces are
+customizable (@code{geiser-font-lock-error-link} and
+@code{geiser-font-lock-doc-link}).
+
+On the other hand, Guile's reaction to evaluation errors is different:
+it enters the debugger in its REPL. Accordingly, the REPL buffer will
+pop up if your evaluation fails in a Guile file, and the error message
+and backtrace will be displayed in there, again clickable and all. But
+there you have the debugger at your disposal, with the REPL's current
+module set to that of the offender, and a host of special debugging
+commands that are described in Guile's fine documentation.
+
+@image{img/guile-eval-error}
+
+In addition, Guile will sometimes report warnings for otherwise
+successful evaluations. In those cases, it won't enter the debugger, and
+Geiser will report the warnings in a debug buffer, as it does for
+Racket. You can control how picky Guile is reporting warnings by
+customizing the variable @code{geiser-guile-warning-level}, whose
+detailed docstring (which see, using, e.g. @kbd{C-h v}) allows me to
+offer no further explanation here. The customization group
+@i{geiser-guile} is also worth a glance, for a couple of options to fine
+tune how Geiser interacts with Guile's debugger (and more). Same thing
+for racketeers and @i{geiser-racket}.
+
+@node Jumping around, Geiser writes for you, To err perchance to debug, Fun between the parens
 @section Jumping around
 
 @cindex jumping in scheme buffers
@@ -394,7 +430,7 @@ This one feature is as sweet as easy to explain: @kbd{M-.}
 (@code{geiser-edit-symbol-at-point}) will open the file where the
 identifier around point is defined and land your point on its
 definition. To return to where you were, press @kbd{M-,}
-(@code{geiser-pop-symbol-stack})..
+(@code{geiser-pop-symbol-stack}).
 
 Sometimes, the underlying Scheme will tell Geiser only the file where
 the symbol is defined, but Geiser will use some heuristics (read,
diff --git a/doc/img/eval-error.png b/doc/img/eval-error.png
index 2a88e91..ec63f99 100644
--- a/doc/img/eval-error.png
+++ b/doc/img/eval-error.png
diff --git a/doc/img/guile-eval-error.png b/doc/img/guile-eval-error.png
new file mode 100644
index 0000000..d62025b
--- /dev/null
+++ b/doc/img/guile-eval-error.png
diff --git a/doc/repl.texi b/doc/repl.texi
index 93632fb..ce0eaff 100644
--- a/doc/repl.texi
+++ b/doc/repl.texi
@@ -73,16 +73,17 @@ down the list unconditionally, just use @kbd{C-c M-p} and @kbd{C-c M-n}.
 In addition, navigation is sexp- rather than line-based.
 
 There are also a few commands to twiddle with the Scheme process.
-@kbd{C-c C-q} will mercilessly kill it (but not before stowing your
-history in the file system). A softer nuke is performed by @kbd{C-c
-C-k}: some (rare, i promise) times, Geiser's @repl{} can get confused by
-the input received from then underlying Scheme (specially if you have
-multiple threads writing to the standard ports), and become
-irresponsive; you can try this command to try to revive it without
-killing the process. Finally, if worse comes to worst and the process is
-dead, @kbd{C-c C-z} will restart it (but the same shortcut, issued when
-the @repl{} is alive, will bring you back to the buffer you came from,
-as explained @ref{switching-repl-buff,,here}).
+@kbd{C-c C-q} will gently ask it to quit, while @kbd{C-u C-c C-q} will
+mercilessly kill the process (but not before stowing your history in the
+file system). A softer nuke is performed by @kbd{C-c C-k}: some (rare, i
+promise) times, Geiser's @repl{} can get confused by the input received
+from then underlying Scheme (specially if you have multiple threads
+writing to the standard ports), and become irresponsive; you can try
+this command to try to revive it without killing the process. Finally,
+if worse comes to worst and the process is dead, @kbd{C-c C-z} will
+restart it (but the same shortcut, issued when the @repl{} is alive,
+will bring you back to the buffer you came from, as explained
+@ref{switching-repl-buff,,here}).
 
 The remaining commands are meatier, and deserve sections of their own.