+-------------------------------------------------+
| SCRUNCH Utility for Compressing OPL Source Code |
+-------------------------------------------------+

Contents:       1. Files in this package
                2. What is SCRUNCH ?
                3. How to use SCRUNCH
                4. How SCRUNCH works
                5. BEFORE.OPL and AFTER.OPL
                6. Contact Information/Disclaimer

+--------------------------+
| 1. Files in this package |
+--------------------------+

   (a)  Files I produced:

        SCRUNCH.TXT     -       this documentation file
        SCRUNCH.BAT     -       batch file to compress OPL files
        FIXUPALL.BAT    -       example file to compress an entire project
        SCRUNCH.SED     -       the SED script to do the "compression"

        BEFORE.OPL      -       sample file to be processed by SCRUNCH
        AFTER.OPL       -       the result of running SCRUNCH on BEFORE.OPL

   (b)  "Freeware" Utility I used:

        SED.EXE         -       the SED program that actually does the work
        SED15X.ZIP      -       archive with SED.EXE and its documentation

        (Not actually described as freeware but the archive contains the
        following text: "You, Dear Reader, may do *anything* you wish with it
        [SED] except steal it. Copyright (c) 1991 Eric S. Raymond, David
        P Kirschbaum & Howard L. Helman")

+----------------------+
| 2. What is SCRUNCH ? |
+----------------------+

When I write OPL programs, I usually use my PC so that I have access to a
wide range of utilities, including a "proper" editor, before transferring
the programs to the Organiser to be translated. As storage space is not a
problem on the PC, I like to put the documentation for my OPL programs inside
the programs by including lots of comments (this makes it easy to keep the
documentation up to date).

Although this scheme makes it easy to keep my OPL programs well documented,
it runs into problems because of the Psion Organiser's limited amount of RAM.
So I produced a SED script and a couple of simple batch files to form the
SCRUNCH utility to "compress" my OPL programs on the PC before sending them
to my Psion Organiser.

+-----------------------+
| 3. How to use SCRUNCH |
+-----------------------+

The SCRUNCH batch file takes a list of OPL file names on the command-line and
converts them one by one.  If a project involves several OPL files, I use
another batch file, e.g. FIXUPALL, to process the entire project.

The version of SCRUNCH.BAT supplied converts the specified OPL source files
and stores the "compressed" versions in a subdirectory called SCRUNCH.  If
this directory does not exist, the batch file will attempt to create it.

Examples:

        scrunch game.opl grafix%.opl

        (converts "game.opl" and "grafix%.opl" in the current directory and
        stores the results in scrunch\game.opl and scrunch\grafix%.opl)

        fixupall

        (does same as the "scrunch game.opl grafix%.opl" command)

+----------------------+
| 4. How SCRUNCH works |
+----------------------+

SCRUNCH uses a simple SED script which does the following:

(1)     Removes a comment block which starts with a line beginning
        in column 1 with the text

                REM (Start of header)

        and ends with a line beginning in column 1 with the text

                REM (End of header)

(2)     Removes all blank lines

(3)     Removes all lines which only contain "REM"

(4)     Removes all leading white space (space and tabs) from lines

(5)     Removes all trailing REM comments (i.e. comments which appear on the
        same line as OPL source, e.g. IF A=B :REM This comment gets deleted)

(6)     Changes tabs into spaces

NB:     SCRUNCH treats comments which start in column 1 as "significant"
        and will NOT remove them (apart from the exceptions noted in items
        (1) and (3) above).

+-----------------------------+
| 5. BEFORE.OPL and AFTER.OPL |
+-----------------------------+

The two sample files, BEFORE.OPL and AFTER.OPL, demonstrate how
effective SCRUNCH can be. The BEFORE.OPL file has lots of comments and
uses indentation, while AFTER.OPL has only two comments and no indentation.

Running SCRUNCH on BEFORE.OPL, using the command "scrunch before.opl",
produces a much smaller file (392 bytes instead of 1,660 bytes).

Note that the "Revision" and "End of file" comments in BEFORE.OPL, were not
deleted by SCRUNCH because they start in column 1 and are treated as
"significant" or "important" comments.

[The output file was renamed as AFTER.OPL so it can exist in the same
directory as the un-scrunched BEFORE.OPL file, to keep this archive simple].

+-----------------------------------+
| 6. Contact Information/Disclaimer |
+-----------------------------------+

No responsibility is accepted for any damage due to the use of the SCRUNCH
utility. This software is provided without warranty of any kind. Especially,
I may not be held liable for any data loss that may result if you modify any
components in the package.

I have found SCRUNCH to be a useful utility and hope it can help you.  If
you have any comments or suggestions for improvements (or even corrections!)
regarding SCRUNCH, please let me know.

Brian Smith, 18-May-98

email: bds@sugelan.co.uk

(end of file)
