A new tutorial bit

13 files changed, 136 insertions, 31 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 185832a..d15fabf 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -28,3 +28,4 @@ web:
                   --top-file=index.html \
                   $(top_srcdir)/doc/web.texi
 	cp $(top_srcdir)/doc/geiser.css ${output_dir}
+	cp -r $(top_srcdir)/doc/img ${output_dir}
diff --git a/doc/geiser.css b/doc/geiser.css
index a172f4e..dd0e08f 100644
--- a/doc/geiser.css
+++ b/doc/geiser.css
@@ -9,7 +9,8 @@ html {
 body {
     padding:10px 10% 10px 10%;
     margin:0px;
-    text-align:justify
+    text-align:justify;
+    /* width: 750px; */
 }
 
 a { color:black; weight=normal }
@@ -49,11 +50,23 @@ pre.example {
 table { width: 100%; }
 
 img {
-    display:block;
+    /* display:block; */
     margin:10px auto 10px auto;
     border:none
 }
 
+img.floatleft {
+    float: left;
+    margin: 4px;
+    padding-right: 1em;
+}
+
+img.floatright {
+    float: right;
+    margin: 4px;
+    padding-left: 1em;
+}
+
 ul {
     list-style-type:square;
     padding-left:1em;
diff --git a/doc/geiser.texi b/doc/geiser.texi
index f5abc93..31ca5ce 100644
--- a/doc/geiser.texi
+++ b/doc/geiser.texi
@@ -40,12 +40,16 @@ The document was typeset with
 @c Output the table of the contents at the beginning.
 @contents
 
-@include top.texi
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top Geiser
+
+@insertcopying
 
 @menu
 * Introduction::
 * Installation::
-* Tutorial::
+* The REPL::
 * Index::
 
 @detailmenu
@@ -62,12 +66,18 @@ Installation
 * Setting it up::
 * Friends::
 
+The REPL
+
+* Starting the REPL::
+
 @end detailmenu
 @end menu
 
+@end ifnottex
+
 @include intro.texi
 @include install.texi
-@include tutorial.texi
+@include repl.texi
 @include index.texi
 
 @bye
diff --git a/doc/img/repl-menu.png b/doc/img/repl-menu.png
new file mode 100644
index 0000000..54a5fda
--- /dev/null
+++ b/doc/img/repl-menu.png
diff --git a/doc/img/repls.png b/doc/img/repls.png
new file mode 100644
index 0000000..6114587
--- /dev/null
+++ b/doc/img/repls.png
diff --git a/doc/index.texi b/doc/index.texi
index 408f780..35adb93 100644
--- a/doc/index.texi
+++ b/doc/index.texi
@@ -1,4 +1,4 @@
-@c This is part of Geiser's user manual., , Tutorial, Top
+@c This is part of Geiser's user manual., , The REPL, Top
 @c Copyright (C) 2010 Jose Antonio Ortega Ruiz
 @c See the file geiser.texi for copying conditions.
 
diff --git a/doc/install.texi b/doc/install.texi
index ef25536..857c59e 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -1,4 +1,4 @@
-@node Installation
+@node Installation, The REPL, Introduction, Top
 @chapter Installation
 
 @menu
diff --git a/doc/intro.texi b/doc/intro.texi
index 2bc134d..77f5434 100644
--- a/doc/intro.texi
+++ b/doc/intro.texi
@@ -3,7 +3,7 @@
 
 Geiser is an Emacs environment to hack and have fun in Scheme. If that's
 enough for you, see @ref{Installation} to get it running and
-@ref{Tutorial} for the fun part.
+@ref{The REPL} for the fun part.
 
 @menu
 * Modus operandi::
diff --git a/doc/macros.texi b/doc/macros.texi
new file mode 100644
index 0000000..cd3507a
--- /dev/null
+++ b/doc/macros.texi
@@ -0,0 +1,12 @@
+
+@macro img{FILE, ALIGN}
+@ifhtml
+@html
+<img src="img/\FILE\.png" class="float\ALIGN\"/>
+@end html
+@end ifhtml
+@ifnothtml
+@image{img/\FILE\}
+@end ifnothtml
+@end macro
+
diff --git a/doc/repl.texi b/doc/repl.texi
new file mode 100644
index 0000000..03ed2ab
--- /dev/null
+++ b/doc/repl.texi
@@ -0,0 +1,85 @@
+@node The REPL
+@chapter The REPL
+@anchor{quick-start}
+If you've followed the indications in @ref{Setting it up}, your Emacs is
+now ready to start playing. Otherwise, i'll wait for you: when you're
+ready, just come back here and proceed to the following sections.
+
+@menu
+* Starting the REPL::
+* First aids::
+* Switching contexts::
+@end menu
+
+@node Starting the REPL, First aids, The REPL, The REPL
+@section Starting the REPL
+
+To start a Scheme REPL (meaning, a scheme process offering you a
+Read-Eval-Print Loop), Geiser provides the generic interactive command
+@command{run-geiser}. If you run it (via, as is customary in Emacs,
+@kbd{M-x run-geiser}, you'll be saluted by a prompt asking which one of
+the supported implementations you want to launch (yes, you can stop the
+asking: see below). Tabbing for completion will offer you, as of this
+writing, @code{guile} and @code{racket}. Just choose your poison, and a
+new REPL buffer will pop-up.
+
+@image{img/repls}
+
+If all went according to plan, you'll be facing an
+implementation-dependent banner, followed by an interactive prompt.
+Going according to plan includes having the executable of the Scheme you
+chose in your path. If that's not the case, you can tell Emacs where it
+is by setting the variable @var{geiser-<impl>-binary} to an appropriate
+value. Returning to our REPL, the first thing to notice is that the
+funny prompt is telling you your current module: its name is the part
+just after the @@ sign (in Guile, that means @code{guile-user}, while
+Racket's top namespace doesn't have a name; cf. @ref{Switching contexts}
+below). Other than that, this is pretty much equivalent to having a
+command-line interpreter in a terminal, with a bunch of add-ons that
+we'll be reviewing below. You can start typing sexps right there: Geiser
+will only dispatch them for evaluation when they're complete, and will
+indent new lines properly until then.
+
+@node First aids, Switching contexts, Starting the REPL, The REPL
+@section First aids
+
+@img{repl-menu, right}
+A quick way of seeing what else Geiser's REPL can do for you, is to
+display the corresponding entry up there in your menu bar. No, i don't
+normally use menus either; but they can come in handy until you've
+memorized Geiser's commands, as a learning device. And yes, i usually
+run Emacs inside a terminal, but one can always use
+@uref{http://www.emacswiki.org/emacs/LaCarte, La Carte} to access the
+menus in a convenient enough fashion.
+
+Or just press @kbd{C-h m} and be done with that.
+
+Among the commands at your disposal, we find the familiar input
+navigation keys, with a twist. By default, @kbd{M-p} and @kbd{M-n} are
+bound to @i{matching} items in your input history. That is, they'll find
+the previous or next sexp that start with the current input prefix
+(defined as the text between the end of the prompt and your current
+position, a.k.a. @dfn{point}, in the buffer). For going up and down the
+list unconditionally, just use @kbd{C-c M-p} and @kbd{C-c M-n}.
+
+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 bad 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.
+
+@node Switching contexts,  , First aids, The REPL
+@section Switching contexts
+@comment  node-name,  next,  previous,  up
+
+
+@c Local Variables:
+@c mode: texinfo
+@c TeX-master: "geiser"
+@c End:
diff --git a/doc/top.texi b/doc/top.texi
index 43168c0..c0a0a8e 100644
--- a/doc/top.texi
+++ b/doc/top.texi
@@ -1,10 +1,3 @@
-@ifnottex
-@node Top, Introduction, (dir), (dir)
-@top Geiser
-@ifnothtml
-@insertcopying
-@end ifnothtml
-
 Geiser is a collection of Emacs major and minor modes that conspire with
 one or more Scheme interpreters to keep the Lisp Machine Spirit alive.
 It draws inspiration (and a bit more) from environments such as Common
@@ -23,8 +16,6 @@ bundle of Elisp shims orchestrates the dialog between the Scheme
 interpreter, Emacs and, ultimately, the schemer, giving her access to
 live metadata. Here's how.
 
-@end ifnottex
-
 @c Local Variables:
 @c mode: texinfo
 @c TeX-master: geiser
diff --git a/doc/tutorial.texi b/doc/tutorial.texi
deleted file mode 100644
index a98ebae..0000000
--- a/doc/tutorial.texi
+++ /dev/null
@@ -1,12 +0,0 @@
-@node Tutorial, Index, Installation, Top
-@chapter Tutorial
-
-@anchor{quick-start}
-I'm working on it... perhaps the
-@uref{http://git.savannah.gnu.org/cgit/geiser.git/plain/README, README}
-file will work for you in the meantime?
-
-@c Local Variables:
-@c mode: texinfo
-@c TeX-master: "geiser"
-@c End:
diff --git a/doc/web.texi b/doc/web.texi
index b5140ed..120cc61 100644
--- a/doc/web.texi
+++ b/doc/web.texi
@@ -1,12 +1,17 @@
+@settitle Geiser
+
+@include macros.texi
 
 @contents
 
+@node Top, Introduction, (dir), (dir)
+
 @include top.texi
 
 @menu
 * Introduction::
 * Installation::
-* Tutorial::
+* The REPL::
 * Index::
 @end menu
 
@@ -24,7 +29,7 @@ list</a>&nbsp;
 
 @include intro.texi
 @include install.texi
-@include tutorial.texi
+@include repl.texi
 @include index.texi
 
 @bye