Initial revision

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..91e9303
--- /dev/null
+++ b/README
@@ -0,0 +1,102 @@
+                       CUPL and CORC for UNIX
+               by Eric S. Raymond <esr@thyrsus.com>
+
+This directory contains sources for cupl, a UNIX implementation of CUPL, the
+Cornell University Programming Language.  It also interprets CORC, the 
+Cornell Computing Language, the immediate ancestor of CUPL.
+
+CUPL was an early (1966) teaching language implemented as a batch compiler on
+the IBM/360 at Cornell University.  It was descended from an earlier (1962)
+experimental language called CORC (CORnell Compiler), which was in turn derived
+from PL/1.
+
+CUPL has only one scalar type, a long floating-point real corresponding to C
+double.  It supports vector and matrix aggregates, and has operations
+specialized for matrix calculations.
+
+CORC is a near-subset of CUPL.  There are some minor differences in keywords.
+In CORC, the statement GO TO <block> is equivalent to CUPL's GO TO <block> END.
+
+The cupl implementation is a Retrocomputing Museum project.  The
+Retrocomputing Museum <http://www.catb.org/retro/retromuseum.html>
+revives long-dead languages for the benefit of students and historians
+of programming-language design.  CUPL was chosen as a representative
+of a significant class of mid-1960s teaching languages.
+
+Files:
+
+                       Documentation files
+
+README                 -- this file
+cupl.doc               -- transcription of the original CUPL documentation
+corc.doc               -- transcription of the original CORC documentation
+cupl.xml               -- description and discussion of the language
+cupl.spec              -- project history is in this RPM spec file
+
+                       Source files
+
+Makefile               -- project makefile
+cupl.y                 -- the YACC grammar
+cupl.l                 -- the LEX lexical-analyzer description
+cupl.h                 -- fundamental types and defines 
+tokdump.c              -- token-dumper code (used for debugging)
+interpret.c            -- parse tree interpretation
+execute.c              -- actual execution
+monitor.c              -- runtime support
+main.c                 -- cupl's main sequence
+
+                       CUPL samples
+(These are all the non-pathological program examples from the CUPL manual)
+
+test/cubic.cupl                -- iterative solution to X**3 * 3*X + 1 = 0
+test/fancyquad.cupl    -- third, fanciest version of quadratic solver
+test/poly11.cupl       -- sum for k = 1 to 11 of k!x**k, plus 1
+test/power.cupl                -- compute the sum as k goes from 1 to n of k!/x**k
+test/prime.cupl                -- test a number for primality
+test/quadratic.cupl    -- solve multiple quadratic equations
+test/random.cupl       -- print 10 pseudo-random numbers
+test/rise.cupl         -- compare iterated +, doubling, squaring, and *
+test/simplequad.cupl   -- simplest version of quadratic equation solver
+test/squares.cupl      -- print a table of squares
+test/sum.cupl          -- compute sum of presented data
+
+                       CORC samples
+(These are all the complete program examples from the CORC manual)
+
+test/factorial.corc    -- compute the factorial function
+test/powercorc.corc    -- compute the sum of a power series
+test/quadcorc.corc     -- solve multiple quadratic equations
+test/sumsquares.corc   -- compute sums of first n integers and squares
+test/title.corc                -- illustate use of NOTE, TITLE, and WRITE
+
+For each .cupl or .corc file, there is a corresponding test file used for
+regression-testing of the interpreter.  The interpreter should pass
+all these tests.
+
+                       Other test files
+MAKEREGRESS            -- generate regression test loads for the front end
+REGRESS                        -- perform regression test on the front end
+
+                       Known problems and bugs:
+
+* The code chrestomathy in the CUPL manual didn't include any matrix algebra
+  examples.  Because of this, the matrix algebra facilities are incomplete. 
+  ALLOCATE, INV and DET are not implemented.  Neither are subscript/slice
+  references or assignments.  Nor are matrix WRITEs or READs. Nor are the
+  implemented matrix facilities at all well-tested.
+
+* For true verismilitude, a program listing should be output before results.
+  This is trickier to do in C than it sounds; the lexer doesn't know about
+  line boundaries.
+
+* GOTO blabel END always goes to the end of the current PERFORM block, even
+  if the label is that of an enclosing block.
+
+* Because the cupl interpreter also interprets CORC, the CUPL keywords
+  BEGIN, DEC, DECREASE, EQL, GEQ, GTR, INC, INCREASE, INT, LSS, NEQ, NOTE,
+  REPEAT, TITLE, UNTIL, and $ are also reserved words in CORC.
+
+Send comments, bug reports, and fixes to esr@thyrsus.com.  Also see my
+home page at http://www.catb.org/~esr for updates and other related
+resources.
+