Authoring Tools

You can author your help book in any application that generates valid HTML 3.2 files. Likewise, you can view your help book in any HTML 3.2–qualified browser; however, you should always test your help book in Help Viewer to ensure that your help book displays properly. If you already have HTML help content, there are tools available to help you quickly and easily convert your files to Apple Help content. For a list of some of the tools you can use to create help content for your help book, see

http://developer.apple.com/ue/help/

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 defines a playlist, a concept fundamental to the iTunes application.

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 add a song from a CD to the user’s playlist.

Topic pages typically include these elements:

• A title identifying the topic. In Figure 2-1, “About playlists” identifies “playlists” as the topic; in Figure 2-2, “Creating lists of your favorite songs” identifies the creation of playlists as the topic.

• The topic introduction. For an overview page, this section defines the relevant terms or concepts. For example, the first two paragraphs in Figure 2-1 define a “playlist” and why it is useful. For a task-oriented page, the introduction provides context for the task description that follows and explains why or when the user would perform the task. In Figure 2-2, the first paragraph briefly summarizes the definition of a playlist and gives a few reasons why you might want to create one.

• 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. Figure 2-2 shows the three steps necessary to create a new playlist. 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 links to related information on creating a playlists using Smart Playlists.

For an example of a basic topic page, see the template file TopicTemplate.htm located in /Developer/Documentation/AppleHelp/Templates/.

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

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

If your help book is chapter based, you should provide a separate table of contents for each chapter. Chapter-based help books are described further in Creating a Chapter-Based Help Book.

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.

Even if your help book is not chapter-based, you can create navigation pages to group related subtopics. This allows users to see and navigate to each of these table of contents subtopics. Figure 2-4 shows a page from iTunes Help. On the left side is the top-level table of contents for iTunes Help; on the right side is a table of contents listing the subtopics related to editing information in iTunes.

Guidelines for Help

Apple Human Interface Guidelines offers information on effectively incorporating help into your application.

Organizing the Help Book Folder

Every help book must be enclosed in its own folder. For a simple help book, Apple recommends that you also create one subfolder for your HTML help files and one subfolder for graphics. Figure 2-5 shows an example of a simple help folder for SurfWriter Help.

The three files at the top level of the SurfWriter Help folder are the index file, the title page, and the book’s icon. 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.

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 selecting the application help item from the Help menu or by selecting your help book in the Help Center. 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, welcomes the reader and offers a number of links to help pages answering common queries to get the reader started.

You can also specify a frameset as the title page, as AppleWorks Help does. AppleWorks Help uses frames to combine an introductory page with a table of contents that allows readers to see what topics are covered by the help book. Figure 2-3 shows the AppleWorks Help title page.

To specify the title page of your help book, include the AppleTitle meta tag in the header section of the HTML file you want to use as your book’s default page. This HTML file must reside at the top level of your help book folder, as shown in Figure 2-5. Here is how you would use the AppleTitle meta tag in the title page for a help book called SurfWriter Help:

<META NAME="AppleTitle" CONTENT="SurfWriter Help">

Figure 2-6 shows the title page for SurfWriter Help.

For a good example of a basic title page, see the template file TOCTemplate.htm installed by the Mac OS X Developer Tools CD in the directory Developer/Documentation/AppleHelp/Templates/.

Specifying a Help Book Icon

When you register a help book, your help book becomes visible in the Help Center. If you provide an icon, Help Viewer displays this icon in the Help Center drawer, 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 AppleIcon meta tag in the header sec tion of your title page file. Here is how you would specify an icon file called surfwritericon16.png for SurfWriter Help.

<META NAME="AppleIcon" CONTENT="SurfWriter%20Help/surfwritericon16.png">

Figure 2-7 shows SurfWriter Help in the Help Center, with the SurfWriter icon next to the book title.

In the example help book folder shown in Figure 2-5, the icon file is placed at the top level of the SurfWriter Help folder, but you can place the icon file in a graphics subfolder and specify the path accordingly. The icon should be a 16-by-16 pixel version of your application icon, saved as a .PNG file.

Organizing a Chapter-Based Help Book Folder

Each chapter has its own title page and may contain its own index and subfolders. For example, SurfWriter features several optional components, so the help book is organized into a main folder and a subfolder for each component. “SurfWriter help book with main folder installed” shows the SurfWriter help book with only the main folder installed.

“SurfWriter help book with optional chapter installed” shows the SurfWriter help book after the user installs the optional spelling checker. Note that each subfolder has its own title page.

In addition, you should provide a separate table of contents for each chapter. This makes your help book truly modular, allowing chapters to be easily added and removed. You can use this chapter-level table of contents as your chapter title page.

Creating a Dynamic Table of Contents

If you have a chapter-based help book, you can create a dynamic table of contents for it. With a dynamic table of contents, you can install and remove chapters, and the top-level table of contents for your help book will always reflect the latest contents of the help book currently on the user’s system.

To create a dynamic table of contents, each chapter in your help book must have a title page containing the AppleTitle meta tag. At the top level of your help book, include a template file for the table of contents. In this template file, specify the format of the table, using HTML comments containing the strings AppleTOCRowBegin and AppleTOCRowEnd. For example, the following lines specify the format of a table row in the dynamically generated table of contents for SurfWriter Help:

<!-- AppleTOCRowBegin -->

<TR HEIGHT=”1”>

    <TD HEIGHT=”1” WIDTH=”158”></TD>

</TR>

<TR>

    <TD WIDTH=”158”><FONT FACE=”Helvetica,Arial” SIZE=”2”>

    <A HREF=”AppleURL” TARGET=”AppleTarget”><B>AppleTitle</B></A></FONT>

    </TD>

</TR>

<!-- AppleTOCRowEnd -->

The AppleTOCRowBegin and AppleTOCRowEnd HTML comments mark the beginning and end of the definition of a table row in the dynamically generated table of contents. Help Viewer locates the title page of each chapter in the book and, using the table row definition in your template file, inserts a row in the table of contents linking to that page. Help Viewer uses the chapter title, defined by the AppleTitle meta tag in the chapter title page, as the text of the link. Any content that appears before the AppleTOCRowBegin command in the template file is copied over to the dynamically generated table of contents without change. Figure 2-10 shows the dynamically generated table of contents for SurfWriter Help in the left frame.

You can use the generated table of contents as your help book’s title page by including the AppleTitle tag at the top of your template file, above the AppleTOCRow commands. You should also include any other relevant title page information, such as your help book icon. If you specify a frameset for your top-level title page, you can include the generated table of contents by linking to the toc.htm file. The frameset for the title page for SurfWriter Help, shown in Figure 2-10, incorporates the dynamically generated table of contents in this way.

For more examples of dynamically generated tables of content, see /Developer/Documentation/Apple Help/Sample Books.

Specifying Chapter Order

You can control the ordering of the chapters in your help book’s table of contents by using the AppleOrder meta tag in the header of each chapter’s title page file. For example:

<META NAME="AppleOrder" CONTENT="80">

When the Help Viewer creates a dynamic table of contents for your help book, it lists each chapter in the order specified by the AppleOrder vaues, lowest to highest. Chapters with no AppleOrder value are listed last. If you do not specify chapter ordering, Help Viewer displays all chapter titles in alphabetical order. For example, given a help book with three chapters titled "About SurfWriter," "Using SurfWriter," and "SurfWriter Reference," the default chapter ordering is as follows:

1. About SurfWriter

2. SurfWriter Reference

3. Using SurfWriter

Using the AppleOrder tag, the chapter ordering for the same book can be changed. Given an AppleOrder value of 10 for "About SurfWriter," 20 for "Using SurfWriter," and 30 for "SurfWriter Reference," Help Viewer orders the table of contents as follows:

1. About SurfWriter

2. Using SurfWriter

3. SurfWriter Reference

If you specify the same AppleOrder value for more than one chapter, Help Viewer sorts those chapters alphabetically.

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 Apple Help Indexing Tool. 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 previews 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 large help systems.

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.

<HEAD>

<TITLE>Importing Files</TITLE>

<META NAME="KEYWORDS" CONTENT="discard, dispose, erase, scrap">

</HEAD>

Adding Abstracts

An abstract is a brief description of a help topic that appears in the bottom frame of the Help Viewer window when the user selects that topic from 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, “How to read files created by other applications.”

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>Importing Files</TITLE>

<META NAME="DESCRIPTION" CONTENT="How to read files created by other applications">

</HEAD>

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

<A NAME="SurfScriptCommand_OPEN"></A>

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

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

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

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

<!-- Topic text goes here-->

<!-- AppleSegEnd -->

<META NAME="ROBOTS" CONTENT="NOINDEX">

Using the Apple Help Indexing Tool

Once you have finished adding abstracts, keywords, and any other indexing information to your help book files, you must run the Apple Help Indexing Tool on your help book. The Apple Help Indexing Tool creates an index for your help content and stores it as a separate file at the top level of the help book folder. The index file may be invalidated if you change or rearrange the content of the help folder, so you should wait to create the index file until the help book content is complete and all files are in their final location.

You can create an index for your help book simply by dragging the folder containing the help book onto the Apple Help Indexing Tool. However, you must modify the default preference settings of the Apple Help Indexing Tool if you are doing any of the following:

1. Indexing a help book for a language other than English. Read Localizing Your Help Book for more information on indexing non-English help books.

2. Using anchors.

3. Supplying help content from a remote server.

Specifying Anchor Indexing

If you add anchors to your help book, you must index your help book with anchor indexing selected in the Apple Help Indexing Tool’s preferences so that Help Viewer can find your anchors. To turn on anchor indexing, perform the following steps:

1. Open the Apple Help Indexing Tool Preferences dialog, by selecting Preferences from the application menu.

2. Click the check-box labeled “Index anchor information in all files,” which is near the bottom of the dialog shown in Figure 2-12.

<META HTTP-EQUIV="Expires" CONTENT="Tue, 01 Jan 1980 1:00:00 GMT">

<META HTTP-EQUIV="Pragma" CONTENT="no-cache">

on open these_items

tell application "Finder"

    activate// 1

    set folderAlias to these_items as alias// 2

end tell

tell application "Apple Help Indexing Tool"

    activate// 3

    turn remote root "on" with root url "http://www.mycompany.com/myhelp/"// 4

    use tokenizer "English"// 5

    turn anchor indexing "on"// 6

    open folderAlias// 7

end tell

end open

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 movies subfolder of the SurfWriter Help folder:

<EMBED SRC="SurfWriter%20Help/movies/SurfScriptDemo.mov">

Use only legal URL characters to specify the URL for the path; for example, the folder name “SurfWriter Help” is specified as SurfWriter%20Help.

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="SurfWriter%20Help/SurfScriptPlayer">

Use only legal URL characters to specify the URL for the path; for example, the folder name “SurfWriter Help” is specified as SurfWriter%20Help.

Using Help URLs in Your Help Book

The URLs using the Help Viewer help: protocol, introduced in Help-Specific Meta Tags, allow you to create links to other help content in your help book, including

• AppleScript scripts

• Help Viewer searches

• anchor locations

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-14 shows a page from Mac Help that uses an AppleScript script to open the International preferences pane in System Preferences when the user clicks the link at the bottom of the page.

The syntax for calling a script is as follows:

<A HREF="help:runscript=help_folder_name/subfolder/scriptnamestring='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="help:runscript=SurfWriter%20Help/scripts/MakeNewSaveFolderstring='My Save Folder'">

Make sure that you enclose the entire tag value in double quotes. You can enclose arguments to help URLs in single quotes, as the string values is shown in the previous example, or you can use standard URL encoding; for example, the folder name “SurfWriter Help” is specified as SurfWriter%20Help. For more information on standard URL encoding, see

http://www.w3.org/Addressing/

<A HREF="help:search='search_term' bookID=help_book_name">

<A HREF="help:search='How do I import files?' bookID=SurfWriter%20Help">

<A HREF="help:anchor=anchor_name bookID=help_book_name">

<A HREF="help:anchor=openfile bookID=SurfWriter%20Help">

Specifying Character Encoding

To specify the character encoding used by your help book, use the standard HTML 3.2 syntax, as shown in the example below, which specifies the Latin-1 character encoding:

<META HTTP-EQUIV="content-type" CONTENT="text/html;charset=iso-8859-1">

In versions of Mac OS prior to 10.1, Help Viewer does not respect the character set tag when rendering HTML. Furthermore, prior to Mac OS X v10.1, Help Viewer supports only a limited number of character encodings. In particular, Help Viewer supports the MacRoman, MacJapanese, MacKorean, MacChineseTrad, and MacChineseSimp encodings.

Specifying Fonts For Display in Help Viewer

If you have a localized help book that uses a non-Roman font, you can specify which font Help Viewer uses for your help book title when it displays your help book in the Help Center, as well as the font used by Help Viewer to display search results from your help book.

To specify a font for your book’s Help Center listing, use the AppleFont property for the <META> element in your help book title page. For example, here is how you would specify the Osaka font for your Help Center listing:

<META NAME="AppleFont" CONTENT="Osaka">

If you need to specify a non-Roman font in which to display search results for your help book, you can use the AppleSearchResultsFont property in the header of your title page file. Here is an example of how to specify the Osaka font to display search results:

<META NAME="AppleSearchResultsFont" CONTENT="Osaka">

Indexing a Non-English Help Book

Once you have created your localized help book, you must run the Apple Help Indexing Tool on the book. To index a non-US English help book, open the Preferences dialog in the Apple Help Indexing Tool by choosing Preferences from the application menu. From the radio button group labeled “Select the tokenizer to use when indexing,” choose the appropriate setting for your target language. Figure 2-15 shows the Preferences dialog of the Apple Help Indexing Tool.

Apple Help Indexing Tool 1.3 supports U.S. English, Western European English, Japanese, Korean, and Chinese language indexing. To use Chinese language indexing, choose the Simple Tokenizer option in the Apple Help Indexing Tool Preferences; this tokenizer supports both the Traditional and Simplified character sets.