< Previous PageNext Page > Hide TOC

Help Book Registration

This chapter describes how to make sure your completed help book is registered so that users—and your application—can access it. When a help book has been registered, it becomes available from the Library menu and from the application Help menu. If the help book is listed in the application’s Info.plist file, it is registered automatically when the user chooses application help from the Help menu or from a help button. You can also register your help book by calling the AHRegisterHelpBook function during application startup. If you are creating a tool or application for Mac OS X, you should read this chapter to learn how to add your help book to your software product.

In this section:

Where to Place Your Help Book Folder
How to Register Your Help Book

Where to Place Your Help Book Folder

Help books, like other resources that are language or region-specific, are kept in localized resource directories, named for their language or region and identified by the .lproj extension. These localized resource directories are placed in the Resources directory of your software bundle.

For example, if your application is localized for English, French, and Japanese audiences, your application bundle should contain a localized resource directory for each language. You should place a help book folder with your application’s help content, localized for the target region, in each directory.

Figure 3-1 shows the contents of an application bundle. The folder containing the English-language version of the application help book is located in the English.lproj subdirectory of the Resources directory. For more information on localization of resources, naming conventions for .lproj directories, and bundle structure, see Bundle Programming Guide.

Figure 3-1  The location of an English-language help book in the application bundle.

Apple strongly recommends that you place your help book in your software bundle. When your help book is bundled with your software, it is installed and moved along with your software.

You can use the following procedure to install the help folder in the .lproj directory using Xcode:

1. In the main project window, select Resources in the Groups & Files pane.

2. From the Action menu, choose Add > Existing files (Figure 3-2).

   Figure 3-2  Adding help files in Xcode

   

3. Select the help folder in the Add Files dialog and click Add.

4. Select the “Create Folder References for any added folders” radio button and click Add (Figure 3-3).

   Important: If you neglect to perform this step, your help book will work as expected on your development system, but will not work when you transfer the help book to another system.

   Figure 3-3  Create folder references in Xcode

   

How to Register Your Help Book

For Cocoa and Java applications, you can take advantage of automatic help book registration by adding the help book name and location to your information property list (Info.plist) file. For Carbon applications, you must take the additional step of calling the Apple Help registration function, AHRegisterHelpBook.

You must register your help book to get the automatic help book support provided by the system. When you register your help book, the system creates a Help menu for your application, populates it with an application help item, and opens your help book when a user chooses this item. In addition, your help book must be registered for it to appear in the Library menu.

Cocoa and Java applications that use the Apple Help API to access their help book content must also call the AHRegisterHelpBook function before making any calls to other Apple Help functions.

Editing the Information Property List File

To register a help book, you need to include the CFBundleHelpBookFolder and CFBundleHelpBookName keys in your Info.plist file. The CFBundleHelpBookFolder key identifies the help book folder; the value associated with this key should be a string specifying the folder name. For example, here is how you would enter the name of the SurfWriter help book folder:

<key>CFBundleHelpBookFolder</key>

<string>SurfWriter Help</string>

The CFBundleHelpBookName key identifies the help book. The value associated with this key should be a string specifying the help book title, as defined by the AppleTitle tag in the title page of the book. For example, here is how you would enter the title of the SurfWriter Help book:

<key>CFBundleHelpBookName</key>

<string>SurfWriter Help</string>

If you are using Xcode to develop your software product, you can add these keys to your Info.plist file with the following steps:

1. From the main project window, select the name of the project in the Groups & Files pane.

2. Select the Info.plist file in the right pane

3. Add the help book folder and help book name keys to the Info.plist file, as shown in Figure 3-4.

   Figure 3-4  Editing the info.plist file in Xcode

   

If you have more than one help book, you can set the value of each of the CFBundleHelpBookName and CFBundleHelpBookFolder keys to an array of strings. However, if you use an array for the value of these two keys, you do not get automatic support for your application help item in the Help menu.

Note that your Info.plist file must also contain a valid CFBundleIdentifier entry. For more information on application packaging and property lists, see Bundle Programming Guide.

Using the Apple Help Registration Function

Applications that call Apple Help functions must first call the Apple Help function AHRegisterHelpBook to register their help book. You would typically do this during application initialization. Once your application has called AHRegisterHelpBook, your help content is accessible through the use of the Apple Help functions.

Listing 3-1 shows an example of how to register a help book using AHRegisterHelpBook.

Listing 3-1  Registering a help book with AHRegisterHelpBook

OSStatus RegisterMyHelpBook(void)

{

    CFBundleRef myApplicationBundle;

    CFURLRef myBundleURL;

    FSRef myBundleRef;

    OSStatus err = noErr;

    myApplicationBundle = NULL;

    myBundleURL = NULL;

    myApplicationBundle = CFBundleGetMainBundle();// 1

    if (myApplicationBundle == NULL) {err = fnfErr; goto bail;}

    myBundleURL = CFBundleCopyBundleURL(myApplicationBundle);// 2

    if (myBundleURL == NULL) {err = fnfErr; goto bail;}

    if (!CFURLGetFSRef(myBundleURL, &myBundleRef)) err = fnfErr;// 3

    if (err == noErr) err = AHRegisterHelpBook(&myBundleRef);// 4

    return err;

}

Here is what the code in Listing 3-1 does:

1. Calls the Core Foundation function CFBundleGetMainBundle to retrieve a reference to the application’s main bundle.

2. Calls the Core Foundation function CFBundleCopyBundleURL to get the path to the application bundle.

3. Calls the Core Foundation function CFURLGetFSRef to convert the path obtained in Step 2 into a file system reference (an FSRef structure).

4. Calls AHRegisterHelpBook, passing the file system reference obtained in the last step. Apple Help finds the help book located in the bundle and caches the name and location of the help book. Apple Help chooses which localized version of the help book to use based upon the current language of the system.

< Previous PageNext Page > Hide TOC