This is the file README, or


                             A POOR SUBSTITUTE FOR
                              A USER'S MANUAL FOR
                             A THEOREM PROVER FOR
                             A COMPUTATIONAL LOGIC

                     Robert S. Boyer and J Strother Moore

                                November 1987

                                    WARNING

  See the warning at the beginning of the file basis.lisp for information
about copying, changing, and using this system.

                                    APOLOGY

  This manual is too short.  We're working on a longer version.

                                  THE THEORY

  The mathematical theory in which our system proves theorems is
described by (a) Chapter III of A Computational Logic (1), (b) pages
133-136 of The Correctness Problem in Computer Science (2), and (c) the
rules about QUOTE hinted at below.  Note that we now use hyphen instead
of period in identifiers, e.g., LEGAL-CHAR-CODE-SEQ instead of the former
LEGAL.CHAR.CODE.SEQ.

                                 LISP SYSTEMS

  Although previous versions of this program have run in Pop-2,
Interlisp, Zetalisp, Maclisp, and PSL, the system now runs only in
Common Lisp.

			  DIRECTORIES AND FILES

  The files for the theorem-prover are usually kept on
Arpanet/Internet host rascal.ics.utexas.edu.  Log in as anonymous, any
password, and get the files in the subdirectory thm.  On this
directory is the Common Lisp version of our theorem-prover as it was
before we added bounded quantification and partial recursive
functions.  This code works in Kyoto Common Lisp, Symbolics Common
Lisp, and Lucid Common Lisp.  We know of no reason for it not to work
in any Common Lisp that uses the Ascii codes for the printing Ascii
characters.

The source files for the system are:

 basis.lisp
 code-1-a.lisp
 code-b-d.lisp
 code-e-m.lisp
 code-n-r.lisp
 code-s-z.lisp
 events.lisp
 genfact.lisp
 io.lisp
 iterate.lisp    ;  MIT loop stuff
 ppr.lisp
 thm.lisp        ;  Compiler and loader

Read the file thm.lisp for instructions on compiling and loading the system.

The test files are:

  xxxs.l              ;  A miscellaneous collection, including
                      ;  Shakar's proof of the Church-Rosser theorem
  xxxs.fm8501         ;  Hunt's thesis -- a verfied microprocessor
  xxxs.goedel         ;  Shankar's thesis -- Goedel's incompleteness
                      ;  theorem

A good test is the first two forms of xxxs.l.  Takes about an hour on
a Symbolics 3640 or a Sun-3/280 running KCL.

All of these files may be extracted from thm.tar.Z by uncompress
and tar.


                          RUNNING THE THEOREM-PROVER

Read the file thm.lisp for instructions on starting up the system.
Once the system has started, you are in a normal read-eval-print loop
in a Lisp containing all of the theorem-prover subroutines.  (All of
the theorem-prover commands are Lisp functions.  You need to be
slightly familiar with the Lisp on your system to use our
theorem-prover.  In order to avoid a lot of typing, you also may want
to use a text editor to prepare input to the theorem-prover, in which
case you will need to know how to get the theorem-prover to read your
input from a file, using functions such as "load".  However, you can
just type your input directly to Lisp.)

  The next step is to initialize the theorem-prover in one of two ways:


   1. Call (BOOT-STRAP), putting the theorem-prover into its most
      elementary state, which corresponds to chapter III of (1).

   2. Call (NOTE-LIB "foo.LIB" "foo.LISP"), putting the theorem-prover
      back into the state that it had when the command (MAKE-LIB "foo")
      was invoked, which created the files "foo.LIB" and "foo.LISP".

Here we briefly list some commonly used commands.

Command:  (DEFN name args body hints)
Example:  (DEFN APPEND (X Y)
                (IF (LISTP X)
                    (CONS (CAR X) (APPEND (CDR X) Y))
                    Y))


  This command attempts to admit name as a function under our principle of
definition.  The optional fourth argument, hints, may be used to specify the
measure and well-founded relation.  For examples look at the definitions of GCD
and NORMALIZE in the file XXXS.LISP.



Command:  (PROVE-LEMMA name types term hints)
Example:  (PROVE-LEMMA ASSOC-OF-APPEND (REWRITE)
                       (EQUAL (APPEND (APPEND X Y) Z)
                              (APPEND X (APPEND Y Z))))


  This command attempts to prove term and to store it as a lemma of
the types specified.  types may be any subset of (REWRITE ELIM
GENERALIZE).  The optional fourth argument, hints, may be used to
specify instantiations of previously proved lemmas to be used, the
names of lemmas that are not to be used, and the first induction to be
done.  See the PROVE-LEMMA commands for TIMES-MOD-2 and
PIGEON-HOLE-PRINCIPLE in the file XXXS.LISP.  For an example of a
"meta-lemma," the one described in (2), see the theorem
CORRECTNESS-OF-CANCEL.



Command:  (TOGGLE name oldname flg)
Example:  (TOGGLE ASSOC-APPEND-OFF ASSOC-OF-APPEND T)


If flg is T, TOGGLE prohibits future utilization of the theorem or definition
oldname.  If flg is NIL, it turns oldname back on.



Command:  (PROVEALL event-list NIL root)
Example:  (PROVEALL '((DEFN BAR (X) (PLUS X X))
                      (PROVE-LEMMA BAR2 (REWRITE)
                                   (EQUAL (BAR X) (TIMES 2 X))))
                    NIL
                    "BAR")


  PROVEALL attempts to process the instructions on event-list.  Output goes to
root.PROOFS and root.TTY (for errors and warnings).  When finished, the files
root.LIB and root.LISP are created.



Command:  (EVENTS-SINCE name)
Example:  (EVENTS-SINCE 'APPEND)


  This command returns the list of commands since the event named name.



Command:  (UNDO-BACK-THROUGH name)
Example:  (UNDO-BACK-THROUGH 'APPEND)


  This command undoes all of the commands since the event named name.

                                  QUOTE VS. "

  In our two books we denote literal atoms with double quotation marks, e.g.
"PUSHV".  When using the theorem-prover, one must use the notation (QUOTE
PUSHV) instead of "PUSHV".  QUOTE may be given Sexpressions.  The meaning of
(QUOTE (A B)) is the same as the meaning of (CONS (QUOTE A) (CONS (QUOTE B)
                                       4


NIL)).  Observe that the Maclisp reader reads 'PUSHV as (QUOTE PUSHV) and '(A
B) as (QUOTE (A B)).

                        RUNNING FUNCTIONS IN THE THEORY

  It is possible to ask for the execution of variable free terms.  For example,
if the logical function FLATTEN is defined in the usual way, then one may
execute



(R '(FLATTEN (QUOTE ((A B) (C D)))))


which will return 


(A B NIL C D NIL NIL).



                                  REFERENCES

1.  R. S. Boyer and J S. Moore.  A Computational Logic. Academic Press, New
York, 1979.

2.  R. S. Boyer and J S. Moore.  Metafunctions:  Proving Them Correct and Using
Them Efficiently as New Proof Procedures.  In The Correctness Problem in
Computer Science, R. S. Boyer and J S. Moore, Eds., Academic Press, London,
1981.
