From 14c436f5f8d73fe80da40eda382c7a76aacb3ef1 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Sun, 27 Jun 2010 01:43:32 +0200 Subject: A new tutorial bit --- doc/Makefile.am | 1 + doc/geiser.css | 17 ++++++++-- doc/geiser.texi | 16 ++++++++-- doc/img/repl-menu.png | Bin 0 -> 147379 bytes doc/img/repls.png | Bin 0 -> 154876 bytes doc/index.texi | 2 +- doc/install.texi | 2 +- doc/intro.texi | 2 +- doc/macros.texi | 12 +++++++ doc/repl.texi | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/top.texi | 9 ------ doc/tutorial.texi | 12 ------- doc/web.texi | 9 ++++-- 13 files changed, 136 insertions(+), 31 deletions(-) create mode 100644 doc/img/repl-menu.png create mode 100644 doc/img/repls.png create mode 100644 doc/macros.texi create mode 100644 doc/repl.texi delete mode 100644 doc/tutorial.texi 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 Binary files /dev/null and b/doc/img/repl-menu.png differ diff --git a/doc/img/repls.png b/doc/img/repls.png new file mode 100644 index 0000000..6114587 Binary files /dev/null and b/doc/img/repls.png 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 + +@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--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  @include intro.texi @include install.texi -@include tutorial.texi +@include repl.texi @include index.texi @bye -- cgit v1.2.3