$_$_TABLE_MIN_COLUMN_SEPARATION 2 $_$_TITLE Jaf's crib sheet for creating Windows help files, with DevStudio $_$_CHANGE_POLICY background colour : FEF4CF $_$_CHANGE_POLICY background image : ../../pics/wpaper.gif $_$_CHANGE_POLICY unvisited link colour : red $_$_CHANGE_POLICY text colour : 800040 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 jaf@jafsoft.com Cheers, Jaf $_$_CONTENTS_LIST 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. - 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 $_$_BEGIN_CODE 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 $_$_END_CODE 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. $_$_INCLUDE ..\..\data\a2hfooter_level2.inc