Authoring Apple Help

This chapter describes how to author help content for Help Viewer and organize it into a help book. Anyone authoring user help for Mac OS X should be familiar with the basic requirements of creating a help book and with the general guidelines for writing user help.

These are the basic steps for creating a help book for Mac OS X:

1. Design the help content.

2. Author the HTML help pages.

3. Organize the help book. This includes creating the necessary auxiliary files that Help Viewer uses.

4. Index the help book.

In addition, this chapter describes how you can include additional content, such as QuickTime movies and AppleScript scripts, in your help book and how you can localize your help book for other languages.

Designing a Help Book

The first steps in authoring your help book are identifying the topics your help must cover and designing a layout for presenting these topics. To this end, you may find it useful to create a topic outline. If the software product for which you are creating help already has existing documentation, you may be able to base your outline on this material. If you are creating a help book from scratch, there are a number of ways you can approach the outline. A few examples:

• Walk through the steps of the main task sequence in order. If you are writing help for a larger application, there may be several different task sequences a user would perform. For example, a productivity suite may have different task sequences for word processing, using spreadsheets, and creating presentations.

• List topics alphabetically.

• Go through each menu and menu item in the application sequentially.

Each topic should be simple enough to be described in a few short paragraphs on a single HTML page. If a topic is lengthy, you should consider breaking it up into smaller subtopics.

Here are some tips to keep in mind when designing your help book.

• Divide the information into overview information and tasks. Overview information defines terms and explains concepts important to an understanding of your software product; task information gives step-by-step directions for accomplishing a particular goal. You should generally place these two kinds of information on separate help pages to give users quick access to the information they want. You can link between pages containing overview and task information when appropriate. Avoid including ‚Äúfeature-oriented‚Äù pages, which describe application features but don‚Äôt tell users what they can do or how.

• Identify any information you think you‚Äôll need to give users more than once in a help book. You can write an individual help page to cover this information and link to it from other topics in the book to avoid duplication.

• Build pages around four central questions:

  • What can users do?

  • Why do they want to do it?

  • How can they do it?

  • How can they solve problems doing it?

  Depending upon the complexity of the task, a well-designed help page may cover each of the first three questions in one or two sentences and the fourth in two or three bullet points.

Authoring Help Pages

Once you have identified the subjects covered in your help book, you need to create HTML files for your help pages. To ensure that your help displays properly in Help Viewer, your help files should comply with the HTML¬†4.01 specification. Your main file‚Äîwhich contains the AppleTitle meta tag‚Äîshould conform to the XHTML¬†1.0 specification. For a comprehensive description of the HTML 4.01 specification, see HTML 4.01 Specification, W3C Recommendation 24 December 1999 (http://www.w3.org/TR/1999/REC-html401-19991224/). XHTML is described in XHTML 1.0 The Extensible HyperText Markup Language (Second Edition), W3C Recommendation 26 January 2000, revised 1 August 2002 (http://www.w3.org/TR/2002/REC-xhtml1-20020801/).

For an example of a help book to use as a starting point, see the files for Mac Help in /Library/Documentation/Help/MacHelp.help/Contents/Resources/.

Authoring Tools

You can author your help book in any application that generates valid HTML 4 files. Likewise, you can view your help book in any HTML 4–qualified browser; however, you should always test your help book in Help Viewer to ensure that your help book displays properly.

Creating Topic Pages

Each help page should cover only one topic, which can be expressed in a few short paragraphs. As mentioned in the section “Designing a Help Book,” your help book may contain both overview and task information. Overview pages define terms and concepts important to your application or offer other general information that users may need to know to understand your software product. For example, the help book page shown in Figure 2-1 describes application menus.

Figure 2-1  A help book page containing overview information

Task pages, on the other hand, offer a step-by-step description of the actions the user must take to perform a common task in your software product. The help book page shown in Figure 2-2 describes the steps necessary to change the background of a Finder window.

Figure 2-2  A task-oriented help book page

Topic pages typically include these elements:

• A title identifying the topic. In Figure 2-1, ‚ÄúAbout application menus‚Äù identifies the topic and indicates that the topic is informational, not task oriented. In Figure 2-2, ‚ÄúChanging a window‚Äôs background‚Äù indicates (by beginning with a verb) that the topic describes a procedure or task.

• The topic introduction. For an overview page, this section describes what the user will learn about by reading this page. For a task-oriented page, the introduction indicates what the user will accomplish by performing the task.

• Requirements for performing the task. For a task page, any conditions that must be met in order for the task to succeed should be mentioned up front, before the user begins the task. For example, if the help topic is "Burning a CD," the system requirements‚Äîsuch as the presence of a CD burner‚Äîfor burning the CD should be mentioned here.

• The task description. These are the steps that the user must perform to accomplish the given task. Overview pages typically do not contain this information.

• The topic wrap-up. This includes any information the user may need in order to wrap up any task described in the page. It is also a good place to include tips, shortcuts, troubleshooting information, and links to related help topics. For example, the last paragraph shown in Figure 2-2 gives a hint the user might need in order to see a large picture in their Finder window.

• Related topics. At the end of a topic is a list of links to other topics that are related to this one and thus might be of special interest to the user.

Printing A Page’s URL

While debugging a help book or examining a help book to learn how it was made, it can be difficult to figure out which file is the source of the page being displayed. To find the URL of the page of a help book, execute the following command in the Terminal application:

defaults write com.apple.helpviewer PrintURLInFooter YES

This command causes every page’s URL to be listed in the footer when the page is printed. The onscreen version of the page does not change. Figure 2-3 shows a printed help page with a URL in the footer.

Figure 2-3  URL printed in footer

Creating Navigation Pages

In addition to topic pages, you may need to create navigation pages for your help book. Users should be able to find most of the information they need by searching and navigating through links in your topic pages. However, navigation pages, such as tables of content, allow users to browse your help book and navigate to topics they want to learn more about without having a particular search topic in mind. You may consider providing a table of contents at the following levels:

• Top level

• Chapter level

• Topic level

Including a table of contents on the title page, at the top level of your help book, allows the user to select a starting point within your help book. A title-page table of contents gets the user started in finding help, even if they do not quite know what they are looking for. Figure 2-4 shows the top-level table of contents for the Mail application.

Figure 2-4  The title-page table of contents for Mail Help

As mentioned in “Designing a Help Book,” you should break complex topics with lengthy descriptions into smaller subtopics in order to keep each help topic short and focused. However, it may not be appropriate to include all of the subtopics directly in your main table of contents.

You can create navigation pages that contain links to sets of related subtopics. Figure 2-5 shows a high-level TOC page from Mac Help. If the user clicks one of the topics, a list of subtopics appears, giving information about each (Figure 2-6). By clicking one of those subtopics, the user can get an information or task page for that subtopic (Figure 2-7). Typically, this page also contains links to further information about this subtopic and to pages for related subtopics.

Figure 2-5  A high-level table of contents in Mac Help

Figure 2-6  A subtopic-level table of contents in Mac help

Figure 2-7  A task page for a subtopic in Mac help

Creating a Basic Help Book

Once you create the HTML files containing your help content, you must organize them into a help book. To do this, create a help book folder and include the following items:

• The topic and navigation pages. These are the HTML pages that you created for your help content, as described in ‚ÄúAuthoring Help Pages.‚Äù

• A title page (also referred to as the default, landing, start, or access page). This is the XHTML file that is displayed by default when the user first opens your help book.

• A help book icon. This icon is displayed next to your help book in the Library menu.

For an example of a help book to use as a starting point, see the files for Mail Help in /Applications/Mail.app/Contents/Resources/English.lproj/MailHelp/. (Note that you have to select Show Package Contents from the contextual menu to see the contents of the Mail.app bundle.)

Organizing the Help Book Bundle

Every help book must be enclosed in its own folder, which is in the Resources folder of the application bundle. The help book folder also contains a Resources folder. In the help books Resources folder, you put a folder for artwork that does not need to be localized and so is shared by all the localized versions of the help book. You then put as many localized versions of the help book as you need. At the top level of the localized help folder are the index file and the title page. The Application help bundle for the SurfWriter application would have the following structure:

• SurfWriter.app/

  • Contents/

    • Resources/

      • SurfWriter.help/

The structure of the English-language help folder for SurfWriter help would look like this:

• SurfWriter.help/

  • Contents/

    • Info.plist

    • Resources/

      • shrd/ <shared artwork>

      • English.lproj/

        • SurfWriter.html <title page>

        • SurfWriter.helpindex

        • ExactMatch.plist <see ‚ÄúSetting Up Exact Match Searching‚Äù>

        • InfoPlist.strings<localized values for Info.plist>

        • pgs/ <the rest of the content pages>

        • gfx/ <localized artwork>

        • sty/ <style sheets, generated list template>

        • scrpt/ <scripts>

The book‚Äôs icon and other nonlocalized graphics files are in the shrd folder. The pgs folder contains the localized HTML pages for all the help topics. The scrpt folder contains AppleScript and JavaScript scripts. The sty folder contains style sheets. Note that this is an example of a typical help folder, not a prescription for how you need to organize your help book. The index file, the title page, the exact match property list file (if any‚Äîsee ‚ÄúSetting Up Exact Match Searching‚Äù) and the localized values (if any) for the Info.plist should be located at the top level of the help folder.

The title page is described in the next section, ‚ÄúCreating a Title Page.‚Äù ‚ÄúSpecifying a Help Book Icon‚Äù describes how to add an icon to your help book. Index files are discussed in ‚ÄúIndexing Your Help Book.‚Äù The language names for the .lproj folders follow the standard Apple naming scheme, as discussed in Language and Locale Designations (Internationalization Programming Topics).

Referencing Graphics

The filepath reference in HTML <img> tags to artwork in the shrd/ folder should look like this:

On the <accesspagename>.html page:

 ../shrd/artworkname.jpg

On a content page in the pgs/ or other folders:

../../shrd/artworkname.jpg

The Info.plist File

Your Apple Help bundle must have an Info.plist file with these keys and values (all values are of type String):

Creating a Title Page

The title page is your help book’s default page, which appears when the user opens your help book, either by choosing the application help item from the Help menu in your application or by choosing your help book from the Library menu. The title page introduces your help book and serves as the entry point into the rest of your help content. All help books registered with the Help Viewer must have a title page.

There are many ways you can approach designing the title page for your help book. For example, the title page from Mac Help, the system help book, has a link to a help page that describes the new features in the current version of Mac OS X, a link to a page that introduces the capabilities of the system, and offers a number of links to help pages answering common queries to get the reader started.

Figure 2-4 shows the title page for Mail Help.

Specifying a Help Book Icon

When you register a help book, your help book becomes visible in the Library menu. If you provide an icon, Help Viewer displays this icon in the Library menu, next to the title of your help book. Adding an icon to your help book makes it easier for users to associate your book with your application.

To specify an icon for your help book, use the HPDBookIconPath key in the Info.plist file.

Figure 2-8 shows the Library menu, with each application’s icon next to the book title.

Figure 2-8  The Library menu

The icon file should be in the shared graphics folder (shrd/). The icon should be a 16-by-16 pixel version of your application icon, with a transparent background, saved as a PNG file. Note that the icon cannot be updated from a remote server. Only the local icon file is used by Help Viewer.

Indexing Your Help Book

To help users quickly find the information they need to accomplish their tasks, you should make your help book searchable by running the Help Indexer utility to create an index for the book. The Help Indexer utility is described in “Using the Help Indexer Utility.”

You should also include additional tags and metadata in your HTML help files to control how your help is indexed. Including this information improves the user experience of searching your help book by increasing the relevance of the results returned for searches of your help book and improving their appearance in Help Viewer. “Controlling Indexing of Your Help” describes how you can improve indexing and searching of your help book.

Controlling Indexing of Your Help

There are a number of tags that you can include in your HTML pages to control how your help content is indexed by the Help Indexer utility. In addition to indexing the text of your help topics, this tool indexes the following items:

• Keywords. Keywords allow you to specify synonyms or common misspellings for a help topic, ensuring that users who search on these alternate terms still get a hit on the relevant topic.

• Abstracts. An abstract is a brief summary of a help topic that is displayed when the user places the cursor over the topic in a list of search results. Users can determine whether they wish to learn more about the topic without actually loading the topic page.

• Anchors. Anchors allow you to uniquely identify a topic or section within a page. Anchors help you provide quick access to help content; you can specify an anchor as the destination of a link or use the Apple Help API to search for and display the content identified by an anchor.

• Segments. Segments divide a single HTML file into subsections, each of which can be indexed and returned as a separate hit in a search. Segments are particularly useful in help systems with lengthy topic pages.

Finally, you can specify which content in your help book should be indexed, as described in “Specifying What Is Indexed.” By using these various elements in your help book, you can greatly improve the search results for your help book and make your help book more easily accessible from your application.

Setting Keywords

Keywords are a set of additional search terms for an HTML help page. When a user searches your help book for a term that is designated as a keyword for a topic page, Help Viewer returns that page as a search result, even though the term may not appear in the body of the page. Using keywords, you can specify a set of synonyms and common misspellings for topics covered in your help book.

You can specify keywords for a help page using the keywords meta tag in the header of the help page‚Äôs HTML file. The following example shows keywords that you could set for a help page that describes how to use the Trash:

<head>

<title>Deleting Files</title>

<meta name="KEYWORDS" content="discard, dispose, delete, clear, erase">

</head>

Do not add keywords for terms that already occur on the page. Repeating a keyword that already appears on the page can cause the page to be given an incorrectly high relevance rating when Help Viewer returns it in response to a user’s query.

Adding Abstracts

An abstract is a brief description of a help topic that appears when the user places the mouse cursor over that topic in a list of search results.

Well-written abstracts help users ascertain whether a given page, returned as a search result, in fact contains the information they were searching for. For example, SurfWriter Help contains a page describing how to import files from other formats. The page’s title, “Importing Files,” gives the user some idea of the page’s contents, but you can provide a fuller description by using an abstract phrase such as, “SurfWriter can import files of the following formats: txt, rtf, pages, and doc.”

To add an abstract to a help page, use the description meta tag in the header section of the page‚Äôs HTML file. Here is an example of how to create such an abstract:

<head>

<title>Removing deleted messages</title>

<meta name="description" content="Permanently remove messages that you've deleted to save space.">

</head>

“Example of a search result showing an abstract” shows how such a page and its abstract show up as a search result.

Figure 2-9  Example of a search result showing an abstract

Setting Anchors

Anchors allow you to uniquely identify topics in your help book. When a user follows a link to an anchor, Help Viewer loads the page containing the anchor. If your link includes the specific file containing the anchor (such as SurfScript.html#anchor1), Help Viewer scrolls to the anchor location (if it is not at the top of the page). For example, assume that SurfWriter has a simple scripting language called SurfScript. In the help page for SurfScript, you could specify a unique anchor for each SurfScript command, enabling Help Viewer to scroll directly to the desired text when the page loads.

If you use multiple files for your help book, you can put an anchor at the beginning of each file and direct links to the anchors so that you don‚Äôt have to know the final locations of the help files when you code your HTML. To do so, you use the help:anchor URL provided by Apple Help in your link (see ‚ÄúCreating a Link to an Anchor Location‚Äù).

You can also use anchors to load an anchored page from within your application by calling the the NSHelpManager method openHelpAnchor:inBook: or, for C applications, the Apple Help function AHLookupAnchor. To continue the example, SurfWriter could provide an online lookup function that loads the help page for a SurfScript command by calling the openHelpAnchor:inBook: method and passing the appropriate anchor name when a user Option-clicks a command name in a SurfScript document.

If you need to access your help content programmatically—as you would, for example, if you provide contextually sensitive help—you should consider using anchors to make your help easily accessible from your application. Because you can change the location of anchors within your help book without affecting your product’s code, anchors provide a simple and maintainable way for your application to access specific topics within your help book.

You can create multiple anchors in a single file. This is especially useful if you split a file into segments, as you can use the anchors to scroll directly to the beginning of each segment. Segments are described in the next section, “Creating Segments in Help Files.”

You specify an anchor using the standard HTML 4 anchor element, as shown in the following example, which creates an anchor called SurfScriptCommand_OPEN in a help page describing SurfScript‚Äôs OPEN command:

<a name="SurfScriptCommand_OPEN"></a>

<!-- Here is the description of SurfScript’s OPEN command -->

You link to an anchor by using an HTML anchor element and a help:anchor URL:

<a href="help:anchor=SurfCmnd_OPEN bookID=com.mycompany.surfwriter.help">Open command</a>

The NSAlert, SFChooseIdentityPanel, SFCertificatePanel classes provide help buttons for dialogs. To display such a help button and link it to an anchor in your help book, use the methods setShowsHelp: and setHelpAnchor: in those classes. See NSAlert Class Reference, SFChooseIdentityPanel Class Reference, and SFCertificatePanel Class Reference for details.

Setting Anchors for Generated Lists

In addition to using anchors to jump to a location in a help book, anchors are used to implement generated lists (‚ÄúGenerating Lists from Anchors‚Äù) and exact match searches (‚ÄúSetting Up Exact Match Searching‚Äù). Unlike anchors used to jump to a specific page, each of which must be used only once, the anchors used for lists can be placed in any number of places. When you specify an anchor to generate a list, every page containing that anchor is included in the list. For example, the anchor corresponding to the ‚ÄúAccounts preferences‚Äù generated list in Mac Help is located in the pages for ‚ÄúAbout administrator accounts,‚Äù ‚ÄúAbout logging in and out,‚Äù ‚ÄúAbout passwords in Mac OS X,‚Äù and so forth. On the other hand, the ‚ÄúAbout administrator accounts‚Äù page (for example) includes a unique anchor used only in that file. The ‚ÄúAbout administrator accounts‚Äù page, therefore, contains one anchor used to jump to that page (mchlp1746) plus several other anchors used in generated lists, including the anchor used for the ‚ÄúAccounts preferences‚Äù generated list (almh10339):

<a name="mchlp1746"></a><a name="almh10045"></a><a name="almh10090"></a><a name="almh10339"></a><a name="almh10564"></a><a name="almh10334"></a>

Creating Segments in Help Files

A large help book may contain hundreds of individual pages. Rather than using a separate HTML file for each page, you can combine several pages into one file by dividing the file into segments. Help Viewer treats segments much like separate files; each segment in a file can have a different abstract, anchor, and keyword set. The following example shows how SurfWriter Help defines a segment and specifies its abstract and keywords:

<!-- AppleSegStart="Opening a File" -->

<!-- AppleSegDescription="How to open a SurfWriter file" -->

<!-- AppleSegKeywords="launch, read, look , examine" -->

<!-- Topic text goes here -->

<div id="pagetitle">

<h1>How to open a SurfWriter file</h1>

</div>

<p>To open a SurfWriter file, you ...

<p>

...

<p>

</p>

<!-- AppleSegEnd -->

The beginning of the segment is marked by the AppleSegStart command. If the segment has an abstract or keywords, they are specified using the AppleSegDescription and AppleSegKeywords commands, respectively. The content of the segment follows. The AppleSegEnd command marks the end of the segment.

Specifying What Is Indexed

By default, each file in your help book is fully indexed. You can use the ROBOTS meta tag in the HTML header of a particular file to control how that file is indexed. The ROBOTS meta tag supports the values shown in Table 2-2.

Apple recommends that you do not index a page that contains only links or graphics, or a page on which you don‚Äôt want the user to land as a result of a search. For example, if you have a sequence of pages that are linked in a series, you might only want to index the first page in the sequence. To specify that a file should not be indexed, use the ROBOTS meta tag with the value NOINDEX as shown in the following example:

<meta name="ROBOTS" content="NOINDEX">

Specify KEYWORDS as the value of the ROBOTS meta tag if you want the indexer to pick up only your specified keywords for use as search results. If you define segments in a file, as described in ‚ÄúCreating Segments in Help Files,‚Äù you can supply a value of SEGMENTS in the file‚Äôs header to specify that only the content of the segments is indexed. The ANCHORS value is useful for pages which you want to be able to retrieve using anchor lookup, but which are not useful as search results, such as your title page.

Using the Help Indexer Utility

Once you have finished adding abstracts, keywords, and any other indexing information to your help book files, you must run the Help Indexer utility on your help book. The Help Indexer utility creates an index file for your help content and stores it as a separate file at the top level of the help book folder. The index file contains links to all the words (or tokens) in your help files that are equal to or greater than the minimum term length, excluding any stopwords. You use Help Indexer preferences to specify the minimum term length and the list of stopwords.

Because the index file may be invalidated if you change or rearrange the content of the help folder, be sure to update the index file after the help book content is complete and all files are in their final location.

You can create an index for your help book by opening Help Indexer (/Developer/Applications/Utilities/Help Indexer.app) and entering your help book folder in the dialog that appears. You can also drag the folder containing the help book onto the Help Indexer utility, or execute the hiutil(1) command from a command line.

You must modify the default settings of the Help Indexer utility if you wish to do any of the following:

• Index a help book for a language other than English.

• Turn on the indexing of anchor information.

• Supply help content from a remote server.

• Specify a minimum term length other than three tokens (three is the recommended setting for character-based languages).

• Specify a list of stopwords.

• Have warnings or status messages returned in addition to errors.

Indexing for Languages Other Than English

Read “Localizing Your Help Book” for more information on indexing non-English help books.

Anchor Indexing

If you add anchors to your help book, you must index your help book with anchor indexing selected in the Help Indexer utility‚Äôs preferences. When anchor indexing is on, the Help Indexer puts information about the anchors in the index file and Help Viewer uses that information to follow the links to help:anchor URLs in your files (see ‚ÄúSetting Anchors‚Äù). Anchor indexing is off by default. If you don‚Äôt use anchors, or don‚Äôt want to use help:anchor URLs to link to your files, you can turn off anchor indexing. To toggle anchor indexing off or on, perform the following steps:

1. Click “Show Details.”

2. Click the checkbox labeled “Index anchor information in all files”.

Storing Pages on Remote Servers

As described in “Internet-Based Help Book Content,” Help Viewer supports Internet-based help. To provide updates to your help content via the Internet, you must specify a remote server from which to download updated help content. To specify a remote server for your help content, do the following:

1. Click “Show Details.”

2. Click the checkbox labeled “Use remote URL for missing files and updates.”

3. In the text field under this checkbox, enter the server address where your remote help content is available.

Help Viewer can also download updated index files from a remote server. If you specified a remote URL in your help book's Info.plist file, Help Viewer contacts the server and checks for an index file at that location. If an index file is present, and if it is newer than the locally stored index, then Help Viewer downloads the file.

You can control how long your help pages are cached, using the two meta tags shown below:

<meta http-equiv="Expires" content="Tue, 01 Jan 1980 1:00:00 GMT">

<meta http-equiv="Pragma" content="no-cache">

The first example sets a specific expiration date for the cached page. A 24-hour clock is used, and the time zone is included when specifying a particular expiration date. The second example tells Help Viewer that the file should never be cached.

Generating an Index Compatible with Different Versions of Mac OS X

Starting with Mac OS X v10.4, the Help Indexer utility can create index files that take advantage of the Search Kit features introduced with that version of the operating system. Improvements starting with Mac OS X v10.4 include the ability to:

• Extract a summary sentence from a help file to use when no DESCRIPTION meta tag is provided (see ‚ÄúAdding Abstracts‚Äù)

• Specify a list of stopwords (see ‚ÄúSpecifying a Minimum Term Length and Stopwords‚Äù)

• Specify a minimum number of tokens for indexed terms (see ‚ÄúSpecifying a Minimum Term Length and Stopwords‚Äù)

Help Viewer can use indexes created for Mac OS X v10.4 or later (file suffix .helpindex). If a help book uses an older index, Help Viewer reindexes the content on the fly.

You can specify a language-specific list of stopwords, as described in the following section, “Specifying a Minimum Term Length and Stopwords.” See “Indexing a Non-English Help Book” for more information.

Specifying a Minimum Term Length and Stopwords

Starting with Mac OS X v10.4, the Help Indexer utility enables you to specify the minimum length of terms to be indexed. For example, if the minimum term length is 3 tokens (the default), then the words “I,“ “to,“ and “at” are not indexed, but “and” and “but” are included in the index. Apple recommends using the default value.

To prevent commonly used or irrelevant words from being included in the index, you can also include a list of words‚Äîreferred to as stopwords‚Äîto be excluded from the index. In the Details section of the Help Indexer window, you can specify whether to use no stopwords or one of the language-specific stopword lists provided with the system. The provided stopword lists are the ones used by Apple, and should be adequate for most purposes. If you require your own list of stopwords, you must run the hiutil(1) tool using the -s option. See the manual page for hiutil for more information.

The provided stopword lists are located in a property list at /usr/share/hituil/stopwords.plist.

Instead of one of the standard lists of stopwords, you can specify your own list. A stopword list must be a property list (.plist) file with an array as its root element

Setting Error Verbosity

There are three levels of information you can log during a run of the Help Indexer utility: errors, warnings, and status messages. Errors are problems that prevent Help Indexer from creating an index. Warnings are problems that don‚Äôt prevent the creation of an index, but that might cause the results to be different from what you are expecting. Status messages indicate the progress of the utility so that you can check for expected results, such as anchors being indexed or pages being skipped due to the ROBOTS NOINDEX meta tag (see ‚ÄúSpecifying What Is Indexed‚Äù). You use the logging options section of Help Indexer to set the level of messages you wish to have logged. If any messages are generated, the log window opens after the utility completes execution (Figure 2-10).

Figure 2-10  Help Indexer log window

Running Help Indexer from the Command Line

You can run the hiutil(1) command from the command line. Type man hiutil for documentation.

Adding Specialized Content to Your Help Book

You can enrich the user experience of your help book by including additional resources such as animated tutorials, scripted tasks, and other multimedia content supported by Help Viewer. This section shows you how to:

• Embed QuickTime movies in your help book

• Automate tasks using AppleScript scripts in your help book

• Initiate Help Viewer searches from a link in your help book

• Link to anchors in your help book

Adding QuickTime Movies to Your Help Book

You can use QuickTime to create animated tutorials or demos for your help book. To link to a QuickTime movie, use the standard HTML embed tag. The following example shows how to call a movie file called SurfScriptDemo.mov located in the SurfWriter help book's shared folder:

src="../../shared/SurfScriptDemo.mov"

Running Other Applications from Your Help Book

You can launch other applications, such as media players or custom help applications, from your help book by using the standard HTML anchor element. Here is an example of how you would specify a link that opens an application called SurfScriptPlayer located in the SurfWriter Help folder:

<a href="/SurfScriptPlayer">

A better strategy than directly executing an application is to execute an AppleScript script that can handle errors such as a missing program, incorrect permissions, and so on. See “Automating Help Tasks with AppleScript.”

Opening an External Web Page in Help Viewer

When you include an http:// link in your help book HTML, Help Viewer ordinarily opens the link in the user‚Äôs default web browser. You can use the target="_helpViewer" attribute to cause the link to open in the Help Viewer window instead. For example, you can use a link of this sort to open a page on your customer service website in Help Viewer, making it appear to the user as if it‚Äôs part of your help book. The following line would cause the support page for iCal on the Apple, Inc. website to open in the Help Viewer window:

<a href="http://www.apple.com/support/ical" target="_helpViewer">Support Website</a>

Using Help URLs in Your Help Book

The URLs using the Help Viewer help: protocol, introduced in ‚ÄúHelp URLs,‚Äù allow you to access other help content, including:

• Executing AppleScript scripts

• Initiating Help Viewer searches

• Jumping to anchor locations

• Generating lists from anchors

• Opening other help books

Automating Help Tasks with AppleScript

You can take advantage of AppleScript’s ability to automate Mac OS events by linking to scripts in your help book. For example, Figure 2-11 shows a page from Mac Help that uses an AppleScript script to open the Network Diagnostics utility when the user clicks the link at the bottom of the page.

Figure 2-11  A link to an AppleScript script in a help page

The syntax for calling a script is as follows:

<a href=x-help-script://com.mycompany.surfwriter.help/scrpt/ScriptName?optional_string_parameter>

The optional string parameter is a string value that you can pass to the script. The script is responsible for parsing the value passed in the string parameter. If the script accepts multiple parameters, use commas to separate the values. The following example shows how to specify a script called “MakeNewSaveFolder” in the scripts subfolder of the SurfWriter Help folder and pass it a folder name value in the string parameter:

<a href="x-help-script://com.mycompany.surfwriter.help/scripts/MakeNewSaveFolder?string=My Save Folder">

Make sure that you enclose the entire tag value in double quotes.

If you pass the script any parameters with the help:runscript command, then you have to have a helphdhp routine inside the script to receive the parameters. For example, Mac Help has an AppleScript handler used to open an application from a Help Viewer page. The HTML command to open the Mail application looks like this:

<a href=x-help-script://com.apple.machelp/scripts/opnbndsig?string='com.apple.mail'</a>

The AppleScript handler that receives the parameter (in this case, an application bundle ID) is as follows:

on «event helphdhp» (completeParam)

    -- localizable text

    set cancelBtn to "Cancel"

    set errorTxt to "The item cannot be opened. It may be disabled or not installed."

    --end localizable text

    try

        tell application "Finder"

            open application file id completeParam

        end tell

    on error errMsg number errNum

       display dialog errorTxt buttons {cancelBtn} default button 1 with icon 0

       return

    end try

end «event helphdhp»

For examples of AppleScript scripts in a help book to use as a starting point, see the scripts included in Mac Help at /Library/Documentation/Help/MacHelp.help/Contents/Resources/. Do not link to any of these scripts; however, you are welcome to make copies of them to put in your own help book.

Initiating a Search from Your Help Book

The help:search URL allows you to create a link in your help book that, when clicked by the user, initiates a search for a particular term or phrase. This is particularly useful for linking to further information about subjects that appear in multiple help pages. Rather than link to each topic page, you can simply set up a search that will find all pages in your help book in which the subject appears. The syntax for initiating a Help Viewer search is as follows:

<a href="help:search='search_term' bookID=com.mycompany.myapp.help">

The bookID parameter is a string value specifying which help book Help Viewer should search. If you do not specify a book, Help Viewer searches all help books currently installed on the system.

The following example creates a link to a search for topics related to importing files in the SurfWriter help book:

<a href="help:search='importing files' bookID=com.mycompany.surfwriter.help">

The value for the book ID should be the help book ID, as defined by the CFBundleIdentifier key in the book‚Äôs property list file.

When the user clicks the resulting link, Help Viewer searches SurfWriter Help for all topics pertaining to importing files, just as if the user had typed the query string "importing files" into Help Viewer’s search field.

Creating a Link to an Anchor Location

Using the help:anchor URL, you can create a link to any help book location identified by an anchor. It is often simpler to create links using anchors than to hardcode the path to the destination in the link, and it allows a link to be moved without having to update all the pages that point to it. The syntax for linking to an anchor location is as follows:

<a href="help:anchor=anchor_name bookID=com.mycompany.myapp.help">

The bookID parameter is a string value identifying the help book in which Help Viewer should search for the anchor. If no help book is specified, Help Viewer searches all of the registered help books currently on the system. The following example creates a link to the topic on opening files in SurfWriter Help:

<a href="help:anchor=openfile bookID=com.mycompany.surfwriter.help">

When the user clicks the link, Help Viewer takes the user to the location identified by the anchor named “openfile.” If more than one anchor is found matching the anchor name, Help Viewer displays all of the matching anchor locations in a search results page. To link to anchor locations in your help book, you must index your help book with anchor indexing turned on, as described in “Anchor Indexing.”

Generating Lists from Anchors

The help:topic_list URL allows you to generate lists of pages to which the user can jump without having to create and maintain such lists manually.

You must provide an anchor ID, a path to the book ID, a path to a template file (used by a Help Viewer XQuery script), a path to a CSS file that specifies the styling for the list, and the name of the list item. Here is the HTML in Mac Help used to generate the Accounts preferences index list:

<p><a href="help:topic_list=almh10090 bookID=Mac Help template=sty/genlist.html stylesheet=sty/genlist_style.css Other=Accounts preferences">Accounts preferences</a></p>

Here is the XQuery template from Mac Help that is referenced by this URL:

<html>

    <head>

        <meta http-equiv="content-type" content="text/html;charset=utf-8">

        <title>AppleTopicListOther</title>

        <meta name="robots" content="noindex">

        <link href="AppleTopicListCSS" rel="stylesheet" media="all">

    </head>

    <body>

        <div id="list">

            <h1>AppleTopicListOther</h1>

            <p>Click a topic below.</p>

            <!-- AppleTopicListRowBegin -->

            <p><a href="AppleTopicListURL">AppleTopicListItemTitle</a></p>

            <!-- AppleTopicListRowEnd --></div>

        <div id="banner">

            <div id="machelp">

                <a class="bread" href="help:anchor='access' bookID=Mac Help">Mac Help</a></div>

            <div id="index">

                <a class="leftborder" href="help:anchor='x1' bookID=Mac Help">Index</a></div>

        </div>

    </body>

</html>

This template replaces the variable AppleTopicListOther with the value passed as the Other parameter. The variable AppleTopicListURL is used to look up all instances of the anchor passed as the topic_list parameter, and the title of the page identified by that anchor is substituted for the AppleTopicListItemTitle variable. The resulting list generated for the ‚ÄúAccounts preferences‚Äù index item is shown in Figure 2-12. Each page in this list contains the anchor specified in the help:topic_list URL (see ‚ÄúSetting Anchors for Generated Lists‚Äù). To add or remove items from a generated list, you add or remove that list‚Äôs anchor ID on the relevant HTML pages in the help book and generate a new index file. Because the list is generated each time it‚Äôs requested, it always reflects the current set of relevant help pages.

For other examples of code used to generate lists, look in the help folders of Mac Help and other Apple help books. Generated lists are used to create the help book index and the See-also lists at the end of topic pages.

Figure 2-12  Accounts preferences generated list

Opening Other Help Books

You can use the help:openbook URL to open a specified help book in Help Viewer. You can use this URL, for example, to open the help book for a related application in an application suite. The syntax for opening a help book is as follows:

<A HREF="help:openbook=com.mycompany.myapp.help">

When the user clicks the link, Help Viewer opens the title page of the specified help book. For example, to create a link that opens the SurfWriter Help book to the title page, you would include the following code in your help book:

<A HREF="help:openbook=com.mycompany.surfwriter.help">

To create a link that jumps to a particular location in a help book, see “Creating a Link to an Anchor Location.”

Setting Up Exact Match Searching

You can provide a list of search terms and corresponding search results. When the user enters a search term that exactly matches a term in your list, Help Viewer takes the corresponding search result from your list, gives it a relevance rating of 100%, and displays it along with other search results. You can use an exact match search list, for example, to provide responses to search terms too short to normally be used in a seach (such as “CD”) or to make sure that the most relevant results receive the highest relevance rating.

To set up exact match searching, you create a property list containing the search terms and search results and place the .plist file inside the appropriate .lproj folder, along with the title page and the help book index (see ‚ÄúOrganizing the Help Book Bundle‚Äù). The property list contains a set of key-value pairs. All keys and values are strings. Each key is a search term, specified as all lowercase with all spaces removed. Hyphens and other punctuation marks are not allowed. Each corresponding value is an anchor ID. As with generated lists, each anchor can be used in any number of help book pages. When a user enters a search term, Help Viewer takes a lowercase, spaces-removed version of the search string and compares it to the keys in the exact match property list. If it finds an exact match for the entire string, Help Viewer returns every page containing the referenced anchor string, assigns it a relevance rank of 100%, adds it to the list of search results, and displays the results. Figure 2-13 shows the exact match property list from Mac Help. Figure 2-14 shows the search results displayed when the user searches for one of the terms in that property list. The top items in the search results, with rankings of 100%, contain the anchor ID in the property list for that search term. It‚Äôs important to note that exact match searching does not return results from stems or partial matches. If you want exact match search results for ‚ÄúCD‚Äù, ‚ÄúCDs‚Äù, "VCD‚Äù, and ‚ÄúCD or DVD‚Äù, for example, you need four entries in the property list: cd, cds, vcd, and cdordvd.

Figure 2-13  Exact match property list

Figure 2-14  Search results corresponding to an exact match

Providing Your Own Online Support Articles

The default behavior for the Help Viewer application is to provide a listing of online support articles in addition to help book topics in response to a query. Help Viewer sends the query to Apple‚Äôs Knowledge Base support website. Instead, you can provide a URL to your own support site. To do so, provide the URL in the HPDBookKBURL key of the help book‚Äôs information property list file (Table 2-1).

<meta name="AppleKnowledgeBaseURL" content="https://mycompany.com/kbsearch.py?p='product'&q='query'&amp;l='lang'"/>

Help Viewer replaces the 'query' argument of the URL with the user‚Äôs query. The 'lang' argument is the current localization (English, zh_TW, and so on). Help viewer fills in 'product' with the value of the HPDBookKBProduct key.

Help Viewer expects the returned results to be in XML, in the form of an array of dictionaries sorted by relevance, highest to lowest, as in the following example::

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"

"http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">

<array>

 <dict>

  <key>title</key>

  <string>Article title</string>

  <key>url</key>

  <string>http://kb.yourcompany.com/article.py?num=23</string>

  <key>abstract</key>

  <string>Article abstract ...</string>

 </dict>

</array>

</plist>

Return no more than 7 articles, the maximum that Help Viewer will display.

If there are no results for the given query, return the following XML:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"

"http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">

<array>

 <dict>

   <key>NoResultsFound</key>

   <string>No results were found.</string>

 </dict>

</array> </plist>

Localizing Your Help Book

If your application will be used in more than one part of the world, your help book should be localized for every relevant language, country, or cultural region where it will be used. Localizing your help book involves translating the text of your help content and customizing graphics and other resources used in your help book.

This section shows you how you can ensure that your localized help content appears correctly in Help Viewer.

For more information on internationalization and HTML, see http://www.w3.org/International/

Language-Specific Resource Directories

For each language you support, you must provide a complete, localized help book in its own resource subdirectory within the Resources directory in the help bundle (see ‚ÄúOrganizing the Help Book Bundle‚Äù).

Each localized version of the help book must have a localized book name in the InfoPlist.strings file in the help bundle.

Character Encoding

Help Viewer uses the UTF-8 character encoding exclusively.

Indexing a Non-English Help Book

Once you have created your localized help book, you must run the Help Indexer utility on each localization of the book. The use of UTF-8 character encoding enables Help Indexer to support all languages for indexers compatible with Mac¬†OS¬†X¬†v 10.4 and later. See ‚ÄúGenerating an Index Compatible with Different Versions of Mac¬†OS¬†X‚Äù for information about creating indexes compatible with different versions of Mac¬†OS¬†X. See the manual page for hiutil(1) for information about the indexer utility.