CHMLIB 0.3
==========

-------
SUMMARY
-------
chmlib is a small library designed for accessing MS ITSS files.  The ITSS file
format is used for Microsoft Html Help files (.chm), which have been the
predominant medium for software documentation from Microsoft during the past
several years, having superceded the previously used .hlp file format.

Note that this is NOT the same as the OLE structured storage file format used
by MS Excel, Word, and so on.  Instead, it is a different file format which
fulfills a similar purpose.  Both file formats may be accessed via instances
of the IStorage COM interface, which is essentially an "acts like a
filesystem" interface.

-------
FILE FORMAT SUPPORT
-------

Lookup of files in the archive is supported, and should be relatively quick.
Reading of files in the archive is also supported.
Writing is not supported, but may be added in the future.

In terms of support for the ITSS file format, there are a few places in which
the support provided by this library is not fully general:

1. ITSS files whose names contain UTF-8 characters which are not part of the
   ASCII subset will not currently be dealt with gracefully.

2. Only version 3 ITSS files are supported at present, though some work has
   gone towards divining the differences between different versions of the
   file format.

3. Archives larger than 4 GB should be supported just fine, but if they
   contain files larger than 4GB, this library may break.  Fortunately, this
   seems somewhat unlikely.

If you run into .chm files (or files you suspect are ITSS files) that this
library doesn't work with, please contact me so I can fix the library.

-------
PORTABILITY
-------

This software was originally developed on a Intel x86 Debian Linux machine,
using gcc 3.0.  It has since been compiled on various flavors of RedHat as
well, and using versions of gcc from 2.95 through 3.2.  Basic Win32 support
should be in this release.  (While a port to Win32 may _seem_ like a funny
idea, given that Windows ships with libraries for CHM access, it turns out that
Win CE does not; I've gotten a request for a port to Windows CE.)

Finally, Andrew Hodgetts has ported to Solaris and IRIX:

On Monday, 7 Oct 2002, Andrew Hodgetts wrote:
> Solaris(Sun):
> 
> I used both SunProC and GCC on the solaris machines to compile. They
> both worked ok.
> However, both required -lsocket on the link line of the Makefile or you
> recieve linking errors.
> 
> I have this working on CPUs ranging from Sun4m (Sparc5) through to
> UltraSparcIII (SunFireV880).
> 
> Irix (SGI):
> 
> I only testing with the MIPS compiler (not GCC). All worked ok - lots of
> warning messages, but it always does that.

He further noted that:

> ... for NON GCC compilers, a little tweaking may be required, but nothing too
> complex.  ie SunProC doesn't understand -fPIC for library building.  Irix
> required -n32 (new 32bit libraries) etc.  These are things that someone who
> uses the OS and compiler should be used to dealing with.

-------
CREDITS
-------

* Thanks to Stuart Caie for developing the LZX decompression code, and for
  granting permission to re-license under the LGPL.

* Thanks to Stan Tobias for bugfixes and the added 'index page' feature of
  chm_http.

* Thanks to Andrew Hodgetts for porting to Solaris and IRIX, as well as fixing
  some little-endian biases in the code.