This is CLISP, a Common Lisp implementation.


What is LISP?
-------------

LISP is a programming language. It was invented by J. McCarthy in 1959.
There have been many dialects of it, but nowadays LISP has been standardized
and wide-spread due to the industrial standard COMMON LISP. There are
applications in the domains of symbolic knowledge processing (AI), numerical
mathematics (MACLISP yielded numerical code as good as FORTRAN), and
widely used programs like editors (EMACS) and CAD (AUTOCAD).
There is an introduction to the language:

  Sheila Hughes: Lisp. Pitman Publishing Limited, London 1986.
  107 pages.

After a while wou will need the standard text containing the language
definition:

  Guy L. Steele Jr.: Common Lisp - The Language. Digital Press.
  1. edition 1984, 465 pages.
  2. edition 1990, 1032 pages.

This book is available in HTML form via FTP from
  ftp.cs.cmu.edu:/user/ai/lang/lisp/doc/cltl/cltl_ht.tgz  and
  ma2s2.mathematik.uni-karlsruhe.de:/pub/lisp/CLtL2/cltl_ht.tgz
and can be viewed through WWW under
  http://www.cs.cmu.edu:8001/Web/Groups/AI/html/cltl/cltl2.html or
  http://www.cs.cmu.edu:8001/afs/cs/project/ai-repository/ai/html/cltl/cltl2.html .

LISP is run in an interactive environment. You input forms, and they will be
evaluated at once. Thus you can inspect variables, call functions with given
arguments or define your own functions.


Contents:
---------

It consists of the following files:

      lisp.exe           main program
      lisp_1mb.exe       main program, use this one if you have
                         only 1 or 2 MB of RAM
      lispinit.mem       memory image needed for startup
      clisp.1            manual page in Unix man format
      clisp.man          manual page
      clisp.html         manual page in HTML format
      clisp.dvi          manual page in dvi format
      impnotes.txt       implementation notes
      cltl2.txt          notes about the relation of CLISP to CLtL2
      clreadline.3       line editing manual page in Unix man format
      clreadline.man     line editing manual page
      clreadline.dvi     line editing manual page in dvi format
      LISP-tutorial.txt  LISP tutorial for beginners
      CLOS-guide.txt     brief guide to CLOS
      emx-user.doc       emx applications user's guide
      emx-faq.doc        frequently asked questions about emx applications
      termcap.dat        terminal capabilities database
      rsx.exe            DOS extender rsx for running clisp under Windows
      rsx-read.txt       general description of rsx
      rsx-inst.txt       installation instructions for rsx
      rsx-faq.txt        frequently asked questions about rsx applications
      rsx-copy.txt       copyright notice for rsx
      delay.exe          auxiliary program for running clisp under Windows
      README             this text
      SUMMARY            short description of CLISP
      ANNOUNCE           announcement
      NEWS               list of modifications since the last version
      COPYRIGHT          copyright notice
      GNU-GPL            free software license
      readline.dvi       GNU readline library documentation
      config.lsp         site-dependent configuration
      timezone.lsp       site-dependent time zone

and - to your convenience, if you like reading source -

      *.lsp              the source of lispinit.mem


Hardware requirements:
----------------------

This DOS version of CLISP requires an 80386 (SX or DX) or an 80486 CPU
and at least 1 MB of RAM.
It also runs on a Pentium; the results CLISP produces are not affected by
the Intel Pentium's division bug.


Installation:
-------------

For overly long input lines to be displayed in a smart manner, it is necessary
that you have a line like

    DEVICE=ANSI.SYS

in your CONFIG.SYS file. Furthermore the environment variable TERM must
be set, and the environment variable TERMCAP must contain the slashified
file name of the terminal capabilities database termcap.dat. It is a good
idea to put this stuff into the clisp.bat built below. You may want to
install termcap.dat in a separate directory, say c:\emx\etc.

Edit the contents of config.lsp appropriately for your site,
especially the definitions of short-site-name and long-site-name.
You may also want to edit the time zone definition at the end of
timezone.lsp.
Then start

         lisp.exe -M lispinit.mem

When the LISP prompt

      > _

appears, type

        (compile-file "config")
        (load "config")

and - in case you modified timezone.lsp -

        (compile-file "timezone")
        (load "timezone")

and then

        (saveinitmem)

to overwrite the file lispinit.mem with your configuration. Then

        (exit)

Then create a directory, and put the executable and the memory image there.
Assuming D:\LIB\LISP :

   mkdir d:\lib\lisp
   copy lisp.exe d:\lib\lisp
   copy lispinit.mem d:\lib\lisp

And create a batch file that starts lisp:

   copy con c:\bat\clisp.bat
   set TERM=ansi
   set TERMCAP=c:/emx/etc/termcap.dat
   d:\lib\lisp\lisp.exe -M d:\lib\lisp\lispinit.mem %1 %2 %3 %4 %5 %6 %7 %8 %9
   [Ctrl-Z]


Installation under Microsoft Windows:
-------------------------------------

CLISP also runs in the DOS box of Microsoft Windows 3.1.
To achieve this, the following additional steps are necessary:

1. Get and install
     ma2s2.mathematik.uni-karlsruhe.de:/pub/lisp/clisp/binaries/dos/clisp.zip
   as described above.

2. If rsx.exe is not already contained in clisp.zip,
   get and install RSX in, for instance, c:\rsx.
     ftp.uni-bielefeld.de:/pub/systems/msdos/misc/dpmigcc4.zip
     ftp.shsu.edu:/tex-archive/systems/msdos/dpmigcc/dpmigcc4.zip
   or
     ftp.uni-bielefeld.de:/pub/systems/msdos/misc/dpmigcc5.zip

3. Call the PIF editor and input the following:

   Program:                c:\rsx\bin\rsx.exe
   Program title:          COMMON LISP
   Program parameters:     c:\lib\lisp\lisp.exe -M c:\lib\lisp\lispinit.mem
       or with dpmigcc5:   -Ra c:\lib\lisp\lisp.exe -M c:\lib\lisp\lispinit.mem
   Start directory:        e:\lisp  (or whatever)
   Screen:                 Text
   Memory requirements:    requires:  500      maximum:  640
   EMS memory:             requires:    0      maximum:    0
   XMS memory:             requires: 1024      maximum:   -1
   Display:                [as you like]
   Quit_closes_window:     [as you like]
   Execution:              [as you like]
   other_options:          [as you like]

   (You will probably choose the directory which contains your lisp programs
   as start directory, instead of e:\lisp.)

   Save it under the name WINCLISP.PIF.

4. In the program manager, in a suitable group:

   Menu "File" -> "New" -> "Program", window "program properties".
   Input there:

   Description:            COMMON LISP
   Command line:           winclisp.pif
   Start directory:        e:\lisp
   Key combination:        Ctrl+Alt+Shift+L      [as you like]

Clicking with the mouse on the such created icon or pressing the key
combination given above in the program manager will now start CLISP.

Remarks:

* Cut & Paste in DOS boxes (via menu "Edit" -> "Mark" resp.
  menu "Edit" -> "Insert") inserts an <Enter> at the end. Therefore one
  cannot re-edit a pasted line.

* But the editing facilities mentioned in CLISP.MAN and READLINE.DVI work.


The editor:
-----------

Normally CLISP's ED function calls the editor you specified in config.lsp.
However, after you did

    (load "editor")

it invokes a builtin screen editor. It is a bit Emacs-like: you can evaluate
lisp expressions from within the editor, and the result is pasted into the
editor buffer. Type Alt-H to see the full set of commands.


When you encounter problems:
----------------------------

If clisp doesn't start up at all, check EMX-USER.DOC. lisp.exe is an EMX
application, so everything mentioned there applies to lisp.exe.

After errors, you are in the debugger:

     1. Break> _

You can evaluate forms, as usual. Furthermore:

     Help
               calles help
     Abort     or
     Unwind
               climbs up to next higher input loop
     Backtrace
               shows the contents of the stack, helpful for debugging

And you can look at the values of the variables of the functions where the
error occurred.

On bigger problems, e.g. register dumps, please send a description of the error
and how to produce it reliably to the authors or the maintainer. Please
accompany it with the CLISP version, which you get by calling
(lisp-implementation-version).


Mailing List:
-------------

There is a mailing list for users of CLISP. It is the proper forum for
questions about CLISP, installation problems, bug reports, application
packages etc.

For information about the list and how to subscribe it, send mail to
listserv@ma2s2.mathematik.uni-karlsruhe.de, with the two lines
          help
          information clisp-list
in the message body.


Acknowledgement:
----------------

If you find CLISP fast and bug-free and you like using it, a gift of $25
(or any amount you like) will be appreciated. Most DOS software costs
something, so you will probably already be used to paying.

If not, feel free to send us suggestions for improvement. Or grab the
source of CLISP, improve it yourself and send us your patches.

We are indebted to
  * Guy L. Steele and many others for the Common Lisp specification.
  * Richard Stallman's GNU project for GCC and the readline library.
  * Eberhard Mattes for EMX.


Authors:
--------

        Bruno Haible
        Michael Stoll

Email: haible@ma2s2.mathematik.uni-karlsruhe.de

Maintainer:
-----------

        Marcus Daniels

Email: marcus@sysc.pdx.edu
