4BSD/usr/lib/lisp/step.doc

                How to Use the step Facility

 The LISP "stepping" package is intended to give the LISP programmer
 a facility analogous to the Instruction Step mode of running a
 machine language program.  The package contains two compiled functions
 which are loaded by
                (fasl "/m2/c122/ucb/lib/lisp/step")
 The user interface is through the function (fexpr) step, which sets
 switches to put the LISP interpreter in and out of "stepping" mode.
 The basic commands are:

                (step t)        Turn on stepping mode.
                (step nil)      Turn off stepping mode.

 These commands are usually typed at top level, and will take effect
 immediately (i.e. the next S-exp typed in will be evaluated in stepping
 mode).  

 In stepping mode, the LISP evaluator will print out each S-exp to
 be evaluated before evaluation, and the returned value after evaluation,
 calling itself recursively to display the stepped evaulation of each
 argument, if the S-exp is a function call.  In stepping mode, the
 evaluator will wait after displaying each S-exp before evaluation
 for a command character from the console:

                <return>         Continue stepping recursively.

                c	        Show returned value from this level
                                only, and continue stepping upward.

                g	 	Turn off stepping mode. (but continue
                                evaluation without stepping).

                p               Redisplay current form in full
                                (i.e. rebind prinlevel and prinlength to nil)

                b               Get breakpoint

                q               Quit

                d		Call debug

 **************** More Advanced Features *************************

 Selectively turning on step:

        (step foo1 foo2 ...)

 If this command is typed at top level, stepping will not commence
 immediately, but rather when the evaluator first encounters a S-expr
 whose car is one of foo1, foo2, etc.  This form will then display
 at the console, and the evaluator will be in stepping mode waiting
 for a command character.

 Using step with breakpoints:

 For the moment, step is turned off inside of error breaks, but not by
 the break function.  Upon exiting the error, step is reenabled.
 However, executing (step nil) inside a error loop will turn off
 stepping globally, i.e. within the error loop, and after return has
 be made from the loop.
 (The more extensive capabilities of the Maclisp version will await
      full development of the Franz error handling capability.)
 
 Overhead of Stepping:

 If stepping mode has been turned off by (step nil), the execution overhead
 of having the stepping packing in your LISP is identically nil.

 If one stops stepping by typing <g>, every call to eval
 incurs a small overhead--several machine instructions, corresponding
 to the compiled code for a simple cond and one function pushdown.

 Running with (step foo1 foo2 ...) can be more expensive, since a
 member of the car of the current form into the list (foo1 foo2 ...)
 is required at each call to eval.