100% found this document useful (2 votes)

4K views

Microsoft HTML Help Workshop Tutorial

No part of these materials shall be reproduced, stored in a retrieval system, or transmitted without written permission from Creative Computing Company. Terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. The author welcomes your comments on these materials and, if she finds them valid, will make every effort to incorporate them into the next edition.

Uploaded by

nadaatodo

Available Formats

Download as PDF, TXT or read online on Scribd

100% found this document useful (2 votes)

4K views

Microsoft HTML Help Workshop Tutorial

Uploaded by

nadaatodo

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 78

Creating HTML Help with Microsoft's HTML Help Workshop

Char James-Tanny Creative Computing Company CharJT@helpstuff.com www.helpstuff.com David Liske, Editor
Prepared for the HTML Help Center

Copyright 1999-2000, Creative Computing Company.

No part of these materials shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without written permission from Creative Computing Company/Char James-Tanny. No patent liability is assumed with respect to the use of the information contained herein. Although every precaution has been taken in the preparation of these materials, the publisher/author assumes no responsibility for errors or omissions. Neither is any liability assumed for damages resulting from the use of the information contained herein. This document is the sole property of Creative Computing Company and may be used only in conference sessions, seminars, and presentations, whether for profit or nonprofit, led by Char James-Tanny or an organization authorized in writing by Creative Computing Company. Receipt of this document does not imply permission to copy or use this document in any way, except for note taking and as a reference for the person attending an authorized conference session, seminar or presentation.

Trademarks
All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Char James-Tanny and Creative Computing Company cannot attest to the accuracy of this information. Use of a term in this book should not be regarded as affecting the validity of any trademark or service mark.

The Author Welcomes Your Feedback

Char James-Tanny, principal of Creative Computing Company, publishes these materials. Creative Computing Company specializes in the development of user documentation, Windows help, and HTML-based help. Char welcomes your comments on these materials and, if she finds them valid, will make every effort to incorporate them into the next edition. You can reach Char at Creative Computing Company, PO Box 8140, Lynn, MA 01902 USA. Phone: +1 (781) 581-3266; fax +1 (603) 452-1342; email CharJT@helpstuff.com; website http://www.helpstuff.com.

Table of Contents
SECTION 1: WHAT IS HTML HELP? ..................................... 5
Understanding the New Help Standard..............................................................................................6 Comparing HTML Help to WinHelp ......................................................................................................8 Comparing HTML Help to HTML-Based Help.....................................................................................9

SECTION 2: UNDERSTANDING HTML HELP WORKSHOP (HHW).... 10

Working with HHW................................................................................................................................ 11 What are the Advantages of HHW? .................................................................................................16 What are the Disadvantages of HHW? ............................................................................................16 Converting WinHelp Projects with HHW..........................................................................................17

SECTION 3: CREATING AN HTML HELP PROJECT WITH HHW..... 19

Creating a Project File ......................................................................................................................... 20 Modifying the Project Settings......................................................................................................... 22 Customizing the Window...................................................................................................................... 23 Adding a Search Stop List .................................................................................................................. 26 Exercise 1: Creating a Project ........................................................................................................... 27

SECTION 4: WORKING WITH TOPICS ................................. 28

Overview of Topics ............................................................................................................................... 29 Creating New Topics............................................................................................................................. 29 Adding Topics to a Project ................................................................................................................. 30 Setting the Default Topic....................................................................................................................31 Exercise 2: Adding Topic Files........................................................................................................... 32

SECTION 5: SAVING AND COMPILING ................................ 33

Setting the Compilation Options ....................................................................................................... 34 Saving and Compiling............................................................................................................................. 36 Viewing the Results............................................................................................................................... 37 Exercise 3: Compiling the Project ..................................................................................................... 37

SECTION 6: CREATING HYPERLINKS................................... 38

Creating Hyperlinks .............................................................................................................................. 39 Creating Text-Only Popups ................................................................................................................. 40 Exercise 4: Creating Hyperlinks ........................................................................................................ 42

iii

SECTION 7: DESIGNING THE TABLE OF CONTENTS................ 43

Adding Contents Information ............................................................................................................ 44 Changing the Contents Settings ........................................................................................................ 47 Exercise 5: Creating a Table of Contents ....................................................................................... 49

SECTION 8: DESIGNING AN INDEX ................................... 50

Adding Index Information...................................................................................................................51 Understanding the Differences: Sitemap and Binary Indexes .................................................. 52 Adding Index Entries to the Index File.......................................................................................... 53 Adding Keywords to Topic Files......................................................................................................... 54 Creating See and See Also Keywords............................................................................................... 56 Sorting the Index ................................................................................................................................. 58 Changing the Index Settings.............................................................................................................. 59 Exercise 6: Creating an Index ........................................................................................................... 60

SECTION 9: ADDING GRAPHICS TO THE PROJECT .................. 61

What Graphic Formats Can Be Included? ....................................................................................... 62 Inserting Graphics ................................................................................................................................ 63 Exercise 7: Inserting Graphics.......................................................................................................... 64

SECTION 10: ADDING THE HTML HELP CONTROL ................... 65

Why Use the HTML Help Control? ................................................................................................... 66 Designing HTML Help Control Links and Results ........................................................................... 67 Creating a Related Topics Button...................................................................................................... 69 Creating a Keyword Search Button................................................................................................... 72 Creating a Splash Screen .................................................................................................................... 73 Exercise 8: Creating HTML Help Controls ...................................................................................... 74

SECTION 11: DISTRIBUTING YOUR HELP FILE ...................... 75

Preparing for Distribution .................................................................................................................. 76 What Files Do You Need to Ship?..................................................................................................... 77

Section 1: What is HTML Help?

! ! !

Understanding the New Help Standard Comparing HTML Help to WinHelp Comparing HTML Help to HTML-Based Help

Understanding the New Help Standard

HTML Help is the new Windows Help standard, combining the functionality of WinHelp with the flexibility of Hypertext Markup Language (HTML) and the power of ActiveX controls and scripts.
!

WinHelp refers to Help files developed with Rich Text Format (RTF) files and the Microsoft Windows Help Compiler (HCW). Since 1995, Help developers could choose between WinHelp 3 for Windows 3.x systems and WinHelp 4 for Windows 95/98/NT. HTML is a browser-independent tagging language used to display information on the World Wide Web. It enables you to display text and graphics and use hyperlinks to navigate to other HTML documents. However, HTML doesn't include WinHelp functionality, such as popups, Tables of Contents, Indexes, full text search, and Related Topics.

HTML Help has a slightly different look than WinHelp. Instead of one screen for the navigation tabs (Table of Contents, Index, and Full-text Search) and another screen for the content, HTML Help combines both into one screen, along with a third component, the toolbar. This gives the main window its name (tri-pane).
!

This interface enables users to see where they are within the navigational structure.

What Are the Advantages of HTML Help?

HTML Help was first announced in February 1996 by Ralph Walden, formerly Microsoft's lead Help architect, at that year's WinWriter's Online Help Conference. After developers recovered from the shock of a new standard, they realized that there were several benefits in basing Help files on HTML.
!

Help files created with HTML Help are much smaller than their counterparts created in WinHelp and there are virtually no limits (file sizes, number of files, and so on). Developers have full control over both tables and text. Unlike WinHelp, which didn't allow for any kind of table formatting and little text formatting, HTML allows both. Developers wouldn't lose any WinHelp functionality. They can still provide popups, Tables of Contents, Indexes, full-text search, and Related Topics.
Section 1: What is HTML Help?
Copyright 1999-2000 Creative Computing Company

Page 6

Improvements made to HTML can be immediately implemented in HTML Help. For example, HTML was at version 2 when HTML Help was announced. Now, HTML is at version 4, enabling us to take advantage of Cascading Style Sheets, JavaScript, and so on. Using scripts, HTML Help Objects, and ActiveX components, developers can deliver as much or as little functionality as they choose.

In addition, they gained new navigational aids. When developing an HTML Help file, you can specify that the Table of Contents should synchronize with the content displayed on the right when the Contents tab is displayed on the left. This means that users can always track their progress within the topics of the HTML Help file. You can add full-text search (basic and advanced) and a Favorites tab that enables users to bookmark frequently used topics.
!

When an HTML Help file is synchronized, users can display information using any means (the Index, through Full-text Search, or the Favorites tab), and then select the Table of Contents to see where the topic falls within the hierarchy. However, the topic must exist on the Table of Contents for synchronization to work.

Developers can provide context-sensitive Help for applications. Your developers need to use a form of the HTML Help API, which can be found in the HTML Help Workshop Help file.
!

The implementation of context-sensitive Help changes for different development environments. API calls can be encapsulated in a DLL, such as David Liskes HTML Help Object Library DLL. If this is used, your developer doesnt need to worry about the API and can use the properties and methods of the DLL instead.
!

If your developer is using Visual Basic 5 or 6, Davids HTML Help Class Module provides the same interface as the HTML Help Object Library DLL, but with better performance.

Are There Any Gotchas?

One major requirement for HTML Help is that Internet Explorer (version 4 or later) MUST be installed on the user's system. It must also be installed on your system. Neither you nor your users actually have to use IE when surfing the Web. HTML Help files use runtime components from IE to display their content. Also, HTML Help doesn't use any of the 88+ WinHelp macros. If you've developed WinHelp files, you might have used these macros for increased functionality. Although some macros have corresponding ActiveX controls (for example, Related Topics), most do not. You might have to write your own scripts, or have a developer write a DLL or ActiveX control, if there's something special you want to provide for your users.
Page 7
Copyright 1999-2000 Creative Computing Company

Section 1: What is HTML Help?

Comparing HTML Help to WinHelp

Similarities
! ! ! ! ! ! ! ! ! ! !

Compiled results (.hlp for WinHelp and .chm for HTML Help) Multiple windows (main, secondary, and popups) Table of Contents and Index Full-text search Static graphics (although each type uses different formats) Hotspot graphics and multimedia Hyperlinks Formatting topics (font families, colors, and sizes) Context-sensitive Help Browse sequences (although HTML Help requires more work) Related Topics, Keyword Links, and A-Keyword Links

Differences
! ! ! ! !

Fully functional tables in HTML Help Fully functional fonts (superscript, subscript, and so on) in HTML Help Non-scrolling regions in WinHelp (can be scripted in HTML Help) Macros in WinHelp Scripting in HTML Help

Page 8
Copyright 1999-2000 Creative Computing Company

Section 1: What is HTML Help?

Comparing HTML Help to HTML-Based Help

Similarities
! ! ! ! ! ! ! ! ! ! !

Cascading Style Sheets Expanding/collapsing Table of Contents Multi-level Index Hyperlinks to URLs, email addresses, newsgroups, or FTP sites Popups Related Topics lists Scripts (JavaScript for both; VBScript for Internet Explorer only) Images and Image Maps Multimedia Forms Context-sensitive Help

Differences
Option Operating systems Compilation Browsers Deploying files Internet access Full-text search Default display format Auto-synchronization in the Table of Contents Information Types Cross-file linking Merging
Section 1: What is HTML Help?
Copyright 1999-2000 Creative Computing Company

HTML Help Windows 32-bit only (95/98/NT) Compiled None Deploy one file Runs locally Yes Yes Yes Yes (although they arent working correctly) Yes Yes

HTML-based Help Any Not compiled All Deploy all files Runs over the Internet Sometimes Browser-dependent No No Yes No
Page 9

Section 2: Understanding HTML Help Workshop (HHW)

! ! ! !

Working with HHW What are the Advantages of HHW? What are the Disadvantages of HHW? Converting WinHelp Projects with HHW

Working with HHW

Microsoft provides HTML Help Workshop (HHW) for free from their Web site.
!

If you want to download the latest version of HTML Help workshop, go to http://msdn.microsoft.com/workshop/author/htmlhelp/download.asp.

However, it includes only a text-based HTML editor, requiring developers to know HTML when making changes.
! !

You can use any HTML Editor to create your HTML files. These HTML files, commonly called topics, display Help information.

HHW includes full HTML Help functionality, including Table of Contents and Index designers, HTML Help objects through hhctrl.ocx, contextsensitivity, and an HTML Help Image Editor. There are numerous HTML Help authoring tools on the market that make development much easier. Three popular tools are:
!

RoboHELP 2000 for Microsoft's HTML Help by Blue Sky Software Corporation ForeHelp Premier 99 by ForeFront Doc-To-Help by WexTech

! !

Menu options
!

HHW (when an HTML file isn't open) includes the following menu options:
!

File New, Open, Close Project, Close All, Save Project, Compile, Decompile, CHM Information, Preferences View Toolbar, Status Bar, Compiled Help File, HTML Help Messages Test Pop-up Attributes, Keyword Lookup, HtmlHelp API Tools HTML Help Image Editor Help Help Topics, HTML Tag Reference, Version
Page 11

Section 2: Understanding HTML Help Workshop (HHW)

When an HTML file is open, the following menu options are added:
!

File Close File, Save All Files, Save File, Save File As View Set Font, In Browser Window Cascade, Tile Horizontally, Tile Vertically, Arrange Minimized Windows Edit Undo, Cut, Copy, Paste, Select All, Compiler Information, Split File, Find, Find Next, Replace Tags Insert Text Block, Edit Text Block, Character Formatting, HTML Help Control, Heading, Comment, Title

Tabs
!

Once you open a project, three tabs display on the left side of HHW. These tabs contain the Project, Contents, and Index information.

Tool bars
!

The main Toolbar displays when you first open HHW and remains when you open projects or HTML files.

The New icon displays the New dialog box, where you can select to create projects, HTML and text files, Table of Contents, and Index. The Open icon displays the Open dialog box, where you can select to open project and HTML files when no projects are open and HTML files when a project is open. The Compile HTML File icon compiles your project. The View Compiled File icon displays your results. The Display Online Information icon displays the appropriate HTML Help topic in an embedded Help window within HHW.

! ! !

Page 12

Section 2: Understanding HTML Help Workshop (HHW)

Once you open a project, the Project toolbar displays.

Change Project Options Displays a tabbed dialog box with the General, Files, Compiler, and Merge Files settings. Add/Remove Topic Files Displays the Topic Files dialog box. Add/Modify Window Definitions Displays the Add Window dialog box if no windows have been created. Once you've created one or more windows, the Window Types dialog box displays, where you can modify the window settings. HtmlHelp API Information Displays the Map, Alias, and Text Pop-ups tabs, where you can add and remove context-sensitive Help information.
!

While HHW Version 1.22 seems to be more stable, it still has a tendency to crash when removing HTML Help information. Make edits to the API information by opening the project (.hhp) file in Notepad.

View HTML Source Displays the HTML of the selected file. You must select a file from the [FILES] list first. Save Project, Contents, and Index Files Saves these three files with one click. Save All Files and Compile Saves all files before compiling your project.

Section 2: Understanding HTML Help Workshop (HHW)

Page 13

The Table of Contents and Index tabs display different vertical toolbars.

The top icons on each toolbar are the appropriate properties icons (Contents Properties and Index Properties). The last two icons display the source of the selected HTML file and save either the Contents or Index file.
!

This is slightly different from the Save icon on the Project tab, which saves the Project, Contents, and Index files.

Each toolbar contains the Edit Selection, Delete Selection, and positioning arrow icons. The Contents toolbar contains icons to Insert a Heading and Insert a Page. The Index toolbar contains an icon to Insert a Keyword.
!

By default, HHW displays headings as folders when first launched. You can change from folders to books by modifying the Contents options. I'll discuss this in Section 7.

Page 14

Section 2: Understanding HTML Help Workshop (HHW)

Once you open an HTML file, the HTML toolbar displays:

Save Saves the current HTML file. Display in Browser Displays the current HTML file in a Help window. HTML Help ActiveX Control Displays the HTML Help wizard. Bold Formats the selected text as bold. Italic Formats the selected text as italic. Underline Formats the selected text as underline. As a rule, Help developers use very little underlining in Help files. Hyperlinks are usually underlined and users could get confused if you use underlining for emphasis.

Section 2: Understanding HTML Help Workshop (HHW)

Page 15

What are the Advantages of HHW?

HHW always contains the latest enhancements. It takes time for the tool vendors to implement the changes. HHW is always free. HHW includes an HTML editor. It includes such enhancements as text blocks, character formatting, headings, comments, and topic title dialog boxes. However, it isn't WYSIWYG. HHW includes the HTML Help Control Wizards for ALink Search, Close Window, HHCTRL Version, Index, Keyword Search, Related Topics, Shortcut, Splash Screen, Table of Contents, Training Card, and WinHelp Topic.
!

! !

I'll discuss these in more detail in Section 10.

The HHW Help file includes the HTML Help API information. This enables you and your developers to attach your Help file to an application.

What are the Disadvantages of HHW?

HHW doesn't include a WYSIWYG editor. You need to know HTML to add content to the topic files.
!

This is by design. Microsoft knew that the tool vendors would implement HTML editors, plus there are many tools on the market available for developing HTML. Popular tools include Allaire's HomeSite, Macromedia's DreamWeaver, and Microsofts FrontPage, which works with Robert Chandlers FAR (available at http://www.helpware.net).

HHW doesn't include an automated linking feature (where you select the hotspot text and then select the target topic). You must code links manually.

Page 16

Section 2: Understanding HTML Help Workshop (HHW)

Converting WinHelp Projects with HHW

! !

You can convert existing WinHelp projects with HHW. You assign the project (and, therefore, the compiled Help file) name during the conversion. HHW uses the WinHelp project name for the names of the Contents and Index files.

Advantages
! ! ! ! ! !

WinHelp project (.hpj) files to HHW project (.hhp) files WinHelp topics (from the .rtf files) to individual HTML files WinHelp Table of Contents (.cnt) files to HHW Table of Contents (.hhc) files WinHelp Index to HHW Index (.hhk) files WinHelp graphic (.bmp or .wmf) files to HTML graphic (.gif or .jpg) files WinHelp jumps to HTML hyperlinks (but not popups)

Disadvantages
!

The naming convention of the conversion process doesn't adequately identify the topic.
! !

All topic file names are eight characters. The first four characters indicate the document name from the WinHelp project (for example, topics from the Tasks document are prefaced with task). The last four characters are assigned by HHW. The list of file names in the [FILES] section on the Project tab follows the original document order.

! !

Section 2: Understanding HTML Help Workshop (HHW)

Page 17

HHW doesn't convert the following WinHelp items:

! ! !

Authorable buttons (inserted with the {button} command) Browse buttons and browse sequences Default topic setting (HHW assigns the first topic in the first document as the default topic) Multiple spaces (HTML ignores spaces and tabs) Non-scrolling regions Popups Secondary windows WinHelp hypergraphic (.shg) files to HTML image maps WinHelp macros

! ! ! ! ! !

Page 18

Section 2: Understanding HTML Help Workshop (HHW)

Section 3: Creating an HTML Help Project with HHW

! ! ! ! !

Creating a Project File Modifying the Project Settings Customizing the Window Adding a Search Stop List Exercise 1: Creating a Project

Creating a Project File

1. Select File | New. The New dialog box displays.

Project is selected by default. Click OK and the New Project dialog box

displays.

If you want to convert a WinHelp project, select the checkbox. The next screen that displays enables you to select the WinHelp project and choose where to save the converted results.

If you want to create a new HTML Help project, click Next without selecting the checkbox. The New Project - Destination dialog box displays, as shown on the next page.

Page 20

Section 3: Creating an HTML Help Project with HHW

4. Type the path and file name information in the input box or click the Browse button to select the folder. The Open dialog box displays. Navigate to the desired folder, enter the name of the project, and click Open. 5. When you're finished, click Next. The New Project - Existing Files dialog box displays.

Select the appropriate checkboxes to add existing files to your project. Click Next on each screen that displays after selecting the desired files. If you don't have any files to include in your project, click Next.

6. 7.

The New Project - Finish dialog box displays. Click Finish. HHW creates the initial project information and displays it on the Project tab.
Page 21

Section 3: Creating an HTML Help Project with HHW

Modifying the Project Settings

! !

New projects include the default project settings. If you want to include full-text search in your results, you must modify the project settings first.
!

If you create the window first, HHW displays a message that the project and window don't match. It's not hard to resolve the problem, since HHW displays dialog boxes where you can just click Next, but it could lead to confusion.

Click Change Project Options and the Options dialog box displays. This dialog box contains four tabs.
Does this

This option General

Controls the Title, Default Topic, Default Window, and International Settings. Once you create a window, the Default Window field is updated. You can't specify a default topic until you add topic files to your project. Displays the path and file name of the Compiled File and Log File (if any). Enables you to specify: 1. 2. 3. The Contents file or automatically create it from headings within your topic files The Index file and, if desired, include topic keywords A Full-text Search stop list, so that common words (such as a and the) aren't included in the full-text search. I'll discuss this in more detail later in this section.

Files

Compiler

Enables you to include Notes and/or Progress information while compiling. Allows you to specify the compatibility (which should always be 1.1 or later), to include folder names during compilation, to support enhanced decompilation, to compile full-text search information, and to create a binary Index or Table of Contents. Specifies if other HTML Help files should be merged with this file when creating modular Help.

Merge

Page 22

Section 3: Creating an HTML Help Project with HHW

Customizing the Window

HTML Help includes the definition for a default tri-pane window.

All compiled HTML Help files use this window to display their content.

The default tri-pane window (with the Search tab) displays as:

! !

The Button Pane has browser navigation icons. The Navigation Pane contains the Contents and Index tabs and, if specified, the Search and Favorites tab. The Contents Pane shows the topic (.htm) files.

! ! !

You can't edit the default window settings. In order to change the window display, you must create a new window.

Section 3: Creating an HTML Help Project with HHW

Page 23

Creating a New Window

1. Click Add/Modify Window Definitions. The Add a New Window Type dialog box displays.
!

This dialog box only displays the first time you click the icon in a new project. Once one window definition exists, you use the Window Types dialog box (discussed next) to create additional windows.

2. 3.

Type the name for the window in the input box and click OK. The Window Types dialog box displays. Modify the window as desired. When finished, click OK. HHW automatically assigns the window to the project.

Modifying the Window

The Window Types dialog box contains seven tabs:

To do this

Use this tab General

Add or remove existing window definitions. Enter the text for the window title bar. Text entered here overrides the title set in the Options dialog box.

Buttons

Set the buttons for the specified window. The default buttons are Hide/Show, Back, Options, and Print. Other choices include Forward, Stop, Refresh, Home, Locate, Jump 1, and Jump 2. For the Jump 1 and Jump 2 buttons to work, you must assign a URL or a topic file. You can add URLs on this tab, or use the File tab to enter a URL or select an existing topic. For the Home button to work, you must enter a URL or select an existing topic on the Files tab.

Position

Set the size and position for the specified window. Click Autosizer to use drag-and-drop to position and resize the window. Click Default Positions to use the default window size and position. Select the checkbox to apply persistence to the window. This allows HHW to remember if users resize and reposition the window.

Page 24

Section 3: Creating an HTML Help Project with HHW

Use this tab Files

To do this

Select the files or enter the URLs you want to use for the Table of Contents, Index, and Default topic, and for the Home, Jump 1, and Jump 2 buttons. Select the checkbox to create the tri-pane window. Then, enter the settings for the tri-pane window, including the width and properties of the navigation pane. Properties include controlling the navigational pane (whether it displays or not when the user first opens the Help file), if the Help and Contents files should autosynchronize, and if the Help file should toggle the navigational pane on and off when the Help file loses focus. Select the default tab (the one that displays on top the first time the user opens the Help file) and if you want to include the Search and Favorites tabs. If you choose to include a Search tab, click the checkbox if you want your file to use the Advanced Search properties. When you add a window definition before creating any other information, the Default Tab selection is blank. If you choose the Search and/or Favorites tabs, the Default Tab selection includes these choices. The Table of Contents and Index tabs aren't available until you create the files and add them to the Files tab.

Navigation Pane

Styles and Extended Styles

Select the styles that you want implemented in your tri-pane window. Not all styles are working yet. For example, Right-to-Left Reading Order hasn't been implemented yet. You have to try different combinations. However, the Help file is fine if you don't select any of these options.

Section 3: Creating an HTML Help Project with HHW

Page 25

Adding a Search Stop List

The full-text search stop list prevents common words, such as the and or, from displaying in the Search results when running the compiled HTML Help file.
!

You can include numbers in the stop list.

Including a stop list reduces the size of the full-text search index, which means that the resulting compiled file will also be smaller. The first step is to create the stop list, which is a text file with an STP extension.
! !

You have to use Notepad or another application that allows text files. One of the easiest ways to create it is to use the sample stop words listed in the HHW Help file. Launch the Help file from HHW and use the Search tab to look for the topic named To create a full-text search stop list. Copy the sample stop list and paste it into your file. If desired, add or delete stop words.

The stop file for HHW Version 1.2 has a size limit of 512 bytes. A file created from the stop list in the HTML Help file is 507 bytes. This means that you have to be careful how many words you add or errors will result. After creating the file, add it to your project by using the Files tab in the Options dialog box.

Page 26

Section 3: Creating an HTML Help Project with HHW

Exercise 1: Creating a Project

Before running the exercises, make sure that you have downloaded the files from the HTML Help Center and copied them to C:\Projects (or another folder of your choice). Create a project file called paint in C:\Projects\Paint. Enable full-text search for the project in the Options dialog box. Create a new window called main. Type Paint Tutorial as the Title Bar Text. Size the window to 800x600, positioned in the upper left corner of the window. Turn on the navigational pane and the Search and Favorites tabs. Copy the stop file from C:\Projects\stoplist.stp to C:\Projects\Paint. Add the stop file to your project on the Files tab in the Options dialog box.

1. 2. 3.

4. 5.

Section 3: Creating an HTML Help Project with HHW

Page 27

Section 4: Working with Topics

! ! ! ! !

Overview of Topics Creating New Topics Adding Topics to a Project Setting the Default Topic Exercise 2: Adding Topic Files

Overview of Topics
! !

Topics are chunks of information in a help file. The following table defines the common topic types that you might use in your Help file:

Topic Type Overview/Navigation

Description

Description of the main concept(s) of this portion of the help file. May help you make decisions about what other related topics you should consider. How-to instructions for completing a specific task. Usually formatted as a list of instructions. Provides more concrete information than an Overview, but without the how-to information of a Procedure. Description of a specific term or concept. Definition topics are usually accessed through popups, although they can also be lists of terms and definitions, as in a Glossary. Uses multimedia (graphics and/or movies) to show how to accomplish a task or the actual result after the tasks have been completed. Opens when the user requests help while using the application.

Procedure (Task) Reference

Definition

Examples and Demonstrations

Context-sensitive Help

Creating New Topics

1. 2. 2. 3. Select File | New | HTML file. Enter the topic title and click OK. The new topic displays in the right side of HHW. Enter the topic content. Click Save. The Save As dialog box displays. Type the file name, making sure you don't enter any spaces. (You should never use spaces in file names when working with HTML Help.)

Section 4: Working with Topics

Page 29

Notes on Adding Topics

When you create topic files in HHW, they aren't automatically assigned to the project. You must use the Topic Files dialog box to add files to your project.

Applying Style Sheets to Topics

If an HTML file doesn't specify a Cascading Style Sheet (CSS), the user's browser settings control the formatting. For consistency and control, you should specify a style sheet in your HTML files. Add <LINK rel=StyleSheet href=filename.css> before the </HEAD> tag.

Adding Topics to a Project

Click Add/Remove Topic Files to display the Topic Files dialog box.

Click Add to display the Open dialog box. The current project folder displays. Select the HTML files that you want to add to your project.
! !

HHW records the path information of all topic files. Before you add the files, you need to copy them to your project folder or to a subfolder of the project.
Section 4: Working with Topics
Copyright 1999-2000 Creative Computing Company

Page 30

Setting the Default Topic

! !

The default topic displays as soon as users launch the Help file. This topic can be the first topic from the Table of Contents or it can be an identity topic.
!

An identity topic contains the name and copyright information for the Help file. The only time users see the identity topic is when they first open the Help file.

If you are adding a splash screen to your Help file, you add the control to the default topic.
!

This way, users only see the splash screen when they first open the Help file. I'll discuss splash screens and other HTML Help controls in Section 10.

! !

To set the default topic: 1. Click Change Project Options. The General tab displays by default. 2. Click the drop-down arrow next to Default File. 3. Select the default topic from the list that displays. 4. Click OK.

Section 4: Working with Topics

Page 31

Exercise 2: Adding Topic Files

1. 2. 3. Create a new topic called Introduction. Before the </HEAD> tag, add the <LINK> tag for ottawa.css. After the <BODY> tag, add the following text to the topic: <h1>Introduction</h1> Use Paint to create small bitmaps or modify existing bitmaps. You can also use Paint to match color palettes to prevent palette flash. <ul> <li>Menus <li>Color Box <li>Status Bar <li>Tool Box </ul> 4. 5. 6. Copy the HTML files from C:\Projects to C:\Projects\Paint. Add all HTML files to your project. Make the Introduction topic your default topic.

Page 32
Copyright 1999-2000 Creative Computing Company

Section 4: Working with Topics

Section 5: Saving and Compiling

! ! ! !

Setting the Compilation Options Saving and Compiling Viewing the Results Exercise 3: Compiling the Project

Setting the Compilation Options

Use the Compiler tab in the Options dialog box to control your compilation settings.

Page 34
Copyright 1999-2000 Creative Computing Company

Section 5: Saving and Compiling

This option When Compiling, Display Notes and/or Progress

Does this

Notes display whether or not the checkbox is selected. Possible notes include missing topics, errors in Contents and Index files, and broken links in your project. Progress information displays the files in the project as they are processed by the compiler.

Compatibility

By default, compatibility is set as version 1.1 or later. The only other option is 1.0 compatibility. However, you will not be able to incorporate any version 1.1 or later functionality if compatibility is set to 1.0. This includes merging multiple .chm files and binary indexes.

Don't Include Folders in Compiled File

HHW allows you to use subfolders for your different files. When compiling, this setting basically ignores the folder structure and puts all files in the root. If any files in different folders have the same name, you must make all file names unique before using this option.

Support Enhanced Decompilation

Select to extract all project information, including the project file, when users decompile your Help file. Select to include full-text search in the compiled Help file. Make sure that the Search tab is selected in the window definition. This option is selected by default. I'll discuss the index in more detail in Section 8. A binary TOC reduces the size of a large Table of Contents, so that it loads quicker. However, other features in the Table of Contents can't be used with a binary TOC.

Compile Full-Text Search Information

Create a Binary Index Create a Binary TOC

Section 5: Saving and Compiling

Page 35

Saving and Compiling

Before compiling, you need to make sure that all files are saved so that the latest information is included in the results.
!

Earlier versions of HHW have been known to have problems. That is, topic files didn't always get saved.

HHW Version 1.22 seems to be having this same problem on different systems. To verify that all files are saved before compiling:
!

Close the topic file. If the file needs to be saved, a prompt displays.

There are several ways to save HTML files:

! ! !

Click the Save icon on the HTML toolbar. Select File | Save. Select File | Save All.

Compiling the Project

Compiling takes the information in the project file, including all files, and runs them through a piece of software to merge them into one file. The results include all topic files, graphics, and hyperlinks. The compiler also takes the information in the Contents and Index files to produce the Contents and Index tabs. To compile your project:
!

Click Compile HTML File on the main toolbar. The Create a Compiled File dialog box displays. The options include Save All Files Before Compiling and Automatically Display Compiled Help File When Done. Make sure the Save option is selected.
!

In earlier versions of HHW, the Display option didn't always work correctly or consistently.

! !

Click Save All Files and Compile on the Project toolbar.

The compiler creates consecutive log files, which saves notes and progress information. When the dialog box displays, click Save to accept the default file name or select an existing file to overwrite.

Page 36
Copyright 1999-2000 Creative Computing Company

Section 5: Saving and Compiling

Viewing the Results

Once you've compiled your file, you can view it to verify the window size and position, topic information, hyperlinks, and so on. If you selected to automatically display the Help file, it should display as soon as the compilation is finished.
!

However, due a bug in Version 1.22, the compiled Help file doesnt always display.

If the file doesn't display as expected, or to view the file at any time, click View Compiled File on the main toolbar. The View Compiled File dialog box displays.
!

The current compiled file name should display in the input box. If it doesn't, click the Browse button to navigate to the project folder and then select it.

You can compile and view the file as often as necessary.

Exercise 3: Compiling the Project

1. 2. 3. 4. 5. 6. Verify the compiler settings, making sure that compatibility is 1.1 or later and full-text search and binary Index are selected. Save all files. Compile your project. View the results. Close your Help file and make any modifications, as desired. When you're finished, close your Help file.

Section 5: Saving and Compiling

Page 37

Section 6: Creating Hyperlinks

! ! !

Creating Hyperlinks Creating Text-Only Popups Exercise 4: Adding Hyperlinks

Creating Hyperlinks
!

With HTML Help, you can choose from the following types of hyperlink destinations:
! ! ! ! !

URL for an intranet or internet website page URL for a topic in the same Help project URL for a topic in a different Help project FTP (File Transfer Protocol) Bookmark (to display content from anywhere in a topic other than the beginning; called a mid-topic jump in WinHelp) Newsgroups Email address

! ! !

Because HHW doesn't include a WYSIWYG editor or automation, you must enter hyperlinks manually or through another HTML Editor. In HTML, a hyperlink requires two parts:
! !

Type <A HREF=target> before the hotspot text. Type </A> after the hotspot text.

Each hyperlink destination uses a different target as the HREF attribute.

! ! !

Intranet or Internet page: target = http://www.website.ext URL for a topic in the same Help project: target = filename.htm URL for a topic in a different Help project: target = projectfilename.chm::/topicfilename.htm FTP: target = ftp://ftp.website.ext Bookmark: target = filename.htm#bookmark Newsgroups: target = news://news.website.ext Email address: target = mailto:name@website.ext

! ! ! !

Section 6: Creating Hyperlinks

Page 39

Creating Text-Only Popups

While HTML Help allows you to use popups, it only allows text-only popups.
!

Text-only popups don't allow any kind of text formatting, such as bold or italic, or graphics.

In order to use text-only popups in HHW, you must use JavaScript and a customized ActiveX control. A basic tutorial, like this one, doesn't usually cover advanced techniques like JavaScript and ActiveX controls. However, once you become familiar with the tool, you might want to add text-only popups. Therefore, the code is provided for future use.
!

Josef Becker (http://www.helpmaster.com) has developed a JavaScript method to create popups. You can get examples and instructions at his site.

Creating the Script

The script for a popup is:

<SCRIPT Language=JavaScript> font_info=font_family[,point size[,charset[,plain bold italic underline]]] popup_text_1=popup text for first popup popup_text_2=popup text for second popup </SCRIPT>
!

font_info, popup_text_1, and popup_text_2 are variables for the script. You can change variable names, as long as you are consistent. font_family is the name of the font you want to use. point size is the size of the font. charset is the name of the Character Set for the font. This value can be omitted. plain bold italic underline sets the attribute for the characters. For example:

! ! !

! !

<SCRIPT Language=JavaScript> popfont=Arial,10,,bold popup1=This is my first popup. popup2=This is my second popup on the same page </SCRIPT>
!

Type this code in your topic. Typically, it's entered at the bottom of the file.
Section 6: Creating Hyperlinks
Copyright 1999-2000 Creative Computing Company

Page 40

Creating the ActiveX Control

! !

The next step is to add the code for the popup ActiveX control. ActiveX controls are identified by their classid.
!

You must type the classid exactly as shown or the popup won't work correctly. If you will be creating more than one popup on a page, you only have to enter the ActiveX control code once.

<OBJECT id=hhctrl type=application/x-oleobject classid=clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11 > </OBJECT>

hhctrl identifies this code when you create the hyperlink. You can change this value, if desired, as long as you are consistent. For example:

<OBJECT id=popup type=application/x-oleobject classid=clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11 > </OBJECT>

Type this code in your topic. Typically, it's entered below the script.

Creating the Hyperlink

Once you enter the script and ActiveX control, you can create the hyperlinks. Scripted hyperlinks are slightly different than the earlier examples.
!

This code uses the variables in my earlier examples.

<A HREF=JavaScript:popup.TextPopup(popup1, popfont,9,9,-1,-1)>Popup Hotspot</a>

The 9,9, variables control the left and right margins. In this case, they are set to 9 pixels each. The -1,-1 variables control the foreground and background colors of the popup. In this case, they use the default settings, which is black text on a dithered yellow background.
!

It is possible to change the colors. However, I've never been able to figure out what values work consistently.

Section 6: Creating Hyperlinks

Page 41

Exercise 4: Creating Hyperlinks

1. In the Introduction topic, create hyperlinks to the following topics:
! ! ! !

Menus Tool Box Color Box Status Bar

Page 42
Copyright 1999-2000 Creative Computing Company

Section 6: Creating Hyperlinks

Section 7: Designing the Table of Contents

! ! !

Adding Contents Information Changing the Contents Settings Exercise 5: Creating a Table of Contents

Adding Contents Information

The Table of Contents is one way users can navigate a Help file. It presents information in a hierarchical format, using headings and pages. You can customize the different levels in your hierarchy by changing the default icons.
!

Headings. By default, headings are shown by folder icons, which you can change to display books instead. They can contain sub-headings and topics and, if you want, can display a topic.
!

This functionality is different from WinHelp, which never allows a book to display a topic. If you choose to use this, you should use it for all books to help prevent user confusion.

Topics. By default, topics are shown by page icons. Displays a (local) topic. URLs. By default, URLs are shown by the Internet icon. Displays the address (URL, email, FTP, newsgroup, multimedia, or remote topic).

Creating the Table of Contents

! !

When you create a project with HHW, there isn't a Contents (.hhc) file. Therefore, when you click the Contents tab, HHW displays the Table of Contents Not Specified message. If you have a .hhc file that you can associate with the project, click the appropriate radio button and select the file. If you need to create a Contents file for your project, accept the default option by clicking OK. The Save As dialog box displays. The default file name is Table of Contents.hhc. However, you should never use spaces in file names in HHW, so you should change this to projectname.hhc or contents.hhc before clicking Save. The Contents tab information displays in HHW and the toolbar updates accordingly.

Page 44

Section 7: Designing the Table of Contents

Adding Headings
!

To create a heading: 1. Click Insert a Heading. The Table of Contents Entry dialog box displays. 2. Type the heading title and click OK. The heading displays at the top of the Contents tab.

To create another heading, click Insert a Heading again. HHW displays a message, asking if you want to insert this heading at the top of the hierarchy. Click Yes or No. You can always reposition books and headings later with the positional arrows.

Adding Pages
!

To create a page to a local topic: 1. Click Insert a Page. When you first insert a page, HHW displays a message, asking if you want to insert this page at the top of the hierarchy. 2. Click Yes or No. The Table of Contents Entry dialog box displays. 3. Type the page title. 4. Click Add. The Path or URL dialog box displays. 5. Select the desired topic from the list of topics and click OK. 6. Click OK.
!

By default, the page is created on the left margin. If you want the page to be an entry under a heading, use the right arrow to indent it under the desired book.

To create a page to another destination: 1. Click Insert a Page. 2. Type the page title. 3. Click Add. The Path or URL dialog box displays. 4. Type desired target in the File or URL input box at the bottom of the dialog box. (See Creating Hyperlinks earlier for targets and formatting.) 5. Click OK twice.

Section 7: Designing the Table of Contents

Page 45

Assigning Topics to Headings

To create a heading with an assigned topic: 1. Click Insert a Heading. 2. Type the heading title. 3. Click Add. 4. Select the desired topic and click OK twice.

To assign a topic to an existing heading: 1. Select the heading. 2. Click Edit. 3. Click Add. 4. Select the desired topic and click OK twice.

Modifying Your Project to Use the Contents File

If you created a custom window, you have to modify the Contents file setting after you create the Contents information. Otherwise, the Contents tab doesn't display. 1. On the Project tab, click Add/Modify Window Definitions. 2. Select the Files tab. 3. Click the drop-down arrow next to TOC and select your contents file (filename.hhc). 4. Select the Navigation Pane tab. 5. Select Auto Sync and change the Default tab to Contents (if desired). 6. Click OK.

Page 46

Section 7: Designing the Table of Contents

Changing the Contents Settings

To change the overall settings of your Table of Contents, click Contents Properties. The Table of Contents Properties dialog box displays.

This option Default Frame and Default Window

Does this

Controls the frame and window where the topic displays. You only have to use these fields if you have customized the frameset or want your topics to display in a secondary window. Sets the default font for all entries. Click the Change button to select the desired font family and size. Selected by default, displays headings as folders. Deselect to display headings as books. Select to use your own icons for your Contents entries. However, a bug in HHW requires the absolute path information for the images file, rendering this useless.

Font

Use Folders Instead of Books Use Custom Images from a File

Section 7: Designing the Table of Contents

Page 47

Changing the Headings and Pages Settings

HHW enables you to also change the default icons for headings (whether originally folders or books) and pages. Select a heading or a page on the Contents tab and click Edit. When the Table of Contents Entry screen displays, select the Advanced tab.
!

The Window and Frame fields are used with custom windows and framesets. You can use the Comment field, if desired.
Mark as a New Entry applies a red starburst to the default icon. Change Entry to a Page displays when a heading is selected. Change Entry to a Heading displays when a page is selected. These options let

! !

you quickly change the selection.

Image Index displays auto by default. Click the up and down arrows to

display the other icons that are available for headings and pages. The following table shows the available choices: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42

! !

By default, HHW uses icons 5 and 6 for headings and icon 9 for pages.

You can change the icon when you first create headings and pages by clicking the Advanced tab on the Table of Contents Entry dialog box.
Section 7: Designing the Table of Contents
Copyright 1999-2000 Creative Computing Company

Page 48

Exercise 5: Creating a Table of Contents

1. Create a Table of Contents with the following headings and pages for local topics. Use the topic title as the Entry Title.
!

Heading: Paint Tutorial linked to Introduction topic

Pages: Color Box, Status Bar, and Tool Box

Heading: Menus linked to Menus topic

! !

Heading: Options Menu linked to Options Menu topic Pages: Get Colors, Edit Colors, Save Colors, and Draw
Opaque

Create the following heading

Heading: Help Over the Web

! ! ! ! ! ! !

Page: Entry Title: Email Char File or URL: mailto:CharJT@helpstuff.com Icon: Email (number 25) Page: Entry Title: Microsoft's HTML Help File or URL:
http://msdn.microsoft.com/workshop/author/htmlhelp/download.asp

Icon: Internet (number 13)

3. 4. 5.

Change the Table of Contents to use books instead of folders. Add the Contents file to the window definition. Compile and run your Help file. When you're finished, close your Help file.

Section 7: Designing the Table of Contents

Page 49

Section 8: Designing an Index

! !

Adding Index Information Understanding the Differences: Sitemap and Binary Indexes Adding Index Entries to the Index File Adding Keywords to Topic Files Creating See and See Also Keywords Sorting the Index Changing the Index Settings Exercise 6: Creating an Index

! ! ! ! ! !

Adding Index Information

Keywords create the index of the Help file.

You can enter keywords in the Index (.hhk) file, in individual topic files, or both. All entries are merged during compilation into the finished index.

! !

A Help file index is comparable to a hardcopy index. A comprehensive index helps the users navigate through your Help file. Duplicate keywords (the same keyword assigned to two or more topics) are displayed once in the index. If the user selects that keyword, the Topics Found dialog box displays, listing all topics containing that keyword.
!

For keywords to display correctly in the Index file, they must be associated with at least one topic.

When using the Index file, you can also:

Add See and See Also keywords to your index (for example, creating, see also adding). When the user clicks this entry, the index displays the adding keyword. By using See and See Also references, you can teach your users the terminology you want them to use. Customize the index. You can place index entries where desired and choose if you want to sort the Index. Create a multi-level index. However, two levels is the norm.

Working with the Index Tab

! !

When you create a project with HHW, there isn't an Index (.hhk) file. Therefore, when you click the Index tab, HHW displays the Index Not Specified message. If you have a .hhk file that you can associate with the project, click the appropriate radio button and select the file. If you need to create an Index file for your project, accept the default option by clicking OK. The Save As dialog box displays. The default file name is Index.hhk. The Index tab information displays in HHW and the toolbar updates accordingly. If you only use topic keywords, you don't have to use the Index tab during development at all. I'll discuss topic keywords a little later in this section.

Section 8: Designing an Index

Page 51

Understanding the Differences: Sitemap and Binary Indexes

By default, HHW creates a binary index for your compiled Help file.
!

A binary index is compiled into your project from keyword entries in the Index (.hhk) file and in the topics. You can't directly edit the binary index. You must use a binary index with associative and keyword linking in your (usually merged) Help system or if you want to be able to merge indexes from different Help files.

! !

The Index (.hhk) file uses the sitemap format, which is an HTML file. The following table shows the differences between the binary and sitemap indexes.
Sitemap Index

Binary Index

Only works with compiled Help files (.chm). Automatically sorted during compilation. Developer cannot control sorting. Compiled size is small, making this a good option for very large indexes. Can be merged with other indexes, which are sorted during compilation. Must be used with associative (ALink) and keyword (KLink) linking.

Works with either compiled Help files or Help projects displayed on a website. (This means a Sitemap Index can be compiled, but doesn't have to be.) Developer has complete control over sorting.

Size is typically larger than a Binary Index. However, due to compression algorithms, this is a better choice for small indexes. Cannot be merged with other indexes. Developer cannot use associative and keyword linking with a Sitemap Index.

Section 8: Designing an Index

Adding Index Entries to the Index File

To create a primary (or first level) keyword associated to a local topic: 1. Click Insert a Keyword. The Index Entry dialog box displays. 2. Type the keyword in the Keyword input box. 3. Click Add. The Path or URL dialog box displays. 4. Select the topic from list of files and click OK. 5. Click OK.

To create a secondary (or multi-level) keyword associated to a local topic: 1. Follow steps 1 through 5 above. 2. The keyword displays as highlighted on the Index tab. Use the up and down arrows to position the keyword under its primary keyword, then use the right arrow to indent it.

To create a keyword to another destination: 1. Click Insert a Keyword. 2. Type the keyword in the Keyword input box. 3. Click Add. The Path or URL dialog box displays. 4. Type desired target in the File or URL input box at the bottom of the dialog box. (See Creating Hyperlinks earlier for targets and formatting.) 5. Click OK twice.

To change the keyword title (which displays in the Topics Found list when multiple topics are associated with a keyword): 1. Click Insert a Keyword. 2. Type the keyword in the Keyword input box. 3. Click Add. The Path or URL dialog box displays. 4. Select the keyword destination. 5. Type the desired title in the Title input box. 6. Click OK twice.
!

You cannot edit the title once the keyword is entered.

Section 8: Designing an Index

Page 53

Adding Keywords to Topic Files

You can add keywords to topics instead of, or in addition to, creating an index file. The following table describes the similarities and differences between keywords stored in topics and keywords stored in the Index file.
Index File

Topic Keywords

Stored within a topic (HTML file). Keyword displays on Index tab only if binary index is created. The HTML Help File must be compiled. Can be merged with other compiled HTML Help files. Cannot be used in See and See Also references. Cannot be custom sorted (automatically alphabetical). Deleting keyword removes it from this topic. Must select checkbox to include topic keywords in project Options. Importing topic with keywords includes all keywords in Index. Can only link to local topics (within the same .chm file). Can be used in Keyword Searches. Cannot be used as a secondary keyword.

Stored within an HHK file (sitemap). Can be used with either binary or sitemap indexes. Can be used with compiled or uncompiled formats (such as WebHelp or JavaHelp). Can be merged with other compiled HTML Help files only if saved in binary format. Can be used in See and See Also references. Can be custom sorted (unless saved in binary format). Deleting keyword removes it from all associated topics. Index file automatically included. Importing topic doesn't include any keywords. Can link to any hyperlink destination. Can be used in Keyword Searches. Can contain up to nine levels of keywords.

Section 8: Designing an Index

To add topic keywords: 1. Open the HTML file and position your cursor before the </BODY> tag. 2. Select Edit | Compiler Information. 3. On the Keywords tab, click Add. The Add Keyword dialog box displays. 4. Type the keyword and click OK. 5. Add other keywords to this topic, as desired, and click OK.

To include topic keywords in your Help file: 1. On the Project tab, select Change Project Options. 2. Click the Files tab. 3. Under Index File, select Include Keywords from HTML Files. 4. Click OK.

Section 8: Designing an Index

Page 55

Creating See and See Also Keywords

One nice feature of HTML Help is the ability to create See and See Also keywords. This allows you to create cross-references (as you would in hardcopy).
! !

See keywords are used for single-entry keywords. See Also keywords are used for multi-level keywords.

See and See Also keywords display in the index, but function differently from regular keywords.
!

When a user clicks the See or See Also entry, the index displays the keyword assigned to that entry.

See and See Also keywords can be entered at any index level (primary or secondary). See and See Also keywords always refer to primary keywords. You have to determine the format you will use to indicate See and See Also keywords.
!

! !

Otherwise, the users won't know they've clicked a See and See Also keyword and can get confused.

Some possible choices are: creating topics: see also adding topics creating topics see also adding topics creating topics (see also adding topics) creating topics, see adding topics

HHW allows you to create primary keywords that link to themselves.

! !

This is a different kind of See or See Also keyword. Primary keywords that are linked to themselves display the following message when selected: To locate information about this keyword,
please select one of the subentries in the list.

This allows you to workaround the hassles associated with primary level keywords, because you don't have to assign one or more topics to the keyword for it to display correctly.
Section 8: Designing an Index
Copyright 1999-2000 Creative Computing Company

Page 56

To create a See or See Also keyword: 1. Click Insert a Keyword. 2. Type the keyword in the Keyword input box. Make sure you include the See or See Also reference so that users understand the keyword functionality. 3. Click Add. The Path or URL dialog box displays. 4. Type the target keyword in the File or URL input box. 5. Click OK. 6. Click the Advanced tab. 7. Select the Target is Another Keyword checkbox. 8. Click OK.

To create a primary keyword that links to itself: 1. Click Insert a Keyword. 2. Type the keyword in the Keyword input box. 3. Click Add. The Path or URL dialog box displays. 4. Type the same keyword in the File or URL input box. This keyword must match the one entered in step 2. 5. Click OK. 6. Click the Advanced tab. 7. Select the Target is Another Keyword checkbox. 8. Click OK.

Section 8: Designing an Index

Page 57

Sorting the Index

If you aren't using the binary index feature, you can custom sort the Index in your Help project.
!

The binary index feature automatically alphabetizes the Index. Custom sorting isn't possible.

To sort the index, click Sort Keywords Alphabetically. All levels sort into alphabetical order. You can use the positional arrows to move index entries, if desired. However, once you click the Sort icon, all entries are sorted.

Section 8: Designing an Index

Changing the Index Settings

To change the overall settings of your Index, click Index Properties. The Index Properties dialog box displays.

This option Default Frame and Default Window

Does this

Font

Section 8: Designing an Index

Page 59

Exercise 6: Creating an Index

1. Create the following primary level index entries and associate them with the listed topic:
Keyword Topic

tool box color box description

Tool Box Color Box Introduction Options Menu

status bar Paint overview editing

Status Bar Introduction Edit Colors

Create the following secondary level index entries and associate them with the listed primary keyword and topic:
Keyword Primary Topic

Options Menu colors

description editing

Options Menu Edit Colors

3. 4. 5.

Create a secondary See Also keyword called Paint under description. Link it to Paint overview. Sort the Index. Compile and run your Help file. When you're finished, close your Help file.

Section 8: Designing an Index

Section 9: Adding Graphics to the Project

! ! !

What Graphic Formats Can Be Included? Inserting Graphics Exercise 7: Inserting Graphics

What Graphic Formats Can Be Included?

GIF (Graphic Interchange Format) files are 8-bit graphic files that can display up to 256 colors. They are best used for screen prints and other small images (for example, bullets). You can change the following GIF characteristics:
!

Transparency. You can select one color in a GIF to be transparent, which allows the background color or background graphic of the HTML file to show through. Remember that all areas of that color will be transparent. (If you have a graphic with a lot of white in it, you might want to change any white around the graphic to another color and then make that color transparent).
!

The common background color for transparent graphics is fuchsia (R:255, G:0, B:255, I:13). You can see an example of this by viewing C:\Program Files\HTML Help Workshop\Java\cntimage.gif.

Interlaced. You can display a GIF as interlaced, which displays every other line of the graphic on the screen and then fills in the missing lines. This lets the user see a rough view of the graphic. Or, you can display the GIF as non-interlaced, which displays the graphic line-by-line from the top. Animation. You can display animated GIFs in your topic files. The animation process stores multiple GIFs in one file, which then play in sequence when the user opens the topic containing the file. Remember that less is usually more: animation can be overly distracting in help. (But according to David, its fun!)

JPEG/JPG (Joint Photographic Expert Group) files are 16 or 24-bit graphic files that contain more than 256 colors. They are best used for photographs and other detailed graphics with many colors. You can also use the following graphics in your project for the specific purposes listed.
!

BMP (bitmap) files are used for splash screens, button faces, and custom Contents images. (You can also use GIFs and JPEG/JPGs for splash screens.) ICO (icon) files are used for button faces.

Page 62

Section 9: Adding Graphics to the Project

Inserting Graphics
! !

To insert graphics in your topics, you use the <IMG> tag. The main attributes of the <IMG> tag are:
! ! ! !

SRC=filename.ext. Include the path information, if necessary. WIDTH=pixels. This should match the width of the graphic. HEIGHT=pixels. This should match the height of the graphic. VSPACE=pixels. This is the number of pixels to display above and below the graphic. HSPACE=pixels. This is the number of pixels to display to the left and right of the graphic. BORDER=pixels. This is the number of pixels for the width of the border. ALIGN=alignment. The possible choices are
! ! ! ! ! ! ! ! !

Default - Uses bottom Left - On the left margin Right - On the right margin Top - Top of graphic with surrounding text Middle - Middle of graphic with surrounding text Bottom - Bottom of graphic with surrounding text Text top - Top of graphic with top of tallest letter on line Abs-middle - Middle of graphic with middle of the line Baseline - Bottom of graphic with baseline (where the capital letters sit) Abs-bottom - Bottom of graphic with bottom of line To center a graphic on a line, use the Center Paragraph option in your HTML Editor. (You can still use any of the other alignment values except Left and Right, which override the centering.)

! !

USEMAP=#mapname. The mapname must match the MAP information included in the HTML file. This information creates an image map, which is a graphic with hotspots.

The <IMG> tag has other attributes. You can find a complete description in the HTML Tag Reference under the Help menu in HHW.
Page 63

Section 9: Adding Graphics to the Project

Exercise 7: Inserting Graphics

1. 2. 3. Copy paint.gif from C:\Projects to C:\Projects\Paint. Insert paint.gif into the Introduction topic after the bullet list. Make sure you place the <IMG> tag after the </UL> tag. Compile and run your Help file. When you're finished, close your Help file.

Page 64

Section 9: Adding Graphics to the Project

Section 10: Adding the HTML Help Control

! ! ! ! ! !

Why Use the HTML Help Control? Designing HTML Help Control Links and Results Creating a Related Topics Button Creating a Keyword Search Button Creating a Splash Screen Exercise 8: Creating HTML Help Controls

Why Use the HTML Help Control?

The HTML Help control is stored in hhctrl.ocx, an ActiveX control designed specifically for use with HTML Help files.
!

ALink Search (creates links to AName objects entered in topics; commonly used for dynamic related topics lists) Close Window (closes the current window or browser) HHCTRL Version (displays the current HHCTRL version in an alert box) Index (displays an index sitemap file) Keyword Search (creates links to Keywords entered in topics; commonly used for dynamic related topics lists) Related Topics (displays a list of coded topics) Shortcut (starts a program or opens a dialog box) Splash Screen (displays a splash screen when the compiled Help file first opens) Table of Contents (displays a contents sitemap file) Training Card (specialized Help topics that send instructions to and receive instructions from a program) WinHelp Topic (displays a topic from a WinHelp Help file)

! !

! ! !

! !

HHW includes the HTML Help wizards. These wizards display different dialog boxes, where you can enter the desired information. You must enter the different variables, such as keywords, AName objects, and program names.

Page 66

Section 10: Adding HTML Help Controls

Designing HTML Help Control Links and Results

For all HTML Help controls except for Table of Contents and Index, you can choose how the link displays. For the Related Topics and Keyword Search controls, you can also choose how the output displays.

Designing the Links

You can choose how your HTML Help controls display to the user:
!

Hotspot (with scripting) Text button Bitmap or icon (You can use any bitmap or icon). You must add the graphic file to the Baggage folder under the Project tab for the button to display correctly.

! !

Designing the Results

You can choose how the results of Related Topics and Keyword Searches display to the user:
!

As a popup

As a Topics Found list

Section 10: Adding HTML Help Controls

Page 67

Designing No-Hit Links

If there's a chance that the ALink Search or Keyword Search you're coding won't have any hits, you have two choices. One controls how the link will look to the user. The other controls the results.
! !

A no-hits link No topics available results

Page 68

Section 10: Adding HTML Help Controls

Creating a Related Topics Button

1. 2. 3. Position your cursor in the topic where you want the Related Topics hotspot to display. Click HTML Help ActiveX Control. The HTML Help ActiveX Control Commands dialog box displays. Related Topics is the default choice for the HTML Help wizards. The second field is only used when scripting the hotspot (to create a text hotspot instead of a button or bitmap). Click Next. The Display Type dialog box displays.

Select Hidden if you will be scripting this control. Otherwise, accept the default for a button. Select Display on a Pop-up Menu unless you want to display the Topics Found dialog box. Select Display Dialog or Menu Even if Only One Title unless you want one hit to immediately jump to the target topic.

Section 10: Adding HTML Help Controls

Page 69

Click Next. The Button Options dialog box displays.

Accept the default selection (Display Text on the Button) to display the hotspot as an HTML Help button. If you want to display a bitmap or icon on the button instead of text, select the appropriate radio button. A Browse button displays under the Text field, so that you can navigate to the graphic. Type the button label in the Text field. If you leave this field blank, a mini-button displays (a 12x12 gray pixel button).

Page 70

Section 10: Adding HTML Help Controls

Click Next. The Related Topics dialog box displays.

Add topics to the list by clicking Add. The Add/Edit Related Topic dialog box displays.

8. 9.

Enter the title for the popup menu or Topics Found list in the Title field. Enter the filename (or a URL) in the File/URL field. Continue to add related topics. If necessary, edit or delete entries by clicking the appropriate button. When you've added your list of topics, click Next.

10. The Finish dialog box displays. Click Finish to create your Related Topics hotspot.

Section 10: Adding HTML Help Controls

Page 71

Creating a Keyword Search Button

1. 2. 3. Position your cursor in the topic where you want the Keyword Search hotspot to display. Click HTML Help ActiveX Control. The HTML Help ActiveX Control Commands dialog box displays. Click the drop-down arrow and select Keyword Search from the list. The second field is only used when scripting the hotspot (to create a text hotspot instead of a button or bitmap). Click Next. The Display Type dialog box displays. Select your display choices. Click Next. The Button Options dialog box displays. Select your button choices. Click Next. The Keyword Search dialog box displays.

4. 5. 6. 7. 8.

This dialog box is very similar to the Related Topics dialog box discussed previously. Click the Add button to add keywords to the list.

Click Next.

10. Click Finish.

Page 72 Section 10: Adding HTML Help Controls
Copyright 1999-2000 Creative Computing Company

Creating a Splash Screen

1. Position your cursor in the topic where you want the Splash Screen control.
!

Unlike clickable ActiveX controls, the Splash Screen control is triggered as soon as the user displays the portion of the topic where the control is located. Because the ActiveX control displays space in the compiled Help file, you should position your cursor after the heading of the topic.

2. 3.

Click HTML Help ActiveX Control. The HTML Help ActiveX Control Commands dialog box displays. Click the drop-down arrow and select Splash Screen from the list. The second field isn't used with the Splash Screen control. Click Next. The Splash dialog box displays.

5. 6. 7. 8.

Type the name of the graphic that you want to display. If necessary, enter path information. Type the number of seconds that the splash screen should display. Click Next. Click Finish.

Section 10: Adding HTML Help Controls

Page 73

Exercise 8: Creating HTML Help Controls

1. 2. Create a new topic with the title Welcome. Add the following text to the topic: <H1>Welcome</H1> 3. 4. 5. 6. 7. 8. 9. Add a Splash Control after the heading to display crayons.gif. Save the file as Welcome.htm. Change the project settings to use Welcome as the default topic. Add Welcome to the files list. Compile and test your Help file. When you're finished, close your Help file. Open the Introduction topic in the HTML editor. Position your cursor on the line following the graphic command.

10. Insert a Related Topics HTML Help Control, specifying Menus, Color Box, Status Bar, and Tool Bar as the topics. 11. Compile and test your Help file. When you're finished, close your Help file.

Page 74

Section 10: Adding HTML Help Controls

Section 11: Distributing Your Help File

! !

Preparing for Distribution What Files Do You Need to Ship?

Preparing for Distribution

Before distributing your help file, you need to be sure to:

! !

Check for broken links and unreferenced topics Verify that your external topic references (URLs, email address, and so on) exist Turn on Full Text Search (in Project Settings), if desired

! !

If necessary, make any corrections, then rerun the reports and make sure everything is fixed.

Page 76

Section 11: Distributing Your Help File

What Files Do You Need to Ship?

Regardless of anything else, you must send users the .chm file.

Internet Explorer 4/4.xx/5

If you know positively that your users have installed Internet Explorer 4 (or a later version), you don't have to do anything else. The latest version of IE will always include the latest version of hh.exe. IE itself includes the other files (registered) that are required. (Even if IE is on the system, it's best to run the latest version of hhupd.exe in order to ensure the HTML Help viewer files are up-to-date.)
! ! !

IE4 installs the viewer files for HTML Help 1.0. IE5 installs the viewer files for HTML Help 1.21. Microsoft Win98 SE, Microsoft Windows 2000, Microsoft Office 2000, and Visual Studio 6 all install IE5.

Section 11: Distributing Your Help File

Page 77

Internet Explorer 3/3.x and Netscape Navigator Only

If users are installing to earlier versions of IE, or on systems that are only using Netscape Navigator, you must install a minimum of IE3 and then run hhupd.exe. This installs the following files:
!

hhctrl.ocx (C:\Windows\System). This file is required if using custom windows or any ActiveX control. itircl.dll (C:\Windows\System). This file is required when installing compressed files (.chm). itss.dll (C:\Windows\System). This file is required if you are including the full-text search tab. hh.exe (C:\Windows). This file is the run-time engine for the .chm file.

! !

HTML Help 1.3 may also install multiple copies of HHCTRLUI.DLL in 28 folders under the folder MUI.
!

On the HTML Help Installation and Update Package page for HTML Help version 1.22, there are/were 28 language versions of hhupd.exe listed, one for each language. HTML Help 1.3, which ships with both Internet Explorer 5.5 and Windows 2000, is set up for both the multiple language operating system Windows 2000 and the multiple language Office 2000. Because of this, HTML Help 1.3 ships with all 28 language versions. Now, it should only install those language versions you've selected in your system.
!

For example, having three English versions (UK, Australia, and Canada) installed in an Office 2000 installation, you should have three versions of HHCTRLUI.DLL on your machine, one for each of these languages.

You may end up with more if you have Office 2000 on your machine, then install other languages when upgrading this machine to Windows 2000.

Page 78