(Interactive Debugger): Cover continuing

execution.
(Stepping and Continuing): New (from CVS HEAD).
(GDS Introduction): Mention traps and continuing execution.

doc/ref/ChangeLog

@@ -1,5 +1,10 @@
 2008-03-19  Neil Jerram  <neil@ossau.uklinux.net>
 
+	* scheme-using.texi (Interactive Debugger): Cover continuing
+	execution.
+	(Stepping and Continuing): New (from CVS HEAD).
+	(GDS Introduction): Mention traps and continuing execution.
+
 	* api-debug.texi (Location Traps): Corrected to reflect that
 	location traps now specify a specific position, not a range of
 	positions.

doc/ref/scheme-using.texi

@@ -163,9 +163,10 @@ The interactive debugger is documented further in the following section.
 @node Interactive Debugger
 @subsection Using the Interactive Debugger
 
-Guile's interactive debugger is a command line application that accepts
+Guile's interactive debugger is a command line application that
-commands from you for examining the stack.  Unlike in the normal
+accepts commands from you for examining the stack and, if stopped at a
-Guile REPL, commands are typed mostly without parentheses.
+trap, for continuing program execution in various ways.  Unlike in the
+normal Guile REPL, commands are typed mostly without parentheses.
 
 When you first enter the debugger, it introduces itself with a message
 like this:
@@ -195,6 +196,7 @@ The other available commands are described in the following subsections.
 * Frame Selection::             up, down, frame.
 * Frame Information::           info args, info frame, position.
 * Frame Evaluation::            evaluate.
+* Stepping and Continuing::     step, next, (trace-)finish, continue.
 @end menu
 
 
@@ -317,6 +319,43 @@ may be continued over multiple lines.
 @end deffn
 
 
+@node Stepping and Continuing
+@subsubsection Single Stepping and Continuing Execution
+
+The commands in this subsection all apply only when the stack is
+@dfn{continuable} --- in other words when it makes sense for the program
+that the stack comes from to continue running.  Usually this means that
+the program stopped because of a trap or a breakpoint.
+
+@deffn {Debugger Command} step [n]
+Tell the debugged program to do @var{n} more steps from its current
+position.  One @dfn{step} means executing until the next frame entry or
+exit of any kind.  @var{n} defaults to 1.
+@end deffn
+
+@deffn {Debugger Command} next [n]
+Tell the debugged program to do @var{n} more steps from its current
+position, but only counting frame entries and exits where the
+corresponding source code comes from the same file as the current stack
+frame.  (See @ref{Step Traps} for the details of how this works.)  If
+the current stack frame has no source code, the effect of this command
+is the same as of @code{step}.  @var{n} defaults to 1.
+@end deffn
+
+@deffn {Debugger Command} finish
+Tell the program being debugged to continue running until the completion
+of the current stack frame, and at that time to print the result and
+reenter the command line debugger.
+@end deffn
+
+@deffn {Debugger Command} continue
+Tell the program being debugged to continue running.  (In fact this is
+the same as the @code{quit} command, because it exits the debugger
+command loop and so allows whatever code it was that invoked the
+debugger to continue.)
+@end deffn
+
+
 @node Using Guile in Emacs
 @section Using Guile in Emacs
 
@@ -444,20 +483,25 @@ popping up in a temporary Emacs window.
 @end itemize
 
 @item
-Debugging a Guile Scheme program.  When your program hits an error,
+Debugging a Guile Scheme program.  When your program hits an error or
-GDS shows you the relevant code and the Scheme stack, and makes it
+stops at a trap, GDS shows you the relevant code and the Scheme stack,
-easy to
+and makes it easy to
 
 @itemize
 @item
 look at the values of local variables
 @item
-see what is happening at all levels of the Scheme stack.
+see what is happening at all levels of the Scheme stack
+@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.
+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