14. preshrunk-cotton: Windows Help Files for Lazy People

Audience level:
March 11th 8:05 a.m. – 8:10 a.m.


Generating a Compiled HTML Help (CHM) file is often necessary when distributing applications on Microsoft Windows platforms. However, many developers may dislike authoring HTML and/or cannot use Microsoft’s help tools. preshrunk-cotton streamlines the creation of CHM files by allowing the author to quickly write documentation in Textile markup and build the help file on almost any platform.


When distributing applications for the Microsoft Windows platform, documentation is often included in Compiled HTML Help form, one of Microsoft’s native help formats. Traditionally Compiled HTML Help, or CHM, files are normally constructed from HTML files using Microsoft’s tools or a variety of wrappers that employ these tools. This workflow is sometimes suboptimal for many developers that are using non-Windows build servers and/or want to avoid authoring HTML directly.

The package to be presented, preshrunk-cotton, is meant to solve two problems simultaneously: eliminate the need to directly author HTML files and allow building CHM files on any platform. To avoid HTML authoring, preshrunk-cotton uses the Textile markup language to significantly accelerate the process of actually writing documentation. Each “page” of help is represented by a separate file in a directory structure written using Textile. The directory structure itself is then used to generate the organizational tree of the resultant CHM file. Images and any other files not written in Textile (including HTML files) are simply left as is, allowing for their inclusion in the CHM file.

Building CHM files on a variety of platforms introduces an interesting issue. Normally, Microsoft’s HTML Help Workshop is used to compile CHM files from HTML and supporting files. However, using the Microsoft tools implies that one has the ability to execute said tools on their build system, which is often not the case. An alternative compiler from the Free Pascal project, chmcmd, also has the ability to build CHM files without the need for any Microsoft tools. The tool was originally created in support of compiling Free Pascal’s documentation, but the small utility has one extraordinary implication: the chmcmd utility allows for the creation of CHM files on any platform supported by FreePascal.

The chmcmd utility is not particularly user-friendly, requiring some cryptic XML files to be present for the purposes of constructing the resultant CHM file. preshrunk-cotton is able to automatically generate all the necessary input files and instructions required by chmcmd. By traversing the directory structure of input files and examining some simple informational files, preshrunk-cotton can construct the proper XML for chmcmd, generate an educated guess at help file index entries, execute the utility, and return the name and location of a valid CHM file.

The biggest strength of preshrunk-cotton is its ability to be integrated with existing build tools. A command line script is available to accept a directory tree containing textile, HTML, and other supporting files and generate a CHM file, allowing simple integration with makefile-based build systems and similar tools. Alternatively, if a build system is based on Python, preshrunk-cotton can be more directly integrated.

This package was originally written to support a proprietary commercial software package, and it continues to be used to construct documentation for said product. However, the package would benefit from additional community involvement, and it may prove helpful to a significant number of developers distributing software for the Windows platform.

More information:

preshrunk-cotton: http://code.google.com/p/preshrunk-cotton/

Free Pascal’s CHM implementation: http://wiki.freepascal.org/chm