Understanding the purpose of the [ALIAS] section

I've been trying to convert a large WinHelp project over to HtmlHelp, for use with my MFC application.

I've got things working mostly; however, I find that invoking help from many contexts within my app produce the completely unhelpful error message.

Failed to launch help.

It appears that if I add the corresponding entry to the [ALIAS] section then it works.

[ALIAS]
HID_FILE_OPEN=Html\HID_FILE_OPEN.htm

My question is, do I really need to do this for every single topic? With WinHelp, the only entries I had to add to the [ALIAS] section were those topics I wanted to be an alias for something else.

Is there no way HTML Help has to know that HID_FILE_OPEN corresponds to the help file Html\HID_FILE_OPEN.htm without me explicitly entering it for every topic?

Solution

Short story - you have to clean up the mapping data files for context-sensitive help. Please test the information below for your needs and your environment.

The purpose of the two files e.g. alias.h and map.h is to ease the coordination between developer and help author. The mapping file links an ID to the map number - typically this can be easily created by the developer and passed to the help author. Then the help author creates an alias file linking the IDs to the topic names. That was the idea behind years (decades) ago by Ralph Walden (ex Microsoft).

You'll find some further Information at Creating Context-Sensitive Help for Applications.

You know - converting WinHelp to HTMLHelp is time consuming. And migrating the context ID's is problematic. I actually don't have old MFC or VB projects connected with WinHelp for testing.

A workaound maybe to use the home of your CHM file e.g. welcome.htm as one target for all context ID's by using it in the right way inside alias.h and map.h.

But, I remember the HHPmod tool. I linked it from my tutorial Converting WinHelp (HLP) to HTMLHelp (CHM).

It's a tool that Sid Penstone wrote to help one in converting WinHelp projects to HTMLHelp projects. He used the automatic conversion provided in HTMLHelp Workshop, but when he came to edit the new HTML project to complete the tasks that were not done by the conversion, there were some problems:

The 8-letter file names used to write the new HTML topic files are not related to the original Topic ID's.
If there are a significant number of topics to manage, it is frustrating to work with the automatically generated file names. My projects have over 100 context ID's and topics per application.
If the original WinHelp project used map or alias files, they are ignored. The user must manually recreate the alias files using the new non-intuitive(!) file names.

HHPMod rewrites the converted project into a new HTML Help project, restoring the original Topic ID names, correcting all the links, and rewriting the alias files. The new HTML project, when compiled, will link correctly to the application's Help Context ID's. You will still have to fix missing images and hot spots, but you will be working with the original Topic ID names.

Please have a look at the Notes on “Fixing Up” HTML Help Created from WinHelp Projects from the download section. Scroll down to e.g. Manual Rewriting of Map and Alias Data in the HTML project.