Revised Documentation for SetAlink, etc

[bobrow at PARC-MAXC]

This is the revised documentation for setalink, and setclink based on Daryl's last
comment.


There are four primitive functions for manipulating the ALINK and CLINK of a
frame.  Combined with the functions for manipulating the structures of a single
frame (stknargs, stkname, setstkname, stkarg, setstkarg, stkargname,
setstkargname) and those for setting up a new frame with specified access and
control links (enveval, envapply), they form a complete set of primitives for
manipulating the control structures of Lisp.  Although all the other functions
can be written in terms of these primitives, the user will usually want to use the
higher level functions described above.

alink[pos, opos) returns a stack pointer to the frame which is referred to by the
access link of the frame specified by pos.  If opos is supplied, and is a
stackpointer, it is reused.  Returns T if the access link points to the top level. 
Same as stknth(1,pos,opos)

clink[pos, opos) returns a stack pointer to the frame which is referred to by the
control link of the frame specified by pos.  If opos is supplied, and is a
stackpointer, it is reused.  Returns T if the control link points to the top level. 
Same as stknth(-1,pos,opos)

setalink[pos, newpos, relflg] sets the alink of the frame specified by pos to be the
frame specified by newpos.  Returns NIL, and does not set the link if the access
chain of the frame specified by newpos contains the frame specified by pos. 
This prevents the user from accidentally creating a circular access chain. 
Returns pos otherwise, and if relflg is nonNil, and newpos is a stackpointer, then
newpos is released.

setclink[pos, newpos, relflg] sets the control of the frame specified by pos to be
the frame specified by newpos.  Returns NIL, and does not set the link if the
control chain of the frame specified by newpos contains the frame specified by
pos.  This prevents the user from accidentally creating a circular control chain. 
Returns pos otherwise, and if relflg is nonNil, and newpos is a stackpointer, then
newpos is released.