This file documents INTER, an interface between EMACS and INTERLISP.
Don't edit this file! It is produced by DOCOND from the INTED file.

INTER provides a means for using EMACS from within INTERLISP to edit or create
LISP functions, variables, etc.  You can learn enough to use INTER from
the node Intro.

Suppose you are in INTERLISP and would like to edit a function.  LOAD the file
<EMACS>INTER.COM.

To edit the function FOO call CF(FOO) instead of EDITF(FOO).  FOO's definition
is written into the EMACS buffer surrounded with a (DEFINEQ ...).  Edit the
definition with EMACS.  When you are finished editing, return to INTERLISP
with C-T U.  INTERLISP will read the (modified) "(DEFINEQ ... )" in the EMACS
buffer and execute it.  When the DEFINEQ is executed, the INTERLISP definition
of the function is changed.  The DEFINEQ is executed as though you had typed
it in at the top level.  Hence the DEFINEQ may be UNDOne, FIXed, ??ed, etc.
INTERLISP's file package keeps track of changes to functions via DEFINEQ as
well as changes via EDITF.

While you are editing a function in EMACS, you can return without effect to
INTERLISP with C-T Z.  INTERLISP will not change the definition of the function
you are editing.  You can later continue editing in EMACS where you left off by
calling (EMACS T).

To define a new function (in general, to construct any expression for
evaluation by INTERLISP), enter EMACS by calling (EMACS).  You are placed in an
empty EMACS buffer.  Exit to INTERLISP with C-T U.

To edit a variable, property list, or record, use CV, CP, or CREC instead of
EDITV, EDITP, or EDITREC.

There are more INTERLISP functions and EMACS commands for INTER.  They are
described in the next two  nodes.

Here are the top-level functions that are defined in INTERLISP by the loading
of <EMACS>INTER.COM.

CF[FNNAME] inserts the definition of a function at the bottom of the EMACS
virtual buffer and dives down to EMACS with the cursor at the beginning of the
insertion.  The definition is written inside a "(DEFINEQ ...)" and hence is
suitable for later execution with C-T U or E.[].  The definition of the
function is fetched much the way that EDITF does except that no spelling
correction is attempted.  If FNNAME is NIL, the value of LASTWORD is used.  If
FNNAME has a LISTP definition, the unadvised, unbroken version is used (unless
the result is not LISTP).  Else if FNNAME has an EXPR property it is used.
Otherwise, the definition is taken from the first file said to contain it.
WHEREIS is used to find the file and filemaps are used to get the definition
into the EMACS buffer quickly.  If EMACS.FASTREADFLG is NIL (default T), then
the definition is first read into LISP then prettyprinted for EMACS.
Setting EMACS.FASTREADFLG to NIL is useful if there are square brackets in the
definition of the function.  If you exit from EMACS with C-T Z, the function's
LISP definition is not changed; to cause the redefinition, use E. or E!, or
else exit from EMACS with C-T U.

CFNS[LST] behaves like CF except that it takes a list of function names, and a
definition of each is placed in the EMACS buffer.

CV[X] writes a variable name and definition inside an "(RPAQQ ...  )" into the
EMACS buffer and descends to EMACS.  The INTERLISP value of the variable is not
changed if you return to INTERLISP with C-T Z; to set the variable, use E.  or
E! or else exit from EMACS with C-T U.

CP[X] writes a litatom and its property list inside a "(SETPROPLIST ... )" into
the EMACS buffer and descends to EMACS.  The property list is not changed if
you return to INTERLISP with C-T Z; to set the property list, use E. or E!  or
else exit from EMACS with C-T U.

CREC[X] writes an INTERLISP record declaration into the EMACS buffer and
descends to EMACS.  The declaration is not changed if you return to INTERLISP
with C-T Z; to declare the edited declaration, use E. or E! or else exit from
EMACS with C-T U.

EMACS[OLDBUFFER] returns to EMACS.  If OLDBUFFER is non-NIL, you are in the
same EMACS state you were when you last left.  If OLDBUFFER is NIL, then you
are placed in an empty virtual buffer, which is useful if you want to write a
definition from scratch.

E.[] reads and then executes the expression starting at the cursor in the EMACS
buffer.  The execution is recorded as an event on the INTERLISP history list
just as if it had been typed into the top level READ-PRINT-EVAL loop.  The
appearance of the execution on your terminal is faked by printing it shallow.
But the event is really there, so ??, REDO, UNDO, etc. all work.

E![N] reads and executes expressions starting at the cursor in the EMACS
buffer.  If N is a number, then N expressions are read and executed.  If N is
NIL, then all the expressions in the buffer after the cursor are executed.

DOWN[NEGATE.ARG.FLG] passes control to EMACS.  CF, CV, CP, and CREC all result
in calls to DOWN.  DOWN causes EMACS to read from the file that is the value of
the INTERLISP variable EMACS.TEMP.FILE.  If NEGATE.ARG.FLG is NIL, then EMACS
inserts at the end of the virtual buffer named *FROM-LISP* everything in the
file EMACS.TEMP.FILE up to the current file pointer (not the end of the file).
If there is something to insert (i.e., the file pointer is not 0), then the
virtual buffer boundaries are narrowed to what is inserted.  (The buffer
boundaries can be widened to the whole buffer with ^R Set Bounds Full.)  If
NEGATE.ARG.FLG is not NIL, the text that would have been inserted is placed in
EMACS' register A and executed.  (Thus to get EMACS to insert text at the
bottom of the virtual buffer named *FROM-LISP*, simply PRINT to EMACS.TEMP.FILE
and call (DOWN).)  Upon return to INTERLISP, the file pointer of
EMACS.TEMP.FILE is set to 0.  The screen is refreshed with NUMBER.OF.LINES of
text from the dribble file unless (a) the terminal is not a display terminal,
(b) the user had a dribble file running at the time START.EMACS was called, or
(c) because the user has called DRIBBLE since START.EMACS was called, there is
no longer a dribble file or it is not the one created by START.EMACS.
NUMBER.OF.LINES is set in START.EMACS, but you can reset it.

REFRESH[] causes the last screenful of characters in the dribble file to be
printed on your terminal.  Your screen is refreshed when you return to
INTERLISP from EMACS under certain conditions enumerated in the documentation
for DOWN.

EDIT.DRIBBLE.FILE[] runs EMACS after inserting the dribble file into an EMACS
buffer called *LISP-DRIBBLE*.  This command is useful for reviewing LISP
terminal output that has rolled off the screen.  The previous contents of the
buffer *LISP-DRIBBLE* are deleted.

START.EMACS[] creates an inferior process (i.e., fork), loads EMACS into the
process, and returns to INTERLISP.  This function is called by the above
functions if the EMACS-INTERLISP interface has not been initialized.  Two
temporary files are created for communication between EMACS and INTERLISP.
Furthermore, if the user does not currently have a dribble file open, a
temporary dribble file is opened so that on return to INTERLISP from EMACS the
display can be refreshed with some of the characters that were there before
the descent to EMACS.

FLUSH.EMACS[] kills the current EMACS created by START.EMACS, if there is one.
Among other things, FLUSH.EMACS kills the EMACS process, closes the two files
that EMACS and INTERLISP use to communicate, and releases a few INTERLISP
pages.  If START.EMACS created a dribble file, then it will be closed by
FLUSH.EMACS if it is still open.  If START.EMACS created a dribble file, no
harm will result if you close it or create another; but if you do, DOWN and
REFRESH will not refresh your screen.  If you close EMACS.TEMP.FILE or
EMACS.MAP.FILE, the EMACS-INTERLISP interface is as good as dead.  CLOSEALL()
will not close them, but CLOSEF and CLOSEALL(T) will.  Since all of the files
created by this EMACS-INTERLISP interface are temporary, they will all be
deleted and expunged when you log off.

All of the INTER commands in EMACS begin with the prefix character C-T.  A
prefix character is a character like C-X that expects another character to be
typed.  The old definition of C-T, ^R Transpose Characters, is hung on C-T C-T.

C-T Z (^R Exit to LISP) simply returns control from EMACS to LISP.  No
expressions in the EMACS buffer are evaluated.  To resume editing in the same
EMACS state, call (EMACS T).

C-T U (^R EVAL) returns to INTERLISP and causes INTERLISP to read and evaluate
each expression in the (virtual) buffer as though it were typed directly into
INTERLISP.

C-T E (^R EVAL) returns to INTERLISP and causes INTERLISP to read and evaluate
the expression after the cursor as though it were typed directly into
INTERLISP.  Approximately identical to C-T Z followed by E..  (If an explicit
argument is supplied, that many expressions are read and evaluated.  A
0 arg means evaluate everything in the (virtual) buffer.

C-T D (^R DEFINEQ) returns to INTERLISP and causes LISP to read and then
evaluate the expression after the cursor as an argument to DEFINEQ.  For
example, if the cursor is just in front of "(FOO (X) (EQUAL X 3))" then C-T D
will result in FOO's being defined as the function that tests whether its
argument X is 3.  This command is useful for perusing files made by MAKEFILE,
because such files usually have just one "DEFINEQ" at the top.  (If an explicit
argument is supplied, that many expressions are read and given to DEFINEQ.
A 0 arg means to DEFINEQ everything in the (virtual) buffer).

C-T Q (^R QUOTE) returns to INTERLISP and makes the expression after the cursor
be the value of the next INTERLISP history event.  This command is useful for
getting your INTERLISP hands on an expression in the EMACS buffer.  After you
return to LISP, the expression can be obtained via the INTERLISP function
VALUEOF.  (If an explicit argument is supplied, that many expressions are read
and quoted. A 0 arg means read and quote each expression in the
(virtual) buffer.)

C-T P (^R Pretty Print) prettyprints the expressions after the cursor
using the LISP pretty printer.  The effect can be undone with the
EMACS command UNDO.

C-T S (^R Eval Sexpr) evaluates in INTERLISP the expression after the cursor in
the EMACS buffer and prints the result into the buffer named *LISP-PRINT* in
the other window.  The previous contents of the buffer named *LISP-PRINT* are
deleted.

C-T L (^R Print to Level) shallowly prints the expression after the cursor into
the buffer named *LISP-PRINT* in the other window.  Useful if the expression
after the cursor is bigger than a screen full.  The previous contents of the
buffer named *LISP-PRINT* are deleted.

C-T A (^R Arglist) prints the arglist of the function after the cursor (or
after the open parenthesis after the cursor if there is one.)

C-T ? prints short documentation on the ^T commands.

C-T F (^R Find Sexp) is for use under the editmacro EMACS: of the standard
INTERLISP structure editor.  This command manufactures a search command for the
structure editor that changes the structure editors's attention to the
expression after the cursor.  One use is in conjunction with BREAKIN to set a
breakpoint in the body of a function definition.  For example (BREAKIN FOO
(AROUND EMACS:)) allows one to insert a breakpoint in the body of FOO by moving
the cursor to the desired spot and entering C-T F.  To use this command, the
cursor should be directly in front of the open parenthesis of the expression
you want to have found.

C-T C (^R Replace Sexp) is for use under the editmacro EMACS: of the standard
INTERLISP structure editor.  This command causes the manufacture of a
replacement command for the structure editor that when executed replaces the
current expression of the structure editor with the contents of the current
EMACS virtual buffer.

C-T C-E (^R LISP ERROR) returns to INTERLISP with an ERROR.  This
command is particularly useful if you are under the structure editor
EDITMACRO EMACS: and wish to return to the structure editor,
no change having been made.

C-T C-D (^R LISP RESET) returns to INTERLISP with a RESET.  That takes you
back to the very toplevel of LISP.

The EMACS function Interlisp Mode sets the delimiter table of EMACS to reflect
INTERLISP syntax.  Interlisp Mode can thus be useful even if you are not using
INTER.  % quotes the next character.  " delimits strings.  (The characters /,
|, and semicolon have no special significance, but are treated just as
alphabetic characters.)

Square brackets are treated just as alphabetic characters.  A function
definition containing square brackets is certainly editable in EMACS, but the
INTERLISP oriented commands of EMACS do not respect the INTERLISP meaning of
square brackets.  Of course, INTERLISP will respect the square brackets when
it reads a modified definition from the EMACS buffer.  If #RPARS is NIL, then
the INTERLISP pretty printer, PRINTDEF, will not use square brackets for
parentheses, even during MAKEFILE.  You can still type them into LISP.  The
value of #RPARS is set to NIL in START.EMACS.

When you are in EMACS, you can pretty print expressions in two ways.  C-M-Q
(^R Indent Sexp) will readjust the number of spaces in the sexpression after
the cursor.  This often works well on slightly edited function.  To get a
genuine LISP pretty printing job done you can use C-T C-P (^R Pretty Print),
which pretty prints the expression after the cursor.  It is unadvisable to use
the EMACS routine Grind Sexp on INTERLISP; Grind Sexp was written for MACLISP.
Grind Sexp is disabled by INTER; if you really want to use it, then call Load
Library on the file GRIND to restore the original definition of Grind Sexp.

It is OK to use multiple EMACS buffers.  Any reference to "the" EMACS buffer in
the documentation of INTER should be construed as a reference to the "current"
EMACS buffer.  E.g., if you execute (E.), then the expression that is evaluated
is the expression after "point" in the "current" EMACS buffer.

When you enter EMACS from INTERLISP with text to be inserted (e.g., by using
CF), the text is inserted at the bottom of the current virtual buffer.  The
text that was already in the buffer (i.e., the text that was there when you
last left EMACS) is undisturbed.  But the "virtual" buffer boundaries are
narrowed to the definition; so all you can see is the definition.  You can
easily obtain access to what's in the rest of the buffer by "widening" the
virtual buffer boundaries to the whole buffer; just invoke ^R Set Bounds Full.

If you are in EMACS perusing a huge file produced by MAKEFILE and decide to use
C-T D to pull in a definition, it will happen faster if you narrow the virtual
buffer to the expression that you are interested in.  All the commands that
draw INTERLISP's attention to the EMACS buffer copy characters out of the EMACS
buffer starting either at the cursor or at the top of the virtual buffer and
going all the way to the end of the virtual buffer.  We copy all the way to the
end because there is no command in EMACS that can perfectly calculate how far
one INTERLISP read will go.  The main problem is the square bracket, which
is likely to occur in files produced by MAKEFILE.

If you set NORMALCOMMENTSFLG to NIL and if you print to EMACS.TEMP.FILE
yourself, be sure to readjust PRETTYPRINTMACROS by consing on (* . GETTCOMMENT)
or you'll get your comments mapped into the EMACS temp file and later munged.

If you want to use some version of EMACS besides the standard one (e.g.,
DMACS), you should redefine the function EMACS.EXE.FILE to be a function of no
arguments that returns the file that you want to run (e.g., 'SYS:DMACS.EXE or
'<SUBSYS>DMACS.SAV, depending upon whether (SYSTEMTYPE) is TOPS20).

The details of the hook EMACS has for communicating with other processes are
found in the last few pages of <INFO>TECORD.

Several INTERLISP utility functions invoke the standard structure editor.  For
example, in a break, the EDIT BREAKMACRO permits you to edit the current
expression.  BREAKIN permits you to place a BREAK at a spot in a function as
found by interactive editing.  It is possible to invoke EMACS from within the
standard editor on the current expression via the EDITMACRO EMACS:.  When you
are under EMACS:, you can return in four ways.  C-T F (^R Find Sexp) tells the
structure editor to find the expression right after the cursor.  C-T C (^R
Replace Sexp) tells the structure editor to replace its current expression with
the contents of the virtual buffer.  C-T C-D (^R LISP RESET) causes LISP to
quit to the top level.  C-T C-E (^R LISP ERROR) aborts EMACS: and returns you
to the structure editor, no changes having been made.

It should be noted that this interface is consistent with the normal usage of
BREAKIN, EDITF etc. The edit chain remains intact and the operations are
generally undoable.