;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;                                                          ;;;;;;;;
;;;;;;  All files in this directory and its subdirectories are  ;;;;;;;;
;;;;;;  copyright 1997, 1998, 1999, 2000, 2002, 2003, 2008      ;;;;;;;;
;;;;;;  by Rafael D. Sorkin.  All rights reserved.              ;;;;;;;;
;;;;;;                                                          ;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

THIS README FILE IS FOR THE CURRENT RELEASE, VERSION 2.1

  If you have trouble with Version 2, you can fall back to 1.4, which is
  preserved here as the compressed (gzipped) tar file, version.1.4.tar.gz
  Please send bug reports to the address given below.


FILES IN THIS DIRECTORY

  lisp.lib.tar  (a tar image of the whole directory for ready retrieval)

  Copyright_Notice
  README (this file)
  Version.notice
  Several files with names of the form "bibliotek..."
  preparations.el and .gcl

  version.1.4.tar.gz


BRIEF DESCRIPTION OF THIS PACKAGE

The files in this directory define a suite of lisp functions and macros
for working with finite posets.  In writing them, I had in mind
specifically causal sets, but most of the suite is independent of the
intended interpretation.  Also present are several functions and macros
of general utility having nothing to do with posets as such.

The part of the package devoted to posets includes functions to return
the past of an individual element, to transitively close a preposet
(acyclic relation), to find the maximal and minimal layers of a poset
and the levels of its individual elements, to compute the Myrheim-Meyer
dimension of an order-interval, to count chains or spanning trees, to
create a new poset by hand or to generate one randomly.  This is just a
small sampling of the functions and macros.  Many more are available.
See the next section below on documentation, and the file herein named
"Some.more.documentation".

The more general part of the package includes a variety of functions
which, compute binomial coefficients, form the union two sets of
symbols, compute (with error bars) the mean and standard deviation of
numerical data, etc, etc.  There are also macros designed to extend or
simplify lisp syntax and macros designed to cope with the lack of local
variables/symbols -- a problem mainly for emacs-lisp.  Examples of their
use can be seen in the source code.  (See especially the macro `deff'
that extends `defun'.)

This suite is designed to work equally well with Emacs Lisp (elisp) and
true Common Lisp, although I've not tested it with all flavors of the
latter.  Since the functioning of elisp is quite consistent from machine
to machine, if you have a (sufficiently current) working emacs, you
should have no trouble using this package.  (I'm using use the word
`package' in its informal English sense.  This library is not set up as
a package in the technical lispy sense.)


DOCUMENTATION

A large amount of documentation is contained within, or together with,
the functions and macros themselves.  Each bibliotek file defines a set
of related functions (or macros), which are listed at the top of the
bibliotek.  (The biblioteks devoted to posets are bibliotek.poset and
bibliotek.extras.)  Most of the functions have descriptive names (mostly
in English), and each incorporates a documentation string that describes
its behavior in detail. (Within emacs, you can access this documentation
string conveniently using the command `describe-function'.)

You can find further discussion of this library, and a longer list of
its poset functions in the file "Some.more.documentation".  I hope to
add to it from time to time.


INSTALLATION INSTRUCTIONS FOR ELISP (for unix systems)

(1) Installing the files

  Create a sub-directory of your home directory named "lisp" and make
  sure it contains all the files whose names begin either with "bibliotek"
  or "preparations".  (A quick way to do this is to retrieve the file
  lisp.lib.tar, place it in your "lisp" directory, and unpack it.)

  (To install in some directory other than ~/lisp, see step 4 below)

(2) Initial compilation

  Start up an emacs and load (or evaluate the contents of) the file
  preparations.el, after temporarily uncommenting the line:

    (setq recompile t)

  near the top of the file.  This should create byte-compiled versions
  of all the bibliotek files, with names ending in ".elc" .  [Be sure to
  comment out the line (setq recompile t) after the .elc files have been
  created.]

(3) Using the package

  Just load the file preparations.el whenever you want to use the package.

(4) [Optional]
  If you wish to install the files in a different directory than ~/lisp/
  you can do so (in theory anyway) by modifying the line flagged  ;! 
  in the file preparations.el  (This is the line which currently reads
  (setq *lisp-home* "~/lisp/").  A few other lines might also be
  flagged this way, indicating other settings you might wish to change.)

INSTALLATION INSTRUCTIONS FOR COMMON LISP (unix systems)

The procedure for Gnu Common Lisp is the same as above, except you use
the file preparations.gcl instead of preparations.el

Versions for Clisp and possibly Cmu Common Lisp will be available in the
future.


COMMENTS AND BUG REPORTS

  Both are welcome!   
  Send them to: sorkin@physics.syr.edu (Rafael Sorkin)