*** empty log message ***

[gnu-emacs] / lispref / edebug.texi

diff --git a/lispref/edebug.texi b/lispref/edebug.texi
index d8459d2bceabcde61a02306214f3a906b163cff3..c40a70d753b57e07e5259dd76593ec65f50d1fe1 100644 (file)
--- a/lispref/edebug.texi
+++ b/lispref/edebug.texi
@@ -9,7 +9,7 @@
 
 @c , Bugs and Todo List, Top, Top
 
 
 @c , Bugs and Todo List, Top, Top
 

-@node Edebug,, Compilation Errors, Debugging
+@node Edebug, Syntax Errors, Debugger, Debugging

 @section Edebug
 @cindex Edebug mode
 
 @section Edebug
 @cindex Edebug mode
 


@@ -36,7 +36,7 @@ Display expression results and evaluate expressions as if outside of
 Edebug.
 
 @item 
 Edebug.
 
 @item 

-Automatically reevaluate a list of expressions and
+Automatically re-evaluate a list of expressions and

 display their results each time Edebug updates the display.
 
 @item
 display their results each time Edebug updates the display.
 
 @item


@@ -199,11 +199,11 @@ steps into the call after instrumenting the function.
 @cindex Common Lisp (Edebug)
 @pindex cl.el @r{(Edebug)}
 @pindex cl-specs.el
 @cindex Common Lisp (Edebug)
 @pindex cl.el @r{(Edebug)}
 @pindex cl-specs.el

-  Edebug knows how to instrument all the standard special forms, an
-interactive form with an expression argument, anonymous lambda
+  Edebug knows how to instrument all the standard special forms,
+@code{interactive} forms with an expression argument, anonymous lambda

 expressions, and other defining forms.  Edebug cannot know what a
 user-defined macro will do with the arguments of a macro call, so you
 expressions, and other defining forms.  Edebug cannot know what a
 user-defined macro will do with the arguments of a macro call, so you

-must tell it; @xref{Instrumenting Macro Calls}, for details.
+must tell it; see @ref{Instrumenting Macro Calls}, for details.

 
   When Edebug is about to instrument code for the first time in a
 session, it runs the hook @code{edebug-setup-hook}, then sets it to
 
   When Edebug is about to instrument code for the first time in a
 session, it runs the hook @code{edebug-setup-hook}, then sets it to


@@ -212,7 +212,7 @@ session, it runs the hook @code{edebug-setup-hook}, then sets it to
 using, but actually load them only if you use Edebug.
 
 @findex eval-expression @r{(Edebug)}
 using, but actually load them only if you use Edebug.
 
 @findex eval-expression @r{(Edebug)}

-  To remove instrumentation from a definition, simply reevaluate its
+  To remove instrumentation from a definition, simply re-evaluate its

 definition in a way that does not instrument.  There are two ways of
 evaluating forms that never instrument them: from a file with
 @code{load}, and from the minibuffer with @code{eval-expression}
 definition in a way that does not instrument.  There are two ways of
 evaluating forms that never instrument them: from a file with
 @code{load}, and from the minibuffer with @code{eval-expression}


@@ -335,8 +335,8 @@ Step into the function or macro called by the form after point.
 @end table
 
 The @kbd{h} command proceeds to the stop point near the current location
 @end table
 
 The @kbd{h} command proceeds to the stop point near the current location

-if point, using a temporary breakpoint.  See @ref{Breakpoints}, for more
-about breakpoints.
+of point, using a temporary breakpoint.  See @ref{Breakpoints}, for more
+information about breakpoints.

 
 The @kbd{f} command runs the program forward over one expression.  More
 precisely, it sets a temporary breakpoint at the position that
 
 The @kbd{f} command runs the program forward over one expression.  More
 precisely, it sets a temporary breakpoint at the position that


@@ -463,7 +463,7 @@ with @kbd{u}.  First move point to the Edebug stop point of your choice,
 then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
 Unsetting a breakpoint where none has been set has no effect.
 
 then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
 Unsetting a breakpoint where none has been set has no effect.
 

-Reevaluating or reinstrumenting a definition forgets all its breakpoints.
+Re-evaluating or reinstrumenting a definition forgets all its breakpoints.

 
 A @dfn{conditional breakpoint} tests a condition each time the program
 gets there.  Any errors that occur as a result of evaluating the
 
 A @dfn{conditional breakpoint} tests a condition each time the program
 gets there.  Any errors that occur as a result of evaluating the


@@ -568,7 +568,7 @@ are bound to the values they had outside of Edebug.
 @subsection Edebug Views
 
   These Edebug commands let you view aspects of the buffer and window
 @subsection Edebug Views
 
   These Edebug commands let you view aspects of the buffer and window

-status that obtained before entry to Edebug.  The outside window
+status as they were before entry to Edebug.  The outside window

 configuration is the collection of windows and contents that were in
 effect outside of Edebug.
 
 configuration is the collection of windows and contents that were in
 effect outside of Edebug.
 


@@ -583,10 +583,12 @@ position (@code{edebug-bounce-point}).  With a prefix argument @var{n},
 pause for @var{n} seconds instead.
 
 @item w
 pause for @var{n} seconds instead.
 
 @item w

-Move point back to the current stop point (@code{edebug-where}) in the
-source code buffer.  Also, if you use this command in a different window
-displaying the same buffer, that window will be used instead to display
-the current definition in the future.
+Move point back to the current stop point in the source code buffer
+(@code{edebug-where}).
+
+If you use this command in a different window displaying the same
+buffer, that window will be used instead to display the current
+definition in the future.

 
 @item W
 @c Its function is not simply to forget the saved configuration -- dan
 
 @item W
 @c Its function is not simply to forget the saved configuration -- dan


@@ -745,7 +747,6 @@ After selecting @samp{*edebug*}, you can return to the source code
 buffer with @kbd{C-c C-w}.  The @samp{*edebug*} buffer is killed when
 you continue execution, and recreated next time it is needed.
 
 buffer with @kbd{C-c C-w}.  The @samp{*edebug*} buffer is killed when
 you continue execution, and recreated next time it is needed.
 

-

 @node Printing in Edebug
 @subsection Printing in Edebug
 
 @node Printing in Edebug
 @subsection Printing in Edebug
 


@@ -765,7 +766,6 @@ and @code{edebug-print-level} specify the values to use within Edebug.)
 @defopt edebug-print-length
 If non-@code{nil}, bind @code{print-length} to this while printing
 results in Edebug.  The default value is @code{50}.
 @defopt edebug-print-length
 If non-@code{nil}, bind @code{print-length} to this while printing
 results in Edebug.  The default value is @code{50}.

-@xref{Printing in Edebug}.

 @end defopt
 
 @defopt edebug-print-level 
 @end defopt
 
 @defopt edebug-print-level 


@@ -785,13 +785,13 @@ edebug-uninstall-custom-print}.
 
 @example
 (setq a '(x y))
 
 @example
 (setq a '(x y))

-(setcar a a))
+(setcar a a)

 @end example
 
 @noindent
 Custom printing prints this as @samp{Result: #1=(#1# y)}.  The
 @samp{#1=} notation labels the structure that follows it with the label
 @end example
 
 @noindent
 Custom printing prints this as @samp{Result: #1=(#1# y)}.  The
 @samp{#1=} notation labels the structure that follows it with the label

-@samp{1}, and the @samp{#1#} notation references the previously labelled
+@samp{1}, and the @samp{#1#} notation references the previously labeled

 structure.  This notation is used for any shared elements of lists or
 vectors.
 
 structure.  This notation is used for any shared elements of lists or
 vectors.
 


@@ -844,11 +844,10 @@ with @code{(apply 'format @var{format-string} @var{format-args})}.
 It also appends a newline to separate entries.
 @end defun
 
 It also appends a newline to separate entries.
 @end defun
 

-  @code{edebug-tracing} and @code{edebug-trace} insert lines in the trace
-buffer even if Edebug is not active.
-
-  Adding text to the trace buffer also scrolls its window to show the
-last lines inserted.
+  @code{edebug-tracing} and @code{edebug-trace} insert lines in the
+trace buffer whenever they are called, even if Edebug is not active.
+Adding text to the trace buffer also scrolls its window to show the last
+lines inserted.

 
 @node Coverage Testing
 @subsection Coverage Testing
 
 @node Coverage Testing
 @subsection Coverage Testing


@@ -857,12 +856,24 @@ last lines inserted.
 @cindex frequency counts
 @cindex performance analysis
 Edebug provides rudimentary coverage testing and display of execution
 @cindex frequency counts
 @cindex performance analysis
 Edebug provides rudimentary coverage testing and display of execution

-frequency.  All execution of an instrumented function accumulates
-frequency counts, both before and after evaluation of each instrumented
-expression, even if the execution mode is Go-nonstop.  Coverage testing
-is more expensive, so it is done only if @code{edebug-test-coverage} is
-non-@code{nil}.  The command @kbd{M-x edebug-display-freq-count}
-displays both the frequency data and the coverage data (if recorded).
+frequency.
+
+  Coverage testing works by comparing the result of each expression with
+the previous result; each form in the program is considered ``covered''
+if it has returned two different values since you began testing coverage
+in the current Emacs session.  Thus, to do coverage testing on your
+program, execute it under various conditions and note whether it behaves
+correctly; Edebug will tell you when you have tried enough different
+conditions that each form has returned two different values.
+
+  Coverage testing makes execution slower, so it is only done if
+@code{edebug-test-coverage} is non-@code{nil}.  Frequency counting is
+performed for all execution of an instrumented function, even if the
+execution mode is Go-nonstop, and regardless of whether coverage testing
+is enabled.
+
+  Use @kbd{M-x edebug-display-freq-count} to display both the
+coverage information and the frequency counts for a definition.

 
 @deffn Command edebug-display-freq-count
 This command displays the frequency count data for each line of the
 
 @deffn Command edebug-display-freq-count
 This command displays the frequency count data for each line of the


@@ -871,15 +882,16 @@ current definition.
 The frequency counts appear as comment lines after each line of code,
 and you can undo all insertions with one @code{undo} command.  The
 counts appear under the @samp{(} before an expression or the @samp{)}
 The frequency counts appear as comment lines after each line of code,
 and you can undo all insertions with one @code{undo} command.  The
 counts appear under the @samp{(} before an expression or the @samp{)}

-after an expression, or on the last character of a symbol.  Values do
-not appear if they are equal to the previous count on the same line.
+after an expression, or on the last character of a variable.  To
+simplify the display, a count is not shown if it is equal to the
+count of an earlier expression on the same line.

 
 The character @samp{=} following the count for an expression says that
 
 The character @samp{=} following the count for an expression says that

-the expression has returned the same value each time it was evaluated
-This is the only coverage information that Edebug records.
+the expression has returned the same value each time it was evaluated.
+In other words, it is not yet ``covered'' for coverage testing purposes.

 
 To clear the frequency count and coverage data for a definition,
 
 To clear the frequency count and coverage data for a definition,

-reinstrument it.
+simply reinstrument it with @code{eval-defun}.

 @end deffn
 
 For example, after evaluating @code{(fac 5)} with a source
 @end deffn
 
 For example, after evaluating @code{(fac 5)} with a source


@@ -930,8 +942,8 @@ program.
 @itemize @bullet
 @item 
 @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
 @itemize @bullet
 @item 
 @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both

-incremented one time to reduce Edebug's impact on the stack.
-You could, however, still run out of stack space when using Edebug.
+incremented once to reduce Edebug's impact on the stack.  You could,
+however, still run out of stack space when using Edebug.

 
 @item 
 The state of keyboard macro execution is saved and restored.  While
 
 @item 
 The state of keyboard macro execution is saved and restored.  While


@@ -1067,8 +1079,8 @@ name.
 @end deffn
 
 Here is a simple example that defines the specification for the
 @end deffn
 
 Here is a simple example that defines the specification for the

-@code{for} macro described in the Emacs Lisp Reference Manual, followed
-by an alternative, equivalent specification.
+@code{for} example macro (@pxref{Argument Evaluation}), followed by an
+alternative, equivalent specification.

 
 @example
 (def-edebug-spec for
 
 @example
 (def-edebug-spec for


@@ -1091,7 +1103,7 @@ None of the arguments is instrumented.
 @item a symbol
 The symbol must have an Edebug specification which is used instead.
 This indirection is repeated until another kind of specification is
 @item a symbol
 The symbol must have an Edebug specification which is used instead.
 This indirection is repeated until another kind of specification is

-found.  This allows you to inherit the specification for another macro.
+found.  This allows you to inherit the specification from another macro.

 
 @item a list
 The elements of the list describe the types of the arguments of a
 
 @item a list
 The elements of the list describe the types of the arguments of a


@@ -1137,9 +1149,8 @@ their meanings:
 
 @table @code
 @item sexp
 
 @table @code
 @item sexp

-A single Lisp object, not unevaluated.
-@c "unevaluated expression" is not meaningful, because
-@c an expression is a Lisp object intended for evaluation.
+A single unevaluated Lisp object, which is not instrumented.
+@c an "expression" is not necessarily intended for evaluation.

 
 @item form
 A single evaluated expression, which is instrumented.
 
 @item form
 A single evaluated expression, which is instrumented.


@@ -1175,8 +1186,9 @@ elements must all match or none, use @code{&optional
 @item &rest
 @kindex &rest @r{(Edebug)}
 All following elements in the specification list are repeated zero or
 @item &rest
 @kindex &rest @r{(Edebug)}
 All following elements in the specification list are repeated zero or

-more times.  All the elements need not match in the last repetition,
-however.
+more times.  In the last repetition, however, it is not a problem if the
+expression runs out before matching all of the elements of the
+specification list.

 
 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
 To specify several elements that must all match on every repetition, use
 
 To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
 To specify several elements that must all match on every repetition, use


@@ -1202,7 +1214,7 @@ succeeds.
 @item &define 
 @kindex &define @r{(Edebug)}
 Indicates that the specification is for a defining form.  The defining
 @item &define 
 @kindex &define @r{(Edebug)}
 Indicates that the specification is for a defining form.  The defining

-form itself is not instrumented (i.e. Edebug does not stop before and
+form itself is not instrumented (that is, Edebug does not stop before and

 after the defining form), but forms inside it typically will be
 instrumented.  The @code{&define} keyword should be the first element in
 a list specification.
 after the defining form), but forms inside it typically will be
 instrumented.  The @code{&define} keyword should be the first element in
 a list specification.


@@ -1260,7 +1272,7 @@ a list whose elements match the specification @var{elements}.
 A sublist specification may be a dotted list and the corresponding list
 argument may then be a dotted list.  Alternatively, the last @sc{cdr} of a
 dotted list specification may be another sublist specification (via a
 A sublist specification may be a dotted list and the corresponding list
 argument may then be a dotted list.  Alternatively, the last @sc{cdr} of a
 dotted list specification may be another sublist specification (via a

-grouping or an indirect specification, e.g. @code{(spec .  [(more
+grouping or an indirect specification, e.g., @code{(spec .  [(more

 specs@dots{})])}) whose elements match the non-dotted list arguments.
 This is useful in recursive specifications such as in the backquote
 example below.  Also see the description of a @code{nil} specification
 specs@dots{})])}) whose elements match the non-dotted list arguments.
 This is useful in recursive specifications such as in the backquote
 example below.  Also see the description of a @code{nil} specification


@@ -1293,7 +1305,7 @@ than once.
 
 @item arg
 The argument, a symbol, is the name of an argument of the defining form.
 
 @item arg
 The argument, a symbol, is the name of an argument of the defining form.

-However, lambda list keywords (symbols starting with @samp{@code{&}})
+However, lambda-list keywords (symbols starting with @samp{&})

 are not allowed.
 
 @item lambda-list
 are not allowed.
 
 @item lambda-list


@@ -1326,33 +1338,35 @@ necessarily mean a syntax error will be signaled; instead,
 exhausted.  Eventually every element of the argument list must be
 matched by some element in the specification, and every required element
 in the specification must match some argument.
 exhausted.  Eventually every element of the argument list must be
 matched by some element in the specification, and every required element
 in the specification must match some argument.

-
-Backtracking is disabled for the remainder of a sublist or group when
-certain conditions occur, described below.  Backtracking is reenabled
-when a new alternative is established by @code{&optional}, @code{&rest},
-or @code{&or}.  It is also reenabled initially when processing a
-sublist or group specification or an indirect specification.
-
-You might want to disable backtracking to commit to some alternative so
-that Edebug can provide a more specific syntax error message.  Normally,
-if no alternative matches, Edebug reports that none matched, but if one
-alternative is committed to, Edebug can report how it failed to match.
-
-First, backtracking is disabled while matching any of the form
-specifications (i.e. @code{form}, @code{body}, @code{def-form}, and
+  
+When a syntax error is detected, it might not be reported until much
+later after higher-level alternatives have been exhausted, and with the
+point positioned further from the real error.  But if backtracking is
+disabled when an error occurs, it can be reported immediately.  Note
+that backtracking is also reenabled automatically in several situations;
+it is reenabled when a new alternative is established by
+@code{&optional}, @code{&rest}, or @code{&or}, or at the start of
+processing a sublist, group, or indirect specification.  The effect of
+enabling or disabling backtracking is limited to the remainder of the
+level currently being processed and lower levels.
+
+Backtracking is disabled while matching any of the
+form specifications (that is, @code{form}, @code{body}, @code{def-form}, and

 @code{def-body}).  These specifications will match any form so any error
 must be in the form itself rather than at a higher level.
 
 @code{def-body}).  These specifications will match any form so any error
 must be in the form itself rather than at a higher level.
 

-Second, backtracking is disabled after successfully matching a quoted
+Backtracking is also disabled after successfully matching a quoted

 symbol or string specification, since this usually indicates a
 symbol or string specification, since this usually indicates a

-recognized construct.  If you have a set of alternative constructs that
+recognized construct.  But if you have a set of alternative constructs that

 all begin with the same symbol, you can usually work around this
 constraint by factoring the symbol out of the alternatives, e.g.,
 @code{["foo" &or [first case] [second case] ...]}.
 
 all begin with the same symbol, you can usually work around this
 constraint by factoring the symbol out of the alternatives, e.g.,
 @code{["foo" &or [first case] [second case] ...]}.
 

-Third, backtracking may be explicitly disabled by using the
-@code{gate} specification.  This is useful when you know that
-no higher alternatives may apply.
+Most needs are satisfied by these two ways that bactracking is
+automatically disabled, but occasionally it is useful to explicitly
+disable backtracking by using the @code{gate} specification.  This is
+useful when you know that no higher alternatives could apply.  See the
+example of the @code{let} specification.

 
 @node Specification Examples
 @subsubsection Specification Examples
 
 @node Specification Examples
 @subsubsection Specification Examples


@@ -1362,7 +1376,7 @@ the examples provided here.
 
 A @code{let} special form has a sequence of bindings and a body.  Each
 of the bindings is either a symbol or a sublist with a symbol and
 
 A @code{let} special form has a sequence of bindings and a body.  Each
 of the bindings is either a symbol or a sublist with a symbol and

-optional value.  In the specification below, notice the @code{gate}
+optional expression.  In the specification below, notice the @code{gate}

 inside of the sublist to prevent backtracking once a sublist is found.
 
 @example
 inside of the sublist to prevent backtracking once a sublist is found.
 
 @example


@@ -1491,19 +1505,11 @@ function entry or exit per line, indented by the recursion level.
 
 The default value is @code{nil}.  
 
 
 The default value is @code{nil}.  
 

-Also see @code{edebug-tracing}, in @xref{Trace Buffer}.
+Also see @code{edebug-tracing}, in @ref{Trace Buffer}.

 @end defopt
 
 @defopt edebug-test-coverage 
 If non-@code{nil}, Edebug tests coverage of all expressions debugged.
 @end defopt
 
 @defopt edebug-test-coverage 
 If non-@code{nil}, Edebug tests coverage of all expressions debugged.

-This is done by comparing the result of each expression
-with the previous result. Coverage is considered OK if two different
-results are found.  So to sufficiently test the coverage of your code,
-try to execute it under conditions that evaluate all expressions more
-than once, and produce different results for each expression.
-
-Use @kbd{M-x edebug-display-freq-count} to display the frequency count
-and coverage information for a definition.

 @xref{Coverage Testing}.
 @end defopt
 
 @xref{Coverage Testing}.
 @end defopt