Mega Code Archive

Writing html help files

How to write HTML help files for Delphi. Writing HTML Help files by Vegard A. Larsen (originally written for UNDU, the Unofficial Newsletter for Delphi Users, adapted for www.HowToDoThings.com) After I had written the application Diary Defender, I did feel the need to write a decent help file to go with the package. Well, I did what I always do, as I am a freeware developer, operating with almost no money available. I found out which help writing programs existed, and checked if any of them were freeware. Well, as it turns out, the closest I got was HelpScribble, which is shareware. On that page I noticed the HTML Help Workshop, from Microsoft, which were indeed free. This is what normally have been used as the compiler for these third party help writers, but as I now saw, it was not impossible to write help files using only this tool. Some of you may have heard of Help Workshop, which does almost the same, only for normal help (.hlp) files. After what I recall, this was extremely complicated, and it was let down badly by the documentation (and hey: this is a help writer program). Well, I decided that it should be possible write this help file only using the HTML Help Workshop and a HTML editor. I quietly sat down and read through the help files that came with it, but this time too, no tutorial were available (shame on you, Microsoft!). So that's when I decided to write this article. I have decided to make this as simple as possible, as help writing is not always as easy as it seems. What you need before you begin: HTML Help Workshop A decent HTML editor (or you can use Notepad if you are talented enough)). To get you started, I recommend you assign a separate directory for this tutorial. Create your first HTML file (I recommend it to be the welcome/contents page) and save it in this directory. I called mine welcome.htm. After you have simply created the page (it doesn't need to contain anything, just the needed <BODY>, <HTML>, and similar tags for it to be a complete HTML file). Fire up HTML Help Workshop (from now on: HHW). Select File, New, and then Project. Skip the first screen by clicking Next, and specify where you want your help file to be created (use the same directory you created above). Click Next, and select the last box (HTML files), and click Next again. Add your HTML file, and click Next, then Finish. You will now be brought to the main window of HHW, were you will be spending a lot of time from now on. Under the [FILES] section in the left frame, you can see that the HTML file you created earlier is present. You will need to add all the HTML files of your project to this section, and this is done by clicking on the second button, counting from the top. Now click on the Contents tab of HHW. Select Create a new contents file when asked, and click OK. Save it in the same directory as before (I am going to assume you have understood this from now on).You will see a completely empty list, and this is what we are going to change next. Right click in the empty listbox and click Insert Topic. In the Entry Title editbox, write whatever you want ("Welcome" would be appropriate), and click Add. Select the only file in the list (it will be listed with the same name as you specified in the HTML <TITLE> tag), and click OK twice. Now you will have one item in the list. Now, click on the Index tab of HHW, and select Create a new index file when asked. You will see a new empty listbox. I'll fill this out in due time. Now you can start creating your second HTML file (and your third, fourth...). Add them all to the Project file list (second button from top). You do not need to create all the files before you start building the file, it is often a good idea to add one file at a time to the project, with complete keywords and were they are supposed to be in the contents list. When you have created and added one or two files more, move back into the Index tab. Right click and select Insert Keyword. Type the keyword, and then click Add. You can associate several files with one keyword. Add more keywords as you go. You can also create sub-key-words, by creating a normal keyword, and moving it by using the arrow buttons (on the toolbar). Move back to the Contents tab. Add Topics and Contents for the files you want to use. You can move these similarly by using the toolbar arrow buttons. Although this is not a very thorough tutorial in how to write help files, I feel it covers what you need to know when you are about to document your program. Experimentation is not a bad thing, especially with a documentation that never bothers to learn users the basics of HTML Help writing. The documentation of HHW have got a simple part (such as "Designing a help system") and a over-technical part ("HTML Help References"). Anyhow, HHW is not a bad program, it is simply let down by it's documentation, and you will notice this when you get used to it's interface. Hope you enjoyed this mini-tutorial. Microsoft had to change the API used to access help functions when they created the HTML Help (HH) system, and therefore the implementation of help in Delphi has become somewhat invalid. To get around this problem I downloaded a freeware kit from www.helpware.net. It is supposed to make the process of implementing a HH file into your application a breeze. When I first looked at the documentation for this kit, I saw that all that came along with it was a simple text file. However, I quickly realized it was the only documentation needed. In this article I am going to set the focus on the function HtmlHelp, used to bring up a HH window displaying any topic you'd like. The topics are found by using the filename of the topic you want to bring up, e.g. if one of the files in your HH file is named "versionhistory.htm", the following call will bring up the HH file with the Version history topic: HtmlHelp(GetDesktopWindow, 'C:\help.chm::/versionhistory.htm', HH_DISPLAY_TOPIC, 0); GetDesktopWindow can be replaced by a simple 0, but the Helpware Group recommends use of GetDesktopWindow. Remember, the example above is a bad way to do it, you would have to have a variable path to the file (do not use Application.HelpFile directly).