Introduction

This file is a "crib sheet" of issues involved when trying to generate Windows help files, particularly when programming your own applications using DevStudio. It's not a tutorial, just a collection of snippets I wish I'd known before I got started.

If it helps just one person avoid the hassle I had finding this out (or indeed if it saves me the hassle many months from now), then it's all been worth it.

I first wrestled with these issues when developing AscToHTM (http://www.jafsoft.com/asctohtm/) the text to HTML converter used to generate this HTML page from this source file .

If you have any comments on this page, especially if you have any corrections/further enlightenment for me, please email me at feedback@jafsoft.com

Cheers, Jaf

Introduction
File Extensions
File names
Key tools used
Editing a .rtf file to make help
Building the help file
DevStudio setup
Problems
Miscellaneous

File Extensions

Extension	File description
.hpj	help project files
.hlp	help files
.cnt	help contents files
.gid	help index files. Generated by Windows the first time you do a search on the help file and can be deleted
.hm	files contain application IDs extracted by makehm from resource.h files

File names

• Contents file should have same name as .hlp
• the Help file should have same name as .exe.
• the .exe file will have the same name as the .dsp file

As far as I know, these relationships are fixed. Change one, you must change them all

• the Help project file can be what you like. You configure the help file that it generates, and you can change its name in the .dsp file should you want to.
  

Key tools used

• MAKEHELP.BAT, executes the help generation inside DevStudio. An initial copy is generated when you create a project, but it isn't maintained as you add configurations.
  
  
• MAKEHELP.BAT processes the resource.h files of your project to create a new .hm file. If resources are shared between projects you may occasionally need to delete (or rename) these .h files, and edit the resourec to get a new and up to date .h file so that the resulting .hm file contains all new controls.

Sometimes it may be necessary to manually copy #define lines from one .h file to another.

• HCW.EXE is the help compiler used. It can be run standalone on .hpj help project files
  
  
• MAKEHM.EXE is a tool used to parse resource.h files and add any resource IDs as topic IDs listed in a .hm file
  
  
• you'll need a tool to generate .rtf files that can cope with underlining, hidden text and footnotes. Word is fine for this, but I suspect WordPad can't cope.
  

Editing a .rtf file to make help

(Note, there are tools on the market that will edit and generate Windows

Help files for you, but I've never used any so I can't recommend any).

• Each topic is separated by a page break.
  
  
• Custom footnotes configure the behaviour

# - Topic ID
K - keywords
$ - Topic Title

i.e. you need to add three footnotes per topic to get the full benfit. It's a good idea to define a Word Macro to do this for you before you go mad.

• The title appears in the Index. If you have lots of titles of the form

  Same Text : different text

the index nicely aligns all the "different text" values and avoids duplicating the "same text"

• Topic IDs are usually of the form ID_NAME... Those generated by your application have an H in front of the resource name, e.g. HIDD_MY_DIALOG is the help topic for a dialog called IDD_MY_DIALOG. The link is made via the .hm file generated by MAKEHELP.BAT (see below)
  
  
• Hyperlinks are achieved by
  
  

  • underlining the text, and then
  • immediately following with the help ID (e.g. HIDD_MYDIALOG)

The ID should be marked in Hidden Text. A Single underline causes a pop-up link. A Double underline moves you to the new topic when clicked.

This is unbelievably painful in Word so either disable auto-select, or define a Word macro to do this for you.

• When compiling, open the .rtf file in Word, with Hidden Text visible so that you can search for references to topics. Also have the footnotes window open.
  
  
• Editing in the footnotes is not like in the main window. In particular you can't remove footnotes by selecting and pressing delete.
  
  
• Each footnote gets a one-character display in the main window. They're very fiddly to interact with, so use the footnotes window.
  
  
• There are more tricks that I don't know about, for example coloured backgrounds on a header, and embedded images.
  

Building the help file

• help compiler is HCW, and is usually associated with the .hpj extension
  
  
• contents files (.cnt) can be edited more or less directly (albeit clumsily) inside HCW.
  
  
• HCW issues warnings and notes, e.g. for jumps to topics that don't exist.
  
  
• Some versions of RTF don't work with some versions of HCW. If in doubt, use an older version of Word and a newer version of HCW. The problem is the newer RTF that is generated (I forget the symptoms). I had problems using RTF generated by Word 97 with the HCW that came with DevStudio 4.2
  
  
• Sometimes older RTF files will start numbering paragraphs in help. The problem if due to automatic numbering features added to later RTF. I forget exactly how I fixed this, but it involved removing all lists (which was a pain).
  

DevStudio setup

• help resources are placed in a .\hlp directory
  
  
• help source file is .rtf (usually AxfDlg.rtf or some such), and is liable to drag in support for the File menu etc. If you change the name of this .rtf file, you'll need to change the name in the .hpj help project file.
  
  
• MAKEHELP.BAT is created when the project is created, but doesn't appear to be updated as configurations are added.
  
  
• topics file is .hm and is generated by MAKEHELP.BAT each time the project is rebuilt (see below)
  
  
• MakeHelp creates help files as follows

1) uses makehm to add resource #defines to the .hm file

• for each .h file
• for resource.h (you'll need to add others)

Several passes are made, one for each .h file/resource type combination. If you use additional resource files, or if your resource file is not resource.h you'll need to edit MAKEHELP.BAT accordingly.

2) copies results to Debug and Release directories. It does this regardless of what

build you are doing. Thus a Debug build is liable to overwrite your Release help file.

If you add extra configurations to your project, you'll have to manually edit MAKEHELP.BAT to copy to the new project subdirectories.

• MAKEHELP.BAT often doesn't work standalone. You may need to add CD and PATH statements so that makehm and relative pathnames all work.

.dsp file

• to make help, add entry as follows, changing "Project" to your Project name. the same name is used for CFG name and .hpj file
  

                SOURCE=.\hlp\Project.hpj

                !IF  "$(CFG)" == "Project - Win32 Release"

                # Begin Custom Build - Making help file...
                OutDir=.\Release
                ProjDir=.
                TargetName=Project
                InputPath=.\hlp\Project.hpj

                "$(OutDir)\$(TargetName).hlp" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)"
                        "$(ProjDir)\makehelp.bat"

                # End Custom Build

                !ELSEIF  "$(CFG)" == "Project - Win32 Debug"

                ....

                !ENDIF

Problems

• if you get "topic does not exist (error 129) check your .hm file was generated correctly, and that you had a topic for the ID entered
  
  
• if you get "can't find help file" check the following
  
  

  • .hlp file is in same directory as .exe file
  • .hlp file has same name as .exe. If not, edit your project files
  • .hlp file is being built. If not, check your .dsp setup

Miscellaneous

• Help Windows remember the size they were last time they were displayed. This information is lost each time a new version is built.

home - news - search this site - feedback - contact us Products: products - ordering - developers - discussion - documentation Resources: introduction to the internet - search engines - web robots - other stuff