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

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

Key tools used

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

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).

# - 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 index nicely aligns all the "different text" values and avoids duplicating the "same text"

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.

Building the help file

DevStudio setup

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.

.dsp 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

Miscellaneous


 

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

Converted by AscToHTM