Added documentation for lisp and lisp libraries.

doc/_info_/stack.info

@@ -0,0 +1,124 @@
+;;;		FRIDAY  NOV 19,1976  10:51:28
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;;;		STACK DEBUGGING TOOLS
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+
+
+;;;	These routines are for crawling around in the LISP stack.  For
+;;;any meaningful stack information to be available *RSET must be set to
+;;;T.  Further,  only minimal information will be present for compiled
+;;;calls unless NOUUO is T.  This package takes up 376. decimal words.
+
+;;;	The variable *FRAME*-*POINTER* (hereafter called the CURSOR) is
+;;;always bound to a "stack frame 4-tuple".  Each tuple is the value of
+;;;an EVALFRAME function call.  All the functions described below,
+;;;unless otherwise noted, have as their value the current CURSOR.
+
+;;;	The CURSOR is either of the form:
+;;;	(EVAL <pdl-ptr> <form> <spec-pdl-ptr>)	or
+;;;	(APPLY <pdl-ptr> (<operator> <arglist>) <spec-pdl-ptr>)
+
+;;;The first atom is a keyword identifier indicating the format of the
+;;;third entry.  EVAL means that the form is an entity that is being
+;;;EVAL'ed and the user could EVAL to see the effect.  APPLY means that
+;;;the third element is the list of the operator and its argument list.
+;;;The argument list has been evaluated and is ready for the operator to
+;;;be APPLY'ed to it.  The user can do the latter by hand to see the
+;;;effect.
+
+;;;	The <pdl-ptr> and <spec-pdl-ptr> print as FIXNUM's.  They are
+;;;pointers that are meaningful for EVALFRAME, FRETURN, EVAL, APPLY and
+;;;a few other commands.  The reader is refered to the MACLISP manual
+;;;for a more detailed discussion.
+
+
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;;;			COMMANDS
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+;;;TOP (no args)
+;;;	Set the CURSOR to the "top" of the stack. The "top" is closest
+;;;to the break.  Like a plant the growing point of a stack is at its
+;;;top.
+
+;;;BOT (no args)
+;;;	Set the CURSOR to the "bottom" of the stack.  The "bottom" is
+;;;the frame of the last call from "command line".
+
+;;;UP (fexpr)
+;;;	Move the CURSOR another frame towards the top.  Falling off the
+;;;top of the stack causes an error message to be printed.  The CURSOR
+;;;is not changed.  (Thus the value of UP will be EQ to its previous
+;;;value). 
+
+;;;DN (fexpr)
+;;;	Move the CURSOR another frame towards the bottom.  Falling off
+;;;the bottom of the stack causes an error message to be printed.  The
+;;;CURSOR is not changed.  (Thus the value of DN will be EQ to its
+;;;previous value). 
+
+
+;;;both 		UP and DN
+;;;take the following arguments:
+;;;	<some number>	 do the operation that many times
+;;;	<some function>	 go to the frame where that function was invoked
+;;;	the letter F	 move the CURSOR until the first user function
+;;;			  call is encountered
+;;;	the letter I	 move the CURSOR until the first non-compiled
+;;;			   user function call is encountered
+;;;	the letter C	 move the CURSOR until the first compiled user
+;;;			  function call is encountered
+;;;	the letter M	 move the CURSOR until the first user macro call
+
+;;;FR (lexpr)
+;;;	Given no argument, its value is simply the CURSOR.
+;;;	Given an argument, it will reset the CURSOR to the argument.
+
+;;;FM (no args)
+;;;	Return only the FORM of the stack frame.  This is the third
+;;;element of the CURSOR structure.  
+
+;;;RET (lexpr)
+;;;	no arg	- reexecute the form at the cursor and unwind the stack 
+;;;		   Only this type execution of RET evaluates in the
+;;;		   original (CURSOR) lambda variable binding environment
+;;;	one arg	- return the arg in place of computing the value of the
+;;;		   form at the CURSOR.
+;;;	two arg	- as above, but use (arg 2) in place of the CURSOR.
+
+;;;EV (lexpr)
+;;;	one arg	- evaluate the arg in the binding environment of the
+;;;		    CURSOR frame.
+;;;	two arg	- as above, but use (arg 2) in place of the CURSOR.
+
+
+;;;EVQ (fexpr)
+;;;	The evalquote version of the above function. 
+
+
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;;;			HINTS
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+
+;;;	When the CURSOR 4-tuple is of the EVAL type (the first element
+;;;of the tuple is EVAL), the form component is EQ to the piece of code
+;;;that is in the actual function being executed.  Thus RPLAC operators
+;;;on this form wil make patches to the function.
+
+;;;	RET is most useful to return the correct value for some
+;;;evaluation sequence that has gone amuck and proceed with the overall
+;;;processing.  It eliminates the necessity of starting again from the
+;;;beginning because of some "simple" bug.
+
+;;;	To evaluate a number of variables and forms in some frame
+;;;context it is often easier to do a (EVQ (BREAK FOO))  rather than
+;;;repetitive EVQ's.  The former expression places a BREAK "at an
+;;;earlier place in the evaluation".  Obviously this BREAK should be
+;;;$P'ed, when it is no longer needed.
+
+