Microsoft HTML Help relies on several Active X controls and DLLs. If these aren't present and registered you will have problems with your help files.

"MJ's Diagnostics is a small utility that reports if all the HTML Help runtime DLLs are installed and registered correctly. If a DLL is not registered then it will ask if you want to register it. It also checks the RoboHelp DLL (HHActiveX.dll)."

Download it from:

http://helpware.net/downloads/

Note: I've downloaded and run this on my computer with no appreciable side effects (so far), but I can provide no guarantee that the download site linked to above is bona fide, or that it is completely harmless – I just crossed my fingers and trusted to Norton Antivirus.

Here's a useful tip if you use a JavaScript file to dynamically rewrite the HTML of your topics. For example, I use a .js file that adds HTML content to every topic at runtime. This keeps the topic files nice and small, reduces the size of the .chm file and makes the HTML of the topics tidier and easier to edit.

But sometimes you want to see the resulting HTML, after the .js file has done its work. You can't use View Source because all you get is the static HTML. One way to display the dynamic HTML is to:

1. Open the .chm file and display the page you're interested in.
2. Right click a topic in the Contents pane.
3. Choose Jump to URL.
4. In the Jump to this URL field, paste this:

javascript:void(window.open("javascript:document.open('text/plain');document.write(opener.document.body.parentNode.outerHTML)"))

When you press OK, the HTML is displayed in a new IE window. The HTML that is displayed is the HTML that the browser window in the Help Viewer uses when displaying the topic.

UPDATE - Jan 2009

The above doesn't work in Internet Explorer 7. However, this does work:

javascript:window.open("").document.open("text/plain", "").write(document.documentElement.outerHTML);

As above, paste this into the Jump to URL dialog box.

Last year I wrote an online help system. I was very pleased with the end product,
but there was one little niggly thing that bugged me.

The help system was modelled after the help for Internet Explorer 6. Like that
system, mine had a “Related Topics” link at the foot of most topics.
The problem was that unless I had an old version of the hhctrl.ocx
Active X control installed I couldn't get the list of related topics to be displayed
in a popup (IE-style) rather than a dialog box. I scoured the Internet for a
solution, to no avail. As a workround I got our development department to add
the old hhctrl.ocx to the client software installation, so
that it gets registered when you install our software. The trouble with this
is that as soon as the user installs a new Windows service pack, or installs
another program that registers a newer version of this Active X control, the
popups go back to being displayed as ugly dialog boxes.

Now it's time to update the help system for a new release of the application.
I was determined, this time round, to get those Related Topics popups working.
But I still couldn't find anything on the Internet, apart from one
mention, with the following explanation:

“This will happen if the language of the OS doesn't exactly match
the language of the chm. The problem is that in some cases this mismatch causes
garbage in the menu (if the language of the chm can't be displayed in the font
the system uses for menus), so we fall back to the Topics Found dialog, in which
we can set the font.”

Gee thanks! So that clears that up then. NOT!

As a last resort, I thought I'd give newsgroups a try. The obvious newsgroup
seemed to be microsoft.public.helpauthoring. I added this newsgroup to Thunderbird
and searched through the postings for anything on “Related Topics”.
No joy. No joy, too, when I tried to post a query. Thunderbird complained about
there being “no sender”, despite my name being in the Sender header.
Okay, never daunted, how about using Microsoft's web front end to their newsgroups
as an alternative way of posting to microsoft.public.helpauthoring. Not as easy
as you might think.

Microsoft's online newsgroups are incredibly difficult to get to if you don't
have a URL or a link to a particular posting within a particular newsgroup.
You'd think you'd be able to go to the main Microsoft page, click the Communities
link, then click the Newsgroups link, then search for the “helpauthoring”
newsgroup. Wrong! If you click the Newsgroups link you get to a page called
“Welcome to Microsoft Discussion Groups” where you can search for
topics across all newsgroups and you can view the posts you find, but you can't
get to a particular newsgroup and you can't post a question/reply.

One way to get to the newsgroups – though I can't recommend it –
is to go to http://communities.microsoft.com/newsgroups/default.asp.

When you browse to this page, a list of public newsgroups starts loading in
a pane on the left of the window. But wait a minute (wait a lot of minutes,
if you have a dial-up connection), because if you try scrolling down the list
too far, too soon, it may stop loading, and then you have to refresh the page,
and start waiting again. Sometimes it just stops loading even if you don't do
anything and it gives you some incomprehensible message about “no data”.
This is a seriously badly designed web page!

By the way, why are Microsoft's web sites SOOOOOOO SSSSSSLLLLLLLLOOOOOOOOOWWWWWWWWWWWWWWW.....?
I can only presume Microsoft have shares in cable companies.

As I said, the only decent way of getting to one of the web-based versions
of Microsoft's newsgroups is to use a URL. Here's the URL for the “helpauthoring”
newsgroup:

http://communities.microsoft.com/newsgroups/default.asp?icp=web_publishing_all&slcid=us&newsgroup=microsoft.public.helpauthoring

If you go to this page and you like accessing the newsgroup that way, be sure
to bookmark the page, or you may have trouble finding it again.

So I posted off my question and, wouldn't you know it, when I check back a
couple of hours later, there's a reply. Not just a reply though: the solution
I had been searching for. The correspondence was as follows:

That totally reinforced my firm belief in the immensely beneficial power for
sharing information offered by the Internet. Next time maybe I won't be so slow
to turn to a newsgroup for help.

Incidentally, Pete Lees, who replied to my query, runs an excellent Help Wiki
at: www.mshelpwiki.com, which I can
recommend.

Another useful resource I came across while looking for an answer to the popup
problem was: www.chmtools.com. This provides
useful information about help authoring tools, and links for downloading those
tools, including htm2chm by Yaroslav Kirillov, which reputedly
“Allows you to convert separate HTML pages with images as well as
whole websites (for example downloaded with offline browsers) into one CHM file
for more convenient storing.” I haven't tried this yet, but it sounds
intriguing.

One program I did try, and I can thoroughly recommend, is KeyTools
by KeyWorks Software. Among other things it allows you to decompile a .chm
file into its component parts. Okay, I know, HTML Help Workshop can do this
very nicely. But KeyTools does it even better. It's very useful for answering
“How did they do that?” type questions.

You can find a list of help authoring newsgroups and forums at: www.chmtools.com/forum.
However, you need to register to post to these newsgroups via this web site.

I'm very happy now that my Related Topics are finally displaying like I always
wanted them to. One final question remains through all this though. If someone
at Microsoft broke hhctrl.ocx some time ago, how come they've
never bothered to fix it? The answer, surely, is that this bug only affects
technical authors outside the US. There just aren't enough technical authors
close enough to Redmond, waylaying them in the street and accosting them at
conferences, to make it worth their while getting round to fixing this bug.
Of course, things have moved on now, HTML Help is out and MAML is in –
so this bug will never get fixed now. But who cares? I've got the workaround
I was looking for. That'll do me!

Update: 15/11/2008
The link in this post is broken. See my comment below for an alternative link on the Internet Archive.

Here's a useful page full of links to information about MAML (Microsoft Assistance Markup Language):

http://longhorn.msdn.microsoft.com/lhsdk/port_tech_helplh.aspx

MAML is Microsoft's XML dialect for producing .HELP files for the next version of Windows (currently named "Longhorn" and recently shunted backwards for release some time in 2007). MAML is a hugely sensible move on Microsoft's part. Anyone who is familiar with using an XML dialect for documentation – for example, DocBook – will find MAML very easy to get to grips with.

Microsoft could have adopted DocBook, but when you're Microsoft you don't adapt existing technologies that don't quite fit what you want to achieve. It was cleaner and probably easier to start from scratch and devise a new, purpose-built XML variety for "assistance" documentation (in most cases that means online help).

If you write online help you'll be hearing a lot more about MAML in the coming months.