TCR COMPRESSOR AND DECOMPRESSOR  v1.04

Here's C source and executable for creating and extracting TCR files.

TCR is a text compression format that's especially useful with Psion Series 3 
and Series 5 machines: there are text viewers for both which can display TCR-
compressed files directly (VReader or EBook for the 5, Reader for the 3).


    SOURCE  (Those funny-looking files ending in .c)

The source code is included here so you can compile it for other machines.  
It's written in C for the GCC compiler, and should be easily portable to 
other compilers.

See the comments in the code for details on the format and algorithms.

A TCR-encoded version of this file is included for you to practice on :)

    INSTALLATION

This program requires STDLIB.SIS and ESHELL.EXE to run on EPOC. Both are
supplied in the ZIP. For EPOC put the TCR.EXE into \SYSTEM\PROGRAMS\
The Linux and Win32 versions do not require any other files.



    USAGE  (What do I with them?)

The program has a simple text interface, for versatility and portability.

The program takes one or more filenames on the command line, and (de)compresses 
those files, creating appropriately named ones with a different 
filename extension - .tcr for compressed files, .txt for uncompressed ones.

To decompress a TCR to text file use the -d option.

Filenames must be supplied using the / notation, not \. If you do not specify
a directory then the files will go in the same location as the Executable, 
i.e. \SYSTEM\PROGRAMS\


    VERSION  (What's this version number thingy about?)

v1.00
  First release.

v1.01
  Fixed two rare bugs in the compressor.
  Decompressor now handles zero codes properly.

v1.02
  Various improvements.  The compressor is now slightly faster; the 
  decompressor is about four times as fast.

v1.03
  Fixed another rare bug in the compressor.  (Perhaps they're not so rare 
  after all?)

v1.04
  Merged TCR and unTCR into one program, use -d to decompress.
  Ported to EPOC.
  Changes by Simon Quinn


    HISTORY  (Where's this `TCR' format from anyway?)

Ian Young originally designed a format called ZVR for a Psion text file 
viewer - see http://ww.rats.demon.co.uk/zvr/, where there's also a program 
called ZVRZ for the de/compression (including source).  Unlike most 
compression formats, which need to be decompressed right from the beginning 
each time, with ZVR you can restart anywhere, which is obviously much better 
for a text viewer.  Compression is still quite good though - average saving 
is about 50%, as compared with (very roughly) 65% for ZIP, although for 
highly repetitive files, compression rates of over 80% aren't unheard-of.

When Barry Childress (73510.1420@compuserve.com) came to write a text file 
viewer for the Psion Series 3, Reader3 (available on 
http://3lib.ukonline.co.uk), he adapted the ZVR format slightly to make TCR 
(Text Compression for Reader). He also included a compression program called 
TCReader - this is very much faster than Ian's ZVRZ, but only runs on a PC.

The format has become quite popular in the Psion world, so that when Jean-Luc 
Damnet (jldamnet@pca.fr) wrote his VReader5 viewer for the Series 5, he also 
included TCR support.  (Currently at http://ady.net/psion/files/vr201.zip)

Meanwhile, although you could use TCR files on a Psion, you needed a PC to 
create them, which was very awkward me as I've an Atari instead.  Barry 
Childress wasn't keen on letting me have his source code, so in desperation I 
decided to write my own!  (And don't I wish I hadn't :)  Although this 
version uses some ideas from Ian's original ZVRZ, and some from interesting 
discussions with pmaud@cix.co.uk, it's all my own work, and (in my very 
biased opinion) is better than previous ones :)  So, with thanks to Ian and 
Peter, and apologies to Barry, here's a version you can compile for your 
machine.

    RESTRICTIONS  (What can I do with this?)

The code and executables are freeware - use and share them freely.  I 
_encourage_ you to compile versions for your own machine, read them for 
ideas, let me know of any bugs or improvements, etc.  However: you're not 
allowed to make any money from them (except for reasonable distribution 
costs, etc.), and if you do use my source code you must credit me and let me  
know!  Reasonable?  (Monetary appreciation would be nice, too :)


    CONTACT  (Who do I send money to?)

Questions, comments, bugs, ideas, etc. to:

        Andrew Giddings

        gidds@cix.co.uk

        1 Pavilion Close
        Southend-on-Sea
        Essex  SS2 4TZ
        UK


    GRATUITOUS GREETINGS

Thanks to Ian Young, Barry Childress and Jean-Luc Damnet for their programs.

Thanks and Hi to Peter Maud for explaining ZVRZ to me, Steve Litchfield for 
putting this on 3-Lib, and Stephan Hradek for testing and ideas.


        Andrew Giddings  16/Feb/2000.

Additional editing of this README by Simon Quinn.
