* api-debug.texi (Traps): Minor edits.

* scheme-using.texi (Using Guile in Emacs, GDS Getting Started):
	Minor edits.

doc/ref/ChangeLog

@@ -1,3 +1,10 @@
+2008-03-18  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* api-debug.texi (Traps): Minor edits.
+
+	* scheme-using.texi (Using Guile in Emacs, GDS Getting Started):
+	Minor edits.
+
 2008-03-12  Neil Jerram  <neil@ossau.uklinux.net>
 
 	* scheme-debugging.texi: Remove lots of text that is now

doc/ref/api-debug.texi

@@ -17,7 +17,7 @@ infrastructure that builds on top of those calls.
 @menu
 * Evaluation Model::            Evaluation and the Scheme stack.
 * Debug on Error::              Debugging when an error occurs.
-* High Level Traps::
+* Traps::
 @end menu
 
 @node Evaluation Model
@@ -608,8 +608,8 @@ Invoke the Guile debugger to explore the context of the last error.
 @end deffn
 
 
-@node High Level Traps
+@node Traps
-@subsection High Level Traps
+@subsection Traps
 
 @cindex Traps
 @cindex Evaluator trap calls
@@ -644,8 +644,8 @@ and @code{behaviour} slots contain @code{my-factorial} and
 @code{debug-trap} would be a trap that enters the command line
 debugger when the @code{my-factorial} procedure is invoked.
 
-The following subsubsections describe all this in greater detail, for both
+The following subsections describe all this in detail, for both the
-the user wanting to use traps, and the developer interested in
+user wanting to use traps, and the developer interested in
 understanding how the interface hangs together.
 
 

doc/ref/scheme-using.texi

@@ -320,15 +320,15 @@ may be continued over multiple lines.
 @node Using Guile in Emacs
 @section Using Guile in Emacs
 
-There are quite a few options for working on Guile Scheme code in
+There are several options for working on Guile Scheme code in Emacs.
-Emacs.  The simplest options are to use Emacs's standard
+The simplest are to use Emacs's standard @code{scheme-mode} for
-@code{scheme-mode} for editing code, and to run the interpreter when you
+editing code, and to run the interpreter when you need it by typing
-need it by typing ``guile'' at the prompt of a @code{*shell*} buffer,
+``guile'' at the prompt of a @code{*shell*} buffer, but there are
-but there are Emacs libraries available which add various bells and
+Emacs libraries available which add various bells and whistles to
-whistles to this.  The following diagram shows these libraries and how
+this.  The following diagram shows these libraries and how they relate
-they relate to each other, with the arrows indicating ``builds on'' or
+to each other, with the arrows indicating ``builds on'' or
-``extends''.  For example, the Quack library builds on cmuscheme, which
+``extends''.  For example, the Quack library builds on cmuscheme,
-in turn builds on the standard scheme mode.
+which in turn builds on the standard scheme mode.
 
 @example
             scheme
@@ -369,23 +369,22 @@ 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 fundamental change to the way that Scheme code
+combination, but with a change to the way that Scheme code fragments
-fragments are sent to the interpreter for evaluation.  cmuscheme and
+are sent to the interpreter for evaluation.  cmuscheme and Quack send
-Quack send code fragments to the interpreter's standard input, on the
+code fragments to the interpreter's standard input, on the assumption
-assumption that the interpreter is expecting to read Scheme expressions
+that the interpreter is expecting to read Scheme expressions there,
-there, and then monitor the interpreter's standard output to infer what
+and then monitor the interpreter's standard output to infer what the
-the result of the evaluation is.  GDS doesn't use standard input and
+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
+evaluation, thus providing similar function to cmuscheme or Quack.
-also include requests for stack exploration and
+They also include requests for stack exploration and debugging, which
-debugging, which go beyond what cmuscheme or Quack can do.  The price of
+go beyond what cmuscheme or Quack can do.  The price of this extra
-this extra power, however, is that GDS is Guile-specific.  GDS requires
+power, however, is that GDS is Guile-specific.  GDS requires the
-the Scheme interpreter to run
+Scheme interpreter to run some GDS-specific library code; currently
-some GDS-specific library code; currently this code is written as a
+this code is written as a Guile module and uses features that are
-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
@@ -588,7 +587,7 @@ 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 various ways of doing this.
+following subsections describe the ways of doing this.
 
 @subsubsection Invoking GDS when an Exception Occurs
 
@@ -622,7 +621,7 @@ is pre-1.8) around the code of interest like this:
     (gds-debug-trap (throw->trap-context key args))))
 @end lisp
 
-In all cases you will need to use the @code{(ice-9 gds-client)} and
+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
@@ -637,7 +636,6 @@ procedure as follows.
 @lisp
 (use-modules (ice-9 gds-client)
              (ice-9 debugging traps))
-
 (on-lazy-handler-dispatch gds-debug-trap)
 @end lisp
 
@@ -686,34 +684,34 @@ This approach is not yet implemented, though.
 
 @subsubsection Utility Guile Implementation
 
-We conclude this subsection with an aside, by noting that the
+The ``utility'' Guile client mentioned above is a simple combination
-``utility'' Guile client described above is nothing more than a
+of the mechanisms that we have just described.  In fact the code for
-combination of the previous options.
+the utility Guile client is essentially just this:
-
-To be precise, 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
+The @code{named-module-use!} line ensures that the client can process
-@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}
+Guile's online help.  The @code{#f} parameter to
-means that the @code{continue} instruction will not cause the
+@code{gds-accept-input} means that the @code{continue} instruction
-instruction loop to exit, which makes sense here because the utility
+will not cause the instruction loop to exit, which makes sense here
-client has nothing to do except to process GDS instructions.
+because the utility client has nothing to do except to process GDS
+instructions.
 
-(The utility client does not use @code{on-lazy-handler-dispatch},
+The utility client does not use @code{on-lazy-handler-dispatch} at its
-because it has its own mechanism for catching and reporting exceptions
+top level, because it has its own mechanism for catching and reporting
-in the code that it is asked to evaluate.  This mechanism summarizes the
+exceptions in the code that it is asked to evaluate.  This mechanism
-exception and gives the user a button they can click to see the full
+summarizes the exception and gives the user a button they can click to
-stack, so the end result is very similar to what
+see the full stack, so the end result is very similar to what
-@code{on-lazy-handler-dispatch} provides.)
+@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
@@ -745,7 +743,7 @@ 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 C-g
+@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