[Emacs-diffs] Changes to emacs/lispref/edebug.texi

[Luc Teirlinck]

Index: emacs/lispref/edebug.texi
diff -c emacs/lispref/edebug.texi:1.30 emacs/lispref/edebug.texi:1.31
*** emacs/lispref/edebug.texi:1.30      Sun May  1 18:51:39 2005
--- emacs/lispref/edebug.texi   Tue Jun 14 23:33:21 2005
***************
*** 65,71 ****
  * Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
  * Jumping::                   Commands to jump to a specified place.
  * Misc: Edebug Misc.          Miscellaneous commands.
! * Breakpoints::                       Setting breakpoints to make the program 
stop.
  * Trapping Errors::           Trapping errors with Edebug.
  * Views: Edebug Views.                Views inside and outside of Edebug.
  * Eval: Edebug Eval.          Evaluating expressions within Edebug.
--- 65,71 ----
  * Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
  * Jumping::                   Commands to jump to a specified place.
  * Misc: Edebug Misc.          Miscellaneous commands.
! * Breaks::                      Setting breakpoints to make the program stop.
  * Trapping Errors::           Trapping errors with Edebug.
  * Views: Edebug Views.                Views inside and outside of Edebug.
  * Eval: Edebug Eval.          Evaluating expressions within Edebug.
***************
*** 75,81 ****
  * Trace Buffer::              How to produce trace output in a buffer.
  * Coverage Testing::          How to test evaluation coverage.
  * The Outside Context::               Data that Edebug saves and restores.
! * Instrumenting Macro Calls:: Specifying how to handle macro calls.
  * Options: Edebug Options.    Option variables for customizing Edebug.
  @end menu
  
--- 75,81 ----
  * Trace Buffer::              How to produce trace output in a buffer.
  * Coverage Testing::          How to test evaluation coverage.
  * The Outside Context::               Data that Edebug saves and restores.
! * Edebug and Macros::         Specifying how to handle macro calls.
  * Options: Edebug Options.    Option variables for customizing Edebug.
  @end menu
  
***************
*** 203,215 ****
  @code{interactive} forms with an expression argument, anonymous lambda
  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; 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
  @code{nil}.  You can use this to load Edebug specifications
! (@pxref{Instrumenting Macro Calls}) associated with a package you are
  using, but only when you use Edebug.
  
  @findex eval-expression @r{(Edebug)}
--- 203,215 ----
  @code{interactive} forms with an expression argument, anonymous lambda
  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; see @ref{Edebug and
! Macros}, 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
  @code{nil}.  You can use this to load Edebug specifications
! (@pxref{Edebug and Macros}) associated with a package you are
  using, but only when you use Edebug.
  
  @findex eval-expression @r{(Edebug)}
***************
*** 253,259 ****
  @item n
  Next: stop at the next stop point encountered after an expression
  (@code{edebug-next-mode}).  Also see @code{edebug-forward-sexp} in
! @ref{Edebug Misc}.
  
  @item t
  Trace: pause (normally one second) at each Edebug stop point
--- 253,259 ----
  @item n
  Next: stop at the next stop point encountered after an expression
  (@code{edebug-next-mode}).  Also see @code{edebug-forward-sexp} in
! @ref{Jumping}.
  
  @item t
  Trace: pause (normally one second) at each Edebug stop point
***************
*** 341,349 ****
  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
! 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
--- 341,348 ----
  Step into the function or macro called by the form after point.
  @end table
  
! The @kbd{h} command proceeds to the stop point at or after the current
! location of point, using a temporary breakpoint.
  
  The @kbd{f} command runs the program forward over one expression.  More
  precisely, it sets a temporary breakpoint at the position that
***************
*** 427,440 ****
  with @kbd{q} or abort one recursive edit level with @kbd{C-]}.  You can
  display a backtrace of all the pending evaluations with @kbd{d}.
  
! @node Breakpoints
! @subsection Breakpoints
  
- @cindex breakpoints
  Edebug's step mode stops execution when the next stop point is reached.
  There are three other ways to stop Edebug execution once it has started:
  breakpoints, the global break condition, and source breakpoints.
  
  While using Edebug, you can specify @dfn{breakpoints} in the program you
  are testing: these are places where execution should stop.  You can set a
  breakpoint at any stop point, as defined in @ref{Using Edebug}.  For
--- 426,448 ----
  with @kbd{q} or abort one recursive edit level with @kbd{C-]}.  You can
  display a backtrace of all the pending evaluations with @kbd{d}.
  
! @node Breaks
! @subsection Breaks
  
  Edebug's step mode stops execution when the next stop point is reached.
  There are three other ways to stop Edebug execution once it has started:
  breakpoints, the global break condition, and source breakpoints.
  
+ @menu
+ * Breakpoints::                 Breakpoints at stop points.
+ * Global Break Condition::    Breaking on an event.
+ * Source Breakpoints::        Embedding breakpoints in source code.
+ @end menu
+ 
+ @node Breakpoints
+ @subsubsection Breakpoints
+ 
+ @cindex breakpoints
  While using Edebug, you can specify @dfn{breakpoints} in the program you
  are testing: these are places where execution should stop.  You can set a
  breakpoint at any stop point, as defined in @ref{Using Edebug}.  For
***************
*** 494,505 ****
  breakpoints.  This command does not continue execution---it just moves
  point in the buffer.
  
- @menu
- * Global Break Condition::    Breaking on an event.
- * Source Breakpoints::        Embedding breakpoints in source code.
- @end menu
- 
- 
  @node Global Break Condition
  @subsubsection Global Break Condition
  
--- 502,507 ----
***************
*** 515,521 ****
  @findex edebug-set-global-break-condition
    The condition expression is stored in
  @code{edebug-global-break-condition}.  You can specify a new expression
! using the @kbd{X} command (@code{edebug-set-global-break-condition}).
  
    The global break condition is the simplest way to find where in your
  code some event occurs, but it makes code run much more slowly.  So you
--- 517,525 ----
  @findex edebug-set-global-break-condition
    The condition expression is stored in
  @code{edebug-global-break-condition}.  You can specify a new expression
! using the @kbd{X} command from the source code buffer while Edebug is
! active, or using @kbd{C-x X X} from any buffer at any time, as long as
! Edebug is loaded (@code{edebug-set-global-break-condition}).
  
    The global break condition is the simplest way to find where in your
  code some event occurs, but it makes code run much more slowly.  So you
***************
*** 582,594 ****
  
  @table @kbd
  @item v
! Temporarily view the outside window configuration
! (@code{edebug-view-outside}).
  
  @item p
! Temporarily display the outside current buffer with point at its outside
! position (@code{edebug-bounce-point}).  With a prefix argument @var{n},
! pause for @var{n} seconds instead.
  
  @item w
  Move point back to the current stop point in the source code buffer
--- 586,599 ----
  
  @table @kbd
  @item v
! View the outside window configuration (@code{edebug-view-outside}).
! Type @kbd{C-x X w} to return to Edebug.
  
  @item p
! Temporarily display the outside current buffer with point at its
! outside position (@code{edebug-bounce-point}), pausing for one second
! before returning to Edebug.  With a prefix argument @var{n}, pause for
! @var{n} seconds instead.
  
  @item w
  Move point back to the current stop point in the source code buffer
***************
*** 610,617 ****
  
    You can view the outside window configuration with @kbd{v} or just
  bounce to the point in the current buffer with @kbd{p}, even if
! it is not normally displayed.  After moving point, you may wish to jump
! back to the stop point with @kbd{w} from a source code buffer.
  
    Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
  saved outside window configuration---so that even if you turn saving
--- 615,626 ----
  
    You can view the outside window configuration with @kbd{v} or just
  bounce to the point in the current buffer with @kbd{p}, even if
! it is not normally displayed.
! 
!   After moving point, you may wish to jump back to the stop point.
! You can do that with @kbd{w} from a source code buffer.  You can jump
! back to the stop point in the source code buffer from any buffer using
! @kbd{C-x X w}.
  
    Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
  saved outside window configuration---so that even if you turn saving
***************
*** 838,845 ****
  @defmac edebug-tracing string address@hidden
  This macro requests additional trace information around the execution
  of the @var{body} forms.  The argument @var{string} specifies text
! to put in the trace buffer.  All the arguments are evaluated, and
! @code{edebug-tracing} returns the value of the last form in @var{body}.
  @end defmac
  
  @defun edebug-trace format-string &rest format-args
--- 847,855 ----
  @defmac edebug-tracing string address@hidden
  This macro requests additional trace information around the execution
  of the @var{body} forms.  The argument @var{string} specifies text
! to put in the trace buffer, after the @address@hidden or @address@hidden  All
! the arguments are evaluated, and @code{edebug-tracing} returns the
! value of the last form in @var{body}.
  @end defmac
  
  @defun edebug-trace format-string &rest format-args
***************
*** 990,996 ****
  @item
  @cindex window configuration (Edebug)
  The outside window configuration is saved and restored if
! @code{edebug-save-windows} is address@hidden (@pxref{Edebug Display Update}).
  
  The window configuration is not restored on error or quit, but the
  outside selected window @emph{is} reselected even on error or quit in
--- 1000,1006 ----
  @item
  @cindex window configuration (Edebug)
  The outside window configuration is saved and restored if
! @code{edebug-save-windows} is address@hidden (@pxref{Edebug Options}).
  
  The window configuration is not restored on error or quit, but the
  outside selected window @emph{is} reselected even on error or quit in
***************
*** 1061,1068 ****
  @code{edebug-continue-kbd-macro}.
  @end itemize
  
  @node Instrumenting Macro Calls
! @subsection Instrumenting Macro Calls
  
    When Edebug instruments an expression that calls a Lisp macro, it needs
  additional information about the macro to do the job properly.  This is
--- 1071,1091 ----
  @code{edebug-continue-kbd-macro}.
  @end itemize
  
+ @node Edebug and Macros
+ @subsection Edebug and Macros
+ 
+ To make Edebug properly instrument expressions that call macros, some
+ extra care is needed.  This subsection explains the details.
+ 
+ @menu
+ * Instrumenting Macro Calls::   The basic problem.
+ * Specification List::                How to specify complex patterns of 
evaluation.
+ * Backtracking::              What Edebug does when matching fails.
+ * Specification Examples::    To help understand specifications.
+ @end menu
+ 
  @node Instrumenting Macro Calls
! @subsubsection Instrumenting Macro Calls
  
    When Edebug instruments an expression that calls a Lisp macro, it needs
  additional information about the macro to do the job properly.  This is
***************
*** 1101,1107 ****
  @deffn Macro def-edebug-spec macro specification
  Specify which expressions of a call to macro @var{macro} are forms to be
  evaluated.  @var{specification} should be the edebug specification.
! It is not evaluated.
  
  The @var{macro} argument can actually be any symbol, not just a macro
  name.
--- 1124,1130 ----
  @deffn Macro def-edebug-spec macro specification
  Specify which expressions of a call to macro @var{macro} are forms to be
  evaluated.  @var{specification} should be the edebug specification.
! Neither argument is evaluated.
  
  The @var{macro} argument can actually be any symbol, not just a macro
  name.
***************
*** 1128,1139 ****
  described in the following sections.
  @end table
  
! @menu
! * Specification List::                How to specify complex patterns of 
evaluation.
! * Backtracking::              What Edebug does when matching fails.
! * Specification Examples::    To help understand specifications.
! @end menu
! 
  
  @node Specification List
  @subsubsection Specification List
--- 1151,1162 ----
  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 address@hidden, all arguments are instrumented.
  
  @node Specification List
  @subsubsection Specification List
***************
*** 1406,1412 ****
  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 it is actually evaluated outside of the
  function body.
  
  @smallexample
--- 1429,1435 ----
  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.
  
  @smallexample