Author: Bruce Byfield
Today, HAT tools focus mainly on Microsoft Compressed HTML Help, also known as HTML Help or, among GNU/Linux developers, as CHM. HTML Help replaces the former WinHelp format, which is still supported by all versions of Windows, but has started to fall out of favor.
HTML Help is a proprietary format. It consists of individual HTML files compiled into a single database-like file with a .chm extension. The compiled files also support tables of content and keyword searches. Windows’ support for the format includes a compiler (hhc) and a viewer (hh) that also doubles as a compiler that breaks down a .chm file into its component HTML files. In addition to online help, the format is also used for some ebooks, presumably on the assumption that the format can be readily viewed by anyone.
Plans for a revised version of HTML Help appear to have been abandoned in favor of a new XML-based format for Vista, the next version of Windows. For now, HTML Help remains the most widely used format for help systems on Windows.
FOSS HTML Help utilities
A search through SourceForge and the Internet shows three major categories of Windows Help utilities are well-represented in free software. Viewers such as kchmviewer and GnoCHM are intended largely for viewing .chm ebooks or occasional APIs published as a .chm file. Other utilities, such as arCHMage, combine viewers with decompilers, allowing users to edit the contents of .chm files.
Another group of tools extracts comments from source code and converts the result into .chm files. Most of these tools are specific to a programming language. They include .Net tools such as NDoc, Java tools such as Javadoc2Help, and Delphi tools such as Opus Documentor and DelphiDoc-JADD. All these tools produce useful results only when the source code is heavily commented. They also assume a workflow in which writers can edit source code and help files are not an afterthought. Such assumptions are relatively rare in software companies, so the usefulness of these tools is probably limited.
The limits of cross-platform solutions
Numerous projects for cross-platform or GNU/Linux-based tools for producing .chm files have been announced, but most of them are in the planning stage, and have released little or no code. The only two that seem polished enough to use are AurigaDoc and DocBook, two XML-based solutions that are well-known in other contexts.
Unfortunately, neither seems ready for widespread use. AurigaDoc is distributed as source code, and requires compiling with Apache Ant, a process that its documentation assumes that users are already familiar with. DocBook is better known, but the number of available elements and the lack of a FOSS graphical editor for it makes it intimidating for typical technical writers whose focus is on the writing aspect of their job rather than the technical. Both also require an understanding of Extensive Stylesheet Language Transformations (XSLT). In addition, DocBook may require some manual editing of files if problems arise.
If you can overcome these obstacles, you can produce basic .chm files with both applications. However, neither supports keyword searches, nor are they set up for project management of multiple files, a feature that is one of the main attractions of proprietary HTML Help products for the average user.
A Windows-based FOSS solution
Windows-based shareware for creating .chm files, such as Angel Writer and GridinSoft Notepad, is relatively common, but beyond the scope of this article. The only FOSS .chm generator that is anywhere near ready for prime time is HelpMaker.
Unlike AurigaDoc or DocBook, HelpMaker offers the graphical interface that Windows users expect. If the editing window looks crude compared to RoboHelps, it is at least familiar to its target audience. More to the point, HelpMaker includes functions such as a search and replace function for Unicode — which HTML Help doesn’t support — and dialogs for assigning Topic IDs and keywords to additional pages. Like RoboHelp, it also manages files destined for the same .chm file in a project tree view.
Its only eccentricity is its definition of styles. These are not the styles you would expect in a word processor-like program like HelpMaker, but font characteristics such as the weight, alignment, and position. Even more strangely, these characteristics are placed, apparently randomly, into two sub-menus labeled Styles 1 and Styles 2.
The one drawback to HelpMaker is that its exact status is unclear. The project’s SourceForge page lists its license as the GPL. However, the online help for the software lists the product as freeware. The help also contains a section entitled Why Not Open Source that suggests that the product was withdrawn because of lack of community support and negative comments. Yet above that section is an unofficial license that reads like an informal version of the GPL. To deepen the mystery, the SourceForge page does not contain source code, and, while the product’s home page contains a link to a more recent build, a link on the page to a newsgroup no longer works. Nothing else is on the home page, nor do the developers listed on SourceForge respond to email.
This uncertainty makes HelpMaker as unsatisfactory a solution as AurigaDoc or DocBook. In theory, if it were ever released under the GPL, its code would be available for other developers, but locating it might be a challenge.
Still useful
Despite all these obstacles, there are several reasons to hope for a viable FOSS HAT. To start with, developers and writers who work on a FOSS platform may also need to work on Windows-based projects. Many, no doubt, would prefer to avoid working on Windows whenever possible, and a GNU/Linux-based tool would allow them to do so. At times, too, developers and writers may work on multi-platform projects that require Windows support, if only as a secondary priority.
More importantly, the lack of an advanced FOSS HAT represents a missed opportunity. For technical-writers, free HATs could be an introduction to FOSS that doesn’t require leaving the familiarity of Windows.
This reason is especially important because of recent developments in the commercial HAT market. In 2003, eHelp, the maker of RoboHelp, the leading HAT tool, was acquired by Macromedia. Since then, the product has apparently suffered a number of setbacks. The FrameMaker version has been discontinued, and RobHelp programmers have been laid off. With rumors that the terms of service contracts have been altered to exclude upgrades, and that a plan to shift development to India was shelved, added to the uncertainy caused by the recent acquisition of Macromedia by Adobe Systems, many believe that RoboHelp is about to be “sunsetted” — that is, allowed to become gradually obsolete.
As a result, many developers of Windows Help are currently looking to other proprietary solutions, such as Doc-to-Help and AuthorIt. Former eHelp employees have recently started a company called Madcap, which plans to release an XML-based HAT called Flare by the end of 2005. However, the experience of seeing a widely used tool abandoned by a proprietary company might well cause some writers to decide that enough is enough and consider FOSS solutions. Unfortunately, today, no satisfactory FOSS solution is available to harness their discontent.
