chmspec -- documentation on the CHM format and associated technologies.
Copyright (C) 2002,2003:
  Paul Wise aka Pabs, <pabs@zip.to>
  Jed Wing, <jedwin@ugcs.caltech.edu>

This is free documentation; you can redistribute it and/or modify it under
the terms of the GNU "Free" Documentation License as published by the Free
Software Foundation; either version 1.2 of the License, or (at your option)
any later version; with no Invariant Sections or Cover Texts.

This documentation 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.

You should have received a copy of the GNU Free Documentation License along
with this documentation; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA, 02111-1307, USA or visit:
http://www.gnu.org

Be aware that while chmspec does not use invariant sections and is thus free
documentation it will be relicenced soon because of the problems identified by
the Debian project in the so called GNU "Free" Documentation License.


About:

chmspec is a whole bunch of documentation on the CHM format and associated
technologies. It focuses mainly on the formats of internal files of CHMs.


Legalese:

I imagine these docs are illegal somewhere, for some reason, most probably in
the insane land of the American copyright and patent system. Meh


Other documentation:

There are no other public docs on the internal files of CHMs, except for a few
lines in the docs for FAR and I think KeyTools as well. The authoring formats
are poorly documented in Microsoft's HHW docs and inteface. Docs on the CHM
wrapper format were first publicly released by Matthew Russotto.


Dependencies:

You need Matthew Russotto's "Microsoft's HTML Help (.chm) format"
(http://www.speakeasy.org/~russotto/chm/chmformat.html) to have the full story
on the whole CHM format. You may also want to read the docs that come with
some proprietary programs such as FAR and KeyTools for background information.


Building, reading & application:

You may want to just get the HTML version if you are only interested in the
content and not contributing fixes or further information.

I've been using xsltproc & saxoncat on my Debian system, so if you want to
compile html or other versions on other platforms you will have to customize
the DTD path in chmspec.docbook and the path to the XSL stylesheets in the
files in xsl directory. My command lines were:

tar jxf chmspec-<version>-src.tar.bz2
cd chmspec-<version>
xsltproc -o chmspec.html xsl/html.xsl chmspec.docbook
or occasionally
saxoncat chmspec.docbook xsl/html.xsl -o chmspec.html
mozilla chmspec.html

You may want to download the following free software before implementing
anything in this specification: chmdeco, hhm, chmlib, chmtools, wine


Limitations:

Most of the problems are because I wanted to get this out after sitting on it
for way too many months and giving it to those who emailed me.

Basically there are lots of unknown bits in the CHM formats. Also I lost
formatting when I converted from HTML to DocBook. See the TODO file & the
FIXMEs in the spec itself for areas that need working on.


Questions:

Please ask away, as there is no FAQ yet.


Enjoy
Pabs <pabs@zip.to>
http://pabs.zip.to
