summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJose Antonio Ortega Ruiz <jao@gnu.org>2010-11-06 14:22:53 +0100
committerJose Antonio Ortega Ruiz <jao@gnu.org>2010-11-06 14:22:53 +0100
commitf972d32e556e305936e4aa9f1249fe2846e07a20 (patch)
treee44a0b9855ae5f6d0ac2d5bb06a9efb43ebf25e5 /doc
parent545ed6843fb39f6ed6ef6d7cb28fe8e4cc07e1c5 (diff)
downloadgeiser-chez-f972d32e556e305936e4aa9f1249fe2846e07a20.tar.gz
geiser-chez-f972d32e556e305936e4aa9f1249fe2846e07a20.tar.bz2
Manual nits
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am2
-rw-r--r--doc/geiser.css1
-rw-r--r--doc/geiser.texi2
-rw-r--r--doc/install.texi2
-rw-r--r--doc/intro.texi12
-rw-r--r--doc/macros.texi4
-rw-r--r--doc/parens.texi (renamed from doc/fun.texi)36
-rw-r--r--doc/repl.texi42
-rw-r--r--doc/web.texi2
9 files changed, 50 insertions, 53 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 247b03d..f2b16bb 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -19,7 +19,7 @@ geiser_TEXINFOS = \
intro.texi \
install.texi \
repl.texi \
- fun.texi \
+ parens.texi \
cheat.texi \
thanks.texi \
index.texi
diff --git a/doc/geiser.css b/doc/geiser.css
index e0ffb18..d05f909 100644
--- a/doc/geiser.css
+++ b/doc/geiser.css
@@ -14,6 +14,7 @@ body {
}
a { color:black; weight=normal }
+a:hover { color: #a22 }
hr { height:0; color:white }
diff --git a/doc/geiser.texi b/doc/geiser.texi
index 3a65e22..0294246 100644
--- a/doc/geiser.texi
+++ b/doc/geiser.texi
@@ -106,7 +106,7 @@ Cheat sheet
@include intro.texi
@include install.texi
@include repl.texi
-@include fun.texi
+@include parens.texi
@include cheat.texi
@include thanks.texi
@include index.texi
diff --git a/doc/install.texi b/doc/install.texi
index b260504..a4ea362 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -19,7 +19,7 @@ at least one of the supported schemes, which right now are
latest and greatest @uref{http://www.gnu.org/software/guile, Guile} 1.9
directly compiled from a recent checkout of
@uref{http://www.gnu.org/software/guile/repository.html, its Git
-@i{master} branch}. Since Geiser supports multiple @repl{}s, having both
+@i{master} branch}. Since Geiser supports multiple REPLs, having both
of them will just add to the fun.
@cindex use the source, Luke
diff --git a/doc/intro.texi b/doc/intro.texi
index 0805eca..f26fa7b 100644
--- a/doc/intro.texi
+++ b/doc/intro.texi
@@ -26,14 +26,14 @@ bulk of the code.
@cindex current module
@anchor{current-module} While being as generic as possible, the
Scheme-Elisp interface makes some assumptions about the capabilities and
-interaction mode of the corresponding @repl{}. In particular, Geiser
+interaction mode of the corresponding REPL. In particular, Geiser
expects the latter to support namespaces in the form of a module system,
-and to provide a well defined way to establish the @repl{}'s current
+and to provide a well defined way to establish the REPL's current
namespace (or module), as well as the current's file module (or
namespace). Thus, all evaluations performed by Geiser either in the
-@repl{} or in a source code buffer happen in the context of the current
+REPL or in a source code buffer happen in the context of the current
namespace. Every time you switch to a different file, you're switching
-namespaces automatically; at the @repl{}, you must request the switch
+namespaces automatically; at the REPL, you must request the switch
explicitly (usually just using means provided by the Scheme
implementation itself).
@@ -76,10 +76,10 @@ Listings of identifiers exported by a given module.
@item
Listings of callers/callees of procedures.
@item
-Rudimentary support for debugging (when the @repl{} provides a
+Rudimentary support for debugging (when the REPL provides a
debugging) and error navigation.
@item
-Support for multiple, simultaneous @repl{}s.
+Support for multiple, simultaneous REPLs.
@end itemize
In the following pages, i'll try to explain what these features
diff --git a/doc/macros.texi b/doc/macros.texi
index 712370a..4b235db 100644
--- a/doc/macros.texi
+++ b/doc/macros.texi
@@ -1,7 +1,3 @@
-@macro repl{}
-@acronym{REPL}
-@end macro
-
@macro img{FILE, ALIGN}
@ifhtml
@html
diff --git a/doc/fun.texi b/doc/parens.texi
index 08bdc33..7ae5420 100644
--- a/doc/fun.texi
+++ b/doc/parens.texi
@@ -1,7 +1,7 @@
@node Between the parens, Cheat sheet, The REPL, Top
@chapter Between the parens
-A good @repl{} is a must, but just about half the story of a good Scheme
+A good REPL is a must, but just about half the story of a good Scheme
hacking environment. Well, perhaps a bit more than a half; but, at any
rate, one surely needs also a pleasant way of editing source code. Don't
pay attention to naysayers: Emacs comes with an excellent editor
@@ -11,7 +11,7 @@ Geiser's support for writing Scheme code adds to Emacs'
@code{scheme-mode}, rather than supplanting it; and it does so by means
of a minor mode (unimaginatively dubbed @code{geiser-mode}) that defines
a bunch of new commands to try and, with the help of the same Scheme
-process giving you the @repl{}, make those Scheme buffers come to life.
+process giving you the REPL, make those Scheme buffers come to life.
@menu
* Activating Geiser::
@@ -46,7 +46,7 @@ you how to fix that in a moment.
The menu provides a good synopsis of everthing Geiser brings to the
party, including those keyboard shortcuts we Emacsers love. If you're
seeing the name of your favourite Scheme implementation in the
-mode-line, have a running @repl{} and are comfortable with Emacs, you
+mode-line, have a running REPL and are comfortable with Emacs, you
can stop reading now and, instead, discover Geiser's joys by yourself.
I've tried to make Geiser as self-documenting as any self-respecting
Emacs package should be. If you follow this route, make sure to take a
@@ -74,7 +74,7 @@ not recognised as such by Emacs, just tell her about it with:
@cindex useless wretch
Now, @i{geiser-mode} is just a useless wretch unless there's a running
Scheme process backing it up. Meaning that virtually all the commands it
-provides require a @repl{} up and running, preferably corresponding to
+provides require a REPL up and running, preferably corresponding to
the correct Scheme implementation. In the following section, we'll see
how to make sure that that's actually the case.
@@ -82,12 +82,12 @@ how to make sure that that's actually the case.
@section The source and the REPL
As i've already mentioned a couple of times, @i{geiser-mode} needs a
-running @repl{} to be operative. Thus, a common usage pattern will be
+running REPL to be operative. Thus, a common usage pattern will be
for you to first call @code{run-geiser} (or one of its variants, see
them described @ref{choosing-impl,,here}), and then open Scheme files;
but there's nothing wrong in first opening a couple Scheme buffers and
-then starting the @repl{} (you can even find it more convenient, since
-pressing @kbd{C-c C-z} in a Scheme buffer will start the @repl{} for
+then starting the REPL (you can even find it more convenient, since
+pressing @kbd{C-c C-z} in a Scheme buffer will start the REPL for
you). Since Geiser supports more than one Scheme implementation, though,
there's the problem of knowing which of them is to be associated with
each Scheme source file. Serviceable as it is, @i{geiser-mode} will try
@@ -117,7 +117,7 @@ element is used as the chosen implementation.
The contents of the file is scanned for hints on its associated
implementation. For instance, files that contain a @code{#lang}
directive will be considered Racket source code, while those with a
-@code{define-module} form in them will be assigned to a Guile @repl{}.
+@code{define-module} form in them will be assigned to a Guile REPL.
@item
The current buffer's file name is checked against the rules given in
@code{geiser-implementations-alist}, and the first match is applied. You
@@ -144,7 +144,7 @@ default value for the latter variable:
((regexp "\\.rkt$") racket))
@end example
which describes the simple heuristic that files with @file{.scm} as
-extension are by default associated to a Guile @repl{} while those
+extension are by default associated to a Guile REPL while those
ending in @file{.ss} or @file{.rkt} correspond to Racket's
implementation (with the caveat that these rules are applied only if the
previous heuristics have failed to detect the correct implementation,
@@ -166,18 +166,18 @@ first served, this new rule will take precedence over the default ones.
@cindex switching to REPL
@cindex switching to source
@anchor{switching-repl-buff} Once you have a working @i{geiser-mode},
-you can switch from Scheme source buffers to the @repl{} or @kbd{C-c
+you can switch from Scheme source buffers to the REPL or @kbd{C-c
C-z}. Those shortcuts map to the interactive command
@code{switch-to-geiser}.
@cindex switching to module
If you use a numeric prefix, as in @kbd{C-u C-c C-z}, besides being
-teleported to the @repl{}, the latter will switch to the namespace of
-the Scheme source file (as if you had used @kbd{C-c C-m} in the @repl{},
+teleported to the REPL, the latter will switch to the namespace of
+the Scheme source file (as if you had used @kbd{C-c C-m} in the REPL,
with the source file's module as argument; cf. @ref{Switching context}).
This command is also bound to @kbd{C-c C-Z}, with a capital zed.
-Once you're in the @repl{}, the same @kbd{C-c C-z} shortcut will bring
+Once you're in the REPL, the same @kbd{C-c C-z} shortcut will bring
you back to the buffer you jumped from, provided you don't kill the
Scheme process in between. This is why the command is called
@i{switch-to-geiser} instead of @i{switch-to-repl}, and what makes it
@@ -198,7 +198,7 @@ a one to one correspondence between paths and modules, while Guile
relies on explicit @code{define-module} forms in the source file).
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
+and communicating with the right REPL instance, let us see what it
can do for us, besides jumping to and fro.
@node Documentation helpers, To eval or not to eval, The source and the REPL, Between the parens
@@ -209,7 +209,7 @@ can do for us, besides jumping to and fro.
@cindex autodoc, in scheme buffers
The first thing you will notice by moving around Scheme source is that,
every now and then, the echo area lightens up with the same autodoc
-messages we know and love from our @repl{} forays. This happens every
+messages we know and love from our REPL forays. This happens every
time the Scheme process is able to recognise an identifier in the
buffer, and provide information either on its value (for variables) or
on its arity and the name of its formal arguments (for procedures and
@@ -342,7 +342,7 @@ incremental evaluation. Some people disagree; if you happen to find
@uref{http://blog.racket-lang.org/2009/03/drscheme-repl-isnt-lisp.html,
their arguments} convincing, you don't have to throw away Geiser
together with the baby: @kbd{M-x geiser-restart-repl} will let you
-restart the @repl{} as many times as you see fit.
+restart the REPL as many times as you see fit.
@cindex evaluation
@cindex incremental development, not evil
@@ -355,7 +355,7 @@ s-expression just before point.
@code{geiser-eval-definition}, bound to @kbd{C-M-x}, finds the topmost
definition containing point and sends it for evaluation. The variant
@code{geiser-eval-definition-and-go} (@kbd{C-c M-e}) works in the same
-way, but it also teleports you to @repl{} after the evaluation.
+way, but it also teleports you to REPL after the evaluation.
@code{geiser-eval-region}, bound to @kbd{C-c C-r}, evals the current
region. Again, there's an @i{and go} version available,
@@ -368,7 +368,7 @@ 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
to the Scheme file from which you're sending your code, which, in
-general, will be different from the @repl{}'s current module. And, if
+general, will be different from the REPL's current module. And, if
all goes according to plan, (re)defined variables and procedures should
be immediately visible inside and, if exported, outside their module.
diff --git a/doc/repl.texi b/doc/repl.texi
index d1ffc08..e707e61 100644
--- a/doc/repl.texi
+++ b/doc/repl.texi
@@ -18,14 +18,14 @@ ready, just come back here and proceed to the following sections.
@section Starting the REPL
@cindex REPL
-To start a Scheme @repl{} (meaning, a scheme process offering you a
+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 @ref{active-implementations,,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.
+choose your poison, and a new REPL buffer will pop-up.
@imgc{repls}
@@ -33,7 +33,7 @@ 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, as described @ref{impl-binary,, below}. Returning to our @repl{},
+is, as described @ref{impl-binary,, below}. 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
@@ -43,7 +43,7 @@ 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. It will also keep track of your input, maintaining a history
-file that will be reloaded whenever you restart the @repl{}.
+file that will be reloaded whenever you restart the REPL.
@cindex remote REPL
@cindex connect to server
@@ -64,7 +64,7 @@ variety of ways. For starters, all you (re)defintions will be visible
everywhere. That's dangerous, but will come in handy when you need to
debug your running webserver.
-Nothing that fanciful this far, but there's more to Geiser's @repl{}. On
+Nothing that fanciful this far, but there's more to Geiser's REPL. On
to the next section!
@node First aids, Switching context, Starting the REPL, The REPL
@@ -72,7 +72,7 @@ to the next section!
@img{repl-menu, right}
@cindex REPL commands
-A quick way of seeing what else Geiser's @repl{} can do for you, is to
+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
@@ -97,13 +97,13 @@ mercilessly kill the process (but not before stowing your history in the
file system). Unless you're using a remote REPL, that is, in which case
both commands will just sever the connection and leave the remote
process alone. 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
+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 or
closing your connection. 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
+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.
@@ -113,14 +113,14 @@ The remaining commands are meatier, and deserve sections of their own.
@cindex current module, in REPL
In tune with Geiser's @ref{current-module,,modus operandi}, evaluations
-in the @repl{} take place in the namespace of the current module. As
-noted above, the @repl{}'s prompt tells you the name of the current
+in the REPL take place in the namespace of the current module. As
+noted above, the REPL's prompt tells you the name of the current
module. To switch to a different one, you can use the command
@command{switch-to-geiser-module}, bound to @kbd{C-c C-m}. You'll notice
that Geiser simply uses a couple of meta-commands provided by the Scheme
-@repl{} (the stock @command{,m} in Guile and @command{,enter} in
+REPL (the stock @command{,m} in Guile and @command{,enter} in
Racket), and that it doesn't even try to hide that fact. That means that
-you can freely use said native ways directly at the @repl{}, and Geiser
+you can freely use said native ways directly at the REPL, and Geiser
will be happy to oblige.
@cindex current module, change
@@ -139,7 +139,7 @@ a prefix-aware list of available module names.
@imgc{mod-completion}
-Which brings me to the next group of @repl{} commands.
+Which brings me to the next group of REPL commands.
@node Completion and error handling, Autodoc and friends, Switching context, The REPL
@section Completion and error handling
@@ -147,7 +147,7 @@ Which brings me to the next group of @repl{} commands.
@cindex completion, module name
We've already seen Geiser completion of module names in action at the
mini-buffer. You won't be surprised to know that it's also available at
-the @repl{} buffer itself. There, you can use either @kbd{C-.} or
+the REPL buffer itself. There, you can use either @kbd{C-.} or
@kbd{M-`} to complete module names, and @kbd{@key{TAB}} or
@kbd{M-@key{TAB}} to complete identifiers. Geiser will know what
identifiers are bound in the current module and show you a list of those
@@ -178,7 +178,7 @@ if so, what arguments does it take? Geiser tries to help you answering
those questions too.
@cindex autodoc, in the REPL
-Actually, if you've been playing with the @repl{} as you read, you might
+Actually, if you've been playing with the REPL as you read, you might
have notice some frantic activity taking place in the minibuffer every
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
@@ -234,7 +234,7 @@ of the information displayed.
@section Customization and tips
@cindex REPL customization
-The looks and ways of the @repl{} can be fine-tuned via a bunch of
+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
@@ -262,7 +262,7 @@ forget about the richness of the Scheme ecosystem with something like
@cindex scheme binary
@cindex scheme executable path
-@anchor{impl-binary} When starting a new @repl{}, Geiser assumes, by
+@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 @code{geiser-guile-binary} and
@code{geiser-racket-binary}, which should be set to a string with the
@@ -283,7 +283,7 @@ for Racket are @code{geiser-racket-collects} and
By default, Geiser won't record duplicates in your input history. If you
prefer it did, just set @code{geiser-repl-history-no-dups-p} to
-@code{nil}. History entries are persistent across @repl{} sessions:
+@code{nil}. History entries are persistent across REPL sessions:
they're saved in implementation-specific files whose location is
controlled by the variable @code{geiser-repl-history-filename}. For
example, my Geiser configuration includes the following line:
@@ -298,11 +298,11 @@ directory.
@cindex autodoc, disabling
@cindex peace and quiet
-If you happen to love peace and quiet and prefer to keep your @repl{}'s
+If you happen to love peace and quiet and prefer to keep your REPL's
echo area free from autodoc's noise, @code{geiser-repl-autodoc-p} is the
customization variable for you: set it to @code{nil} and autodoc will be
-disabled by default in new @repl{}s. You can always bring the fairies
-back, on a per @repl{} basis, using @kbd{C-c C-a}.
+disabled by default in new REPLs. You can always bring the fairies
+back, on a per REPL basis, using @kbd{C-c C-a}.
@subsubheading Remote connections
diff --git a/doc/web.texi b/doc/web.texi
index 19633c1..828c02d 100644
--- a/doc/web.texi
+++ b/doc/web.texi
@@ -34,7 +34,7 @@ list</a>&nbsp;
@include intro.texi
@include install.texi
@include repl.texi
-@include fun.texi
+@include parens.texi
@include cheat.texi
@include thanks.texi
@include index.texi