0 Replies Latest reply on Nov 24, 2007 11:51 AM by Handy13

    Converting from Winhelp to HTMLHelp Part 1

    Handy13
      Converting an existing application from Winhelp to HTMLHelp
      PART I

      TRIALS AND TRIBULATIONS:
      1. Had a nice Winhelp system using Word under Robohelp Office (Circa 2001) that was doing a great job. Then Microsoft finked out on Winhelp and is not distributing the reader on Vista and not allowing us to provide it to our customers.
      2. I had an integrated system where my Visual Studio compiler would run the compile from a command line embedded in the .hpj file’s Custom Build Step.
      3. Could also edit and do everything necessary in Robohelp Office.
      4. I understood how Context Sensitive Help worked and what to do to show help topics within my application executable.
      5. SO… upgraded to RoboHelp 7 to try to get HTML Help working.
      6. Compiled my project using Robohelp for Word.
      a. Compiled OK but when I’d try to view the result, I would get “mk:@MSITStore…” error and the result would refuse to display.
      b. Called Robohelp for help.
      c. Not much help. They were nice though.
      d. The Robohelp program’s Help – Contents & Index resulted in some weird semi-on-line page.
      i. It brought up an error message when I tried to search for help on anything (like the word “map” for example)
      ii. Search using that page says “LiveDocs Search Results – your search for map site: http://help.adobe.com/en_US/Robohelp/RHTML/7.0 did not match any documents…”
      iii. There was no scroll bar so when I did manage to get something up in that window I could not see the rest of the article.
      iv. I did not discover the html help files buried in the Robohelp installation directory until a couple of weeks had gone by. That did not help my understanding of how to use Robohelp.
      e. Robohelp Office (Circa 2001) came with a 492 page hardcopy manual! That would have helped immensely. I ordered Robohelp to be mailed to me expecting that the package would include a current manual. It did not! It just had a disk, a license number and a really lame 10-page “Getting Started” guide that provided no clue as to how to use Robohelp 7.
      f. Could not at all figure out how to compile from a command line so my Visual Studio interface was essentially broken!
      g. People I was talking with at Robohelp suggested switching to Robohelp HTML.
      7. Started trying to switch to Robohelp HTML.
      a. No clue regarding how to go about converting the project. Found some bits and pieces of what I needed to know via a Google search (remember I still had not found the manual and the built-in help was (and still is) broken.
      b. Did a couple of false starts using Microsoft’s HHW.exe
      c. Then tried to figure out what to do in RoboHelp HTML to convert my project.
      i. On the opening page of Robohelp there is an “Import” item.
      ii. Doing what I wanted to do was not important enough to be listed there. It was buried under the “More” item.
      iii. Selecting the “More” item revealed a choice called “Winhelp Project (*.hpj). I selected that.
      iv. Seemed to go OK.
      8. OK, completed switch to Robohelp HTML
      a. Compiled OK.
      b. “EnableHtmlHelp();” Microsoft doc said:
      Call this member function from within the constructor of your CWinApp-derived class to use HTMLHelp for your application's help.
      Since my application had been based heretofore on Winhelp, I had to add the line.
      c. However, when I ran my application and hit F1, I got a window that said: “Failed to launch help”. What a disgustingly uninformative error message! This one is Microsoft’s fault! A few more lines of data regarding what they were looking for would have helped!
      d. Entered heavy research phase to try to figure out how to get F1 to display the new .chm file.
      e. After much Google searching, I discovered an “Enable Bughunter” option under the Tools menu in Robohelp HTML. No clue regarding how it worked – or what it would do.
      f. Experimentation led me to believe that if I started my application and pressed F1, that the Bughunter might tell me something. Pressed F1 in my application with Bughunter running and it said:

      CHM File Name: c:\MyProjects\HandyAvi\HandyAvi\debug\HandyAvi.CHM
      Command: HH_HELP_CONTEXT
      Result: Cannot find 131200 in c:\MyProjects\HandyAvi\HandyAvi\debug\HandyAvi.CHM

      g. Great. But what the hell was 131200? I mean that is an interesting number but I had no clue regarding what to do with it. (If I had discovered the Robohelp documentation I would have discovered that the number is a “MAP” number. That would have provided an important clue. HEY ROBOHELP GUYS! Why doesn’t that message read:

      CHM File Name:
      c:\MyProjects\HandyAvi\HandyAvi\debug\HandyAvi.CHM
      Command: HH_HELP_CONTEXT
      Result: Cannot find MAP ID# 131200 in c:\MyProjects\HandyAvi\HandyAvi\debug\HandyAvi.CHM

      h. When you write a message, please include enough information to make it useful! Since your documentation didn’t work and I had not yet found your OTHER documentation I had no clue regarding what that number meant!
      i. Lots more searching of the internet for information.
      j. Found a web site giving the format of .chm files: http://www.speakeasy.org/~russotto/chm/chmformat.html
      k. And I had a clue that some number was missing from the .chm file.
      l. Brought up the .chm file in visual studio’s binary editor.
      m. I saw /afxcore/AFX_HIDD_FILEOPEN.htm in the file.
      n. I then guessed that I might see AFX_HIDD_FILEOPEN in the Robohelp “Edit Map IDs” list. Yep. It was there and it was “assigned” to a topic.
      o. Did some experimenting in my application and was able to bring up the help file for the AFX_HIDD_FILEOPEN using an htmlhelp call.
      p. I then realized that I should look in for 131200 in Robohelp’s “Edit Map IDs” window. I sorted on MAP # and found 131200 associated with HIDR_MAINFRAME. HIDR_MAINFRAME was not assigned to a topic…
      q. I assigned a topic to it, recompiled, ran my application and the F1 key then brought up the assigned topic!
      r. So how many people in the world know that the F1 key is looking for an assigned HIDR_MAINFRAME? Not many! If you Google search HIDR_MAINFRAME F1, you only get 9 hits! None of them are from Microsoft! (Does anyone at Microsoft know this? I know their code knows this… Their documentation doesn’t know this…) Here is one of the few sites that does know about this: http://www.geocities.jp/beloodphoto/Microsoft_Visual_CPLUS_NET/LiB0172.html
      s. So finally I understood that I had to use the “Edit Map IDs” panel in Robohelp HTML to assign topics to anything I wanted to display in my software application. To display stuff in C++ I did this:

      HtmlHelp(Email_SMTP_Server_Setup, HH_HELP_CONTEXT);

      Where Email_SMTP_Server_Setup is the name of one of my topics.