Tools for analysing and converting software for Colour Emu              31.5.97
*******************************************************************************
by Burkhard Lehner (b_lehner@informatik.uni-kl.de)
and Stephan Scholz (stscholz@informatik.uni-kl.de)
Colour Emulator Homepage http://www.student.uni-kl.de/~sscholz/ColourGenie.html

This is a software package for reading and analysing Colour Genie tapes.
Moreover we integrated a tool for attaching comments to virtual tapes and
snapshot files of Colour Emu.

Don't worry ! You haven't missed version 2.0 ! :-)
We just thought, since these tools are closely related to Colour Emu, we would
match the version numbers of the tools to the version of the emulator. All of
the tools have been extended to support the new features of Colour Emu 3.0,
namely comments for the virtual tapes and snapshot files. CASSSAVE allows a
direct access of the Sound Blaster, so there is no need to use VOC files for
this tool anymore !

This package consists of the four following tools:

CASSLOAD.EXE converts a VOC-File to a CAS-File (virtual tape) for the Colour
             Genie Emulator.
CASSSAVE.EXE converts a CAS-File to a VOC-File for using with the original 
             machine, or sends it directly to the Sound Blaster.
ANALYSE.EXE  analyses a CAS-File and checks for errors.
COMMENT.EXE  attaches a text file to a virtual tape or snapshot file

Since we want to improve the emulator more and more, we need a lot of software
for testing it. Please send us your CAS-files via email, it will help a lot !

CASSLOAD 3.0
************
Syntax:  CASSLOAD vocfile[.VOC] [cassfile[.CAS]]
Example: CASSLOAD chopper
         CASSLOAD meteor.voc meteor.cas

CASSLOAD converts a VOC-File to a CAS-File. The VOC file should include exactly
one Colour Genie program. It needs to be sampled at 10989 Hz, 8-bit mono 
(uncompressed). You can use any sampling tool for it, for example Cool95 or
Goldwave (both are shareware programs). You should use the .CAS-extension in
order not to get too much confused with your files. This is also the default
extension. You can load the analysed program directly into the emulator, or
you can check it first using the ANALYSE tool.

CASSSAVE 3.0
************
Syntax:  CASSSAVE cassfile[.CAS] [vocfile[.VOC]]
      or CASSSAVE -sb cassfile[.CAS]
Example: CASSSAVE africa.cas
         CASSSAVE kong.cas kong.voc
         CASSSAVE -sb meteor

CASSSAVE converts a CAS-File to a VOC-File. You can use the VOC file to load
the program into the original Colour Genie. This tool is meant for
verifying programs on the emulator with the original machine.
Use the option -sb to avoid those large and uncomfortable VOC files. This way
the sound is sent directly to the Sound Blaster. You can even see how much
(in per cent) of the program is already transferred. We hope to have this
feature for the CASSLOAD tool as well very soon.

ANALYSE 3.0
***********
Syntax:  ANALYSE [-d] cassfile[.CAS]
Example: ANALYSE chopper
         ANALYSE *
         ANALYSE -d meteor.cas

You may use wild cards !
With this tool, you can analyse a virtual tape. It is checked whether the 
CAS-File contains a COLOUR BASIC or a machine code (SYSTEM) program. For BASIC
programs, the line pointers are checked, and a warning is printed if there is a
possible error. For the machine code programs, the checksums are checked and a 
warning is printed if there is an error.
If you use the -d option, more (detailed) information is given, for example the
code of the analysed program.

COMMENT 3.0
***********
Syntax:  COMMENT cassfile[.CAS] [textfile[.TXT]]
         COMMENT snapfile[.SNP] [textfile[.TXT]]
Example: COMMENT kong32
         COMMENT death.snp death.txt

With this tool, you can attach any text file to a virtual tape or a snapshot
file. The main reason for doing this is that DOS file names are very short,
and often you can't tell from this file name which program is actually
represented by it. Moreover you can put hints for games or information on how
this special program is used in the CAS/SNP file this way. We suggest that
you use the following format, which is also stored in the file COMMENT.TXT
which you can find in the package:

Name       : (Name of program)
Author     : (Author)
Copyright  : (Company, year of release)
Description: (Short explanation of program. Maybe a more detailed description
              afterwards)

The easiest way to create a comment for a file is to edit it with a normal
text editor, save it with the name of the CAS/SNP file using the TXT extension,
and enter COMMENT <filename> afterwards. The advantages for doing this are that
you don't get confused with the different names, and there is less to type :-).
Example: If you want to attach a comment to Colour Kong (32K version, we
expect that you saved it with the name KONG32.CAS ), you create the comment file
KONG32.TXT. Then you enter COMMENT KONG32 and the tool automatically uses the
right text file KONG32.TXT ! We did this with a little help from Windows95: we
linked the CAS file extension to the COMMENT tool, and by just double clicking
on the icon the comment was attached - nice & easy ! By the way, if you are not
too familiar with Windows95, you can change the links for the file extensions
by selecting a file, and using SHIFT together with the right mouse button to
get the menu item "Open with...". Simply select the desired program (maybe
you'll have to browse for it) and put a mark in the check box "always open with
this program".
A simple way of reading the comment in a CAS/SNP file without starting the
emulator is by using a good text editor or the TYPE command for MS-DOS; for
example TYPE KONG32.CAS. Editing this comment directly with an editor should
not work however. Please use the COMMENT tool for it. To extract the comment
from a CAS/SNP file to a text file, you can also use MS-DOS; for example
TYPE KONG32.CAS > KONG32.TXT
You can then edit this text again with a regular editor (delete the first line
of the text, since it would be added for a second time by the COMMENT tool).
