D CHM generator
Compiled HTML Help for the D programming language
In an attempt to ease the life of D programmers, I decided to write an utility which would automatically convert the D documentation, distributed with DMD, to an HTML Help project. It was an interesting task, and through some effort I managed at automating the creation of an usable CHM file.
The .chm format was initially created by Microsoft as a next-generation help file format instead of the dating Windows Help (.hlp) format. It was introduced in Windows 98, and is still currently supported. Since then, many 3rd-party applications for various operating systems have been developed to support the format. (more information)
The advantages of using a CHM help file over the included HTML files:
- it's one compressed file, instead of many
- the contents is somewhat easier to navigate
- it has instantaneous indexed search, supporting boolean operators
- comprehensive index of literally too many keywords...
The program doesn't make many assumptions on how the help files are laid out, so it will probably work with future D releases. The only exception is that the program uses Kirk McDonald's keyword index, since I didn't find a reliable way to find where respective keywords are explained in the documentation. The full unmodified source of that wiki page is embedded in the program source, so it should be just as easy to update.
When preparing the help files for the CHM format, the program does the following modifications:
- remove the left navigation bar (it is replaced by the HTML Help's navigation pane)
- skip Google AdSense ads, which don't make any sense in offline media - browsers don't (and shouldn't) allow uploading contents of local data to web services, thus Google AdSense displays rubbish/Chinese ads anyway.
Build instructions
To generate your own CHM from the D HTML files:
- download and install the Microsoft HTML Help Workshop
- save chmgen.d to ...\dmd\html\
- compile and run it
- open the d.hhp file with HTML Help Workshop and compile it
— or —
run:hhc.exe d.hhp
- enjoy your brand new d.chm !
Pre-compiled CHMs
Alternatively, you can download precompiled CHM files. Don't expect these to be always up-to-date with the latest D versions, though.
Usage instructions
To read the CHM file, you need some kind of CHM viewer. The Microsoft CHM reader (usually located in C:\Windows\hh.exe) comes included with every Windows version since Windows 98. For non-Windows operating systems, there are many free and open-source CHM readers on the web.
Troubleshooting
If you see a "Navigation to the webpage was canceled" error page instead of the HTML content, you have to uncheck the "Always ask before opening this file" checkbox on the "Open File - Security Warning" dialog. Alternatively, click the "Unblock" button on the file's "Properties" dialog.
Version history
- 21st January 2011 - added Troubleshooting section to webpage; new precompiled CHMs
- 15th April 2010 - updated for the new documentation layout; moved source to GitHub; new precompiled CHMs
- 24th February 2008 - better support for the new documentation layout; new precompiled CHMs
- 8th November 2007 - this webpage was created; ignore links to 1.x/2.x sections to prevent warnings; updated keyword index (__traits); small bugfix that prevented __traits being added
- 12th April 2007 - program updated to support direct linking to Phobos identifiers
- 25th March 2007 - Released to digitalmars.D.announce
Roadmap
Things that could still be improved:
- a cleaner/more accurate index
- splitting the articles in categories (D syntax, Phobos, ...) to allow filtering
- adding Tango docs for an all-in-one D help file?
- the code could be generally cleaned up in some places...
License
I release the source code (chmgen.d) to the Public Domain (no rights reserved). However, the contents of the included wiki page is distributed under FDL.