![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
![]() ![]() |
Under Microsoft Windows Vista (formerly code-named "Longhorn") and launched January 30, 2007 WinHelp will not ship with the operating system. This tutorial gives a step-by-step description how to convert WinHelp (HLP) to HTMLHelp (CHM) on a freeware/shareware and "low budget" level. The conversion project example from the download section includes a working structure and example files.
You can of course use a helpauthoring tool (HAT) like Help & Manual or any other HAT to convert existing WinHelp projects to HTMLHelp.
WinHelp 1.0 (HLP) has been around since the early '90s and has now largely been superseded by HTML Help 1.x (CHM). Under Microsoft Windows Vista - formerly code-named "Longhorn" and available since January 30, 2007 - WinHelp will not ship with the operating system. The engine will be downloadable. So its official now - the notice has been published as a KB article KB917607.
It means WinHelp will go away and ISVs (Independant Software Vendors) should stop promoting WinHelp as a viable help system. Authors should move over to HTML Help 1.x if they haven't done so already.
You should not count on any of your WinHelp files being viewable in Windows Vista without specific download. Get used to the idea of Windows without WinHelp.
So don't invest any more time and money in WinHelp and try to convert to HTMLHelp. Microsoft say HTMLHelp will be around for a long time. Once in HTML it will be easier to port to any future platform. You will find WinHelp RTF based help difficult to port but not impossible.
The easiest way to learn what problems you can expect is to actually prepare and run the conversion.
The common source format for a WinHelp project is an *.HPJ file defining the help file's general properties, with a corresponding RTF file containing the actual help text. These files are used by the WinHelp compiler to create the final *.HLP file.
Having a pair of *.HPJ and *.RTF files for an existing help project, you can use these files to convert by HTMLHelp Workshop. If you have troubles converting the existing *.HPJ and *.RTF files exported by your previous help authoring tool, use the decompiler instead.
If you have an existing WinHelp *.HLP file without the *.HPJ and *.RTF source files only, you can use the WinHelp decompiler to recreate the HPJ and RTF sources from the HLP file. The decompiler will generate the *.HPJ and *.RTF files, along with a series of bitmap files if the help file contains images.
WinHelp
|
HTML
Help |
Description |
.hlp | .chm | Main Compiled Help File. |
.hpj | .hhp | Project file, optionally the context-sensitivity control codes |
.cnt | .hhc | Table Of Contents file. HHC is compiled into the CHM file. |
.hhk | Index file. HHK is compiled into the CHM file. | |
hcw.exe | hhw.exe | Help Workshop. Free basic authoring
tool from MS. Earlier versions of hcw are hc31, hc, etc. |
winhelp.exe | hh.exe | Launches the help file. HH.EXE is just a small stub that calls the HTML Help API. |
hcrtf.exe | hhc.exe | Command Line Compiler. Hcrtf.exe isn't a console program, but it does take command line parameters and can be run from a DOS prompt. |
.rtf | .htm, .html | HTML Help is HTML based while WinHelp is RTF based. |
.bmp .dib .wmf .shg |
.jpg .gif | HTML Help uses HTML document graphics. |
.gid | .chw hh.dat |
The .GID file stores merged keywords (.CHW) and position/preferences information (hh.dat). |
.fts .ftg | With HTML Help FTS information is stored inside the CHM | |
.ann .bmk | hh.dat | WinHelp run time files for storing annotations and bookmarks. HTML Help 1.2 does not yet offer annotations, while favorites are stored in HH.DAT. |
You'll see some of the codes below at the top of each topic in your *.RTF file:
Code |
Specifies |
# |
The topic ID. The only required code. |
$ |
The topic title specified using a code in order to display on the Index and Find tabs. |
K |
The keywords that form the Index tab and that are used by the KLink macro. |
A |
The keywords used by the ALink macro to create Related Topics lists. |
+ |
The browse sequence code. |
! |
The topic entry macro(s). |
* |
The build tag for conditional builds at the topic level. |
> |
The default window type in which to display a topic when it’s opened from the Index or Find tab or via a KLink or ALink macro. |
To view or edit these codes, called footnote codes, place the pointer in the topic whose codes you want to edit. Then, in Word either:
To insert new footnote codes manually, use Word's custom footnote feature.
To move or delete a footnote code, select the code character on the topic title line and not in the footnote region.
In preparation for the conversion process create some work directories. I recommend using the same folder names for this walkthrough to save time in your conversion process and to compare your results.
Save some more time by downloading the WinHelp - Conversion Project Example and unzip to "C:\_WinHelpToHH" to create the subfolders and some example files. After having a look at the example files and saving the ZIP file, please clean up the work directories (hh_out, hh_updated) before following this step-by-step tutorial. You may clean up more work directories later (e.g. wh_project, wh_source) for your own projects. Those who like good old DOS command line or following up step-by-step see steps below.
"hh" is a acronym for HTMLHelp and "wh" for WinHelp. Hold the files in the "hh_out" directory save as a result of the conversion wizard (see below). "hh_updated" holds your updated and cleaned up files.
If the original files (*.CNT, *.HPJ, *.RTF etc.) are available, then you do not need to decompile - you can go straight to converting to HTMLHelp by HTMLHelp Workshop or another Help Authoring Tool (HAT).
Even if you have the *. HPJ and *.RTF sources of the HLP file, you still may want to use the decompiler. Each and every application has its own interpretation of the loosely defined RTF format. The decompiler generates very clean RTF files.
If you have an existing WinHelp (*.hlp) file without the *.HPJ and *.RTF source files only, you can use the WinHelp decompiler to recreate the HPJ and RTF sources from the HLP file. The decompiler will generate the *.HPJ and *.RTF files, along with a series of bitmap files if the help file contains images. A table of contents (*.CNT) file can be re-created without any navigation structure only.
HelpDeco Version 2.1 is a decompiler for Windows HLP files and multimedia titles from Manfred Winterhoff. Several Windows programs are available to control HelpDeco.
HlpDecoGUI is a GUI shell/wrapper of HELPDeco from Dipak Auddy. HELPDECO is a nice little program, which decompile WinHELP files. But it is a console program, so sometimes it is very tiresome and error prone to use it correctly. So HlpDecoGUI was created for HELPDECO Version 2.1 (32bit).
I recommend HlpDecoGUI and using the same folder names for the following step-by-step tutorial to save time and to compare your results. By downloading the WinHelp - Conversion Project Example and unzip to "C:\_WinHelpToHH"you can skip step 1-4.
Cleaning up the decompiled files will be required!
; This file is maintained by HCW. Do not modify this file directly. [OPTIONS] COMPRESS=12 Hall Zeck ERRORLOG=winh_hh.log LCID=0x407 0x0 0x0 ; Deutsch (Deutschland) REPORT=Yes FTS=1 TITLE=WinHelp Example CNT=winh_hh.cnt COPYRIGHT=(c) www.help-info.de CITATION=(c) www.help-info.de HLP=winh_hh.hlp [FILES] winh_hh.rtf [MAP] First_Topic=10000 Second_Topic=20000 Third_Topic=30000 [WINDOWS] Main="",(653,102,360,600),60672,(r14876671),,f3 [CONFIG] BrowseButtons()
:Base winh_hh.hlp
:Title Example WinHelp to HTMLHelp
[# indicating indentation level] [entry text]=[rtf topic id]>[window name] 1 First Steps 2 Migrating WinHelp=Migrating_WinHelp .. 1 Context-sensitive Topics 2 First Topic=First_Topic ..
The decompiler could not bring back the indentation level of your table of contents file so, your decompiled .cnt file looks like this:
:Base WINH_HH.HLP>main :Title WinHelp Example 1 Migrating WinHelp=Migrating_WinHelp 1 Resulting HTMLHelp=Resulting_HTMLHelp 1 First Topic=First_Topic 1 Second Topic=Second_Topic 1 Third Topics=Third_TopicSo, make a screenshot of the existing WinHelp contents and update the *.cnt file e.g. "winh_hh.cnt" before converting WinHelp to HTMLHelp by HTMLHelp Workshop.
Of course one can run the conversion process by HTMLHelp Workshop with a "one level" result and fix it later by the TOC & Index Editor of FAR (www.helpware.net/FAR) like shown below:
Microsoft HTMLHelp is an online help authoring tool (Freeware). You can use it to develop and author online help for software applications or web sites. A wizard can convert an existing WinHelp (.hpj) project and will help you to create a new HTML Help project.
HTMLHelp Workshop (HHW) doesn't convert the following WinHelp items - but remenber, I above mentioned to avoid "creative coding" for later migrating into other languages and use standard HTML.
The wizard can convert an existing WinHelp (.hpj) project to HTMLHelp Workshop (.hhp) project files. It will convert the RTF files to individual HTML files, the WinHelp index to an HTMLHelp index (.hhk) file and the WinHelp Table of Contents (.cnt) file to an HTMLHelp (.hhc) file. WinHelp jumps are translated o HTML hyperlinks (but not popups).
You must install the Microsoft HTMLHelp Workshop on your computer before you can use this feature. Follow the steps in the HTML Help install guide wizard to complete the installation.
After you are finished thereby start HTMLHelp Workshop for the first step, select "File | New", specify "Project" and on the dialog box click OK.
Select the "Convert WinHelp project" check box and then click "Next".
All the files referenced by the existing Help project (.hpj) file must be in the locations specified or the conversion process will fail. HTML Help Workshop converts the entire project as defined in the WinHelp project file.
Click "Next" and "Finish" to create your project. The conversion will now happen. Once it has completed, HTMLHelp Workshop will display the project details.
HTMLHelp Workshop uses the WinHelp project name for the names of the Contents and Index files. The naming convention of the conversion process doesn't adequately identify the topic. The filenames "winh4qgg.htm, .." created in the conversion process for each unique topic's HTML page are not "user-friendly".
In fact they would be extremely difficult to refer to at a later stage when creating future links as they would have no meaning related to the topic for future authors or intranet developers.
Note: Don't change file names at this step!
There is new tool HHPMod
developed by Sid Penstone. HHPMod rewrites the converted WinHelp project into
a new HTMLHelp project, restoring the original Topic ID names, correcting all
the links, and rewriting the ALIAS files. The new HTMLHelp project, when compiled,
will link correctly to the application's Help Context ID's. You will still have
to fix missing images (see "Graphic Files Quality"
below) and hot spots, but you will be working with the original Topic ID names.
Please see below for further information.
The result in your "C:\_WinHelpToHH\hh_out\" directory has a structure like this:
Try to compile your project and view the compiled CHM file
A first result of your compiled help (CHM) includes plain HTML, the table of contents "winh_hh.hhc" and index "winh_hh.hhk" as shown below:
If you have troubles converting the existing *.HPJ and *.RTF files exported by your previous help authoring tool, use the decompiler instead or see "Troubleshooting".
Cleaning up the generated files will be required!
Copy all files from hh_out to hh_updated. Save your work (!) by copying the hh_updated folder from time to time to e.g. hh_updated_20060921-01. Don't edit the filenames at this stage, except you are a extended user.
Graphic Files Quality
The graphic file conversion by HTMLHelp Workshop Image Editor (installed with HH Workshop) isn't always clean. So try a freeware tool like IrfanView (www.irfanview.com) to get better results. IrfanView is a very fast and innovative FREEWARE (for non-commercial use) graphic viewer for Windows.
- Start IrfanView and click on the File Menu, select Batch Conversion/Rename. A dialog allows you to select a directory from which the files will be taken e.g. "C:\_WinHelpToHH\wh_project\images"
- Select the output directory at middle right. If you don't have the full path for this directory, click the Browse button to find it. Find a directory and when you have selected a directory, click the OK button to load the directory name as output directory e.g. "C:\_WinHelpToHH\hh_updated\images"
- Select the same Output Format at bottom left as converted before (*.GIF). This works just like Save and Save As. The Options button lets you choose from the various file format specific save options, just like the Save and Save As dialog. Overwrite your files in the ..\images
- Click "Start" for the Batch Conversion
- Compile your project again.
Help Viewer
If you want to include full-text search in your results, you must modify the project settings first.
- Open your project file with HTMLHelp Workshop
- Click icon "Change Project Options" and the Options dialog box displays.
- Go to the "Compiler" tab and always specify the compatibility 1.1 or later
- Set the "Compile full-text search information" check box to true
All compiled HTMLHelp files use a tri-pane window to display their contents. In order to change the window display, you must create a new window.
- Open your project file with HTMLHelp Workshop
- Click Add/Modify Window Definitions. The Add a New Window Type dialog box displays. This dialog box only displays the first time you click the icon in a new project. Once the window definition exists, you use the Window Types dialog box to create additional windows.
- Type the name (e.g. "main") for the window in the input box and click OK. The Window Types dialog box displays.
- Enter a Title bar text e.g. "Converting WinHelp to HTMLHelp Example"
- Go to the "Navigation Pane" tab and set the "Navigation pane width" to e.g. 250
- Set the "Search tab" check box to true
- Modify the window as desired and click OK when finished.
Compile again and compare the new and old CHM result - you have better graphics and a full-text search tab. But remember that less is usually more. There is some work more waiting for you.
Clean up the generated HTML Code
see cybertext ..
Bullets
Numbered
Headings
Migrating HTML Code
If you want to do more, see the "Migrating HTMLHelp for future use" article.
Since XML is at the root of single-sourcing formats, you want to be using standard coding with no proprietary features. So, make "clean" XHTML code and avoid creative coding , which can cause trouble when you port to any future platform like XML, other lanuages or XML subsets like DocBook, DITA or AML. Once in HTML or XHTML it will be easier to port.
1. All the files referenced by the existing Help project (.hpj) file must be in the locations specified or the conversion process will fail. HTML Help Workshop converts the entire project as defined in the WinHelp project file.
2. The installation program for the HTML Help Compiler Workshop (otherwise known as the HTML Help Kit) for a number of versions appears to have a bug in that it doesn't registrar several key DLLs that it requires for things like converting an old WinHelp project into an HTML Help project. One such version is the latest one - ver. 1.3. This little program asks you where you installed HTML Help Workshop and then registers all of the DLLs it requires. *New in version 1.1* - now includes support for registering the standard HTML Help runtime components (ITIRCL.DLL; ITSS.DLL; HHCTRL.OCX).
3. Sometimes there are problems using the context menu of a *.hhp file from
Windows Explorer. (Open with Microsoft HTMLHelp Workshop).
A DOS path quotation is the cause. Start HTMLHelp Workshop from the Start menu
and use File | Open.
4. A topic in the WinHelp file may require the option to launch an external
EXE (e.g. a backup utility for the app's files). This worked fine in WinHelp
(using ExecFile), but one cannot get it to work with HTML Help by using HTML
Help Workshop.
By default, HTML Help shortcuts will only work on local drives, so make sure
you're not running on a network or removable drive. You can read more about
these security restrictions here:
5. Converting from Winhelp to HTML Help Leaves Bitmaps Behind. When you use the HTML Help Workshop to convert a Winhelp project to an HTML Help project, bitmaps in the .rtf files are not transferred to the HTML Help .htm files.
If the original Winhelp files had any images in subdirectories, they get
converted OK, but when the .gif files are added to the HTML project, they
are all placed in the /images directory with no sub folders. However, the
<img> references in the .htm files will contain the subdirectory address,
so the images cannot be found by the .htm files.
6. When migrating from WinHelp to HTMLHelp there seems to be an issue with
context sensitive help. It appears all this information is lost when converting
is done?
Yes, unfortunately there is not a convenient one-to-one conversion mechanism
in the basic tools we provide. If you use a tool like RoboHelp, you may be able
to more successfully import your .hlp source and convert it to an HTML Help
project.
Finishing up the HH Workshop conversion
HHPmod (http://post.queensu.ca/~penstone/) is 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. Here are the project relationships:
Download from Sid Penstone site at http://post.queensu.ca/~penstone/
Sid Penstone have written some additional notes summarizing some of the problems encountered in converting from WinHelp to HTML Help, and some suggested fixes.
Version 3.1.13 Released 2010/08/14 New Wizard Interface; Extract the text files needed to support popups, and automatically insert all of the necessary Javascript text in the .htm files to recover the Help file popups. It also writes the cshelp.txt file and other support files for application popups. Inserts Javascript Popup commands in .htm files. .. Version 2.5.9 Released 2008/09/25 Removed limit on number of topic files - (tested with >2000 files); Detects topics with "hot spots"; detects problem comment formats in alias files. (Intermediate file versions 2.5.1 etc. were internal Beta) Version 2.4.8 Released 2008/02/20 Fixed a bug that interfered with selecting the new folder under some conditions. Cleaned up "HTML Options" operation. Version 2.4.7 Released 2007/09/27 Fixed a bug that caused an error rewriting HREF links associated with multiple Topic ID's under some conditions. Version 2.4.6 Released 2007/08/29 Removed file date checking function. If a user created a new version of the HTML project using HTML Workshop in the same folder as an earlier version, the .htm files kept the old creation date but got a new modification date, so that it looked to HHPMod like they had been edited. So HHPMod complained incorrectly. Functionally identical to Version 2.4.5. Version 2.4.5 Released 2007/08/23 Handles files with Unicode headers; cleaned up some bugs in handling context IDs; updated Help file. Version 2.3.15 Released 2007/08/14 Handles duplicate Topic ID's; complains if .htm files may have been edited; miscellaneous cleanups. Version 2.3.14 Released 2007/07/27 Fixed a bug that caused program to fail when there was no old alias data. Version 2.3.12 Released 2007/07/11 Fixed a new bug that caused program to fail when there was no context-sensitive data. Version 2.3.11 Released 2007/07/09 Automated extraction of context-help data from the old WinHelp file. Added reports for scans and rewrites. Fixed bug when rewriting alias file a second time. Version 2.2.14 Released 2007/06/28 Fixed several bugs. Changed handling of Map and Alias files. Updated Help files. Added option to use HTML style sheet. Thanks to Thomas Schmidt for suggestions and testing. Version 2.1 Released 2007/05/16 Fixed bug that dropped multiple HREFs on the same line Version 1.1 Released 2007/04/02
Batch convert
If for some reason the conversion doesn't work, you may need to Download HTML Help DLL Registrar or to download and re-install HTML Help Workshop. Alternatively, Ralph Walden, the original Microsoft Help guru, offered this suggestion:
"Here's an undocumented feature that might help you. Using Notepad or some other ASCII editor, create a file with the extension ".hcw" as in convert.hcw. The first line in this file should point to the full path of your HPJ file, and the second line should point to the full path of the HHP file you want to create, as in:
C:\_WinHelpToHH\wh_project\winh_hh.hpj
C:\_WinHelpToHH\hh_out\winh_hh.hhpNext, open that file in HHW -- you will probably see a quick flash as a dialog box comes and goes, and then no further messages -- however, your help project will be converted.
Note that you can use this to convert multiple projects at once -- each two-line pair contains the name of the HPJ followed by a line with the HHP.
Loading the .hcw file into HHW (right mouse click) will convert every pair in the file."
Automatically create contents file (.hhc) when compiling
The help table of contents (.hhc) file is a sitemap file that contains the topic titles for your table of contents. When a user opens the table of contents in a compiled help file and clicks a topic title, the HTML file associated with that title will open.
If you don't have a .cnt file at all you can use a feature of HHW to automatically generate a table of contents.
Note:
I recommend to use it only once to generate a .hhc file unless you really want to use this feature.
If you make changes to a contents file that has been automatically generated, you will lose them if you compile the project again. To prevent this, make sure the Automatically create contents file when compiling check box is cleared before you recompile.
- Open a project (.hhp) file.
- Click Change Project Options (Specifies files, compiler, window, and other project settings.) , and then click the Files tab.
- Click Browse, next to the Contents file box, and then locate the folder that you want to store your contents file in.
- In File name box, type a name (using .hhc for the file name extension e.g. "winh_to_hh.hhc") for your contents file.
- Click Open. The name of your contents file and the full path appear in the Contents file box.
- Select the Automatically create contents file (.hhc) when compiling check box.
- In the Maximum head level box, click the maximum heading level you want entries generated for in your contents file. For example, if you click 3 for the maximum head level, entries will be generated with <H1>, <H2>, and <H3> heading tags.
- Compile the project
..
![]() |