open-watcom/open-watcom-v2 — pull request #41 by ArmstrongJ (2014-02-26 14:39:14+00:00)
Title: Support for Free Pascal's CHM Help Compiler

This pull request adds the ability to use the Free Pascal project's **chmcmd**, a command-line help compiler that can produce CHM (Windows Compressed/Compiled HTML Help) files without any Microsoft tooling. The major advantage of using Free Pascal's help compiler is that the tool is available natively on non-Microsoft operating systems, notably GNU/Linux, but also Windows, OS/2, and a host of others. It is the only open-source implementation of a CHM compiler.

The Free Pascal compiler is a bit fussy about help project files, more so than Microsoft's compiler. I've made some minor changes to how the .hhp files are generated that should not affect the Microsoft compiler. These changes are:

* Removed the "[WINDOWS]" section as the defaults generated by either compiler should be sufficient
* Moved alias definitions into the .hhp file, which makes it bigger but doesn't effect functionality
* Removed any references to .chi files as these are only used when docs are meant to [exist on CD-ROMS](http://msdn.microsoft.com/en-us/library/aa975617%28v=vs.71%29.aspx) rather than being installed to the hard disk.
* The "Index_of_Topics" sections are compiled into the help files *but never referenced in the table of contents* simply because the Free Pascal help compiler complains about an unused reference to it in the project files' [MAP] sections.

There is a new variable in setvars.sh called *OWCHMCMD* that specifies the location of the compiler. It remains commented by default, similar to *OWHHC*.

If you wish to try this new method on Linux, you can install the Free Pascal compiler to give these changes a shot. Specifically, if you are on a Debian-based distro, you'll need the *"fp-utils"* package, which provides *chmcmd*.

These changes are not strictly necessary, but they do simplify building Open Watcom docs on Linux (and other non-Windows operating systems).