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.
The next step is to export the separate HTML files (if necessary). In H&M, this is accomplished by generating ‘Browser-based Help’ (via ‘File|Compile Help File…’ or the toolbar). First, however, you will want to click ‘Customize Browser-based Help’ and make a few changes to the default options. On the ‘Layout’ page, select the page layout that puts everything in the same window (i.e., no frames, no scripts). Next, on the ‘Popup Topics’ page, select ‘HTML encoded topics’, which should remove any Javascript. Finally, on the ‘HTML Export Options’ page, change the ‘Extension for HTML topic files” to “.html” (from “.htm”).
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.
Hello Gregg,
Very interesting article, thank you for publishing it! Please let me add a suggestion. You write, that it is necessary to insert an <a name=”topicid” /> tag into every page and suggest that one uses a “HTML code object” for this task.
This is not necessary. There is an even easier way to do this with H&M: change the topic HTML page template and implement the tag right after the <body> tag. In the template, change:
…
<body>
…
to
…
<body>
<a name=”<%TOPICID%>” />
…
This modification writes the topic anchor automatically. Note that the variable <%TOPICID%> returns the topic ID exactly as you enter it in H&M, including case sensitive letters.
Thanks! This is a great tip, especially for somebody just starting a new help file. In our case, we have very explicit naming requirements, and a help file with rule topics (already written) for 725 games, so we have to adjust all of those topic IDs (easy in H&M), but were I starting from scratch, I would definitely be using your method.
By the way, thanks for making Help & Manual such a great tool (even if I personally find the ribbon interface to be a step backwards from a proper menu :)).
To make it simpler for other H&M users, here is how the above is done:
In H&M 5, simply open ‘Configuration’ in the ‘Project Explorer’ (on the left), select ‘HTML Page Templates’ and ‘Default’ under that, then add “<a name=”<%TOPICID%>” />” at the appropriate location (after the <body> tag).
In H&M 4, select ‘File|Compile Help File…’ (Ctrl+F9) from the menu, or press the equivalent toolbar button, select the ‘Browser based Help’ output format, and click on the ‘Customize Browser-based Help’ link. From there, select ‘Topic Pages’, enable the ‘Let me edit HTML code directly’ checkbox, and then edit the template (as above).
Edit and enjoy!