summaryrefslogtreecommitdiff
path: root/doc/ref/scheme-using.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2010-10-12 13:01:10 +0200
committerAndy Wingo <wingo@pobox.com>2010-10-12 13:01:34 +0200
commit767dbb1af30500cc0ad44d6bd0e0e179a1191ec6 (patch)
tree9a449eea3766094dd5ff0910e091ede407b7be46 /doc/ref/scheme-using.texi
parentced9917e127456a63c6c09d28424d886b8f14634 (diff)
downloadguile-767dbb1af30500cc0ad44d6bd0e0e179a1191ec6.tar.gz
remove gds docs, telling users instead to use geiser and paredit
* doc/ref/scheme-using.texi (Using Guile in Emacs): Remove GDS docs, as we don't have GDS any more. Instead of surveying the field, be opinionated and tell users what to use: Geiser and Paredit.
Diffstat (limited to 'doc/ref/scheme-using.texi')
-rw-r--r--doc/ref/scheme-using.texi757
1 files changed, 43 insertions, 714 deletions
diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi
index 810ee1574..4e666d70a 100644
--- a/doc/ref/scheme-using.texi
+++ b/doc/ref/scheme-using.texi
@@ -567,735 +567,64 @@ Finally, as a word to the wise: hackers close their REPL prompts with
@node Using Guile in Emacs
@section Using Guile in Emacs
-@cindex GDS
@cindex Emacs
-There are several options for working on Guile Scheme code in Emacs.
-The simplest are to use Emacs's standard @code{scheme-mode} for
-editing code, and to run the interpreter when you need it by typing
-``guile'' at the prompt of a @code{*shell*} buffer, but there are
-Emacs libraries available which add various bells and whistles to
-this. The following diagram shows these libraries and how they relate
-to each other, with the arrows indicating ``builds on'' or
-``extends''. For example, the Quack library builds on cmuscheme,
-which in turn builds on the standard scheme mode.
-
-@iftex
-@center @image{scheme,5in}
-@end iftex
-@ifnottex
-@example
-@verbatiminclude scheme.txt
-@end example
-@end ifnottex
-
-@dfn{scheme}, written by Bill Rozas and Dave Love, is Emacs's standard
-mode for Scheme code files. It provides Scheme-sensitive syntax
-highlighting, parenthesis matching, indentation and so on.
-
-@dfn{cmuscheme}, written by Olin Shivers, provides a comint-based Scheme
-interaction buffer, so that you can run an interpreter more directly
-than with the @code{*shell*} buffer approach by typing @kbd{M-x
-run-scheme}. It also extends @code{scheme-mode} so that there are key
-presses for sending selected bits of code from a Scheme buffer to this
-interpreter. This means that when you are writing some code and want to
-check what an expression evaluates to, you can easily select that code
-and send it to the interpreter for evaluation, then switch to the
-interpreter to see what the result is. cmuscheme is included in the
-standard Emacs distribution.
-
-@dfn{Quack}, written by Neil Van Dyke, adds a number of incremental
-improvements to the scheme/cmuscheme combination: convenient menu
-entries for looking up Scheme-related references (such as the SRFIs);
-enhanced indentation rules that are customized for particular Scheme
-interpreters, including Guile; an enhanced version of the
-@code{run-scheme} command that knows the names of the common Scheme
-interpreters and remembers which one you used last time; and so on.
-Quack is available from @uref{http://www.neilvandyke.org/quack}.
-
-@dfn{GDS}, written by Neil Jerram, also builds on the scheme/cmuscheme
-combination, but with a change to the way that Scheme code fragments
-are sent to the interpreter for evaluation. cmuscheme and Quack send
-code fragments to the interpreter's standard input, on the assumption
-that the interpreter is expecting to read Scheme expressions there,
-and then monitor the interpreter's standard output to infer what the
-result of the evaluation is. GDS doesn't use standard input and
-output like this. Instead, it sets up a socket connection between the
-Scheme interpreter and Emacs, and sends and receives messages using a
-simple protocol through this socket. The messages include requests to
-evaluate Scheme code, and responses conveying the results of an
-evaluation, thus providing similar function to cmuscheme or Quack.
-They also include requests for stack exploration and debugging, which
-go beyond what cmuscheme or Quack can do. The price of this extra
-power, however, is that GDS is Guile-specific. GDS requires the
-Scheme interpreter to run some GDS-specific library code; currently
-this code is written as a Guile module and uses features that are
-specific to Guile. GDS is now included in the Guile distribution; for
-previous Guile releases (1.8.4 and earlier) it can be obtained as part
-of the @code{guile-debugging} package from
-@uref{http://www.ossau.uklinux.net/guile}.
-
-Finally, @dfn{xscheme} is similar to cmuscheme --- in that it starts up
-a Scheme interaction process and sends commands to that process's
-standard input --- and to GDS --- in that it has support beyond
-cmuscheme or Quack for exploring the Scheme stack when an error has
-occurred --- but is implemented specifically for MIT/GNU Scheme. Hence
-it isn't really relevant to Guile work in Emacs, except as a reference
-for useful features that could be implemented in one of the other
-libraries mentioned here.
-
-In summary, the best current choice for working on Guile code in Emacs
-is either Quack or GDS, depending on which of these libraries' features
-you find most important. For more information on Quack, please see the
-website referenced above. GDS is documented further in the rest of this
-section.
+Any text editor can edit Scheme, but some are better than others. Emacs
+is the best, of course, and not just because it is a fine text editor.
+Emacs has good support for Scheme out of the box, with sensible
+indentation rules, parenthesis-matching, syntax highlighting, and even a
+set of keybindings for structural editing, allowing navigation,
+cut-and-paste, and transposition operations that work on balanced
+S-expressions.
+
+As good as it is, though, two things will vastly improve your experience
+with Emacs and Guile.
+
+@cindex Paredit
+The first is Taylor Campbell's
+@uref{http://www.emacswiki.org/emacs/ParEdit, Paredit}. You should not
+code in any dialect of Lisp without Paredit. (They say that
+unopinionated writing is boring---hence this tone---but it's the
+truth, regardless.) Paredit is the bee's knees.
+
+@cindex Geiser
+The second is José Antonio Ortega Ruiz's
+@uref{http://www.nongnu.org/geiser/, Geiser}. Geiser complements Emacs'
+@code{scheme-mode} with tight integration to running Guile processes via
+a @code{comint-mode} REPL buffer.
+
+Of course there are keybindings to switch to the REPL, and a good REPL
+environment, but Geiser goes beyond that, providing:
-@menu
-* GDS Introduction::
-* GDS Architecture::
-* GDS Getting Started::
-* Working with GDS in Scheme Buffers::
-* Displaying the Scheme Stack::
-* Continuing Execution::
-* Associating Buffers with Clients::
-* An Example GDS Session::
-@end menu
-
-
-@node GDS Introduction
-@subsection GDS Introduction
-
-GDS aims to allow you to work on Guile Scheme code in the same kind of
-way that Emacs allows you to work on Emacs Lisp code: providing easy
-access to help, evaluating arbitrary fragments of code, a nice debugging
-interface, and so on. The thinking behind the GDS library is that you
-will usually be doing one of two things.
-
-@enumerate
+@itemize @bullet
@item
-Writing or editing code. The code will be in a normal Emacs Scheme mode
-buffer, and GDS extends Scheme mode to add keystrokes and menu items for
-the things that are likely to be useful to you when working on code:
-
-@itemize
+Form evaluation in the context of the current file's module.
@item
-completing the identifier at point, with respect to the set of variable
-names that are known to the associated Guile process
+Macro expansion.
@item
-accessing Guile's built in ``help'' and ``apropos'' commands
+File/module loading and/or compilation.
@item
-evaluating fragments of code to check what they do, with the results
-popping up in a temporary Emacs window.
-@end itemize
-
+Namespace-aware identifier completion (including local bindings, names
+visible in the current module, and module names).
@item
-Debugging a Guile Scheme program. When your program hits an error or
-stops at a trap, GDS shows you the relevant code and the Scheme stack,
-and makes it easy to
-
-@itemize
+Autodoc: the echo area shows information about the signature of the
+procedure/macro around point automatically.
@item
-look at the values of local variables
+Jump to definition of identifier at point.
@item
-see what is happening at all levels of the Scheme stack
+Access to documentation (including docstrings when the implementation
+provides it).
@item
-continue execution, either normally or step by step.
-@end itemize
-
-The presentation makes it very easy to move up and down the stack,
-showing whenever possible the source code for each frame in another
-Emacs buffer. It also provides convenient keystrokes for telling Guile
-what to do next; for example, you can select a stack frame and tell
-Guile to run until that frame completes, at which point GDS will display
-the frame's return value.
-@end enumerate
-
-GDS can provide these facilities for any number of Guile Scheme programs
-(which we often refer to as ``clients'') at once, and these programs can
-be started either independently of GDS, including outside Emacs, or
-specifically @emph{by} GDS.
-
-Communication between each Guile client program and GDS uses a TCP
-socket, which means that it is orthogonal to any other interfaces that
-the client program has. In particular GDS does not interfere with a
-program's standard input and output.
-
-
-@node GDS Architecture
-@subsection GDS Architecture
-
-In order to understand the following documentation fully it will help to
-have a picture in mind of how GDS works, so we briefly describe that
-here. GDS consists of three components.
-
-@itemize
+Listings of identifiers exported by a given module.
@item
-The GDS @dfn{interface} code is written in Emacs Lisp and runs inside
-Emacs. This code, consisting of the installed files @file{gds.el} and
-@file{gds-server.el}, is responsible for displaying information from
-Guile in Emacs windows, and for responding to Emacs commands and
-keystrokes by sending instructions back to the Guile program being
-worked on.
-
+Listings of callers/callees of procedures.
@item
-The GDS @dfn{server} code is written in Scheme and runs as an Emacs
-inferior process. It acts as a multiplexer between the (possibly
-multiple) Guile programs being debugged and the interface code running
-in Emacs. The server code is the installed file
-@file{gds-server.scm}.
-
+Rudimentary support for debugging and error navigation.
@item
-The GDS @dfn{client} code is written in Scheme (installed file
-@file{gds-client.scm}), and must be loaded as a module by each Guile
-program that wants to use GDS in any way.
+Support for multiple, simultaneous REPLs.
@end itemize
-@noindent
-The following diagram shows how these components are connected to each
-other.
-
-@iftex
-@center @image{gds,5in}
-@end iftex
-@ifnottex
-@example
-@verbatiminclude gds.txt
-@end example
-@end ifnottex
-
-@cindex TCP, use of
-The data exchanged between client and server components, and between
-server and interface, is a sequence of sexps (parenthesised expressions)
-that are designed so as to be directly readable by both Scheme and Emacs
-Lisp. The use of a TCP connection means that the server and Emacs
-interface can theoretically be on a different computer from the client
-programs, but in practice there are currently two problems with
-this. Firstly the GDS API doesn't provide any way of specifying a
-non-local server to connect to, and secondly there is no security or
-authentication mechanism in the GDS protocol. These are issues that
-should be addressed in the future.
-
-
-@node GDS Getting Started
-@subsection Getting Started with GDS
-
-To enable the use of GDS in your own Emacs sessions, simply add
-
-@lisp
-(require 'gds)
-@end lisp
-
-@noindent
-somewhere in your @file{.emacs} file. This will cause Emacs to load the
-GDS Emacs Lisp code when starting up, and to start the inferior GDS
-server process so that it is ready and waiting for any Guile programs
-that want to use GDS.
-
-(If GDS's Scheme code is not installed in one of the locations in
-Guile's load path, you may find that the server process fails to start.
-When this happens you will see an error message from Emacs:
-
-@lisp
-error in process filter: Wrong type argument: listp, Backtrace:
-@end lisp
-
-@noindent
-and the @code{gds-debug} buffer will contain a Scheme backtrace ending
-with the message:
-
-@lisp
-no code for module (ice-9 gds-server)
-@end lisp
-
-@noindent
-The solution for this is to customize the Emacs variable
-@code{gds-scheme-directory} so that it specifies where the GDS Scheme
-code is installed. Then either restart Emacs or type @kbd{M-x
-gds-run-debug-server} to try starting the GDS server process again.)
-
-For evaluations, help and completion from Scheme code buffers that you
-are working on, this is all you need. The first time you do any of
-these things, GDS will automatically start a new Guile client program as
-an Emacs subprocess. This Guile program does nothing but wait for and
-act on instructions from GDS, and we refer to it as a @dfn{utility}
-Guile client. Over time this utility client will accumulate the code
-that you ask it to evaluate, and you can also tell it to load complete
-files or modules by sending it @code{load} or @code{use-modules}
-expressions.
-
-When you want to use GDS to work on an independent Guile
-application, you need to add something to that application's Scheme code
-to cause it to connect to and interact with GDS at the right times. The
-following subsections describe the ways of doing this.
-
-@subsubsection Invoking GDS when an Exception Occurs
-
-One option is to use GDS to catch and display any exceptions that
-are thrown by the application's code. If you already have a
-@code{lazy-catch} or @code{with-throw-handler} around the area of code
-that you want to monitor, you just need to add the following to the
-handler code:
-
-@lisp
-(gds-debug-trap (throw->trap-context key args))
-@end lisp
-
-@noindent
-where @code{key} and @code{args} are the first and rest arguments that
-Guile passes to the handler. (In other words, they assume the handler
-signature @code{(lambda (key . args) @dots{})}.) With Guile 1.8 or
-later, you can also do this with a @code{catch}, by adding this same
-code to the catch's pre-unwind handler.
-
-If you don't already have any of these, insert a whole
-@code{with-throw-handler} expression (or @code{lazy-catch} if your Guile
-is pre-1.8) around the code of interest like this:
-
-@lisp
-(with-throw-handler #t
- (lambda ()
- ;; Protected code here.
- )
- (lambda (key . args)
- (gds-debug-trap (throw->trap-context key args))))
-@end lisp
-
-Either way, you will need to use the @code{(ice-9 gds-client)} and
-@code{(ice-9 debugging traps)} modules.
-
-Two special cases of this are the lazy-catch that the Guile REPL code
-uses to catch exceptions in user code, and the lazy-catch inside the
-@code{stack-catch} utility procedure that is provided by the
-@code{(ice-9 stack-catch)} module. Both of these use a handler called
-@code{lazy-handler-dispatch} (defined in @file{boot-9.scm}), which you
-can hook into such that it calls GDS to display the stack when an
-exception occurs. To do this, use the @code{on-lazy-handler-dispatch}
-procedure as follows.
-
-@lisp
-(use-modules (ice-9 gds-client)
- (ice-9 debugging traps))
-(on-lazy-handler-dispatch gds-debug-trap)
-@end lisp
-
-@noindent
-After this the program will use GDS to display the stack whenever it
-hits an exception that is protected by a @code{lazy-catch} using
-@code{lazy-handler-dispatch}.
-
-@subsubsection Accepting GDS Instructions at Any Time
-
-In addition to setting an exception handler as described above, a
-Guile program can in principle set itself up to accept new
-instructions from GDS at any time, not just when it has stopped at an
-exception. This would allow the GDS user to evaluate code in the
-context of the running program, without having to wait for the program
-to stop first.
-
-@lisp
-(use-modules (ice-9 gds-client))
-(gds-accept-input #t)
-@end lisp
-
-@code{gds-accept-input} causes the calling program to loop processing
-instructions from GDS, until GDS sends the @code{continue} instruction.
-This blocks the thread that calls it, however, so it will normally be
-more practical for the program to set up a dedicated GDS thread and call
-@code{gds-accept-input} from that thread.
-
-For @code{select}-driven applications, an alternative approach would be
-for the GDS client code to provide an API which allowed the application
-to
-
-@itemize
-@item
-discover the file descriptors (or Scheme ports) that are used for
-receiving instruction from the GDS front end, so that it could include
-these in its @code{select} call
-
-@item
-call the GDS instruction handler when @code{select} indicated data
-available for reading on those descriptors/ports.
-@end itemize
-
-@noindent
-This approach is not yet implemented, though.
-
-@subsubsection Utility Guile Implementation
-
-The ``utility'' Guile client mentioned above is a simple combination
-of the mechanisms that we have just described. In fact the code for
-the utility Guile client is essentially just this:
-
-@lisp
-(use-modules (ice-9 gds-client))
-(named-module-use! '(guile-user) '(ice-9 session))
-(gds-accept-input #f))
-@end lisp
-
-The @code{named-module-use!} line ensures that the client can process
-@code{help} and @code{apropos} expressions, to implement lookups in
-Guile's online help. The @code{#f} parameter to
-@code{gds-accept-input} means that the @code{continue} instruction
-will not cause the instruction loop to exit, which makes sense here
-because the utility client has nothing to do except to process GDS
-instructions.
-
-The utility client does not use @code{on-lazy-handler-dispatch} at its
-top level, because it has its own mechanism for catching and reporting
-exceptions in the code that it is asked to evaluate. This mechanism
-summarizes the exception and gives the user a button they can click to
-see the full stack, so the end result is very similar to what
-@code{on-lazy-handler-dispatch} provides. Deep inside
-@code{gds-accept-input}, in the part that handles evaluating
-expressions from Emacs, the GDS client code uses
-@code{throw->trap-context} and @code{gds-debug-trap} to implement
-this.
-
-
-@node Working with GDS in Scheme Buffers
-@subsection Working with GDS in Scheme Buffers
-
-The following subsections describe the facilities and key sequences that
-GDS provides for working on code in @code{scheme-mode} buffers.
-
-@menu
-* Access to Guile Help and Completion::
-* Evaluating Scheme Code::
-@end menu
-
-
-@node Access to Guile Help and Completion
-@subsubsection Access to Guile Help and Completion
-
-The following keystrokes provide fast and convenient access to Guile's
-built in help, and to completion with respect to the set of defined and
-accessible symbols.
-
-@table @kbd
-@item C-h g
-@findex gds-help-symbol
-Get Guile help for a particular symbol, with the same results as if
-you had typed @code{(help SYMBOL)} into the Guile REPL
-(@code{gds-help-symbol}). The symbol to query defaults to the word at
-or before the cursor but can also be entered or edited in the
-minibuffer. The available help is popped up in a temporary Emacs
-window.
-
-@item C-h G
-@findex gds-apropos
-List all accessible Guile symbols matching a given regular expression,
-with the same results as if you had typed @code{(apropos REGEXP)} into
-the Guile REPL (@code{gds-apropos}). The regexp to query defaults to
-the word at or before the cursor but can also be entered or edited in
-the minibuffer. The list of matching symbols is popped up in a
-temporary Emacs window.
-
-@item M-@key{TAB}
-@findex gds-complete-symbol
-Try to complete the symbol at the cursor by matching it against the
-set of all defined and accessible bindings in the associated Guile
-process (@code{gds-complete-symbol}). If there are any extra
-characters that can be definitively added to the symbol at point, they
-are inserted. Otherwise, if there are any completions available, they
-are popped up in a temporary Emacs window, where one of them can be
-selected using either @kbd{@key{RET}} or the mouse.
-@end table
-
-
-@node Evaluating Scheme Code
-@subsubsection Evaluating Scheme Code
-
-The following keystrokes and commands provide various ways of sending
-code to a Guile client process for evaluation.
-
-@table @kbd
-@item M-C-x
-@findex gds-eval-defun
-Evaluate the ``top level defun'' that the cursor is in, in other words
-the smallest balanced expression which includes the cursor and whose
-opening parenthesis is in column 0 (@code{gds-eval-defun}).
-
-@item C-x C-e
-@findex gds-eval-last-sexp
-Evaluate the expression that ends just before the cursor
-(@code{gds-eval-last-sexp}). This is designed so that it is easy to
-evaluate an expression that you have just finished typing.
-
-@item C-c C-e
-@findex gds-eval-expression
-Read a Scheme expression using the minibuffer, and evaluate that
-expression (@code{gds-eval-expression}).
-
-@item C-c C-r
-@findex gds-eval-region
-Evaluate the Scheme code in the marked region of the current buffer
-(@code{gds-eval-region}). Note that GDS does not check whether the
-region contains a balanced expression, or try to expand the region so
-that it does; it uses the region exactly as it is.
-@end table
-
-If you type @kbd{C-u} before one of these commands, GDS will immediately
-pop up a Scheme stack buffer, showing the requested evaluation, so that
-you can single step through it. The Scheme stack display, and the
-options for continuing through the code, are described in the next two
-sections.
-
-
-@node Displaying the Scheme Stack
-@subsection Displaying the Scheme Stack
-
-When you specify @code{gds-debug-trap} as the behaviour for a trap and
-the Guile program concerned hits that trap, GDS displays the stack and
-the relevant Scheme source code in Emacs, allowing you to explore the
-state of the program and then decide what to do next. The same
-applies if the program calls @code{(on-lazy-handler-dispatch
-gds-debug-trap)} and then throws an exception that passes through
-@code{lazy-handler-dispatch}, except that in this case you can only
-explore; it isn't possible to continue normal execution after an
-exception.
-
-The following commands are available in the stack buffer for exploring
-the state of the program.
-
-@table @asis
-@item @kbd{u}, @kbd{C-p}, @kbd{@key{up}}
-@findex gds-up
-Select the stack frame one up from the currently selected frame
-(@code{gds-up}). GDS displays stack frames with the innermost at the
-top, so moving ``up'' means selecting a more ``inner'' frame.
-
-@item @kbd{d}, @kbd{C-n}, @kbd{@key{down}}
-@findex gds-down
-Select the stack frame one down from the currently selected frame
-(@code{gds-down}). GDS displays stack frames with the innermost at the
-top, so moving ``down'' means selecting a more ``outer'' frame.
-
-@item @kbd{@key{RET}}
-@findex gds-select-stack-frame
-Select the stack frame at point (@code{gds-select-stack-frame}). This
-is useful after clicking somewhere in the stack trace with the mouse.
-@end table
-
-Selecting a frame means that GDS will display the source code
-corresponding to that frame in the adjacent window, and that
-subsequent frame-sensitive commands, such as @code{gds-evaluate} (see
-below) and @code{gds-step-over} (@pxref{Continuing Execution}), will
-refer to that frame.
-
-@table @kbd
-@item e
-@findex gds-evaluate
-Evaluate a variable or expression in the local environment of the
-selected stack frame (@code{gds-evaluate}). The result is displayed in
-the echo area.
-
-@item I
-@findex gds-frame-info
-Show summary information about the selected stack frame
-(@code{gds-frame-info}). This includes what type of frame it is, the
-associated expression, and the frame's source location, if any.
-
-@item A
-@findex gds-frame-args
-For an application frame, display the frame's arguments
-(@code{gds-frame-args}).
-
-@item S
-@findex gds-proc-source
-For an application frame, show the Scheme source code of the procedure
-being called (@code{gds-proc-source}). The source code (where
-available) is displayed in the echo area.
-@end table
-
-@kbd{S} (@code{gds-proc-source}) is useful when the procedure being
-called was created by an anonymous @code{(lambda @dots{})} expression.
-Such procedures appear in the stack trace as @code{<procedure #f
-(@dots{})>}, which doesn't give you much clue as to what will happen
-next. @kbd{S} will show you the procedure's code, which is usually
-enough for you to identify it.
-
-
-@node Continuing Execution
-@subsection Continuing Execution
-
-If it makes sense to continue execution from the stack which is being
-displayed, GDS provides the following further commands in the stack
-buffer.
-
-@table @asis
-@item @kbd{g}, @kbd{c}, @kbd{q}
-@findex gds-go
-Tell the program to continue running (@code{gds-go}). It may of course
-stop again if it hits another trap, or another occurrence of the same
-trap.
-
-The multiple keystrokes reflect that you can think of this as ``going'',
-``continuing'' or ``quitting'' (in the sense of quitting the GDS
-display).
-
-@item @kbd{@key{SPC}}
-@findex gds-step-file
-Tell the program to do a single-step to the next entry or exit of a
-frame whose code comes from the same source file as the selected stack
-frame (@code{gds-step-file}).
-
-In other words, you can hit @kbd{@key{SPC}} repeatedly to step through
-the code in a given file, automatically stepping @emph{over} any
-evaluations or procedure calls that use code from other files (or from
-no file).
-
-If the selected stack frame has no source, the effect of this command is
-the same as that of @kbd{i}, described next.
-
-@item @kbd{i}
-@findex gds-step-into
-Tell the debugged program to do a single-step to the next frame entry or
-exit of any kind (@code{gds-step-into}). @kbd{i} therefore steps
-through code at the most detailed level possible.
-
-@item @kbd{o}
-@findex gds-step-over
-Tell the debugged program to continue running until the selected stack
-frame completes, and then to display its result (@code{gds-step-over}).
-Note that the program may stop before then if it hits another trap; in
-this case the trap telling it to stop when the marked frame completes
-remains in place and so will still fire at the appropriate point.
-@end table
-
-
-@node Associating Buffers with Clients
-@subsection Associating Buffers with Clients
-
-The first time that you use one of GDS's evaluation, help or completion
-commands from a given Scheme mode buffer, GDS will ask which Guile
-client program you want to use for the operation, or if you want to
-start up a new ``utility'' client. After that GDS considers the buffer
-to be ``associated'' with the selected client, and so sends all further
-requests to that client, but you can override this by explicitly
-associating the buffer with a different client, or by removing the
-default association.
-
-@table @kbd
-@item M-x gds-associate-buffer
-Associate (or re-associate) the current buffer with a particular Guile
-client program. The available clients are listed, and you can also
-choose to start up a new ``utility'' client for this buffer to associate
-with.
-
-@item M-x gds-dissociate-buffer
-Dissociate the current buffer from its client, if any. This means that
-the next time you use an evaluation, help or completion command, GDS
-will ask you again which client to send the request to.
-@end table
-
-When a buffer is associated with a client program, the buffer's modeline
-shows whether the client is currently able to accept instruction from
-GDS. This is done by adding one of the following suffixes to the
-``Scheme'' major mode indicator:
-
-@table @asis
-@item :ready
-The client program (or one of its threads, if multithreaded) is
-currently ready to accept instruction from GDS. In other words, if you
-send it a help or evaluation request, you should see the result pretty
-much immediately.
-
-@item :running
-The client program is not currently able to accept instruction from
-GDS. This means that it (or all of its threads, if multithreaded) is
-busy, or waiting for input other than from GDS.
-
-@item :debug
-The client program (or one of its threads, if multithreaded) is stopped
-in ``debugging mode'' with GDS displaying the stack for a trap or
-exception. It is waiting for instruction from GDS on what to do next.
-@end table
-
-
-@node An Example GDS Session
-@subsection An Example GDS Session
-
-Create a file, @file{testgds.scm} say, for experimenting with GDS and
-Scheme code, and type this into it:
-
-@lisp
-(use-modules (ice-9 debugging traps)
- (ice-9 gds-client)
- (ice-9 debugging example-fns))
-(install-trap (make <procedure-trap>
- #:behaviour gds-debug-trap
- #:procedure fact1))
-@end lisp
-
-@noindent
-Now select all of this code and type @kbd{C-c C-r} to send the selected
-region to Guile for evaluation. GDS will ask you which Guile process to
-use; unless you know that you already have another Guile application
-running and connected to GDS, choose the ``Start a new Guile'' option,
-which starts one of the ``utility'' processes described in @ref{GDS
-Getting Started}.
-
-The results of the evaluation pop up in a window like this:
-
-@lisp
-(use-modules (ice-9 debugging traps)\n @dots{}
-
-;;; Evaluating subexpression 1 in current module (guile-user)
- @result{} no (or unspecified) value
-
-;;; Evaluating subexpression 2 in current module (guile-user)
- @result{} no (or unspecified) value
-
---:** *Guile Evaluation* (Scheme:ready)--All------------
-@end lisp
-
-@noindent
-this tells you that the evaluation was successful but that the return
-values were unspecified. Its effect was to load a module of example
-functions and set a trap on one of these functions, @code{fact1}, that
-calculates the factorial of its argument.
-
-If you now call @code{fact1}, you can see the trap and GDS's stack
-display in action. To do this add
-
-@lisp
-(fact1 4)
-@end lisp
-
-@noindent
-to your @file{testgds.scm} buffer and type @kbd{C-x C-e} (which
-evaluates the expression that the cursor is just after the end of).
-The result should be that a GDS stack window like the following
-appears:
-
-@lisp
-Calling procedure:
-=> s [fact1 4]
- s [primitive-eval (fact1 4)]
-
-
---:** PID 28729 (Guile-Debug)--All------------
-@end lisp
-
-This stack tells you that Guile is about to call the @code{fact1}
-procedure, with argument 4, and you can step through this call in
-detail by pressing @kbd{i} once and then @kbd{@key{SPC}}
-(@pxref{Continuing Execution}).
-
-(@kbd{i} is needed as the first keystroke rather than @kbd{@key{SPC}},
-because the aim here is to step through code in the @code{(ice-9
-debugging example-fns)} module, whose source file is
-@file{@dots{}/ice-9/debugging/example-fns.scm}, but the initial
-@code{(fact1 4)} call comes from the Guile session, whose ``source
-file'' Guile presents as @file{standard input}. If the user starts by
-pressing @kbd{@key{SPC}} instead of @kbd{i}, the effect is that the
-program runs until it hits the first recursive call @code{(fact1 (- n
-1))}, where it stops because of the trap on @code{fact1} firing again.
-At this point, the source file @emph{is}
-@file{@dots{}/ice-9/debugging/example-fns.scm}, because the recursive
-@code{(fact1 (- n 1))} call comes from code in that file, so further
-pressing of @kbd{@key{SPC}} successfully single-steps through this
-file.)
+See Geiser's web page at @uref{http://www.nongnu.org/geiser/}, for more
+information.
@c Local Variables: