1

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?

Jonathan Wood
  • 65,341
  • 71
  • 269
  • 466

1 Answers1

1

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.

help-info.de
  • 6,695
  • 16
  • 39
  • 41
  • I will carefully review all your links but so far I'm a little confused by your answer. I have no idea what you mean by cleaning up the links. Also, I have no alias.h file. And yes, I know converting WinHelp to HtmlHelp is time consuming. I've spent nearly a week so far. But the only thing that isn't working is context-sensitive topics that I did not define under the ALIAS section. And I'm still unclear why every topic needs to be manually added to that section. – Jonathan Wood Sep 29 '17 at 13:16
  • I think some useful information you'll find in the **Manual Rewriting of Map and Alias Data in the HTML Project** section at Sid Penstone's PDF. I have had contact to him years ago. Do you have a map.h file? – help-info.de Sep 29 '17 at 14:49
  • No map.h file. I just manually added an entry in the form `HID_MYID=HID_MYID.htm` for every entry and it seems to work. That seems to be an extra step needed because HTML help requires a string instead of a number to find the topic. Perhaps Visual Studio can be made to generate some of this information automatically, but I don't think it knows the names of my HTML files. – Jonathan Wood Sep 29 '17 at 16:21
  • Copied from PDF: (1) Map header files (usually *.h or *.hm) are often written automatically by the program development software. (2) Do not write alias definitions directly into the [ALIAS] section; while this will work, you should minimize manual editing of the HTML Project file. Means use an external by hand edited **foobar.ali** file in your `[ALIAS]`section copied to your root project folder before compiling the CHM. – help-info.de Sep 29 '17 at 16:37
  • Hope I'd help - really old help authoring stuff - as me. Upvoting is welcome. Have a nice weekend. – help-info.de Sep 29 '17 at 16:45
  • None of the HM files I had in the old version contained the ALIAS information that I had to add manually. The only HM file I had contains the same information I now have in HTMLDefines.h, but that is *not* the information needed for my ALIAS section in order to work correctly. You are very knowledgeable about HTML Help and I appreciate your help. I have marked your answer as the correct one, which is good for 15 reputation points. – Jonathan Wood Sep 29 '17 at 16:59
  • And an upvote from the other [chm] regular. So that is about max achievable score :-) – Marco van de Voort Oct 06 '17 at 08:37