How to Use the STEP Facility
	
<comments and problems accepted>		Charles Rich, TS-824
						x3-6032
						AI: RICH
 Nov 03/76


 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 
		(FASLOAD STEP FASL DSK LIBLSP)
 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). Also <ctl G>, in addition to returning to top level, turns off
 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:

		<space>		Continue stepping recursively.
	
		<rubout>	Show returned value from this level
				only, and continue stepping upward.

		<cr> or <tab>   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; proceed with alt-P

		M		See advanced features under
				"stepping macro expansions"

 **************** 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.

 Stepping Macro Expansions:

 If the stepper is proceeded with a <sp>, it will not step the execution
 of macro expansions, but will rather just show the result of the macro
 of expansion and wait for another command.

 To see the execution of the macro expansion itself, proceed the stepper
 with an M instead of a <sp>.

 Using STEP with breakpoints:

 The above description applies to turning stepping on and off globally
 at top level.  More detail is necessary to use STEP flexibly in and
 out of breakpoints (e.g. together with TRACE).  

 If stepping is turned on by (STEP T) at top level, the evaluator will
 NOT be in stepping mode within a breakpoint loop.  If you wish to use
 stepped evaluation within a break loop you must turn it on locally
 by (STEP T).  Conversely, if stepping was not turned on at top level
 and it is turned on by (STEP T) in a break loop, it will NOT be on
 when return is made from the break loop by <alt>P.

 However, executing (STEP NIL) inside a break loop will turn off
 stepping globally, i.e. within the break loop, and after return has
 be made by <alt>P.

 The most useful feature is the following, however:

		(STEP)		Command at top level has no immediate effect.

 After (STEP) has been executed at top level, a subsequent (STEP T) inside
 of a break loop will have the effect of turning on stepping mode both
 inside the break loop and globally, i.e. the evaluator will start to
 step as soon as the return is made from the break loop by <alt>P.  Thus,
 for instance, one could set TRACE to break at some special place, and then
 use the break to turn on stepping.

Interaction with PRIN1, PRINLEVEL and PRINLENGTH:

 If the user has provided an alternate top-level printing function as the value
 of PRIN1, step will also use this printing function whenever it prints.

 In the present version, for convenience, PRINLEVEL and PRINLENGTH are
 lambda-bound inside the hooking function to 3 and 5 respectively.  These
 could be changed by editing the EXPR code and recompiling.

 When the P command is used, PRINLEVEL and PRINLENGTH are temporarily bound
 to NIL, and the toplevel printer (value of atom PRIN1) is used to redisplay 
 current form.


 Overhead of Stepping:

 If stepping mode has been turned off by <ctl G>, the execution overhead
 of having the stepping packing in your LISP is identically NIL.


 If stepping mode has been turned off by (STEP NIL), 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) entered at top level is the same overhead-wise
 as running with (STEP NIL).

 Stopping stepping by responding <tab> incurs the same
 continued overhead as (STEP NIL).

 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.

 Memory-wise, the total compiled stepping package occupies about  423
 words of binary program storage.
 
 Interaction with DEBUG and TRACE:

 To the best of my knowledge, the STEP package has no special interactions
 with DEBUG, TRACE, or any other system packages.