-*-TEXT-*-
This file contains documentation on the LISPT package for running
TECO editors as a inferior jobs to LISP (or MACSYMA).

File: INFO;LISPT	Node: TOP		Up: (DIR)

The LISPT inferior job editor package

This package is intended to support TECO based editors as inferior jobs
to a LISP or MACSYMA.  The superior/inferior relationship between the
LISP and TECO allows a unique interaction between them, namely the
direct reading and writing of text from/to TECO buffers and a convenient
command scheme for passing the console back and forth between the
jobs.  This package is highly dependent on ITS job control features and
is unlikely to be transportable.  Also some features are dependent on
the EMACS macro library and can be used only with editors based on
EMACS.

* MENU:

* LISP Usage: LISP		Basic use of LISPT from LISP
* MACSYMA Usage: MACSYMA	Basic use of MACST from MACSYMA
* Console Passing: CONSOLE	Between LISP (MACSYMA) and editors
* Editor Commands: EDIT		Editor Commands for TECO, E, TE, ...
* Job Functions: JOB		Editor killing, disowning, etc
* Details - LISP: LDETAILS	Functions and Variables in LISPT
* Details - EMACS: EDETAILS	EMACS macros supporting LISPT
* Other info: Other		Misc. information about LISPT

(not all of these are written yet)

Type 1 for basic information on using LISPT from LISP; type 2 for
use from MACSYMA (the inferior editor is called MACST in this case).


File: LISPT	Node: LISP	Next: CONSOLE		Up: TOP

The Basic Use of LISPT from LISP

The first thing you must do is load LISPT into your LISP by either
FASLOAD'ing LIBLSP;LISPT FASL or using the INF-EDIT function which has
an autoload property when LISP is started.  The basic functions for
entering the editor are INF-EDIT, TECO, EMACS, and TECMAC.  These
functions will pass the console to an inferior-job editor,  creating,
loading, and starting the editor job, as necessary.

INF-EDIT - (MACRO) This function always tries to find an existing
	   editor, reowing or detaching it from DDT if possible.
	   If the editor does not exist, one will be created as
	   specified below.  If the editor is currently under
	   some job other than DDT, you will be asked if you want
	   to create another editor or wait for the existing one.
	   The default job name of the editor is LISPT (actually
	   the value of the variable LISPT-JNAME).  If INF-EDIT is
	   given at least one argument, it must be a symbol and is 
	   taken as the editor's job name.
	   If an editor is not found, it must be loaded from a file.
	   With no arguments, it will load <udir>;TS LISPT, or,
	   if that is not found, SYS2;TS LISPT.  <udir> is the result
	   of (STATUS UDIR).  <udir>;TS EDIT is also checked. TS LISPT
	   on SYS2 is a plain TECO with the LISPT macro library loaded.
	   With one argument, the files UDIR;TS <arg> and SYS2;TS <arg>
	   are checked first.  If a second argument is given, it is
	   taken as a namelist from which to load the editor, with
	   the feature that if it is a symbol, ((SYS2) TS <arg2>)
	   is used.  INF-EDIT* is an LSUBR version of INF-EDIT.
	   Example:  In a fresh LISP, (INF-EDIT EMACS) will put you
	   in an inferior job EMACS editor.

TECO, EMACS, TECMAC - These functions are like INF-EDIT except they
	enter bare TECO, E, or TE editors respectively.  However,
	unlike INF-EDIT, they do not have autoload properties in
	built-in to LISP.

Currently, only one editor sub-job is allowed.  When multiple inferior-
job editors are implemented, there will be some way to specify which
job you want the console passed to.

The next node (CONSOLE) describes how to pass the console back and
forth between DDT, the superior job LISP or MACSYMA, and the inferior
job editor.

File: LISPT	Node: MACSYMA			Up: TOP

The Basic Use of MACST from MACSYMA

To enter an inferior job editor, you must execute one of the following
funcitons:

EDIT();		With no arguments, EDIT loads <udir>;TS LISPT, 
		<udir>;TS EDIT, or SYS2;TS LISPT (which ever is found
		first).  SYS2;TS LISPT is a plain TECO with the LISPT
		TECO macro library loaded.  With one argument, EDIT
		will load the specified editor.  Examples:
		EDIT(EMACS);  loads SYS2;TS EMACS, the standard editor.
		EDIT(EDIT,[MY,EDITOR,DSK,JLK]) loads a special editor from
		JLK; (actually the file spec is merged with
		[TS,LISPT,DSK,SYS2]).  The job name will be EDIT.

TECO(), EMACS(), TECMAC()	
		These functions load editors of the same name.

The first time an editor function is called, an inferior editor job is
created (job creation is announced by a message typeout).  Currently,
only one inferior job editor is allowed (but this may change someday).
On subsequent calls to these functions, the previously created editor
is simply re-entered (this means the job is started and the console is
passed to it).

The next node (CONSOLE) describes how to pass the console back and
forth between DDT, the superior job LISP or MACSYMA, and the inferior
job editor.


File: LISPT	Node: CONSOLE	Next: EDIT	Up: TOP

Passing the Console between LISP (or MACSYMA) and Editors

The console is passed to the editor by the various editor creating
functions.  Once an editor is created, using these functions
subsequently, simply causes the editor to be re-entered.  For
convenience, an interrupt character ^T is provided, which passes
the console directly to the editor.  In fact, this can be done
while your LISP or MACSYMA job is running.  If you want this
console-passing function on some other character, see
*note LISP-DETAILS: LDETAILS, for how its done.

Once the console has been passed to the inferior-job editor, you
return by typing CALL (^Z on non-meta keyboards) or by executing
some command in the editor for returning to its superior (e.g.
^C in bare TECO, ^Z in EMACS or TECMAC, etc.).  LISPT will type
a message telling you the console has been reconnected to LISP
and will reprompt, if the LISP job is in a read state.

If you want to exit all the way back to DDT, you can type Back/Next
twice (or ^_^_ on non-meta keyboards).  This is convenient for times
when you want to go back to DDT momentarily (say, to look at a SENDs
message) and return to the editor.  When your LISP job is re-entered,
the console is passed back to the editor immediately.  You can avoid
this by prefixing the ^_ command with ^U.  Then the console stays
in LISP when it is returned from DDT.  Of course you can also just
do 2 CALL's (^Z's) but this is messier.

Next is a description of the editor commands for causing the
superior LISP or MACSYMA to read commands from the editor's
buffer.


File: LISPT	Node: EDIT	Next: JOB, Previous: CONSOLE, Up: TOP

Editor commands

One of the primary capabilities of the LISPT system is to allow a
LISP or MACSYMA to read directly out of an inferior-job editor's
buffer.  This reading is initiated by commands in the editor which
set the virtual buffer boundaries around the text to be read, and
send a command to the superior, requesting the read.

* MENU:

* Plain TECO::		Text reading commands in plain TECO [Type 1]

* EMACS Commands::	Commands for editors using the EMACS Library
			(including E, TECMAC, etc) [Type 2]


File: LISPT	Node: Plain TECO	Next: JOB	Up: EDIT

Text Reading Commands in Plain TECO

The primary text-read-by-superior-job command in plain TECO is MZ (that
is, Q-register Z contains a macro for requesting reads by a superior).

With no arguments or an argument of 1, this macro will cause the piece
of code containing or following the TECO cursor (/\) to be read by
the superior.  The macro determines by the contents of the text, whether
the text is LISP code or MACSYMA code.

With one argument, the piece of code pointed at and <arg>-1 subsequent
commands or expressions are read (if the argument is negative, <arg>-1
preceeding expressions are read).

With a prefix argument (e.g. 1, MZ), the current expression and all
subsequent expressions in the buffer are read.  This is particularly
useful when a previous read encountered an error part way through,
and you want to continue reading at the expression that had the error.

With two arguments ( m,n MZ), the range of the buffer delimited by
the two arguments is read, that is, the two arguments are character
pointers into the buffer, relative to the beginning.  For example
B,Z MZ or H MZ would read the whole buffer, while B,. MZ would
read from the beginning up to ".".

Real-time edit mode characters Meta-Z and Control-Meta-Z function
like MZ and 1,MZ respectively, but these may be hard to type in
when using plain TECO, unless you have a keyboard with a meta key.

Next is a discussion of some job manipulations that can be
performed on inferior-job editors.


File: LISPT	Node: EMACS Commands	Next: JOB	Up: EDIT

Text Reading Commands in EMACS-based Editors



File: LISPT	Node: JOB	Next: Other, Previous: EDIT, Up: TOP

Manipulating editor jobs (killing, disowning, reowning, etc.)

(KILL-EDITOR),  KILLEDITOR();
(DISOWN-EDITOR), DISOWNEDITOR();
(REOWN-EDITOR JNAME) REOWNEDITOR(JNAME);
(EDITOR-TO-DDT) ; snarfs it from DDT
(EDITOR-FROM-DDT JNAME) ; gives it back to ddt


File: LISPT	Node: Other	Previous: JOB,	Up: TOP

Miscellaneous Information about LISPT

LISPT was originally implemented by Rich Bryan (RLB) as an experiment
in the use of inferior jobs and the USR device.  It has since been
developed somewhat by JLK.  LISPT requires an inferior job package
to accomplish job managing operations.  Currently it uses the LDDT
package (LIBLSP;LDDT FASL) which in turn uses the HUMBLE package
for low level primitives.  These may be replaced in the near future
by a combined package (GSB;QJOB >).

There are various problems in using the USR device for transmitting
ASCII text.  Neither LISP nor ITS supports this mode of operation,
and therefore it is necessary that a kludgey patch be made (automatically)
to LISPT when LISPT is loaded (see JLK;LISPT PATCH).  This patch causes 2
otherwise shareable pages in LISP to become unshared.  Hopefully this
situation will not persist, but for the moment it is an overhead which
must be considered.  The necessity for this patch is due to the
desirability of being able to use READ, PRINT, SPRINTER, etc on a USR
device channel to or from a TECO buffer.

Many of the job managing aspects of LISPT are still in a state of
development (e.g. allowing multiple inferior editors, passing the
editor between LISP and DDT, TTY passing, TTY-RETURN prompting
and acknowledgement, etc.).  Any suggestions in this area would be
appreciated.


File: LISPT	Node: LDETAILS			Up: TOP

Details on the LISPT implementation for LISP Programmers
(information you need for customizing LISPT behavior)

(SSTATYS TTYINT...) for tty passing, reown-disown, etc, LISPT-NULL
TTY-RETURN hackery, JOB-RETURN-TTY
variables controling job loading, jname, etc.(LISPT-FILE, LISPT-JNAME)
READ-EVAL-PRINT uses values of READ, EVAL, and PRIN1.  Also LISPT-READTABLE
Alternate read loops (LISPT-READ-LOOP, DEFAULT-LISPT-READ-LOOP,
	CATCH-READ-LOOP)
	Can't read LAP yet
	does handle INCLUDE
	CATCH-READ-LOOP punts upon encountering ^C (more reliable but
			can't read files with ^C in them)

LISPT-PROTECT, EDPROTECT
LISPT-VERBOSE (not implemented)
EDITOR-JOB, EDITOR-JNAME
SUSPENDing LISP with inferiors
When VALRETing you may want to bind TTY-RETURN off
LDDT features (P, :CONTIN, :PROCEED, G, :JCL, ...)
JCL hacking

TECO-BATCHing in MACSYMA - reads "..." in bothcases


File: LISPT	Node: EDETAILS			UP: TOP

EMACS Macros used with LISPT

Low level text sending protocol
FS SUPERIOR conventions
List of macros
Setup hook
window hackery
deferred sending of text
.Z q-vector of macros and other things