ADC Home > Reference Library > Technical Q&As > User Experience > Help Technologies >

Where should I install my help book, and how does Help Viewer locate it?


Q: We ship a help book inside of our application's bundle. Where should I install my help book, and how does Help Viewer locate it? And, what keys should we include in our Info.plist file so the book will be recognized by the Help Viewer?

A: For the help viewer to find your application's help content, you application should provide the CFBundleIdentifier, CFBundleHelpBookFolder, and the CFBundleHelpBookName plist tags. These tags are defined as follows:

CFBundleIdentifier - identifies your bundle to the system.

CFBundleHelpBookFolder - the name of your help book's folder.

CFBundleHelpBookName - identifies the name of the page in your help book that should be displayed when your application's help is chosen from the help menu. For example, the HTML shown in listing 1 defines a page named "Simple Help".



<HTML>

  <HEAD>
    <META HTTP-EQUIV="content-type" CONTENT="text/html;charset=iso-8859-1">
    <TITLE>Simple Help Page</TITLE>
    <META NAME="AppleTitle" CONTENT="Simple Help">
  </HEAD>

  <BODY BGCOLOR="#ffffff">

     <P>Simple Help!</P>

  </BODY>

</HTML>

Listing 1. HTML contents of the main entry page in a Help Book entitled "Simple Help".



Normally, an application will provide a separate help book for each language localization it provides inside of its application bundle. Figure 1 illustrates the appropriate location for an English version of a help book inside of an application's bundle.



Location of a help book named

Figure 1.Location of a help book named "Simple Help Book" in a Mac OS X application Bundle.



The bundle shown in Figure 1 together with the HTML shown in listing 1 can be used to illustrate appropriate usage of the CFBundleHelpBookFolder and the CFBundleHelpBookName plist tags. Say, for example, the HTML shown in Figure 1 is the contents of the file index.html shown in Figure 1. Then, the Help Book name (CFBundleHelpBookName) is "Simple Help", and the Help Book folder name (CFBundleHelpBookFolder) is "Simple Help Book".



Note:
For Mac OS X version 10.0, CFBundleHelpBookName is localizable, whereas CFBundleHelpBookFolder is not.



The Help Viewer application will use the CFBundleHelpBookFolder and the CFBundleHelpBookName plist tags to locate your application's help content. For Cocoa applications, help content is located automatically, but Carbon applications must explicitly register their application bundle's help book when they start up. This is done using the AHRegisterHelpBook routine as shown in Listing 2.



    /* RegisterMyHelpBook registers an application's help
    book.  It can be called as part of the application's
    initialization sequence.  Once it has been called, the
    application is free to use any of the other Apple Help
    routines to access and display the contents of their
    help book.

    This routine illustrates how one would use the
    AHRegisterHelpBook routine in their application.  */
OSStatus RegisterMyHelpBook(void) {
    CFBundleRef myAppsBundle;
    CFURLRef myBundleURL;
    FSRef myBundleRef;
    OSStatus err;

        /* set up a known state */
    myAppsBundle = NULL;
    myBundleURL = NULL;

        /* Get our application's main bundle
        from Core Foundation */
    myAppsBundle = CFBundleGetMainBundle();
    if (myAppsBundle == NULL) { err = fnfErr; goto bail;}

        /* retrieve the URL to our bundle */
    myBundleURL = CFBundleCopyBundleURL(myAppsBundle);
    if (myBundleURL == nil) { err = fnfErr; goto bail;}

        /* convert the URL to a FSRef */
    if ( ! CFURLGetFSRef(myBundleURL, &myBundleRef) ) {
        err = fnfErr;
        goto bail;
    }

        /* register our application's help book */
    err = AHRegisterHelpBook(&myBundleRef);
    if (err != noErr) goto bail;

        /* done */
    CFRelease(myBundleURL);
    return noErr;

bail:
    if (myBundleURL != NULL) CFRelease(myBundleURL);
    return err;
}

Listing 2. How your application registers its help book when it starts up.



References

The Apple Help SDK provides samples and documentaiton explaining appropriate layout of help books.

The Apple Help Documentation provides documentation about Help Books, calls for displaying specific help content, and tips for help content writers.


[Apr 09 2001]


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.