* scheme-using.texi (Error Handling, Interactive Debugger): Minor

editorial improvements.
(Leave Debugger): Removed.
(Display Backtrace): Minor updates.
(Frame Selection, Frame Information, Frame Evaluation) : Minor
editorial improvements.
(Stepping and Continuing): Merged from three previous nodes; plus
minor improvements.  Removed doc for `trace-finish', which no
longer exists.

* debugging/ice-9-debugger-extensions.scm (debugger:step):
Docstring improvements.
(debugger:next): Docstring improvements.
(debugger:continue): Docstring improvements.

* debugger/commands.scm (up, down): Docstring corrections.
(info-args, info-frame, position, evaluate): Docstring
improvements.

doc/ref/ChangeLog

@@ -1,3 +1,15 @@
+2006-09-25  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* scheme-using.texi (Error Handling, Interactive Debugger): Minor
+	editorial improvements.
+	(Leave Debugger): Removed.
+	(Display Backtrace): Minor updates.
+	(Frame Selection, Frame Information, Frame Evaluation) : Minor
+	editorial improvements.
+	(Stepping and Continuing): Merged from three previous nodes; plus
+	minor improvements.  Removed doc for `trace-finish', which no
+	longer exists.
+
 2006-09-20  Ludovic Courtès  <ludovic.courtes@laas.fr>
 
 	* api-data.texi (Standard Character Sets): Documented the

doc/ref/scheme-using.texi

@@ -94,7 +94,7 @@ the execution context where the error occurred and can give you three
 levels of information about what the error was and exactly where it
 occurred.
 
-By default, Guile then displays only the first level, which is the most
+By default, Guile displays only the first level, which is the most
 immediate information about where and why the error occurred, for
 example:
 
@@ -105,7 +105,8 @@ standard input:2:19: In procedure + in expression (+ 3 #\s):
 standard input:2:19: Wrong type argument: #\s
 ABORT: (wrong-type-arg)
 
-Type "(backtrace)" to get more information or "(debug)" to enter the debugger.
+Type "(backtrace)" to get more information
+or "(debug)" to enter the debugger.
 @end lisp
 
 @noindent
@@ -156,7 +157,7 @@ frame (the @code{evaluate} command --- see @ref{Frame Evaluation}).
 @end itemize
 
 @noindent
-This is documented further in the following section.
+The interactive debugger is documented further in the following section.
 
 
 @node Interactive Debugger
@@ -181,18 +182,21 @@ debug>
 
 @noindent
 ``debug>'' is the debugger's prompt, and a reminder that you are not in
-the normal Guile REPL.  The available commands are described in the
+the normal Guile REPL.  In case you find yourself in the debugger by
-following subsections.
+mistake, the @code{quit} command will return you to the REPL.  
+
+@deffn {Debugger Command} quit
+Exit the debugger.
+@end deffn
+
+The other available commands are described in the following subsections.
 
 @menu
 * Display Backtrace::           backtrace.
 * Frame Selection::             up, down, frame.
 * Frame Information::           info args, info frame, position.
 * Frame Evaluation::            evaluate.
-* Single Stepping::             step, next.
+* Stepping and Continuing::     step, next, (trace-)finish, continue.
-* Run To Frame Exit::           finish, trace-finish.
-* Continue Execution::          continue.
-* Leave Debugger::              quit.
 @end menu
 
 
@@ -221,7 +225,7 @@ option @code{depth} determines the maximum number of frames printed.
 @end deffn
 
 The format of the displayed backtrace is the same as for the
-@code{backtrace} procedure.
+@code{display-backtrace} procedure (@pxref{Examining the Stack}).
 
 
 @node Frame Selection
@@ -256,13 +260,13 @@ Frame 1 at standard input:36:14
 
 @deffn {Debugger Command} up [n]
 Move @var{n} frames up the stack.  For positive @var{n}, this
-advances toward the outermost frame, to higher frame numbers, to
+advances toward the outermost frame, to lower frame numbers, to
 frames that have existed longer.  @var{n} defaults to one.
 @end deffn
 
 @deffn {Debugger Command} down [n]
 Move @var{n} frames down the stack.  For positive @var{n}, this
-advances toward the innermost frame, to lower frame numbers, to frames
+advances toward the innermost frame, to higher frame numbers, to frames
 that were created more recently.  @var{n} defaults to one.
 @end deffn
 
@@ -276,85 +280,79 @@ frame to select; it must be a stack-frame number.
 @node Frame Information
 @subsubsection Frame Information
 
-[to be completed]
+The following commands return detailed information about the currently
+selected frame.
 
 @deffn {Debugger Command} {info frame}
-All about selected stack frame.
+Display a verbose description of the selected frame.  The information
+that this command provides is equivalent to what can be deduced from the
+one line summary for the frame that appears in a backtrace, but is
+presented and explained more clearly.
 @end deffn
 
 @deffn {Debugger Command} {info args}
-Argument variables of current stack frame.
+Display the argument variables of the current stack frame.  Arguments
+can also be seen in the backtrace, but are presented more clearly by
+this command.
 @end deffn
 
 @deffn {Debugger Command} position
-Display the position of the current expression.
+Display the name of the source file that the current expression comes
+from, and the line and column number of the expression's opening
+parenthesis within that file.  This information is only available when
+the @code{positions} read option is enabled (@pxref{Reader options}).
 @end deffn
 
 
 @node Frame Evaluation
 @subsubsection Frame Evaluation
 
-[to be completed]
+The @code{evaluate} command is most useful for querying the value of a
+variable, either global or local, in the environment of the selected
+stack frame, but it can be used more generally to evaluate any
+expression.
 
 @deffn {Debugger Command} evaluate expression
-Evaluate an expression.
+Evaluate an expression in the environment of the selected stack frame.
-The expression must appear on the same line as the command,
+The expression must appear on the same line as the command, however it
-however it may be continued over multiple lines.
+may be continued over multiple lines.
 @end deffn
 
 
-@node Single Stepping
+@node Stepping and Continuing
-@subsubsection Single Stepping
+@subsubsection Single Stepping and Continuing Execution
 
-[to be completed]
+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} single-steps to the next frame
+Tell the debugged program to do @var{n} more steps from its current
-entry or exit of any kind.  @var{n} defaults to 1.
+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} single-steps to the entry or
+Tell the debugged program to do @var{n} more steps from its current
-exit of a frame whose code comes from the same source file as the
+position, but only counting frame entries and exits where the
-selected stack frame.  (See @ref{Step Traps} for the details of how
+corresponding source code comes from the same file as the current stack
-this works.)  If the selected stack frame has no source, the effect of
+frame.  (See @ref{Step Traps} for the details of how this works.)  If
-this command is the same as of @code{step}.  @var{n} defaults to 1.
+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
 
-
-@node Run To Frame Exit
-@subsubsection Run To Frame Exit
-
-[to be completed]
-
 @deffn {Debugger Command} finish
-Tell the program being debugged to continue running until the
+Tell the program being debugged to continue running until the completion
-completion of the selected stack frame, and at that time to print the
+of the current stack frame, and at that time to print the result and
-result and reenter the command line debugger.
+reenter the command line debugger.
 @end deffn
 
-@deffn {Debugger Command} trace-finish
-Trace until evaluation of the current frame is complete.
-@end deffn
-
-
-@node Continue Execution
-@subsubsection Continue Execution
-
-[to be completed]
-
 @deffn {Debugger Command} continue
-Tell the program being debugged to continue running.
+Tell the program being debugged to continue running.  (In fact this is
-@end deffn
+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.)
-@node Leave Debugger
-@subsubsection Leave Debugger
-
-[to be completed]
-
-@deffn {Debugger Command} quit
-Exit the debugger.
 @end deffn
 
 

ice-9/ChangeLog

@@ -1,3 +1,14 @@
+2006-09-25  Neil Jerram  <neil@ossau.uklinux.net>
+
+	* debugging/ice-9-debugger-extensions.scm (debugger:step):
+	Docstring improvements.
+	(debugger:next): Docstring improvements.
+	(debugger:continue): Docstring improvements.
+
+	* debugger/commands.scm (up, down): Docstring corrections.
+	(info-args, info-frame, position, evaluate): Docstring
+	improvements.
+
 2006-08-18  Neil Jerram  <neil@ossau.uklinux.net>
 
 	* debugging/trc.scm: New file.

ice-9/debugger/commands.scm

@@ -67,9 +67,9 @@ If the number of frames isn't explicitly given, the debug option
   (throw 'continue))
 
 (define (evaluate state expression)
-  "Evaluate an expression.
+  "Evaluate an expression in the environment of the selected stack frame.
-The expression must appear on the same line as the command,
+The expression must appear on the same line as the command, however it
-however it may be continued over multiple lines."
+may be continued over multiple lines."
   (let ((source (frame-source (stack-ref (state-stack state)
 					 (state-index state)))))
     (if (not source)
@@ -100,18 +100,26 @@ however it may be continued over multiple lines."
 	       (lambda args args)))))
 
 (define (info-args state)
-  "Argument variables of current stack frame."
+  "Display the argument variables of the current stack frame.
+Arguments can also be seen in the backtrace, but are presented more
+clearly by this command."
   (let ((index (state-index state)))
     (let ((frame (stack-ref (state-stack state) index)))
       (write-frame-index-long frame)
       (write-frame-args-long frame))))
 
 (define (info-frame state)
-  "All about selected stack frame."
+  "Display a verbose description of the selected frame.  The
+information that this command provides is equivalent to what can be
+deduced from the one line summary for the frame that appears in a
+backtrace, but is presented and explained more clearly."
   (write-state-long state))
 
 (define (position state)
-  "Display the position of the current expression."
+  "Display the name of the source file that the current expression
+comes from, and the line and column number of the expression's opening
+parenthesis within that file.  This information is only available when
+the 'positions read option is enabled."
   (let* ((frame (stack-ref (state-stack state) (state-index state)))
 	 (source (frame-source frame)))
     (if (not source)
@@ -124,14 +132,14 @@ however it may be continued over multiple lines."
 
 (define (up state n)
   "Move @var{n} frames up the stack.  For positive @var{n}, this
-advances toward the outermost frame, to higher frame numbers, to
+advances toward the outermost frame, to lower frame numbers, to
 frames that have existed longer.  @var{n} defaults to one."
   (set-stack-index! state (+ (state-index state) (or n 1)))
   (write-state-short state))
 
 (define (down state n)
   "Move @var{n} frames down the stack.  For positive @var{n}, this
-advances toward the innermost frame, to lower frame numbers, to frames
+advances toward the innermost frame, to higher frame numbers, to frames
 that were created more recently.  @var{n} defaults to one."
   (set-stack-index! state (- (state-index state) (or n 1)))
   (write-state-short state))

ice-9/debugging/ice-9-debugger-extensions.scm

@@ -45,7 +45,10 @@
       (user-error "This debug session is not continuable.")))
 
 (define (debugger:continue state)
-  "Continue program execution."
+  "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.)"
   (assert-continuable state)
   (throw 'exit-debugger))
 
@@ -59,13 +62,20 @@ print the result obtained."
   (debugger:continue state))
 
 (define (debugger:step state n)
-  "Continue until entry to @var{n}th next frame."
+  "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."
   (assert-continuable state)
   (at-step debug-trap (or n 1))
   (debugger:continue state))
 
 (define (debugger:next state n)
-  "Continue until entry to @var{n}th next frame in same file."
+  "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."
   (assert-continuable state)
   (at-step debug-trap
 	   (or n 1)