chm

From Free Pascal wiki
Revision as of 14:37, 18 June 2010 by Marcov (talk | contribs)
Jump to navigationJump to search

Package CHM is a set of units distributed with FPC 2.2.2 and newer that allow to read/write .chm compressed html help files on multiple platforms. The package is still continued, and already 2.5.1 contains stuff that didn't make 2.4.0 (2.4.0 roughly is the compiler of early august 2009 with the RTL/Libraries of oct 1st, 2009)

There are two projects that use the CHM package, the textmode IDE ( 2.2.4 and up), and the Lazarus chmhelp package (which features a separate helpsystem, connected over TCPIP). The original author is Andrew Haines, but some parts are by others (specially Lars/z505).

The write aspect is mostly used in combination with fpdoc, an doxygen like documentation tool, but contrary to that of the strictly out-of-source kind.

It is expected that in the next FPC release, chm will replace the doc-html archive with its thousands of separate htmls.

The package is pure pascal, and thus portable in principle (and seems to have had endianess fixes). 64-bit status not known yet.

The package also packages two examples, chmls and chmcmd (see below)

Package status

The basic system works since 2.2.4 and was refined with 2.4.0. However keep in mind that the FPC helpsystems, while massive (30000+ webpages in the various chms) are generated, compiled and read mostly by FPC tools. (and an occasional test in Windows/gnochm/kchmviewer to see if it opens properly).

If you want to use FPC's chm package/compiler for own projects, take the follow advise under consideration:

  • For now, use trunk. If only for the CHM generating parts. There has been quite some post 2.4.0 action
  • Don't expect it to work right away.
  • Keep in mind what is implemented and what is not (see below)
  • report bugs in the FPC tracker with a reproducable description.
    • and if you are in an hurry with patch :_)

Units

  1. chmbase - some structures, constants and helper funcs (compare and compression streaming helpers)
  2. chmfiftimain - the unit that is responsible for reading and writing the search index of chms (TChmSearchReader, TChmSearchWriter)
  3. chmfilewriter - TChmProject, a class that describes a CHM project in the form of a XML description. Can be used to generate CHMs easily.
  4. chmreader - the base CHM Reader
  5. chmsitemap - Support for sitemaps (toc and index, the unit helps transforming these xml files to collections)
  6. chmspecialfiles - Streaming helpers for special index files in the chm
  7. chmtypes - CHM helper class types.
  8. chmwriter - the base CHM Writer.
  9. fasthtmlparser - Base skeleton of a html parser.
  10. htmlindexer - Contains classes that TChmWriter uses to parse and index the contents of html files for searching
  11. htmlutil - helperfunctions. Mostly getting info out of html/xml tags.
  12. lzxcompressthread - wrapper around paslzxcomp that will do compression in multiple threads
  13. paslznonslide - (de)compression routines
  14. paslzxcomp - (de)compression routines
  15. paslzx - (de)compression routines

Files

Besides the library units, there are also two endprograms:

  • chmls - lists contents of a chm
  • chmcmd - creates a CHM using a XML file made with the TCHMProject class. Roughly equivalent to a simple help compiler.
  • unblockchm - unlock downloaded CHMs on Vista/w7 with wildcards. (2.4.2+)

chmcmd is, like the library itself, more a backend tool than an userfriendly tool. It is unforgiving if your files are inconsistent (will throw exceptions on missing files), and does not support goodies like autoindexing. It is probably only a substitute for backend jobs where you assure the input is consistent.

Missing features

  • merged chm support
    • Combining of indexes of multiple chm files. (.CHW/.CHI?)
    • slave file support ? (making slave CHMs, and getting them out, will make for easy master/toc CHMs later)
  • Writing of binary indexes is multiple level, loading not. (???)
  • Expand TCHMProject to support
    • aliases. 2.4.2+ (via .hhp in 2.4.4+)
    • control over textual/binary toc generation, textual/binary index generation etc from the XML/project (2.4.2+)
    • also support .ini (MS helpcompiler compat?) (2.4.4+)
    • lcid/language (?)
    • Window list (in progress, probably 2.4.4+)
  • Alinks
  • auto index/toc(?) generation
  • (popup) comments
  • samples (fpdoc?) Make samples extractable, MSDN style.

Implemented features

  • Full text search
  • Binary Table of contents
  • Binary Index (experimental)
  • Experimental threaded LZX Compression
  • context ids.
  • threaded compilation (requires recompile, see below)

disable binary toc/index generation

Generating binary forms can be disabled in fpdoc resp with --no-bintoc and --no-indextoc.

Note that these options were not added to save space, but to be able to temporarily not generate them if some viewer has a problem with them, and refuses to fall back to default.

One can notice that kchmviewer loads chms with binary index and toc significantly faster.

How to enable threaded LZX Compression

If you want to test multithreaded chm compression add -dLZX_USETHREADS when compiling the package (or the whole snapshot).

The program using the package (fpdoc must have cthreads added in it's uses section on *nix.

On my Core2 1.73GHz laptop this reduced time from 2min 57s to 2m 7s, iow a reduction by slightly less that a third.

It is unknown how to configure the number of paralel threads.

See also

Go to back Packages List