Practical Magic:
Converting WinHelp To HTML-Based Help

If you’re new to HTML, the transition can be intimidating.  But today’s authoring tools are so good that the mechanics of the conversion are often a snap.  The complexity, if any, often lies in areas like design and legacy coding problems.  This column focuses on these problems, specifically:

• Conversion mechanics and goals.
• Design conversion.
• Single-sourcing considerations.

When I discuss tools, I focus on major help authoring tools – RoboHelp and ForeHelp.  There’s a growing debate over replacing such tools with web authoring tools like DreamWeaver.  I’ll touch on this where appropriate in this column.  However, the subject of replacing help authoring tools with web authoring tools could be a column all its own.  For more information and to get a sense of the arguments, see the eGroups archives at www.egroups.com/messages/HATT/.  The “Beyond the Bleeding Edge” stem of the STC annual conference will also offer a presentation on the subject, currently scheduled for Tuesday, May 15.

Conversion Mechanics

• RoboHelp Classic - Start your project, open RoboHelp Explorer, expand Single-Source, and double-click Microsoft HTML Help to perform the conversion.  When it ends, you can close RoboHelp Classic and open the project in RoboHelp HTML.

• RoboHelp HTML - Select File/New/Project, select the Import tab, and select WinHelp or WinHelp Project to perform the conversion.

• ForeHelp - Open the mode pulldown at the right end of the toolbar and select HTML.  The project will immediately be in HTML format.

• I haven’t used Doc-To-Help for a while so I don’t know the specific steps.  However, it’s a big, powerful package and the process should be equally straightforward.

• If you’re using some other tool, like DreamWeaver, convert your WinHelp to HTML and then start a new project and import the HTML files.

If the WinHelp project’s code is “clean” (no kludges or creative coding), the conversion should go about as smoothly as the previous bullets suggest.  However, given the history of many WinHelp projects, that may not be the case.  You may encounter two types of problems:

• The WinHelp may date from the early authoring tool days, when developers often had to tweak code by hand.  It may even date from the pre-authoring tool days when everything was done by hand.  Back then, developers, with few standards and little experience, did things that made sense then but not in hindsight.  For example, some developers added watermark effects by using a freak behavior of table columns in Word.  However, the conversion tools inadvertently fixed that behavior, breaking the watermark effect.

• The WinHelp may have been revised so many times by so many developers that it’s just turned into a tangle, invariably undocumented.  In this case, things can go wrong for no apparent reason until you go into the code.

How you handle such problems depends on your conversion goal - whether you’re converting to HTML once or repeatedly.

Conversion Goals and Legacy Coding Problems

Supporting WinHelp and HTML-Based Help

You might do this for a standalone online documentation project like an insurance policy manual used by people on a variety of platforms including WinHelp.  In this case, you have to convert every time you modify the material, so you’ll want a simple design and structure that converts as predictably and cleanly as possible in order to avoid having to waste time fixing the same errors or making the same modifications each time you convert.  There will always be some clean-up, especially for the design (discussed below) no matter how carefully you work, but you want it to be minimal.

An irritating time-waster is to perform a conversion, find a code problem, spend time fixing it, and then discover that it’s immaterial because users don’t see the effect.  For example, the WinHelp compiler (used by RoboHelp Classic, ForeHelp Classic, and other help authoring tools) displays an error message if the WinHelp contains a table with cell borders.  Several types of formatting can produce the actual error message, and you may spend a lot of time trying to fix it only to find that users don’t even notice the problem.  (It’s even more irritating to waste time like this and then find that, because there’s no project documentation, your predecessor did the same thing.  Always try to create a project spec to help your sucessor avoid repeating your mistakes.)

If there are legacy code problems, it’s more efficient to fix them in the WinHelp to eliminate their recurring each time you convert.  Depending on the complexity of the problems, it may be worth the expense to bring in a consultant who’s familiar with your help authoring tool but who can also work at the code level to fix the problems for good.

Moving to HTML and Abandoning WinHelp

You might do this if you’re working on a help system and want to update its look and/or features as the application is updated.  Or you might need to create online material that can be viewed on a variety of platforms in addition to Windows.  In this case, you can largely ignore the WinHelp side (unless you’re getting a fatal error), convert the material to HTML, and do all your clean-up in the HTML.  Because you’ll only convert once and modify the material in HTML from then on, conversion predictability is less important.  Obviously you want a simple and clean conversion, but you’ll only have to deal with any problems once. 

Depending on the complexity of the problems, consider hiring a consultant who knows your help authoring tool but who can also work directly in the HTML to fix the problems once and for all.  If you do this, however, be sure to specify what tool and version the consultant should use, for two reasons: 

• Going backward on the version is likely to cause problems, such as hiring a consultant who uses ForeHelp 5 while you use ForeHelp 4.

• Some consultants mix tools, such as using RoboHelp for project control and compilation but creating topics in HomeSite.  The ability to use an external HTML editor is new in RoboHelp 9, and a welcome feature for people who don’t like RoboHelp’s HTML editor.  However, mixing tools has some drawbacks.  New developers face a steeper learning curve since they have to know RoboHelp plus the HTML editor chosen by the consultant.  Different HTML editors can also cause conflicts within RoboHelp.

Design Issues In Conversion

• Many WinHelp files use non-scrolling title regions for which there’s no direct equivalent in HTML.  To get them in HTML, you have to create framesets.  It’s not hard; frameset editors in today’s authoring tools take most of the effort out of it.  The problem is that you may have to create, maintain, and manage multiple framesets.  It’s one more detail in a collection of details that can become overwhelming.

• Some WinHelp files contain extensively customized menu and button bars.  But there is no equivalent in HTML, so what happens to the features provided by the customization?  For example, one WinHelp developer at a modem company added a “Commands” entry on the WinHelp menu which, when clicked, opened a series of cascading menus that listed the 400+ commands used in one of his company’s products.  What happens to this feature when he converts this WinHelp file to HTML?

Whether or not you’ll encounter such problems depends on the WinHelp file.  The easiest way to find out is to create a test project.

The Test Project

This approach is realistic but it has a problem.  If the WinHelp file is large or complex and you’re new to HTML, it may be difficult to figure out exactly what you’re looking at and relate it back to the original WinHelp.

The solution is to create a little test project that simulates the real WinHelp and use it to see how well the design comes across, plus look for any legacy coding errors.  There are several ways to create a test project, but they all require you to create a set of topics that offers a representative sample of the design features.  To do so, first review the WinHelp and make a list of the features it contains.  At a minimum, these will be standard features like the menu and button bars, jumps and popups, and so on.  It may also include such things as customization of the menu and button bars, macros, graphics, non-scrolling regions, secondary windows, and so on.  This is the list of features that you need to either reproduce or eliminate in the HTML.  Then, you can either:

• Create a new project containing all features in your list.  I can usually do so with 10 to 20 topics, so the complete design and development of a test project takes about a day.  The benefit to this approach is that it creates a clean project with no legacy problems.  There are two drawbacks.  First, you may overlook some design features that exist in the real project.  Second, this approach will probably not include the legacy coding problems that you’d have to deal with.

• Copy the real project, identify and use the topics that contain examples of all the features in your list, and delete all other topics.  The benefit to this approach is that it will create a realistically representative example.  The drawback is the need to handle problems that stem from the test project’s incompleteness, such as links that broke because you used a topic that contained a link but deleted the target topic.

However you do it, creating and working with the test project will give you a very good idea of the problems you’ll encounter in the real thing.

Single-Sourcing Considerations

Since HTML or XML are at the root of all these formats, you want to be using standard code with no proprietary features.  Unfortunately, the mainstream help authoring tools can add proprietary codes to their HTML files, which can cause trouble later when you convert to XML or other languages such as WML.  Therefore, before converting any WinHelp to HTML, determine what your company’s strategic direction is for online material and make sure that you convert to HTML in a way and using a tool that’s as flexible and non-proprietary as necessary.