ReadMe file for the distribution of the Franz implementation of PEARL.
						 8/9/83 by Joe Faletti

PEARL is an AI programming language implemented on top of Franz Lisp
by Joseph Faletti and Michael Deering under the direction of Robert
Wilensky at the Berkeley AI Research Project (BAIR).

DOCUMENTATION
    For more information on PEARL's capabilities, see the following:

[1] Deering, M., Faletti, J., and Wilensky, R.  1981.  PEARL:  An Efficient
Language for Artificial Intelligence Programming.  In the Proceedings
of the Seventh International Joint Conference on Artificial Intelligence.  
Vancouver, British Columbia.  August, 1981.

[2] Deering, M., Faletti, J., and Wilensky, R.  1982.  The PEARL Users Manual.
Berkeley Electronic Research Laboratory Memorandum No.
UCB/ERL/M82/19.  March, 1982.

[3] Faletti, J., and Wilensky, R.  1982.  The Implementation of PEARL.
Unpublished memo. 

The last two are included in vtroff source form in this distribution
but the page numbers of [2] may be off by a bit (sorry! -- if someone
bothers to convert the manual for automatic table of contents and
index generation, we'd be happy to use it!).  (More below).

The manual [2] may be printed and distributed to users with no fear
of copyright infringement.  However, for those without suitable printing
facilities, a single photocopy of the manual suitable for auto-feed copying
for local distribution of the manual may be acquired from:
    Berkeley AI Research Project
    Robert Wilensky, Director
    Computer Science Division
    553 Evans Hall
    University of California, Berkeley
    Berkeley, CA  94720
This version will include an addendum summarizing the changes
described in the file ChangeLog.

BUG REPORTS:
    Bug reports should be mailed to Pearl-Bugs@Berkeley by ARPANET or
ucbvax!pearl-bugs by USENET.  PEARL is being provided as is for the
cost of distribution with Franz and as such carries no warranty or
guarantee.

CONTENTS OF THIS DIRECTORY:
    The files in this directory fall into two categories: A) the source and
make file for building a version of PEARL in Franz and B) documentation.

    A) Source and make file for building a version of PEARL in Franz.
These files are described briefly after the following description of
how to make a version of PEARL.

To Make PEARL:
    A version of PEARL may be made by changing to this directory and
executing a "make pearl".  As delivered, this makes "small" which compiles
PEARL in two pieces, and builds "pearl.o" (which loads the two pieces
into a lisp) and then executes the "savepearl" function which dumps a
lisp called "pearl" in the current directory containing all of PEARL
with the PEARL top level installed and ready to start up from scratch.
This form is necessary on machines with less than about 2.5Mb of memory.
If your installation is larger, you can change "pearl" to make "big"
instead of "small" and change "install" to make "biginstall" instead
of "smallinstall".  This will compile PEARL in one piece, creating
"pearl.o" simply by compiling the file "pearl.l" which "includes" all
the other source files described below.
    Making PEARL from scratch takes about 13 minutes of CPU time, or about
15 minutes of real time (times the load average) on a VAX 780.
    To install the executable pearl in the usual object directory,
/usr/ucb, and the load module pearl.o in the Franz library /usr/lib/lisp,
execute a "make install".  If you change where the library is you must
also change the absolute path names in the file "pearllib.l" (which is used
in a "make small" to make it easy to load the two halves of PEARL with a
single file).

The Source for PEARL:
    The source for PEARL is described below in the order that it is
included in "pearl.l".

ucisubset.l --- PEARL was originally implemented in UCILisp.  This file
    defines those functions from UCILisp still used in PEARL.
franz.l --- Franz version of functions that are likely to need
    to be redefined for a particular lisp.
lowlevel.l --- Lowest level functions (mostly macros) in PEARL
    used to access the various data structures.
db.l --- Functions for creating databases.
vars.l --- Functions to handle pattern-matching variables.
symord.l --- Functions for creating symbols and ordinals.
hook.l --- Functions used by everything else to handle hooks (demons).
create.l --- Functions to create PEARL structures.
scopy.l --- Functions to copy PEARL structures.
path.l --- The PATH function.
print.l --- Functions to print PEARL objects.
hash.l --- Functions using hashing info in structures to insert and
    fetch from data bases.
match.l --- Functions to match and/or compare structures.
history.l --- Functions used to implement the history mechanism in the
    toplevel loop.
toplevel.l --- Variation on the Franz toplevel loop for PEARL,
    including functions for dumping various versions of a running PEARL.
fix.l --- Variation on the "fixit" debugger adapted for PEARL.
alias.l --- Code to save various functions under alternative names.
inits.l --- Code which must run at load time to initialize a PEARL
    environment.

Documentation included in this directory:

manual.ms --- The -ms source of the PEARL manual as published in the
    reference [2] above.  This should be vtroffable to produce a copy
    of the PEARL manual, although the page numbers were done by hand
    and thus may be off by a bit if anything is changed.  It may also
    be nroffed, although the page numbers will most certainly be off.
update.ms --- The -ms source for an update to the manual covering PEARL
    up through Version 3.9 paginated for appending to the manual.
ChangeLog --- A listing in reverse date order of things changed in
    PEARL since the manual was published.
template --- Visual representation of the allocation of information in
    the hunks used by PEARL for various internal data structures.
implement.ms --- An unfinished memo on the implementation of PEARL.
    Includes a simple example of how to implement forward and backward
    chaining in PEARL and a bit more detail on the hashing mechanism.
ltags --- A tags file for the various function and macro definition
    mechanisms used in PEARL (more than standard Franz).
ptags --- A tags file for files which contain mixed Lisp functions and
    PEARL structure definitions.

