The Help Viewer Window

Users typically launch Help Viewer by choosing the application help item from the Help menu, or by typing a query in the Spotlight For Help text field in the Help menu (see How Users Access Your Help ). When Help Viewer launches, it brings up a window displaying help for the application from which the user requested assistance. In Figure 1-1, the Help Viewer window displays the system help book, Mac Help.

There are four user interface elements in the toolbar at the top of the Help Viewer window: the Back and Forward buttons, the Home button, the Action menu button, and the search field. The Back and Forward buttons on the left side of the toolbar allow users to view their navigation history and navigate through previously visited help pages. Clicking the Home button opens the title page of the currently open help book; if the user presses this button, a menu of all the available help books appears. The Action menu provides items such as Make Text Larger (or smaller), Find (which finds text strings on the current page), and Print. The search field allows users to search all help in the current book or all help on the system—they click the magnifying glass at the left of the search field to choose which.

Searching in Help Viewer

One of the primary advantages of Help Viewer for viewing online help is its ability to quickly and accurately search an installed set of help content. Users often arrive at online help with an idea of what they want to accomplish; help should allow them to get the information they need as quickly as possible and get on with their tasks. Especially for large help systems, searching is often the most efficient and effective way for users to obtain help.

The text entry field at the right side of the Help Viewer window’s toolbar allows users to search the available help content on the system. Users enter the term or concept for which they want to obtain help into the text field. Figure 1-2 shows a query entered in the text field of the Help Viewer window, with Search All Help selected.

When the user presses Return, Help Viewer searches the help books installed on the system (if the user selected Search All Help) or in the selected help book (if they selected that option) for the relevant term or terms. Help Viewer returns up to 15 help topics, sorted in order of relevance as determined by SearchKit)

Help Viewer displays the title of each relevant help topic in a table of search results, along with the help book in which that topic is found (if the user selected Search All Help). When the user moves their cursor over a topic from the search results, an abstract of the help topic appears, if available. The user can view the selected topic by clicking the topic in the search results table. Figure 1-3 shows the abstract for a help topic returned as a search result for the query entered in Figure 1-2. For information on how to provide abstracts for help topics, see Adding Abstracts.

To ensure that certain queries return the most relevant results regardless of the search term’s occurrence in the text, you can provide a list of search terms and corresponding search results to be displayed. This is referred to as exact match searching. You can use an exact match search list, for example, to provide responses to search terms too short to normally be used in a search (such as “CD”), to make sure that a particular help topic is included in the responses when there are likely to be more than 15 matches to a query, or to make sure that the most relevant results receive the highest relevance rating regardless of the algorithm used to rank results. Exact match searches are described in more detail in Setting Up Exact Match Searching.

Cross-References and Index Lists

There are Apple Help–specific URLs that you can use to create links to help pages in your help book. You can create individual links to specific locations in your book, and you can generate lists of links to use for index pages or for “see also” lists at the end of help topics. See Apple Help URLs for a list of these URLs and cross-references to their descriptions in this document.

The Help Menu

Users access your application’s help book and other help resources through the Help menu, normally the rightmost menu in the application region of the menu bar. Although your application may also provide additional means of obtaining help, such as contextual menu items or help buttons, the Help menu is the most obvious means of obtaining assistance for the majority of users. Because the Help menu is easily visible, remains in a consistent location, and is always accessible, it is the first place users go when they have a question. Help menu items are not context-sensitive.

Figure 1-4 shows the Help menu in Mail.

The Help menu is supplied by the system. If you have registered your help book, the system not only creates the Help menu, it also adds an application help menu item and opens Help Viewer to the home page of your application’s registered help book when the user chooses your application help. In OS X v10.5 and later, the user can also use the Spotlight For Help search field to search the content of your help book. When they do so and choose one of the returned search items, the system opens the appropriate page in your help file.

In addition to your application’s primary help book, you may want to include in the Help menu a few items for other help resources, such as links to support or customer service websites or tutorials.

Help Buttons

A help button is a small round button displaying the standard help icon—a question mark. This button is available in Interface Builder.

When contextually relevant help is available, you can use a help button in a window or dialog to take users directly to the pertinent information. For example, you can use a help button in a Preferences window to take users directly to information about setting preferences for your application. The button is customarily placed in the lower-right corner of the window when there are no other buttons in that location and in the lower-left corner otherwise.

Figure 1-5 shows a typical help button, in the lower-right corner of a Mail preferences window.

You should use help buttons only when contextually relevant help exists for the current window or dialog. Help buttons should allow users to obtain assistance for the task at hand without searching through your help book.

When the user clicks the help button, your application should load the relevant help topic in Help Viewer, using the NSHelpManager method openHelpAnchor:inBook: or, for C applications, the Apple Help function AHLookupAnchor. See The Apple Help Application Programming Interface for more information on using these API calls.

Help-Specific Meta Tags

Help Viewer recognizes a set of properties for the standard HTML meta element, which you can use to control how your help book appears in search results. You can also use these meta tags to control how your help is indexed. Authoring Apple Help describes many of these meta tags and how you can use them. For a complete list of the help-specific metadata recognized by Help Viewer, see Table A-1.

Help URLs

There are several URLs, using the Help Viewer help: protocol, that you can use in your help book to create links to additional help content. You use the standard a href syntax for a source link with these help URLs. Although you can use help URLs to link to HTML help pages, you can use standard hyperlinks for that purpose as well. The main advantage of the help URLs is that they allow you to create hyperlinks that, when clicked, initiate searches in Help Viewer, run AppleScript scripts, and perform anchor lookup.

The help URLs are listed in Table B-1. That table includes cross-references to discussions of these URLs in this document.

VoiceOver Summaries

To support readers with visual disabilities, the W3C document HTML Techniques for Web Content Accessibility Guidelines 1.0 (http://www.w3.org/TR/2000/NOTE-WCAG10-HTML-TECHS-20001106/) defines a summary attribute for the table element. You can use this, for example, to provide VoiceOver with a description of the relationships among cells in a table. The Help Viewer application supports the summary attribute.