Mega Code Archive

Helphowto

Creating a Windows Help File. (Notes by Richard Ebbs, Feb '98) As usual on-line Help is written by techies with negligible empathy for other human beings who assume that you know most of it anyway... (yawn)... So here hopefully I'll set down succinctly the BASICS! Use a text editor that allows you to save a file in Rich Text Format (eg most versions of Word for Windows). Note: I have found that sometimes versions of Word after version 2.0 do not save an RTF file correctly, so the best solution to this problem is to use Word v2.0. Unless your Help system is going to be enormous, you can put ALL of the Help information in one RTF file. The most important things to create now are topics. Some planning may be in order of course. TOPICS are created by inserting a) a hard page break just before the topic, and b) a footnote (see below for info on the use of # and $ characters). However (and the HCW utility that is bundled with Delphi for making Windows Help files won't tell you this) the way you use the footnotes facility in Word is very important indeed. Do not use 'standard' footnotes. When you select Insert/Footnote a wee dialogue box appears. Select Custom Mark, and then type in the character used by the Help Compiler to signify the kind of footnote ie: # for a TopicID, $ for a Topic Title, K for a keyword, and so on. Then click on return and type your TopicID, or Topic Title, or Keyword (or keyword-list with each keyword separated by a semi-colon) into the footnote window. Do not hit return after each entry in the footnote window. Also, it's best to type things in with no spaces, eg 4 #Intro where the Intro topic identifier is typed in immediately after the hash. Bundled with these notes is an example RTF file, and also the Help Project file and the Help Contents file for a complete Help System- see Crossword.RTF first of all (by loading it into Word and selecting View/Footnotes). There are many topics here, and as you will see, adjacent to each topic, or '#', footnote, there is a '$' footnote which is the title for that topic. The compiler will warn you if you have untitled topics. There are also many keywords, defined using 'K' footnotes. If you want to set up hotword links that enable the user to jump somewhere you can do, but this example is best kept simple. When you have defined things in the way described above, then choose Save As and save the file as a Rich Text Format file. Now it's time to use Delphi's Help Workshop… Help Workshop is a program that you use to create Help (.hlp) files and edit project and contents files. Help Workshop takes the information in the project (.hpj) file to combine the topic (.rtf) files, and other sources into one Help file that can be viewed using the Microsoft Windows Help program. You will find HCW in the Delphi folder accessed from the Program menus. Start it up. When you click on File/New in HCW, you have the option of dealing with various kinds of file. You will definitely need an .HPJ file, since this is a project file required in the compilation of your Help system, and you may well need a .CNT file too- this is a contents file, and a requirement if you mean to set up your Help to have a wee window with Contents, Index and Find on three wee tabs, which is neat and well worth doing as it's nae sae difficult. First though, specify a name for your project (.hpj) file. This will probably want to be the same as the name of your application. Save it immediately (HCW is weird like that) and then choose Files and Add and provide the names of your topic file(s). Save the project file again. Click on compile. Hey presto, you've got the beginnings of a Windows Help File. Now for the Contents. Click on File/New in Help Workshop again, but this time specify a file of type 'Help Contents' or '.CNT' file. A window appears wherein you must give various particulars. In the Default Filename box, type the Help filename that most of your topics are in (without the .rtf extension). (eg: Crossword). In the Default Title box, type the text you want to appear in the title bar of the Help Topics dialog box. (eg Crossword Help). The next thing is to define contents categories that are useful to the user. Say, for example, that you want to provide the user with immediate access to the introduction, that is the FIRST topic defined in your RTF file. Well first of all unless you tell HCW that your default topic is to be something other than the first, it will come up first in the help window, BUT also you want the user to have immediate access from the contents window. Click on Add Below. A wee dialogue box appears prompting you for 1) The title for this category. This text will appear to the user in the Contents window. 2) The TopicID of the topic you want them to jump to when they click on the category in the Contents window. In this case it will be #Intro or something similar. (And of course what you type here must exactly match the text of the TopicID, minus the hash at the beginning). 3) the name of the .hlp file that will finally contains this topic eg Crossword for Crossword.hlp (it's not necessary for you to type the extension). A time-saving device here is open up your original RTF file in Word, and choose View/Footnotes and then select all of the footnotes by mouse dragging, and copy them to Notepad so that you can have this open on the desktop while you're filling in the topic details for the help contents file in Help Workshop… The example above will result in the appearance of a small question mark in the Contents window against the name of the category. BUT you might want to group categories under a heading. Simple. Still in the Contents file definition window (as above), after clicking on Add Above or Add Below, tell it that you want a heading (check the wee check box). This will result in a book icon appearing to the user against whatever text you type in here, so then it's simple to click on Add Below to define the individual topics that appear when the user clicks on the book icon. If you have got keywords defined in your RTF file (achieved by using 'K' footnotes) then you will also want to create a Help file that access these via an Index tab and a Find tab. So, if you do have such keywords defined, then in HCW with your .cnt (Contents) file loaded, you should click the 'Index Files' button (bottom right). Then click add. Then type in your Help file title (eg Crossword) and the name of the final Help file (eg Crossword.hlp). Piece of piss? Now go back to File and Save your .CNT file, and then compile the contents file. Whatever kind of file you're dealing with in HCW it always likes you to save your files before doing anything else (like compiling) and I've just saved you a lot of frustration by telling you this… You don't need to compile the Contents file. Now load up your project file again and click on Options and then click the Files tab. Type the full name of your new Contents file into the Contents File input box (eg Crossword.cnt). SAVE the project file again, and then compile your project file. OK? If not, then deal with the cock-ups back in Word, amending the file as best you can when you've made sense of the compiler error messages (like 109, or 207 -nasty!). If all is well you now have a working Help system with topics and Contents and an Index and a Find facility that allows the user to find any text in Help. This can be run alone by clicking on the Help icon or you can run it from a program. Note that doing it this way you need your .CNT file to be there in the same directory as your .HLP file (which is the result of compilation). If you want to run Help from Delphi, include this kind of code: procedure TCWForm.HelpButtonClick(Sender: TObject); begin Application.HelpFile := 'NameOfHelpFile.hlp'; Application.HelpCommand(HELP_CONTENTS, 0); end;