summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJose Antonio Ortega Ruiz <jao@gnu.org>2010-06-27 01:43:32 +0200
committerJose Antonio Ortega Ruiz <jao@gnu.org>2010-06-27 01:43:32 +0200
commiteab369930516ece1d40658b891f4629d6f9ed8ac (patch)
tree155d5a500a716db809712195457165c0c4826640 /doc
parent58ab7aec6417e4410c0b5f886b16c8f49168fa7c (diff)
downloadgeiser-guile-eab369930516ece1d40658b891f4629d6f9ed8ac.tar.gz
geiser-guile-eab369930516ece1d40658b891f4629d6f9ed8ac.tar.bz2
A new tutorial bit
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am1
-rw-r--r--doc/geiser.css17
-rw-r--r--doc/geiser.texi16
-rw-r--r--doc/img/repl-menu.pngbin0 -> 147379 bytes
-rw-r--r--doc/img/repls.pngbin0 -> 154876 bytes
-rw-r--r--doc/index.texi2
-rw-r--r--doc/install.texi2
-rw-r--r--doc/intro.texi2
-rw-r--r--doc/macros.texi12
-rw-r--r--doc/repl.texi85
-rw-r--r--doc/top.texi9
-rw-r--r--doc/tutorial.texi12
-rw-r--r--doc/web.texi9
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
Binary files differ
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
Binary files differ
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