Copyright: Copyright ME, 1994.
Citation: You shouldn't have printed this without my permission.


About This Topic File Sample

This is the first topic of a very short but functional topic file. The idea is to cover some of the basics within the context of an actual component of a Help file.

This topic file (SAMPLE6.RTF) is one of three components of a WinHelp 4.0 Help file. The other two are the Project file (SAMPLE.HPJ) and the Contents file (SAMPLE.CNT). Compiled together these three files comprise the Help file (SAMPLE.HLP).

This topic file was prepared in MS Word 6.0 using the Normal template and saved in the Rich Text Format type.

We recommend you read through this file once quickly to get an overall concept of its structure and then spend some time examining individual topics. Many of the topics here contain instructional and sometimes reference material, but keep in mind as your read this material that it was never intended to be complete.

Once you are relatively familiar with the contents of this topic file, print out a paper copy, run SAMPLE.HLP, and compare the two with an eye to how the results were achieved. And then repeat this with the Project and Contents files.


About Topics

The Help topic is the basic unit of information in a Help file. Topics are prepared, one to a page, in topic files. Topic files are saved as Rich Text Format type and must have an .RTF extension.

An individual topic contains one or more of the following components:

Informational material. This is the text you are reading now, including the headline, “About topics.” We’ll say more about informational material in another topic of this topic file.

Hotspots. Hotspots are special points on a topic screen. When the user clicks on a hotspot, another topic appears or a macro is run. A hotspot can be a word, a phrase, a graphic, or a portion of a graphic. In this topic the three subheads are designated as hotspots. The text formatted Hidden (shown here in dotted underline) is the topic ID of the topic that will appear.

When this topic is displayed in the finished Help system, these hotspots will appear single-underlined and green. The hidden topic ID text, of course, will not be visible. We’ll say more about hotspots in another topic of this topic file.

Footnotes. Footnotes with custom footnote marks define certain characteristics of each topic. This topic has five footnotes. To view their contents select Footnotes from the View menu. We’ll say more about footnotes in another topic of this sample topic file.

Note

The text {bmc bullet.bmp} is a bitmap reference that results in the display of a bullet symbol when this topic appears in the finished Help system.


About Informational Text

Before we get into informational text, notice the reference text with curly brackets just above this sentence. This is a custom button configured as a hotspot. The text “ALink” is the name of a macro that displays a list of all topics having the A-keyword designated in the parentheses, in this case “DO_IT.” The text “proc4” specifies that the topic is to be displayed in a proc4 window as defined in the Project file. Only one topic in this topic file has the A-keyword “DO_IT,” so only one topic is displayed in the list.

Back to information text....

Information text is what the user sees when he runs a Help system. Here the informational material comprises the title, “Informational material” and this paragraph of text.

This topic has five footnotes, but no hotspots

When this topic is displayed in the finished Help file, a vertical scroll bar will appear to allow the user to scroll through the entire text. The heading “About Informational Material” will not scroll because it has been formatted “Keep with Next” in the Paragraph dialog box (available on the Format menu).

The rest of this topic is dummy text to demonstrate jumps within a topic and the effect of long topics with scroll bars and nonscrolling text.

Jump to beginning of topic

Jump to Alpha

Jump to Beta

Jump to Gamma

Jump to Omega

This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text.

Alpha

This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text.

This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text.

Beta

This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text.

This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text.

This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text.

Gamma

This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text.

This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text.

This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text.

This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text.

This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text.

Omega

This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text. This is dummy text.


About Hotspots

Hotspots are special points on a topic screen. A cursor arrow become a pointing hand when over a hotspot. When the user clicks on a hotspot, another topic appears or a macro is run. A hotspot can be a word, a phrase, a graphic, or a portion of a graphic.

1. The following text is a jump hotspot:

Footnotes

The word “Footnotes” is double underlined and will appear single-underlined and green in the finished Help file. The word “FOOTNOTE” is the topic ID (a topic’s unique identifier) for a topic about footnotes. The word “FOOTNOTE” is formatted as hidden text and does not appear in the displayed Help file. When the user clicks “Footnote” in the displayed Help file, the current topic will disappear and the topic with the topic ID “FOOTNOTE” will appear in its place.

2. The following text is a graphic hotspot:

The bitmap reference “{bmct light.bmp}” is double underlined to make it a hotspot, but the displayed graphic will appear normal (that is, with no underlining or green overlay) in the displayed Help file. The word “GRAPHICS” is formatted as hidden text and does not appear in the displayed Help file.

3. The following text is a pop-up hotspot:

Pop-up

The word “Pop-up” is single underlined and will appear dotted underlined and green in the finished Help file. The word “POPUP” is the topic ID for a topic that will display in the pop-up window. The word “POPUP” is formatted as hidden text and does not appear in the displayed Help file. When the user clicks “Pop-up” in the displayed Help file, the current topic will remain, but the topic with the topic ID “POPUP” will appear on top until the user clicks anywhere.

4. The following graphic is a multiple hotspot graphic

It was prepared using the Microsoft Hotspot Editor (SHED.EXE) and has seven hotspots. When the user clicks on a portion of the map, a pop-up topic displays to identify the region.


About Multimedia

Multimedia can often be more useful to a user than ordinary text. For example, an animation of a task might be more helpful than a step-by-step description, or it might be useful as a summary. In addition, sound can be useful in providing feedback to the user.

The following topic statement adds a sound (.WAV) file to the Help file:

The EXTERNAL command keeps the file outside of the Help file, so it does not increase the size of the compiled Help file. The PLAY command causes the sound file to play as soon as the topic is opened.

Note

If your computer is not setup to play multimedia files, you will get an error message when you display this topic.


About Footnotes

Footnotes define certain characteristics of each topic. This topic has five footnotes. To view their contents select Footnotes from the View menu.

Parameter	Footnote mark	Purpose

Topic ID	#	Defines a unique identifier for a topic. Mandatory. In this topic the topic ID is FOOTNOTE. (Note: Actually, a topic can have more than one topic ID distributed throughout a single topic. Jumps to one of these additional topic IDs will open a topic at the point the custom mark was inserted.)

Title	$	Specifies the title of the topic as it appears in various places throughout the Help file. In this topic, the title is “About footnotes.” Note the lowercase ‘f’.

Keyword	K	Specifies words used in the index and in KLink macros. In this topic, keywords are cross-listed for their separate listing in the index and as sublistings under the heading, “footnotes.”

A-Keyword	A	Specifies words that identify the topic to ALink macros. In this topic an A-keyword footnote contains “sample_a.”

Browse Code	+	Defines topic's place in a browse sequence. This topic’s browse code is ‘005,’ indicating that it is the fifth in sequence when the user clicks the browse buttons.

Entry Macro	!	Specifies a macro that runs when user opens the topic. In this topic the entry macro footnote is not used.

Build tag	*	Identifies topics for conditional compiler builds. This topic’s build tag is ‘maybe.’ By placing an instruction in the project file, you can exclude this topic from the finished help file but retain it in the topic file. When build tags are used, their footnote marks must be the first of any series of footnote marks.

Window type	>	Specifies a window type for the topic. In this topic the window type footnote is not used.

Comment	@	Includes an author's notes about the topic. User does not see this text. This topic has internal note about a pending issue.


About Graphics

You can include graphics of the following formats in your Help file.

Format	Description

.DIB	Windows bitmap

.BMP	Windows bitmap

.WMF	Windows metafile

.SHG	Windows Help multi-hotspot bitmap

.MRB	Windows Help multi-resolution bitmap

Although it is possible to paste a graphic directly into topic from the clipboard, the best way to include a graphic in a topic is indirectly by using the special bitmap reference statement {bmx}. This method has the following advantages:

Correct display of standard system colors

Correct display of pictures using custom color palettes

Permits portions of the graphic to serve as hotspots for topic, pop-up, and macro jumps

Correct display of transparent bitmaps


This is an example of a pop-up topic. Pop-up topics are ideal for context-sensitive help and short definitions. They seldom need more than a topic ID footnote.


How to do almost anything

1.	Plan

2.	Draft

3.	Finalize

Expecting a longer procedure? Actually, this is here just to give you an example of a secondary window. Secondary windows are topic windows without a menu bar. Because they remain open unless explicitly closed, they are ideal for procedures and other information that the user will frequently consult while actually working within an application.

 Related Topics


This is North America.


This is Mexico.


This is South America.


This is Europe.


This is Africa.


This is Asia.


This is Australia