BRIEF GUIDE TO NISP & DUCK  
==========================

Released version, September, 1992

Directory Structure
-------------------

This release was presumably built from a tar file that stored its
wares in five subdirectories of the "nisp" directory:

nils/ : Nisp Implementation Lisp Subset
decl/ : Nisp types and declarations
duck/ : Duck
extra/ : A few miscellaneous things
doc/ : Some documentation.

Documentation
-------------

NISP is described in two Yale Techical Reports:
   * "The NISP Manual" (June 1983, YALEU/DCS/RR #274).
   * "Revised NISP Manual" (August 1988, YALEU/DCS/RR #642).
The latter is available in "doc" directory here:
   * nispman.tex is the LaTeX text file, accompanied by various
	complementary files (index, table of contents, etc).
   * nispman.dvi is the device-independent output file,
	suitable for printing (e.g. using lpr -d).
Unless you are working with old NISP code, the revised manual is the
only one you should need.

Recent changes to nisp are described in doc/nisprecent.txt, in the doc
subdirectory of nisp.

DUCK is described in two documents:
   * "The DUCK Manual" (June 1985, YALEU/DCS/RR #399).
   * "DUCK Syntax" (June 1987), an elaboration on the syntax of
	DUCK programming, has not been published in printed form
	but is available in LaTeX/dvi formats in the "doc" directory.
        See doc/ducksyn.tex

Both documents are based on the earlier version of NISP; changes
described in the "Revised NISP Manual" apply equally to DUCK, much of
the code for which has been updated.  

See also doc/duckrecent.txt for some "recent" changes to Duck.

Source Code, Compiling & System Building
----------------------------------------

A third of the NILS files, and one of the DECL files (hostypes),
exist in separate versions for T and Common Lisp, and you may have
to adjust the filename extensions for the Common Lisp versions 
(e.g. from ".lisp" to ".lsp").  >> If you are not at Yale you will
probably not have the T versions.

Virtually all other system-specific customizations are made in the
NILS files "start.lisp" (or "start.t") and "depnisp.nsp" .  

Check "start" for four possible types of customization:
   1. If your lisp is close to the dialect described in CLTL2 
      ("Common Lisp The Language Second Edition"), add :NEWFANGLED
      to the *FEATURES* list.  Just uncomment the
      (PUSH ':NEWFANGLED *FEATURES*) code in start.
      Right after that, there are adjustments to package names for
      new-fangled and old-fashioned systems.  Fiddle with these so
      that CL: is a package prefix for the host "LISP" package, and
      CL-USER: is the package prefix for the "USER" package.
   2. Find the code (DEFCONSTANT HOST-SYS* ...)
      Make sure that the host systems you are using are supported 
	there.  If not, you will need to add appropriate entries for
	things like default filename cases and extensions (these 
	should be fairly obvious, or easily testable).
   3. Check the defining form for NISP-HOME-DIR*.  This should be set
	to a string which specifies the directory in which the file 
	you are now reading is located.  Similarly for NILS-HOME-DIR*
      etc.  NILS-HOME-DIR* and DECL-HOME-DIR* are normally
      subdirectories of NISP-HOME-DIR*.
   4. At the end of "start" are various optional customizations,
	which you are free to change if you wish.  (E.g.,
        *PRINT-ARRAY* is true by default.)

If you are using a previously unsupported lisp implementation or 
machine environment, you should also check occurrences of !D, !S, #+
and #- in later NISP files, to make sure the right thing will happen
(or, at least, to be aware of something that may break).

The file "depnisp.nsp" defines modules and logical directory names.
After the line "****** Customizations:", make any additions or
deletions that you require.

When you load "start", it will ask "Compile?"  The first time you load
it, answer "Y", and it will recompile the basic prenils stuff.  Normally
you answer "N", and it will just reload the binaries for the basic
prenils stuff.

Once start is loaded, type (NISP:GOTONISP) to get into the Nisp
readtable and package.

To build a Nisp system, do the following:

(DSKLAP NILS/ BUILDSYS)
[ may prompt for whether buildsys should be compiled ]

(BUILD-SYSTEM (DEPENDS-ON NILS) (DEPENDS-ON NISP) ...)

[ assuming you're building a complete Nisp.  Put any other files you
want in your core-image in the space marked by "..."   To build Duck,
put in (DEPENDS-ON DUCK). ]

In Lucid Common Lisp, 

(SAVE-NISP-SYSTEM file herald)

will save a core image in file.  When the core image is run, the
herald string will be printed, and patch files will be loaded.  For
nisp, this includes any file named nisp-init in your home directory;
for duck, it includes any file named duck-init.

** Alas, if you have a non-Lucid or Lispworks system, you are going to have to
define SAVE-NISP-SYSTEM using your own local facilities by mimicking
the Lucid version.  I would appreciate receiving your versions for
future releases.

Once the appropriate files are loaded, "(DSKLAP DECL/ NISPTEST)"
will test the proper behaviour of NISP, and  "(DSKLAP DUCK/ DUCKTEST)"
will do the same for DUCK.  You can answer either way when asked
by DSKLAP whether these files should be compiled first.

Patches & Run-Time Customization
--------------------------------

Patch files are provided, in the normal directories, for NILS
(nilspatch), DECL (declpatch) and DUCK (duckpatch).  These are loaded
by the appropriate "(LOAD...)" calls, and the saved systems are set up
to check for and load them whenever the executables are started.
Rather than patching NISP and DUCK directly -- apart from the system
customizations mentioned earlier -- any bug fixes or whatever would
normally go into these three files.

Individual user customizations should go into "nisp-init.nsp" and 
"duck-init.nsp" files in the user's home directory.  Provision for
loading these is made in saved systems; otherwise, they must be
loaded specially.  Vanilla versions are provided in the "misc"
directory.


Packages
--------

Nisp resides in the "NISP" package.  If you want to use it in some
other package, do the usual (USE-PACKAGE "NISP"), and most of the symbols
described in the Nisp manual will be accessible without colons.
However, there are a few Nisp symbols whose names clash with those of
built-in Lisp constructs.  To get around this problem, you can do one
of two things:

1) For each renegade Nisp symbol, use the following synonyms instead:

   LOOP -- REPEAT
   DEFTYPE -- NISPDEFTYPE,DEFNISPTYPE
   DEFCLASS -- NISPDEFCLASS,DEFNISPCLASS
   COMPLEMENT -- SET-DIFFERENCE 
   SYMBOL -- BUILD-SYMBOL

2) Run the function (NISP-PENETRATE-PACKAGE p) to cause package p to
use the NISP package, and to do a shadowing-import of all the renegade
Nisp symbols.  From then on, you can use Nisp's DEFTYPE in p without a
colon, but you'll have to say LISP:DEFTYPE to get the built-in
version.  (NISP-WITHDRAW-FROM-PACKAGE p) undoes this.  

(USE-NISP) sets the readtable to the Nisp read table and does a 
NISP-PENETRATE-PACKAGE for the USER (or COMMON-LISP-USER) package.  
(UNUSE-NISP) undoes that.

