# HG changeset patch # User Glenn Morris # Date 1247627392 0 # Node ID e52d10e14bc0613c18dd9a94e2150651361fe588 # Parent a4d216dbf5178303f14e4eaead3844dcff706f08 Minor re-phrasings throughout. (Edebug Execution Modes): Sit-for affects continue mode too. (Jumping): Use `forward-sexp' rather than its keybinding. (Edebug Misc): Fix Q binding. (Edebug Eval): Remove cl version. (Printing in Edebug): Clarify print-length etc. (Instrumenting Macro Calls): Defopt edebug-eval-macro-args. (Specification List): Remove edebug-unwrap findex entry. (Specification Examples): defmacro is actually not the same as defun. Escape "`" in example. diff -r a4d216dbf517 -r e52d10e14bc0 doc/lispref/ChangeLog --- a/doc/lispref/ChangeLog Wed Jul 15 02:05:32 2009 +0000 +++ b/doc/lispref/ChangeLog Wed Jul 15 03:09:52 2009 +0000 @@ -1,3 +1,16 @@ +2009-07-15 Glenn Morris + + * edebug.texi: Minor re-phrasings throughout. + (Edebug Execution Modes): Sit-for affects continue mode too. + (Jumping): Use `forward-sexp' rather than its keybinding. + (Edebug Misc): Fix Q binding. + (Edebug Eval): Remove cl version. + (Printing in Edebug): Clarify print-length etc. + (Instrumenting Macro Calls): Defopt edebug-eval-macro-args. + (Specification List): Remove edebug-unwrap findex entry. + (Specification Examples): defmacro is actually not the same as defun. + Escape "`" in example. + 2009-07-15 Chong Yidong * markers.texi (The Mark): Document optional arg to diff -r a4d216dbf517 -r e52d10e14bc0 doc/lispref/edebug.texi --- a/doc/lispref/edebug.texi Wed Jul 15 02:05:32 2009 +0000 +++ b/doc/lispref/edebug.texi Wed Jul 15 03:09:52 2009 +0000 @@ -14,7 +14,7 @@ @section Edebug @cindex Edebug debugging facility - Edebug is a source-level debugger for Emacs Lisp programs with which + Edebug is a source-level debugger for Emacs Lisp programs, with which you can: @itemize @bullet @@ -40,7 +40,7 @@ display their results each time Edebug updates the display. @item -Output trace info on function enter and exit. +Output trace information on function calls and returns. @item Stop when an error occurs. @@ -56,7 +56,7 @@ @end itemize The first three sections below should tell you enough about Edebug to -enable you to use it. +start using it. @menu * Using Edebug:: Introduction to use of Edebug. @@ -188,7 +188,7 @@ (@code{edebug-instrument-callee}) instruments the definition of the function or macro called by the list form after point, if is not already instrumented. This is possible only if Edebug knows where to find the -source for that function; for this reading, after loading Edebug, +source for that function; for this reason, after loading Edebug, @code{eval-region} records the position of every definition it evaluates, even if not instrumenting it. See also the @kbd{i} command (@pxref{Jumping}), which steps into the call after instrumenting the @@ -199,7 +199,7 @@ expressions, and other defining forms. However, Edebug cannot determine on its own what a user-defined macro will do with the arguments of a macro call, so you must provide that information using Edebug -specifications; see @ref{Edebug and Macros}, for details. +specifications; for details, @pxref{Edebug and Macros}. 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 @@ -293,18 +293,18 @@ of the keyboard macro. This is not easy to fix. Also, defining or executing a keyboard macro outside of Edebug does not affect commands inside Edebug. This is usually an advantage. See also the -@code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}). +@code{edebug-continue-kbd-macro} option in @ref{Edebug Options}. When you enter a new Edebug level, the initial execution mode comes -from the value of the variable @code{edebug-initial-mode}. -(@xref{Edebug Options}.) By default, this specifies step mode. Note +from the value of the variable @code{edebug-initial-mode} +(@pxref{Edebug Options}). By default, this specifies step mode. Note that you may reenter the same Edebug level several times if, for example, an instrumented function is called several times from one command. @defopt edebug-sit-for-seconds This option specifies how many seconds to wait between execution steps -in trace mode. The default is 1 second. +in trace mode or continue mode. The default is 1 second. @end defopt @node Jumping @@ -329,7 +329,7 @@ (@code{edebug-forward-sexp}). @item o -Run the program until the end of the containing sexp. +Run the program until the end of the containing sexp (@code{edebug-step-out}). @item i Step into the function or macro called by the form after point. @@ -340,22 +340,22 @@ The @kbd{f} command runs the program forward over one expression. More precisely, it sets a temporary breakpoint at the position that -@kbd{C-M-f} would reach, then executes in go mode so that the program -will stop at breakpoints. +@code{forward-sexp} would reach, then executes in go mode so that +the program will stop at breakpoints. With a prefix argument @var{n}, the temporary breakpoint is placed @var{n} sexps beyond point. If the containing list ends before @var{n} more elements, then the place to stop is after the containing expression. -You must check that the position @kbd{C-M-f} finds is a place that the -program will really get to. In @code{cond}, for example, this may not -be true. +You must check that the position @code{forward-sexp} finds is a place +that the program will really get to. In @code{cond}, for example, +this may not be true. For flexibility, the @kbd{f} command does @code{forward-sexp} starting at point, rather than at the stop point. If you want to execute one -expression @emph{from the current stop point}, first type @kbd{w}, to -move point there, and then type @kbd{f}. +expression @emph{from the current stop point}, first type @kbd{w} +(@code{edebug-where}) to move point there, and then type @kbd{f}. The @kbd{o} command continues ``out of'' an expression. It places a temporary breakpoint at the end of the sexp containing point. If the @@ -398,7 +398,7 @@ @item Q Like @kbd{q}, but don't stop even for protected code -(@code{top-level-nonstop}). +(@code{edebug-top-level-nonstop}). @item r Redisplay the most recently known expression result in the echo area @@ -641,7 +641,8 @@ interference with the evaluation. @item M-: @var{exp} @key{RET} -Evaluate expression @var{exp} in the context of Edebug itself. +Evaluate expression @var{exp} in the context of Edebug itself +(@code{eval-expression}). @item C-x C-e Evaluate the expression before point, in the context outside of Edebug @@ -651,8 +652,8 @@ @cindex lexical binding (Edebug) Edebug supports evaluation of expressions containing references to lexically bound symbols created by the following constructs in -@file{cl.el} (version 2.03 or later): @code{lexical-let}, -@code{macrolet}, and @code{symbol-macrolet}. +@file{cl.el}: @code{lexical-let}, @code{macrolet}, and +@code{symbol-macrolet}. @node Eval List @subsection Evaluation List Buffer @@ -718,10 +719,10 @@ Thus, if you type @kbd{C-c C-u} again without changing the buffer text, the evaluation list is effectively unchanged. - If an error occurs during an evaluation from the evaluation list, the -error message is displayed in a string as if it were the result. -Therefore, expressions that use variables not currently valid do not -interrupt your debugging. + If an error occurs during an evaluation from the evaluation list, +the error message is displayed in a string as if it were the result. +Therefore, expressions using variables that are not currently valid do +not interrupt your debugging. Here is an example of what the evaluation list window looks like after several expressions have been added to it: @@ -769,10 +770,10 @@ One way to cope with circular structure is to set @code{print-length} or @code{print-level} to truncate the printing. Edebug does this for -you; it binds @code{print-length} and @code{print-level} to 50 if they -were @code{nil}. (Actually, the variables @code{edebug-print-length} -and @code{edebug-print-level} specify the values to use within Edebug.) -@xref{Output Variables}. +you; it binds @code{print-length} and @code{print-level} to the values +of the variables @code{edebug-print-length} and +@code{edebug-print-level} (so long as they have non-@code{nil} +values). @xref{Output Variables}. @defopt edebug-print-length If non-@code{nil}, Edebug binds @code{print-length} to this value while @@ -876,7 +877,7 @@ 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 +performed for all executions of an instrumented function, even if the execution mode is Go-nonstop, and regardless of whether coverage testing is enabled. @@ -891,12 +892,12 @@ This command displays the frequency count data for each line of the 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{)} -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. +It inserts frequency counts as comment lines after each line of code. +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 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 expression has returned the same value each time it was evaluated. @@ -954,8 +955,8 @@ @itemize @bullet @item @code{max-lisp-eval-depth} and @code{max-specpdl-size} are both -incremented once to reduce Edebug's impact on the stack. You could, -however, still run out of stack space when using Edebug. +increased 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 @@ -1011,7 +1012,7 @@ @item The variables @code{overlay-arrow-position} and -@code{overlay-arrow-string} are saved and restored. So you can safely +@code{overlay-arrow-string} are saved and restored, so you can safely invoke Edebug from the recursive edit elsewhere in the same buffer. @item @@ -1103,7 +1104,7 @@ @end smallexample The Edebug specification says which parts of a call to the macro are -forms to be evaluated. For simple macros, the @var{specification} +forms to be evaluated. For simple macros, the specification often looks very similar to the formal argument list of the macro definition, but specifications are much more general than macro arguments. @xref{Defining Macros}, for more explanation of @@ -1135,7 +1136,7 @@ None of the arguments is instrumented. @item a symbol -The symbol must have an Edebug specification which is used instead. +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 from another macro. @@ -1145,12 +1146,16 @@ described in the following sections. @end table -@vindex edebug-eval-macro-args If a macro has no Edebug specification, neither through a @code{debug} declaration nor through a @code{def-edebug-spec} call, the variable -@code{edebug-eval-macro-args} comes into play. If it is @code{nil}, -the default, none of the arguments is instrumented for evaluation. -If it is non-@code{nil}, all arguments are instrumented. +@code{edebug-eval-macro-args} comes into play. + +@defopt edebug-eval-macro-args +This controls the way Edebug treats macro arguments with no explicit +Edebug specification. If it is @code{nil} (the default), none of the +arguments is instrumented for evaluation. Otherwise, all arguments +are instrumented. +@end defopt @node Specification List @subsubsection Specification List @@ -1170,8 +1175,8 @@ sublist or group they are contained in. When a specification list involves alternatives or repetition, matching -it against an actual macro call may require backtracking. -@xref{Backtracking}, for more details. +it against an actual macro call may require backtracking. For more +details, @pxref{Backtracking}. Edebug specifications provide the power of regular expression matching, plus some context-free grammar constructs: the matching of sublists with @@ -1191,7 +1196,8 @@ A single evaluated expression, which is instrumented. @item place -@findex edebug-unwrap +@c I can't see that this index entry is useful without any explanation. +@c @findex edebug-unwrap A place to store a value, as in the Common Lisp @code{setf} construct. @item body @@ -1275,11 +1281,11 @@ specification} should be either a list specification that is used in place of the symbol, or a function that is called to process the arguments. The specification may be defined with @code{def-edebug-spec} -just as for macros. See the @code{defun} example. +just as for macros. See the @code{defun} example. Otherwise, the symbol should be a predicate. The predicate is called with the argument and the specification fails if the predicate returns -@code{nil}. In either case, that argument is not instrumented. +@code{nil}, and the argument is not instrumented. Some suitable predicates include @code{symbolp}, @code{integerp}, @code{stringp}, @code{vectorp}, and @code{atom}. @@ -1355,7 +1361,7 @@ @item def-form The argument is a single, highest-level form in a definition. This is -like @code{def-body}, except use this to match a single form rather than +like @code{def-body}, except it is used to match a single form rather than a list of forms. As a special case, @code{def-form} also means that tracing information is not output when the form is executed. See the @code{interactive} example. @@ -1374,15 +1380,15 @@ in the specification must match some argument. When a syntax error is detected, it might not be reported until much -later after higher-level alternatives have been exhausted, and with the +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. +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 @@ -1413,6 +1419,7 @@ optional expression. In the specification below, notice the @code{gate} inside of the sublist to prevent backtracking once a sublist is found. +@c FIXME? The actual definition in edebug.el does not have a gate. @example (def-edebug-spec let ((&rest @@ -1420,14 +1427,14 @@ body)) @end example -Edebug uses the following specifications for @code{defun} and -@code{defmacro} and the associated argument list and @code{interactive} -specifications. It is necessary to handle interactive forms specially -since an expression argument is actually evaluated outside of the -function body. +Edebug uses the following specifications for @code{defun} and the +associated argument list and @code{interactive} specifications. It is +necessary to handle interactive forms specially since an expression +argument is actually evaluated outside of the function body. (The +specification for @code{defmacro} is very similar to that for +@code{defun}, but allows for the @code{declare} statement.) @smallexample -(def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.} (def-edebug-spec defun (&define name lambda-list [&optional stringp] ; @r{Match the doc string, if present.} @@ -1447,11 +1454,12 @@ The specification for backquote below illustrates how to match dotted lists and use @code{nil} to terminate recursion. It also illustrates how components of a vector may be matched. (The actual -specification defined by Edebug does not support dotted lists because -doing so causes very deep recursion that could fail.) +specification defined by Edebug is a little different, and does not +support dotted lists because doing so causes very deep recursion that +could fail.) @smallexample -(def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.} +(def-edebug-spec \` (backquote-form)) ; @r{Alias just for clarity.} (def-edebug-spec backquote-form (&or ([&or "," ",@@"] &or ("quote" backquote-form) form) @@ -1465,6 +1473,9 @@ @subsection Edebug Options These options affect the behavior of Edebug: +@c Previously defopt'd: +@c edebug-sit-for-seconds, edebug-print-length, edebug-print-level +@c edebug-print-circle, edebug-eval-macro-args @defopt edebug-setup-hook Functions to call before Edebug is used. Each time it is set to a new @@ -1513,7 +1524,7 @@ displayed buffers. Saving and restoring point in other buffers is necessary if you are -debugging code that changes the point of a buffer which is displayed in +debugging code that changes the point of a buffer that is displayed in a non-selected window. If Edebug or the user then selects the window, point in that buffer will move to the window's value of point. @@ -1552,6 +1563,8 @@ @xref{Edebug Execution Modes}. @end defopt +@c FIXME edebug-unwrap-results + @defopt edebug-on-error Edebug binds @code{debug-on-error} to this value, if @code{debug-on-error} was previously @code{nil}. @xref{Trapping