summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNeil Jerram <neil@ossau.uklinux.net>2006-09-25 21:05:46 +0000
committerNeil Jerram <neil@ossau.uklinux.net>2006-09-25 21:05:46 +0000
commitee6be719ce2e34d23b6dcd0cf1095ed40261ad88 (patch)
tree2a25548ecc581954c553bd0b424387875bb2d404
parent534cd148682af22fbf6a820126fe7c1806f2d3db (diff)
downloadguile-ee6be719ce2e34d23b6dcd0cf1095ed40261ad88.tar.gz
* 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.
-rw-r--r--doc/ref/ChangeLog12
-rw-r--r--doc/ref/scheme-using.texi118
-rw-r--r--ice-9/ChangeLog11
-rw-r--r--ice-9/debugger/commands.scm24
-rw-r--r--ice-9/debugging/ice-9-debugger-extensions.scm16
5 files changed, 110 insertions, 71 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index 7838e31ca..493da2849 100644
--- a/doc/ref/ChangeLog
+++ b/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
diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi
index 6eac11aee..6ff3c0df0 100644
--- a/doc/ref/scheme-using.texi
+++ b/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
-following subsections.
+the normal Guile REPL. In case you find yourself in the debugger by
+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.
-* Run To Frame Exit:: finish, trace-finish.
-* Continue Execution:: continue.
-* Leave Debugger:: quit.
+* Stepping and Continuing:: step, next, (trace-)finish, continue.
@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.
-The expression must appear on the same line as the command,
-however it may be continued over multiple lines.
+Evaluate an expression in the environment of the selected stack frame.
+The expression must appear on the same line as the command, however it
+may be continued over multiple lines.
@end deffn
-@node Single Stepping
-@subsubsection Single Stepping
+@node Stepping and Continuing
+@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
-entry or exit of any kind. @var{n} defaults to 1.
+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} single-steps to the entry or
-exit of a frame whose code comes from the same source file as the
-selected stack frame. (See @ref{Step Traps} for the details of how
-this works.) If the selected stack frame has no source, the effect of
-this command is the same as of @code{step}. @var{n} defaults to 1.
+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
-
-@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
-completion of the selected stack frame, and at that time to print the
-result and reenter the command line debugger.
-@end deffn
-
-@deffn {Debugger Command} trace-finish
-Trace until evaluation of the current frame is complete.
+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
-
-@node Continue Execution
-@subsubsection Continue Execution
-
-[to be completed]
-
@deffn {Debugger Command} continue
-Tell the program being debugged to continue running.
-@end deffn
-
-
-@node Leave Debugger
-@subsubsection Leave Debugger
-
-[to be completed]
-
-@deffn {Debugger Command} quit
-Exit the debugger.
+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
diff --git a/ice-9/ChangeLog b/ice-9/ChangeLog
index c2ff7715a..9786388b5 100644
--- a/ice-9/ChangeLog
+++ b/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.
diff --git a/ice-9/debugger/commands.scm b/ice-9/debugger/commands.scm
index 1d716e2bb..ef6f79026 100644
--- a/ice-9/debugger/commands.scm
+++ b/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.
-The expression must appear on the same line as the command,
-however it may be continued over multiple lines."
+ "Evaluate an expression in the environment of the selected stack frame.
+The expression must appear on the same line as the command, however it
+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))
diff --git a/ice-9/debugging/ice-9-debugger-extensions.scm b/ice-9/debugging/ice-9-debugger-extensions.scm
index dc1eb8fc8..217d935b9 100644
--- a/ice-9/debugging/ice-9-debugger-extensions.scm
+++ b/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)