Docs: REPL tutorial completed

4 files changed, 75 insertions, 16 deletions

diff --git a/doc/geiser.css b/doc/geiser.css
index dd0e08f..e0ffb18 100644
--- a/doc/geiser.css
+++ b/doc/geiser.css
@@ -50,7 +50,7 @@ pre.example {
 table { width: 100%; }
 
 img {
-    /* display:block; */
+    display:block;
     margin:10px auto 10px auto;
     border:none
 }
@@ -73,6 +73,10 @@ ul {
     margin-left:1em
 }
 
+kbd {
+    font-weight: bold;
+}
+
 div.navigation {
     background-color: #efebe7;
     line-height: 100%;
diff --git a/doc/geiser.texi b/doc/geiser.texi
index 31ca5ce..fb88b58 100644
--- a/doc/geiser.texi
+++ b/doc/geiser.texi
@@ -69,6 +69,10 @@ Installation
 The REPL
 
 * Starting the REPL::
+* First aids::
+* Switching context::
+* Let Geiser spy::
+* Customization and tips::
 
 @end detailmenu
 @end menu
diff --git a/doc/img/repl-mod.png b/doc/img/repl-mod.png
new file mode 100644
index 0000000..29ae007
--- /dev/null
+++ b/doc/img/repl-mod.png
diff --git a/doc/repl.texi b/doc/repl.texi
index f8ba2c9..5854cf8 100644
--- a/doc/repl.texi
+++ b/doc/repl.texi
@@ -1,4 +1,4 @@
-@node The REPL
+@node The REPL, Index, Installation, Top
 @chapter The REPL
 @anchor{quick-start}
 If you've followed the indications in @ref{Setting it up}, your Emacs is
@@ -78,7 +78,7 @@ 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 bad comes to worst and the process is
+killing the process. Finally, if worse comes to worst and the process is
 dead, @kbd{C-c z} will restart it.
 
 The remaining commands are meatier, and deserve sections of their own.
@@ -138,8 +138,8 @@ now and then. That was Geiser trying to be helpful (while, hopefully,
 not being clippy), or, more concretely, what i call, for want of a
 better name, its @dfn{autodoc} mode. Whenever it's active (did you
 notice that @i{A} in the mode-line?), Geiser's gerbils will be scanning
-what you type and showing arity information about the procedure nearest
-to point.
+what you type and showing (unless you silent them with @kbd{C-c a})
+arity information about the procedure nearest to point.
 
 @image{img/repl-autodoc}
 
@@ -151,20 +151,71 @@ when the optional argument has a default value, it's represented by a
 list made up of its name and that value. When the argument is a keyword
 argument, its name is preceded by a colon.
 
-If that's still not enough, Geiser can jump to the symbol's definition
-via @kbd{M-.}. A buffer with the corresponding file will popup, with its
-point resting upon the identifier's defining form. When you're done
-inspecting, @kbd{M-,} will bring you back to where you were. As we will
-see, these commands are also available in scheme buffers.
+If that's still not enough, Geiser can jump, via @kbd{M-.}, to the
+symbol's definition. A buffer with the corresponding file will pop up,
+with its point resting upon the identifier's defining form. When you're
+done inspecting, @kbd{M-,} will bring you back to where you were. As we
+will see, these commands are also available in scheme buffers.
+
+Finally, Geiser can produce for you a list, classified by kind, of the
+identifiers exported by a given module: all you need to do is press
+@kbd{C-c d}, and type or complete the desired module's name.
+
+@image{img/repl-mod}
+
+The list of exported bindings is shown in a buffer belonging to Geiser's
+documentation browser, of which more details are given in forthcoming
+sections (but just perusing it's associated key bindings, by any of the
+methods we've already used for the REPL, will give you enough
+information to use it effectively enough).
 
 @node Customization and tips,  , Let Geiser spy, The REPL
 @section Customization and tips
-@anchor{active-implementations}
-active implementations
-@anchor{impl-binary}
-geiser-impl-binary
-geiser-collections
-geiser-repl-history-no-dups-p
+
+The looks and ways of the REPL can be fine-tuned via a bunch of
+customization variables. You can see and modify them all in the
+corresponding customization group (by using the menu entry or the good
+old @kbd{M-x customize-group geiser-repl}), or by setting them in your
+Emacs initialization files (as a rule, all knobs in Geiser are turnable
+this way: you don't need to use customization buffers if you don't like
+them).
+
+I'm documenting below a proper subset of those settings, together with
+some related tips.
+
+@subsubheading Choosing a Scheme implementation
+Instead of using the generic @command{run-geiser} command, you can start
+directly your Scheme of choice via @command{run-racket} or
+@command{run-guile}. @anchor{active-implementations} In addition, the
+variable @var{geiser-active-implementations} contains a list of those
+Schemes Geiser should be aware of. Thus, if you happen to be, say, a
+racketeer not to be beguiled by other schemes, you can tell Geiser to
+forget about the richness of the Scheme ecosystem with something like
+@example
+(setq geiser-active-implementations '(racket))
+@end example
+@noindent in your initialisation files.
+
+@anchor{impl-binary} When starting a new REPL, Geiser assumes, by
+default, that the corresponding Scheme binary is in your path. If that's
+not the case, the variables to tweak are @var{geiser-guile-binary} and
+@var{geiser-racket-binary}, which should be set to a string with the
+path to the adequate binary.
+
+@subsubheading History
+
+By default, Geiser won't record duplicates in your input history. If you
+prefer it did, just set @var{geiser-repl-history-no-dups-p} to
+@code{nil}. History entries are persistent across REPL sessions: they're
+saved in implementation-specific files whose location is controlled by
+the variable @var{geiser-repl-history-filename}. For example, my Geiser
+configuration includes the following line:
+@example
+(setq geiser-repl-history-filename "~/.emacs.d/geiser-history")
+@end example
+@noindent which makes the files @file{geiser-history.guile} and
+@file{geiser-history.racket} to live inside my home's @file{.emacs.d}
+directory.
 
 
 @c Local Variables: