Topics in this chapter   Customizing Error Messages     Creating Custom Help Topics     Making Custom Help Content Accessible

Creating Custom Help Topics

You can expand the scope of built-in Microsoft Office XP Help by using Microsoft HTML Help Workshop and the Microsoft Answer Wizard Builder to create and distribute custom Help topics. Users gain access to those topics by using the Office Help system and the Office Assistant.

Using Microsoft HTML Help Workshop

Help for applications can be created by using Microsoft HTML Help Workshop or an HTML text editor. The associated Help file available with HTML Help Workshop is an excellent source of information that explains what is required to create Help content. Included within the Help for HTML Help Workshop are several recommendations for how to configure your help project to best suit your needs, as well as the required steps you must take to create and call the Help from within an application. HTML Help Workshop can also be used to test your Web site or compiled Help, but if you prefer, you can use a Web browser to test and navigate that content.

Help content you create and compile with HTML Help Workshop is displayed by an Office application, or an application you have developed, by using the Microsoft HTML Help application that ships with Office. The HTML Help application can use either CHM files (compressed HTML Help metafile) or HTML content in a Web site as a source. Content destined for compilation by HTML Help Workshop can come from an HTML text editor, Microsoft FrontPage, Microsoft Word, or HTML Help Workshop itself. To compile help content into a CHM file, all you need to do is install HTML Help Workshop and perform the necessary steps to do a build.

To add custom Help to an existing Office application, you must create new Help topics and a new Answer Wizard (AW) file. Depending on the number of new topics you need to create, the effort required to create an additional help source and AW file can vary greatly. A few topics with very little cross-references or links is relatively easy. The more topics you add and the number of links you add to other sources or topics greatly increases the amount of effort necessary to create a complete, consistent, and stable Help source.

To modify an existing custom Help system (other than the Office Help system) for a custom-built application, you must have the original HTML files used to create the Help. Having these materials is required if you plan to delete any topics from the custom system and then recompile all topics into one CHM file. Access to the original Help source materials for an application is not required if you are only adding topics and creating a new AW file.

If you need to ignore some topics in your Help system, it is possible to selectively ignore topics by clearing the check box in the Topics frame for each topic in the Answer Wizard Builder. When set to unchecked, the topic is not included in the probability index and, therefore, never appears in the Office Assistant What would you like to do? dialog.

Customizing Help content for users

Microsoft Office XP allows you to create and distribute custom Help content for users. For instance, you can use custom Help to explain new features you have added to Office or instruct how to use a template or form. When a user asks the Office Assistant a question about a custom feature, applicable topics will appear in the search list generated by the Answer Wizard, and the topics will look like built-in Help.

Creating and distributing custom Help content for use in Office Help involves the following steps:

• Creating HTML-compatible Help files

  Custom Help topics can be HTML Help files that reside on a Web site, or compressed HTML (CHM) Help files that you distribute to users' computers or store on a network server. The Answer Wizard Builder analyzes the words contained in these files when it indexes your topics.

• Creating a custom Answer Wizard (AW) file

  The Microsoft Answer Wizard Builder stores your custom Help topics in a project file (AWB file) that is used to build an AW file — an index that is searched by the Answer Wizard in response to users' queries.

• Registering the custom Help files

  To make your custom Help content available to users, copy the new AW file to each user's computer and update each user's Windows registry for the AW file. The next time a user asks the Office Assistant a question, the custom Help content automatically becomes part of the Answer Wizard results list.

Creating custom Help content

Creating custom Help topics involves these steps:

• Choosing a custom Help file format (HTML or CHM files)

  Each file type has its advantages and disadvantages, depending upon your needs — namely, how you plan to store the Help files, and how often you plan to update them.

• Creating the custom HTML topics

  If you want to create, format, and link HTML Help topics, you can use any HTML editor. If you want to create CHM files, install Microsoft HTML Help Workshop and compile your custom Help. You have the option of compiling HTML pages into a CHM file when your custom Help is complete.

Choosing a Help file format

The format you choose for your Help files also depends on where you plan to store the files and how often you need to update the content. Custom Help topics can be stored on a user's computer, on a server, or hosted on a Web site. Each file type has its advantages and disadvantages, depending upon your needs.

Advantages of using HTML Help

HTML Help files can be stored on either a Web server or a network file share. If they are stored on either of these, the following advantages apply:

• You can update Help content in one place and not have to worry about deploying or updating it on individual computers.
  
  
• No hard-disk space is required on a user's computer.
  
  
• If you already have a Web-based Help site, you can use its contents to create the custom AW file.
  
  
• You do not have to register Web-based Help on each user's computer.
  
  
• HTML Help does not require a hosted Web site to display Help content.

Disadvantages to using HTML Help files include the following:

• If you use HTML Help files hosted on a Web site, users must have access to the Web.
  
  
• If a Web server is used to host the Help files, you must also maintain the Web server and site.
  
  
• If a Web server or network file server share is used, users might experience slow response times when they submit queries due to network traffic or Web site loading.

Advantages of using compressed HTML Help (CHM)

A CHM file is a compressed HTML Help metafile. You can take the equivalent of an entire Web site and compile it into a CHM. It uses a special technology to combine HTML files into one file with a special directory, index, and file structure similar to a compressed drive. A CHM file can only be read by the HTML Help system and Microsoft Internet Explorer. CHM files are created by HTML Help Workshop and require creating a special project and build area where you create and organize Help topics in HTML format.

Access to CHM files can be obtained through a network share or locally on a user's computer. CHM files offer the following advantages over other file types:

• CHM files can be compressed, taking up less hard-disk space and providing more portability than an entire Web site.
  
  
• Users get faster results when the CHM file is stored locally.
  
  
• A single CHM file can contain an entire Web site of HTML files.
  
  
• Users do not need access to the Web or the network.

If you use CHM Help files, you must deploy them to each client computer whenever you update the content.

Disadvantages to using CHM files include the following:

• You are required to register the CHM before it can be used.

  However, once it is registered, it does not need to be registered again.

• You are required to recompile the file every time a change is made to the Help system.
  
  
• You are required to redistribute the Help file each time a CHM file is modified.
  
  
• CHM files take up hard-disk space on the user's computer, if posted locally.

The rule of thumb for creating CHM files is based on how often your Help will change. If your Help changes frequently, it is probably better to leave your Help in HTML pages and post them on a file server where everyone can gain access to them, and where you can update them easily.

If your content rarely changes, you can create CHM files with Microsoft HTML Help Workshop. This compresses the HTML pages and makes a nice, portable single file for your Help system.

Creating custom Help topics

Once you choose what format you will use for your custom Help topics, you can begin creating your topics. Where you start the process of creating custom Help depends on what format your Help files are in. If you have CHM files or Help topics in WinHelp format, you can import them into HTML Help Workshop. If you have HTML Help topics already posted on a Web site, you can point the Answer Wizard Builder to the Web site.

Start with WinHelp sources

Many companies already have custom Help that exists in Windows Help format (winhlp or winhlp32). Microsoft HTML Help Workshop can automatically convert the source files for these to HTML.

After converting your source files, use HTML Help Workshop to create a CHM file from the new HTML files.

Follow the procedure below to convert the source files for an existing Winhelp Help system to HTML Help.

To convert an existing Help project to an HTML Help project

1. On the File menu, click New, and then click Project.
   
   
2. Select the Convert WinHelp project check box, and then click Next.
   
   
3. Specify the location of the existing Help project (.hpj) file you want to convert.
   
   
4. Specify a location and name for the new HTML Help project you are creating, click Next, and then click Finish.

Note   All the files referenced by the existing Help project (.hpj) file must be in the locations specified or the conversion process will fail. HTML Help Workshop converts the entire project as defined in the WinHelp project file.

Start with HTML files

If your Help content is currently in HTML format, you can create an AW file by creating an Answer Wizard Builder project with the URL to the Web site or the drive where the HTML files are currently stored.

If you need to edit or update HTML files, modify them first by using an HTML editing tool (such as FrontPage) or HTML Help Workshop.

You can also use HTML Help Workshop to create a new CHM file based on existing HTML files. If you create a Help system with fairly static information, a CHM file is a good solution. If your Help information will change frequently, it is a good idea to post the HTML files on a server accessible by all users and direct the AW to use the files in that location.

Start with compressed HTML files

If users do not have access to the Web, intranet, or are frequently accessing Help from portable systems, you can use HTML Help Workshop to create CHM files and store them either on the network or local to the user's computer. You can use your existing CHM files with the Answer Wizard Builder or, if they need editing, modify them first by using HTML Help Workshop.

When using CHM files to create an Answer Wizard (AW) file, you have the option of not including topics in the results list. By doing so, the Answer Wizard ignores the topics you do not include in the result list. For more information, see Making Custom Help Accessible.

Start from scratch

If you do not have any existing content, you can create your own Help topics in HTML Help Workshop or in any other HTML authoring tool (FrontPage, Word, text editors). Then use the Answer Wizard Builder to create the AW file from the HTML or CHM Help content.

For help in developing an HTML Help system, consult the Help for Microsoft HTML Help Workshop.

Making custom Help content look like built-in Help

If you want your custom Help to look like the built-in Office XP Help system, create HTML files using the two Microsoft cascading style sheets provided with the Office Resource Kit. Then add your custom Help content to the Answer Wizard with the Answer Wizard Builder. Accessing Help content through the Answer Wizard ensures your Help uses the same window definitions and functionality as Office Help.

Toolbox   HTML Help Workshop helps you create custom HTML Help content for use with the Office Help system. To help you create files that look like Office Help files, the Office Help cascading style sheet files are included. For more information on installing HTML Help Workshop, see HTML Help Workshop in the Toolbox.

The Office Resource Kit includes the two cascading style sheets Office10.css and startpag.css. The Office10.css is the main style sheet used for all basic Help topics. The startpag.css style sheet is used for the main start page for each Office application main Help (for example: Help menu, Microsoft Word Help option). Attach the appropriate cascading style sheet to each HTML file in your project, and use the defined styles when you format the Help text within each topic.

To view the HTML source for help files

1. Start an Office application.
   
   
2. Enter a question in the Office Assistant.
   
   
3. Right-click on the displayed Help file.
   
   
4. Select View Source.

The HTML source will display in the Notepad editor.

Note   To view the definitions for each style in a cascading style sheet file, open the file with a text editor. Each style is listed, along with the formatting specifications for that style, such as font and size.

To provide easy access to the style sheets, store each style sheet in the same folder where the HTML Help source files are stored and add the following code to the header in each HTML page:

<LINK rel=stylesheet type="text/css" href="Office10.css">
<LINK REL="stylesheet" HREF="startpag.css" type="text/css">

The user's Web browser determines which cascading style sheet file is used when the HTML page is opened.

Both Office10.css and startpag.css are for Microsoft Internet Explorer 4.02 or later.