Building an HTML Help File
The first step in implementing Apple Help is building an HTML help file. Apple Help is the default help system in Mac OS X, and it is fundamentally a system for displaying HTML 4.01 from an application. In order to use some (or any) of the features of Apple Help, one must do some minor customization, which is what I intend to describe here. (The actual writing process is left as an exercise for the reader.)
For an overview of Apple Help, see this Apple Help Programming Guide.
Any decent HTML (or text) editor can be used to produce the necessary help files, but since ours is a help system for a product available on both Mac OS X and Windows, it makes sense to start with a full-featured help editor under Windows. In our case, we use Help & Manual, which is an excellent and capable product. (Note that we still choose to use the older H&M 4, since version 5 added the silly ribbon toolbar interface.)
Starting with a help project appropriate for Windows HTML Help (.chm), and with a tool that either works with or exports separate HTML files, there are only a few extra steps required to make an equivalent version for Apple Help. In H&M, you use the ‘Browser-based Help’ option to write the necessary HTML files (as described later).
The common method of accessing a topic in HTML Help (as well as in the older WinHelp format) is via help context numbers. Apple Help, on the other hand, uses a named anchor tag for each topic that needs to be accessed directly from an application. For example, for a topic referenced as ‘contents’, you would add the following HTML tag to the topic:
<a name="contents" />
A similar tag should be added to every desired topic page, each with a unique name. In H&M, this can be done by using the ‘Insert|Plain HTML Code…’ menu option, or you could edit the HTML directly, of course. I found it most useful to have the basic tag on the clipboard, paste it onto each page, and then directly edit/add the name portion.
Important Note: Do not use spaces or capital letters for the topic names. Apple Help seems to have trouble finding such tags, so context help and searching may fail.
Once your help files are together, you need to add two custom meta tags to the header of the main help page (the one you want to display when the help is opened generically). The “AppleTitle” meta tag sets the title of the help file, and the “AppleIcon” meta tag sets the name of the help icon (described below). For Pretty Good Solitaire Mac Edition, which has all the help files in a ‘Help’ folder, we add the following lines inside the page header (<HEAD>) of our contents page, just after the title (<TITLE></TITLE>):
<meta name="AppleTitle" content="Pretty Good Solitaire Help" /> <meta name="AppleIcon" content="Help/help.png" />
The help icon (‘help.png’, in the above example) should be a 16×16, 32-bit image (with alpha transparency) that represents the help file, usually a small version of the application icon. Place this image in the same folder with all of the HTML files. Note that Apple Help in recent versions of OS X do not display the help icon prominently (if at all), but help icons were important in earlier versions.
Finally, in order to appear similar to other Mac applications, you will want to change the fonts in your CSS (you did use CSS, right?) to prefer ‘Geneva’ over ‘Arial’ for the display font. H&M generates a ‘default.css’ file, so to make this change, you need only replace each instance of “font-family: ‘Arial’;” in this file with “font-family: ‘Geneva’, ‘Arial’;” and you are done.
As a final hint, if you are using Help & Manual, you can provide a link to the keyword index (automatically generated) by manually adding a link similar to the following (for the ‘pgsme’ project):
<a href="pgsme_kwindex.html">Help Index</a>
At this point, you should have a folder containing all of the HTML files for your help system, with the necessary tags, and a help icon file. Now, just prepare to transfer these files onto your Mac development system and wait for the second installment, in which I will explain how to generate the Apple Help index and add the help files to an Xcode project.