CommonLisp Win32 HTML Help solutions

Available are the [Harlequin] Common Lisp Hyperspec CLHS.chm (v3.0),
the [Digital Press] Common Lisp the Language 2nd Edition CLtL2.chm,
and the Corman Lisp CormanLisp.chm. (v1.3)

If you cannot run the chm files (compressed html), download hhupd.exe
(see below) and run it. This installs hhctrl.ocx which enables your IE
(at least 3.0) to act as help browser. Compressed HTML is superior to
ordinary HTML and Winhelp, because it is much smaller, loads faster, and
provides the same features as Winhelp and ordinary HTML.

CormanLisp.chm was compiled to be merged at run-time with CLHS.chm
when it is found in the same directory.
This means that you should copy CLHS.chm to the Corman Lisp
documentation directory. Then the "Index" Tab inside Corman Lisp
includes the complete CLHS Reference. The "Contents" Tab includes links
to both big CL files if they are in the same directory. If one of those
is not found, it tries to connect to the online websites, where these
documents usually reside.


Structural Decisions

Since a Winhelp or CHM supports additional structural elements, i.e.
extra Contents and Index lists, some decicions had been made to
accomplish the best possible way to present this information. (at the
left pane) CLHS and CLtL2 include in the Index the full alphabetical
master index, generated automatically from the appropriate index HTML
files. The CLHS Contents section is only one level deep, i.e. only the
top chapters 1-26, no subsections, and sorted according the start page.
The CLtL2 Contents section is also one level deep, but all chapters up
to the 2nd level are also included.

Technical Information

HTML help is slowly emerging but will be common at least when Office2000
will be available. It is the official replacement for Winhelp. I used
it for one year now (stdlib, opendwg) and people seem to be quite happy
with it. For these files used the latest version 1.21. The files are
hhctrl.ocx 1.1 compatible.

Typical compression rates are:
30%-80% the size of a Winhelp. This depends on the winhelp formatting.
  Winhelp is only compressed RTF and this can be bloated by useless
  formatting tags, if you know how Winword does store its formatting. My
  CHM files are larger because they already contain the FTS (fulltext
  search information).
10%-50% the size of uncompressed HTML. HTML using CSS (stylesheets)
  should be much better compressable, for example the complete book of
  "Inside OLE2" has only 2.5MB, using consistently css. These documents
  were not reformatted in anyway, it is the pure online available HTML
  text, generated by Latex2HTML, which didn't know CSS that times.

CLHS.chm:  3.5mb (with FTS)
CLHS HTML: 15mb  (with lots of now redundant indexes)
CLtL2.chm: 1.8mb (with FTS and binary TOC)
CLHS HTML: 5mb   (with lots of now redundant indexes)

Where to get it?

ftp://xarch.tu-graz.ac.at/pub/autocad/lisp/cl/hhupd.exe		(476kb)
ftp://xarch.tu-graz.ac.at/pub/autocad/lisp/cl/CLHS.chm		(3.5mb)
ftp://xarch.tu-graz.ac.at/pub/autocad/lisp/cl/CLHS-hhsrc.zip 	(19kb)
ftp://xarch.tu-graz.ac.at/pub/autocad/lisp/cl/CLtL2.chm  	(1.8mb)
ftp://xarch.tu-graz.ac.at/pub/autocad/lisp/cl/CLtL2-hhsrc.zip  	(19kb)
ftp://xarch.tu-graz.ac.at/pub/autocad/lisp/cl/README.txt
ftp://xarch.tu-graz.ac.at/pub/autocad/lsp_tools/clwinhelp.zip
                                                     (194kb) cormanlisp

hhupd.exe (a self-extracting installer) is the only redistributable file
from Microsoft. It includes the latest hhctrl.ocx and some more, hope
that hh.exe is there also included. If not
"mk:@MSITStore:CLHS.chm::/FrontMatter/index.html" inside IE should work
also, but is not that beautiful. The free HTML Workshop 1.21 is at
http://msdn.microsoft.com/workshop/author/htmlhelp/default.asp (4mb)

If you download the free HTML Workshop from Microsoft, you can decompile
any CHM and get the HTML sources back again. I didn't try that lately,
so I don't know exactly if the filenames will be garbled, but I don't
think so.
You can also convert any existing Winhelp to CHM automatically, but I
would recommend to improve the generated Index and TOC files and have a
deep look at the generated HTML files. They are often misformatted. It
only uses the WinWord RTF->HTML formatter, which is seriously damaged.
I wrote some perl scripts to repair most of it for the automatic stdlib
documentation efforts. (you might see the utils dir there)

---
I don't work for or am otherwise related in any way to the above
mentioned companies. I just needed it for personal use (not happy enough
with the Allegro Winhelp files, and the LWW v5.0 CLHS) and after having
read the disclaimers, realized that may I redistribute it to others as
well.
CormanLisp.chm and .hlp was updated to reflect the release 1.3 changes.

Autor: 	Reini Urban <rurban@x-ray.at>
Date:   26.05.99
URL:    http://xarch.tu-graz.ac.at/autocad/lisp/cl/ or
	ftp://xarch.tu-graz.ac.at/pub/autocad/lisp/cl/