[README FILE - START]

Copyright (C) 2002-2003 Idan Nof

0. Contents of this file:

	1. Quick Summary
	2. License
	3. Supported platforms
	4. How to compile
	5. Files in this package
	6. Program description
	7. Technical issues
	8. Notes
	9. Acknowledgments
	10. Plans for future versions
	11. Release history

1. Quick Summary

	Name    : huff - Huffman Compression
	Version : 0.01a (English)
	Author  : Idan Nof [idannof@hotmail.com]
	Homepage: http://www.geocities.com/idannof/    (case sensitive)
	Excerpt : this program will compress (and decompress)
                  binary files using Huffman's algorithm.

	Usage   : use 'huff -?' and 'chopmerg -?' to see available 
        	  command-line arguments

2. License 

	Copyright (C) 2002-2003 Idan Nof
	(See attached file "GPL.TXT" and/or visit "www.gnu.org" )

	This program is free software; you can redistribute it and/or
	modify it under the terms of the GNU General Public License
	as published by the Free Software Foundation; either version 2
	of the License, or (at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program; if not, write to the Free Software
	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
	"This program is free software; you can redistribute it and/or
	modify it under the terms of the GNU General Public License
	as published by the Free Software Foundation.

3. Supported platforms

	You may go ahead and try to compile under any ANSI-C environment,
        but 'huff' was tested to compile and run under the following platforms-

	Borland-C 2.0/DOS ( manual project compilation )
	GCC 3.03/DOS      ( Makefile )
	GCC 2.96/RH-Linux ( ./makeunix which uses Makefile )
	GCC 2.7.2.3/Unix  ( ./makeunix which uses Makefile )

4. How to compile

	a) Instruction For GCC/DOS
	   - Build                                : use 'make all'
	   - Build project and run on sample input: use the batch 'go.bat'
	   - Build and run internal tests         : use the batch 'inttest.bat'
	   - Clean                                : use 'make clean'

	b) Instruction For GCC/Unix compatibles
	   - First, make 'chmod_script' executable using 
             'chmod +x ./chmod_script' then execute it.

	   - Build: use the script './makeunix all' which transfers 
             parameters to 'make'

	   - Build project and run on sample input: use the script './go'
	   - Build project, run on sample input and validate result: 
             use the script './test'

	   - Build and run internal tests   : use the script './internal_test'
	   - Clean                          : use 'make clean'

5. Files in this package

	go            Unix script to build and run project
	go.bat        an equivalent DOS batch 

	internal_test Unix script to build and run internal tests
	inttest.bat   an equivalent DOS batch

	Makefile      GCC compatible Makefile
	makeunix      Unix script to call 'make'

	readme.txt    this file
	filesize.txt  list of all files and their sizes, under DOS
	reference.zip holding of some bibliography and reference
	src.txt       a list of files in /src directory

	rm.bat        DOS helper batch
	test          Unix script to build, run and validate project
	test_expected expected results of 'test' script, under GCC 2.7.2.3/Unix

	/src          source code (see src.txt for a list of files)
	/doc          documentation [OOPS, I ripped that off]

6. Program description

	'huff' uses the classical Huffman Compression algorithm to compress
	individual binary files. It will also decompress files created by
	itself to their original content.

	The current implementation carries out compression using a minimum
	binary heap structure. Compression and decompression is sluggishly done
	bit-wise but with byte-wise memory buffers.

7. Technical issues

	a) In the cleaning process, we only delete *.exe in '/bin' so other 
	   garbage remains there and can be manually deleted.

	b) 'make' of GCC v2.7.2.3/Unix seems to not search for already-compiled
	   targets in the VPATH. This results in always recompiling the targets
	   in '/bin' directory. Note that only executables are put there.

	c) The archive file format which is used by the project is compiler/
	   platform-dependant, because of the 'int' field used in its header.
	   This means that archive files created across different compilers/
	   platforms are not compatible.

8. Notes

	-> Please report bugs/suggestions!
	-> The project still lacks thorough tests.

9. Acknowledgments

	A more complete bibliography and references may be found in
	'reference.zip' in the current directory. Nevertheless, here
        is a list of contributers:

	* Mark Allen Weiss [http://www.cs.fiu.edu/~weiss/] for the 
	  minimum binary heap and binary tree implementations

        * Karen Van Houten [http://www.cs.uidaho.edu/~karenv/] for the
	  useful description of the classical Huffman Code Algorithm

	* Shay Gueron [http://math.haifa.ac.il/~shay/shay01.htm] for making 
	  this project possible

	* D.J. Murdoch [http://www.murdoch-sutherland.com/] of which I took
	  the outline of this Readme file

10. Plans for future versions

	! Optimize compression and decompression by enhancing bufferio.c to
	  support dynamic, handles-based buffers.

11. Release history

	a) Project Started (2002-02-10)
	
	b) Version 0.01a, unreleased (2002-07-08)
	   * actually works

	c) Version 0.01b, first public release (2003-04-14)
	   * package structure and documentation altered
	   * code unchanged

[README FILE - END]
