------------------------------------------------------------------------
This is the 2.42 release of PRECCX  (README)                 August 1994
Peter T. Breuer   <ptb@eng.cam.ac.uk,ptb@comlab.ox.ac.uk,ptb@dit.upm.es>
------------------------------------------------------------------------ 

INTRODUCTION:

  PRECCX is an infinite-lookahead compiler compiler for context
  dependent attributed grammars. Copyright P.T. Breuer, 1989-1994.

Compiler compilers aren't that easy to describe! You ought to have
some familiarity with the UNIX yacc utility, or GNU's bison under DOS,
in order to figure out what to do with PRECCX and why. This document
will genenerally assume that you know the basics, but still ... a
compiler compiler converts a high-level script into low level source
code. The script defines a language and the source code implements a
parser for that language. The parser may execute actions - in which
case the compiler compiler has compiled an interpreter - or it may
build complex structures such as further source code - in which case
the compiler compiler has compiled a compiler.

So a compiler compiler provides an easy path to the construction of a
complex utility. Just specify the language and some associated actions
and structures and let the compiler compiler build the source for you.

Why the new release of PRECCX?

This release fixes a few bugs from the 2.40 alpha release of the 2.4x
development line, and includes more technical improvements. The new
functionality sketched in in 2.40 and beta-ed in 2.41 has finally been
completed and tested successfully.  On the technical front, the back
end has shifted from interpretation to compilation for the runtime
machine, resulting in increased robustness. As far as theory goes, the
extra functionality of 2.42 over the 2.3x series now permits seamless
mixing of synthetic and inherited parameters. (This facility\x is a
powerful(x) !!)

          --------------------------------

(README) CONTENTS:
          INTRODUCTION ........  What you just read.
          CONTENTS ............  Where you are.
          DIFFERENCES .........  For those who are upgrading -
          NEW .................  and those who are thinking of it.
          TESTING .............  A word on operating systems.
          INSTRUCTIONS ........  What to do next.

          --------------------------------

DIFFERENCES: This release should be upwardly compatible with the 2.3x
line except in the following respects. The first three provisos relate
to the yacc-style $1, $2, $3, ... numbered attribute references
required by 2.3x and which are now obsoleted in favour of $foo named
references:

1) use the -old switch while running precc over these old scripts;
2) don't use $0 or lower references;
3) don't use $$ (this is a _big_ change - see below);

4) you now have to put { } tightly round actions. E.g.

   @ foo = bar {: gum :}

This is to avoid conflicts with C code ":"s in the gum part.

          --------------------------------

NEW:     1)  !{handler}

                          ********* error handling

         2)  sum = term\x <'+'> term\y {: printf("%d",$x+$y); :}

                          ********* named attribute references

         3)  prod = term\x term\y {@ $x*$y @}

                          ********* inline attribute synthesis

1) The backtracking  error handler construct tells precc where to 
branch to in case of an  attempt to  backtrack  across  the !  mark.  
The handler parser  should  eat  tokens and branch to a standard  
parser when it thinks it has found something standard.

This is implemented extremely efficiently internally - no worries
about C stack buildup, so use with impunity.

2) The new attribute style has permitted the run-time attribute stack
to be dispensed with (see the manual). This saves RAM. The call_mode
parameter is now obsolete (it was anyway for users - the default was
never changed in practice). I think the style also looks better!

3) It is now generally impossible to make assignments to attributes
from within actions along yacc lines using {: $$=foo; :} because
attributes are now being built and used earlier: during the parse,
when they can be most useful, and this takes place before actions are
executed. So yacc-style writes to attributes from within actions have
no effect. You have to use the new {@ foo @} notation instead. 


The -old switch is an attempt to continue to support the yacc-style
$1, $2, $3, etc. attribute dereferences as far as possible. It
generates nasty code and it is preferable to convert scripts to the new
style of named attributes and dereferences instead! Note that there is
no longer support for the $$ yacc-style attribute target in actions.

          --------------------------------

TESTING: I have done much preliminary testing on HP-UX with c89, sunOS
UNIX with gcc and MSDOS with BorlandC/TurboC v2.0, building multi-stage
projects of various sizes. See history.txt. PRECCX is not certified for
anything else but only because I do not have direct access to anything
else. Reports say it seems to work on almost any system with ANSI C,
modulo the occasional renaming of include files.

          --------------------------------

INSTRUCTIONS: If you are using UNIX, unpack the source code and makefiles
(see the PACKING.LST), run `make', then read the preccx.1 manual in the
usual way. That means, either `nroff -man preccx.1 |more' or put preccx.1
in one of your manual directories (/usr/local/man/manl) and `man preccx'.

If you are using DOS then place all the distribution files in one directory
and run INSTALL.EXE. Further instructions for DOS follow.

 -- Peter T. Breuer

------------------------------------------------------------------------
    This is the PRECCX distribution for DOS. Version 2.42.
------------------------------------------------------------------------

PRECCX is an infinite-lookahead compiler compiler for context dependent
grammars.

To install, copy ALL the files in this directory or archive to a diskette
or DOS directory and then run INSTALL.EXE. The install instructions are
viewable in the install.001 file.

The choices you make in the install routines cause various target
directories to be built and some of the .ZIP archives to be copied
across and `unzipped' to them. If you don't believe me, use a virus
checker, or do the unpacking yourself. PRECCX is packaged using
Info-ZIP's compression utility and the installation program uses UnZip
to read the archives. Info-ZIP's software (Zip, UnZip and related
utilities) is free and can be obtained ubiquitously as source code or
executables at anonymous-ftp sites, including ftp.uu.net in directory
/pub/archiving/zip, and src.doc.ic.ac.uk in directory
/computing/systems/msdos/simtel/zip (for example). 


The list of archived files is in PACKING.LST. This is the pattern:

README      = this file                 -> HOME    directory
INDEX       = this list                 -> HOME    directory
PACKING.LST = a more detailed list      -> HOME    directory

preccxx.zip = executables               -> BIN     directory
preccxl.zip = compiled libraries        -> LIB     directory
preccxd.zip = manuals                   -> MAN     directory
preccxi.zip = C header files            -> INCLUDE directory
preccxe.zip = examples                  -> EXAMPLE directory
preccxn.zip = life cycle documentation  -> DOC     directory
preccxs.zip = source code and makefiles -> SRC     directory

If automatic installation does not work, read INSTALL.INS.  In fact, you
ought to read it anyway to see exactly what should have been installed.

After installation, you should run  README.EXE in the manuals directory.
Then look at the example scripts & check that they compile.  See RUN.INS
in the the root directory for some very direct advice.

------------------------------------------------------------------------
Peter T. Breuer   <ptb@eng.cam.ac.uk,ptb@comlab.ox.ac.uk,ptb@dit.upm.es>

