Adding Help Files to an Xcode Project

The second step in implementing Apple Help is integrating the help files into an Xcode project, so they will be properly added to an application bundle, and generating an Apple Help index file.  This article describes the process continuing from the HTML files generated in the previous blog entry (Part 1).  Be sure to read the comments there, too, where Alexander Halser of Help & Manual describes an alternative (and probably quicker) method of adding the necessary ‘name’ tags.

First, transfer the entire folder containing the HTML help files to your Mac OS X development system (as/if necessary).  [A discussion of how this is done is far below the scope of this article.]  The rest of this article assumes that this folder is named “Help”; rename the folder or adjust the instructions as appropriate.

Next, you will be adding the files to the application bundle.  Open your project in Xcode.  Highlight the ‘Resources’ group, right-click (or Command-click) it, and select ‘Add->Existing Files…’ from the context menu.  Choose the ‘Help’ folder and then click the ‘Add’ button.  In the next dialog box, mark the ‘Copy items into destination group’s folder (if needed)’ check box, select the ‘Create Folder Reference for any added folders’ radio button, and then click the ‘Add’ button.  This will create a folder reference in the project, such that the entire contents of the ‘<Project>/Help’ folder will be added to the bundle as a unit.  In other words, you can add, delete, or change files in that folder from outside Xcode and those changes will be reflected in the build without explicitly adjusting the project file.

If you want to add a localized help file instead (which is not a bad idea, even if translating the help file is not in the immediate plans), the above process is slightly different.  In that case, explicitly copy (or move) the ‘Help’ folder into the appropriate project language folder, such as ‘<Project>/English.lproj’.  Follow the same procedure (‘Add->Existing Files…’), but select the ‘<Project>/English.lproj/Help’ folder, and do not (or, rather, it is unnecessary to) mark the check box, but the radio button is still important.  In this case, you will see that instead of just adding a ‘Help’ subgroup to the ‘Resources’ group, Xcode will automatically add the group as ‘Help/English’ (or whichever language).  Repeat as necessary for additional languages.

Now that the help (HTML) files will be properly copied to your application bundle(s), you need to identify these files as the Apple Help files for the project.  To do this, open the ‘Info.plist’ file for the project, a property list that contains global project settings.  Right-click (or Command-click) and select ‘Add Row’ from the context menu, choosing ‘Help Book directory path’ [or ‘CFBundleHelpBookFolder’].  Edit the value of that row to be “Help”.  Using the same procedure, add a ‘Help Book main page CONTENT attribute’ [or ‘CFBundleHelpBookName’] row, and set its value to the identical string from the “AppleTitle’ meta name (e.g., “Pretty Good Solitaire Help” [sans quotes]).  You can now close Xcode.

Creating an Apple Help Index

In order for a user to be able to search your help file, you must create an Apple Help index file.  The tool you need for this is (the enigmatically named) Help Indexer, which should already be installed on your system in the ‘/Developer/Applications/Utilities’ folder.  (I find it convenient to create an alias to this particular utility in a more accessible location.)

Launch the Help Indexer tool.  On the first execution (and thereafter as necessary), you will want to set the utility preferences (‘Help Indexer->Preferences…’), as they determine the parameters for the Apple Help index (or indices) you will create.  In the ‘Index Style’ panel, clear the ‘Generate Panther-compatible Indices’ checkbox, unless you plan to support Mac OS X 10.3 or earlier.  (At this point, we only support 10.4 [Tiger] and later [Leopard and Snow Leopard].)  I recommend selecting the ‘Errors and warnings’ radio button in the ‘Logging Options’ panel, as including the status messages for large help files simply produces too much noise that could hide any valid warning or error messages.

To actually generate the help index file, once the tool is configured, is quite simple.  Click the ‘Select…’ button, browse to select/highlight the ‘Help’ folder, and click the ‘Open’ button.  Then, click the ‘Create Index’ button, and the process begins.  When finished, review the warning/error messages (if any), and then click ‘Quit’ to close the tool.  (Note that, if you do generate a Panther-compatible index, the messages are shown in a separate tab, and you may get a ‘Warning: [filename].html — Error parsing file.  Check validity of HTML.’ message for each file.  In our experience, we were unable to eliminate these warnings, but the indexing still seemed to work properly on the older systems.)

At this point, you can open Xcode and, if you look into your ‘Help’ group (added above), you will see that a new ‘Help.helpindex’ file has been added (as well as a Panther-compatible ‘Help idx’ file, if selected).  The advantage of adding the folder as a reference group, as noted earlier, is that changes to the folder contents (such as adding the index file) are automatically reflected in the project.  The corresponding disadvantage, however, is that these changes do not necessarily trigger a bundle rebuild, so after making help file changes, you will want to either clean your target (‘Build->Clean’ or Shift-Command-K) or explicitly incorporate the changes by right-clicking (or Control-clicking) on the project group that hold the help files and selecting the ‘Preprocess’ command from the context menu.

Now you have a fully indexed Apple Help system incorporated into your project.  All that remains is to add code to programmatically access the main help content, as well as individual topics, which I will cover in the third installment, so please stay tuned.