*** C Adventure Toolkit (CAT) - Introduction

This file introduces the concepts behind the C Adventure Toolkit (CAT),
tells you how to install it, and explains how it should be used.

******************************************************************************

The CAT system is shipped on a 720K MS-DOS formatted disk, with both PC and ST 
versions included. The ST can use MS-DOS format disks with no problems, so 
the system is available to users of both families of machines.

The principle behind CAT is simple: You provide details of your adventure to 
CAT in a very high level language, which will be 'compiled' into C source 
code. Your generated C code can  then be compiled, along with standard CAT C
code, to produce your finished adventure! The code generated by CAT is
portable - I have tested in on Sozobon C; MWC; and LaserC on the ST, as well 
as TurboC on the PC.

The CAT system comprises of a generator program, standard definition
files, and standard C code to be compiled with your generated code.

   The generator program (GEN.TTP or GEN.EXE) lives in the \CAT folder.
   The standard definition files live in the \CAT\STD folder.
   The standard C code files live in the \CAT\GENSRC folder.

******************************************************************************

To use CAT, you will need the following:

    PC
    ==
    At least 512K memory.
    At least 720K floppy.
    A C compiler.
    A text editor that will write pure ASCII files.
    A vivid imagination
    A basic understanding of C is recommended.

    ST
    ==
    At least 512K memory.
    At least 720K floppy.
    A C compiler.
    A text editor that will write pure ASCII files.
    A vivid imagination
    A basic understanding of C is recommended.

    Note: Whilst CAT will run happily with 512K on an ST, you may find that 
          some memory intensive C compilers run out of memory when compiling
          the generated C code. 

          Sozobon C is memory intensive - source generated by CAT will
          probably be too big to be compiled by Sozobon C with just 512K.

          MWC is disk intensive - this means it can compile far bigger 
          programs, as all of its' work is done on disk, not in memory!

******************************************************************************

Installation:
=============

 1) Make a back up copy of the production disk!

 2) Copy the CAT folder, and all sub-folders to the root folder on your
    working drive. It is recommended that CAT is run from a Hard disk, but a
    floppy will be okay, as long as it is formatted to at least 720K.

 2) If you are running CAT on a PC, modify your AUTOEXEC.BAT file to 
    include \CAT in the PATH. Add this line to the end of the file...
    PATH %PATH%;\CAT

 3) If you are running CAT on a PC, make sure that at least 30 FILES are
    available. You should have a line like this in your CONFIG.SYS file...
    FILES=30

 4) If you are running CAT on an ST, and you are using a shell program 
    (i.e. Gulam; MSH etc), then set your PATH environment variable to 
    include \CAT - the command will be something like this for MSH...
       setenv PATH=$PATH,\CAT
    or this for GULAM...
       setenv PATH $PATH,\CAT
       rehash

 5) If you are running CAT from a PC, you can delete any .PRG and .TTP 
    files - these are for the ST version and you won't be needing them!

 6) If you are running CAT from an ST, you can delete all .EXE and .BAT 
    files - these are for the PC version and you won't be needing them!

 7) You are now ready to use CAT!
 
******************************************************************************

The main program (GEN.TTP on an ST, or GEN.EXE on a PC), processes your
adventure definition, and generates C code for your adventure program.

When GEN starts up, it looks in the current folder for a file called 
'GENLIST'. The GENLIST file should contain the names of each definition file
that is to be used to generate the adventure source. These definition files 
can have any names, but it would be advisable to use the standard extendor '.d'
e.g. - file1.d, file2.d file3.d. You can use any number of definition files
to create your adventure.

Each line in the GENLIST file can contain a simple file name, or a file 
with a pathname, and optionally a drive - so a typical GENLIST file may be:

   OBJECTS.D
   ROOMS.D
   MESSAGES.D
   LOGIC.D
   A:\MYSTDS.D
   \CAT\STD\ZZRQD.D 
   \CAT\STD\ZZSTD.D  
                        
The next thing GEN will do is look for a sub-folder from the current folder,
called CSOURCE. This is the destination folder for the generated C code. 

If all is okay, GEN will begin it's work. As it works, GEN will display any
potential errors it encounters on the screen, and these will also be written
to the file 'GENOUT.TXT'.

******************************************************************************

You will notice the two standard defintion files ZZRQD.D and ZZSTD.D are
included in the sample GENLIST file detailed above. These definition files are
supplied with CAT, and provide the vast majority of the processing you need.
You should use these files, or a version of them to create your adventure.

ZZRQD.D - contains all the required definitions. CAT refers to anything that
          is defined in this file internally. You can change this file, 
          but make sure all the names remain the same.

ZZSTD.D - contains standard logic for your adventures. The definitions in this
          file are not referred to internally by CAT, so you can change 
          anything contained in it.

******************************************************************************

The GEN program has the following command line options:

   -Spath   - use this to specify the source folder. This option is useful if
              you are using GEN via the GEM desktop on the ST. The option
              forces GEN to change directory to the selected folder - i.e.
              the folder where your GENLIST lives. The -S option does not
              allow a drive to be specified.

   -L       - This tells GEN to list the definition source as it processes it.

   -V       - This tells GEN to give a verbose list of all possible errors 
              it discovers. By default, GEN only reports the more rare and
              possibly hazardous errors.

   -E       - This tells GEN to encrypt the code it produces, safe from 
              prying eyes. You should always use this option when producing
              a finished copy of your adventure.

   -C       - This tells GEN to compress the text in your adventure.
              WARNING: compressing adventures with small amounts of text may
                       result in LARGER programs being generated. Compression
                       will be most successful in games with a lot of text.

   -I       - This tells GEN to print the names of all the items that are
              defined. By default, GEN only reports those items that are
              defined but are not directly referred to.
   
   -F       - This tells GEN to do full logic checks. i.e. it makes sure that
              low priority logic is only used in low priority logic, that 
              logic tests are not used in commands, that logic tokens are
              recognised tokens, etc. This switch is additional to -V.
   
   -R       - Perform a report only run. Do not write any files. This is 
	      FAST, and allows you to easily check the syntax of your source.

   -Dpath   - Specify the destination path (override default of CSOURCE).
              This can include a drivespec. The path should be direct i.e.
              -DF:\output or relative to the folder to where the GENLIST file
              lives i.e. -Dtest\output. This option is useful if you want to
              direct the output to a ramdrive - much faster!

   -Apath   - Autocopy GENSRC files to destination folder. By default, the 
              GENSRC files will be copied from \CAT\GENSRC, but you can 
              optionally specify the folder where GEN can find GENSRC files.
              The folder can include a drivespec.
 
GEN -E -I -F
   would look for a GENLIST in the current folder, encrypt all output, and
   produce a list of all the items that were defined. Full logic checking will
   be performed.

GEN -S\ADVENT -V -L
   would look for a GENLIST in the folder \ADVENT. It would list the definition
   files as it processed them, and give a verbose list of ALL errors. It would
   not encrypt the generated C source. Only those items that are defined but
   not directly referred to will be listed. Full logic checking will not be 
   performed.
 
GEN -R
   would look for a GENLIST in the current folder, and perform a report run.

GEN -A -E
   would look for a GENLIST in the current folder, encrypt all output and
   automatically copy the GENSRC files from \CAT\GENSRC.

GEN -AA:\CAT\GENSRC -S\AWE -Df:\ 
   would look for a GENLIST in \AWE. Output would be created in F:\ - GENSRC
   files would be automatically copied to F:\ from A:\CAT\GENSRC.

******************************************************************************

GEN switches can now be specified in your GENLIST file. Any switches 
included in the GENLIST file will override conflicting switches from the
command line.

     For example, the following GENLIST will automatically copy GENSRC from
     \CAT\GENSRC, and output will be encrypted.

     -e
     -a 
     \cattutr5\first.d
     \cattutr1\tutor1.d
     \cattutr2\tutor2.d
     \cattutr3\tutor3.d
     \cattutr4\tutor4.d
     \cattutr5\tutor5.d
     \cat\std\zzstd.d
     \cat\std\zzrqd.d
     \cattutr5\last.d

******************************************************************************

Once your C source has been generated, if you didn't use the -Autocopy option,
then you will need to copy all the files from the \CAT\GENSRC folder into your
destination folder (CSOURCE by default). After this, you can compile your
adventure with your favourite C compiler.

If you are compiling on a PC, you must define PC, and use the large model i.e.
  
   TCC *.c -DPC -ml

FAILING TO DEFINE PC WHEN COMPILING A PC ADVENTURE WILL RESULT IN FAILURE!

******************************************************************************

Two batch files have been supplied, with PC and ST versions of each:

The first batch file (GEN1) generates encrypted C code in CSOURCE, and copies
all the standard C files from \CAT\GENSRC into CSOURCE.

The second batch file (GEN2) compiles the C source in CSOURCE, and produces
the runnable adventure program 'ADVENT' in the current folder.

******************************************************************************

ST version of GEN1 - suitable for MSH (and possibly Gulam?)

GEN1
----
gen -e -a

******************************************************************************

ST version of GEN2 - suitable for MSH (and possibly Gulam?)

GEN2
----
cd csource
cc *.c -o advent.prg
mv advent.prg ..
cd ..

******************************************************************************

PC version of GEN1 - suitable for Turboc

GEN1.BAT
--------
gen -e -a

******************************************************************************

PC version of GEN2 - suitable for Turboc

(In my case the TurboC libraries live in D:\PC\TURBOC
                TurboC header files live in D:\PC\TURBOC\INCLUDE)

GEN2.BAT
--------
@cd csource
tcc -Ld:\pc\turboc -Id:\pc\turboc\include -ml -DPC -eADVENT.EXE *.c
@copy advent.exe ..
@cd ..

******************************************************************************
