[Home]
[Search]
[CTG]
[RTL]
[IDDE]
Last update Jan 29, 2003
HC: Help Compiler
A Help system provides users with online information about an
application. Creating the system requires the efforts of both a
Help writer and a Help programmer. The Help writer plans, writes,
codes, builds, and keeps track of Help topic files, which are text files that
describe various aspects of the application. The Help programmer
ensures that the Help system works properly with the application.
This chapter assumes you are familiar with the Help application for
Microsoft Windows 3.x. The advice it contains about how to plan and
structure Help systems is applicable to Windows NT and Windows 95.
For more information on creating Windows Help, see:
- Windows Help Authoring Guide, Microsoft Press.
- Chapter 12, "User Assistance," in Windows Interface
Guidelines: A Guide for Designing Software, Microsoft
Press.
- Moving to Windows 95 Help, Blue Sky Software.
What's in This Chapter
- Planning a Help system.
- Structuring topic files.
- Designing, structuring, and coding Help topics.
- Authoring tools.
- Dealing with graphic images.
- Creating the Help Project file.
- Compiling Help files for Win16 applications.
Creating a Help System: The Development Cycle
The creation of a Help system for a Windows application comprises
the following major tasks:
- Gathering information for Help topics.
- Planning the Help system.
- Writing the text for Help topics.
- Entering all required control codes into the text files.
Control codes determine how the user can move around
the Help system.
- Creating a project file for the build.
The Help project file provides information that the Help
Compiler needs to build a Help resource file.
- Building the Help resource file.
The Help resource file is a compiled version of the topic
files the writer creates.
- Testing and debugging the Help system.
- Programming the application so it can access Windows
Help.
How Help appears to the user
To the user, the Help system appears to be part of the application and
is made up of text and graphics displayed in the Help window in front
of the application. The Help window displays one sample Help topic,
a partial description of how to perform one task. By pressing the
mouse button when the cursor is on an underlined word, the user can
read the definition, which appears in an overlapping box as long as
the mouse button is held down.
Cross-references to related topics are called jumps. By clicking a jump
term for a related topic (denoted by underlined text), the user
changes the content of the Help window to a description of the new
topic or command.
How Help appears to the Help writer
To the writer, the Help system is a group of topic files, which are text
files that include special codes. To create a topic, the Help writer
describes the task, formats the text, and inserts codes using
strikethrough text, underlined text, and footnotes. In place of
strikethrough, the writer can use double underlining if the word
processor does not support strikethrough formatting. Footnotes in the
text contain linking information required by the Help Compiler.
How Help appears to the Help programmer
To the programmer, Windows Help is a stand-alone Windows
application that the user can run like any other application. Your
application can call the WinHelp function to ask Windows to run the
Help application and specify the topic to be displayed in the Help
window.
See the section "Building the Help File" later in this chapter for details
about the Help application programming interface (API).
Planning the Help System
The initial task for the Help writer is to develop a plan for creating
the system. This following sections discuss planning the Help system
for a particular application.
These sections cover the following topics:
- Developing a plan
- Determining the topic file structure
- Designing the visual appearance of Help topics
Developing a Plan
Before you begin writing Help topics using the information you have
gathered, you and the other members of the Help team should
develop a plan to:
- Define the audience for your application
- Plan the content of the Help topics
- Design the structure of topics
- Display the use of context-sensitive topics
You might want to present your plan in a design document that
includes an outline of Help information, a diagram of the structure of
topics, and samples of the various kinds of topics your system will
include. Keep in mind that context-sensitive Help requires increased
development time, especially for the application programmer.
Defining the audience
The audience determines what kind of information you make
available in your Help system and how you present the information.
Users of Help systems might be classified as follows:
- Novice
- Completely new to computing.
- Beginner
- Some knowledge of computing, but new to your
kind of application. For example, if you are
providing Help for a spreadsheet program, the
application novice might be familiar only with
word-processing packages.
- Experienced
- Knowledgeable about your kind of application.
- Expert
- Extensive experience with your type of
application.
Keep in mind that one user may have various levels of knowledge.
For example, the expert in word processors may have no experience
using spreadsheets.
Designing the content of the Help system
Create topics that are numerous enough and specific
enough to provide your users with the help they need.
Novice users need help learning tasks and definitions of terms. More
sophisticated users occasionally seek help with a procedure or term,
but most often refresh their memory of commands and functions. The
expert user tends to seek help only with command or function syntax,
keyboard equivalents, and shortcut keys.
There are no rules for determining the overall content of your Help
system. If you are providing Help for all types of users, you will want
to document commands, procedures, definitions, features, functions,
and other relevant aspects of your application. If you are providing
help for expert users only, you might want to omit topics that describe
procedures. Let your audience definition guide you when deciding
what topics to include.
Keep in mind that the decision to implement context-sensitive Help
is an important one. Context-sensitive Help demands a close working
relationship between the Help author and the application
programmer and, therefore, increases the development time
necessary to create a successful Help system.
Planning the structure of Help topics
Many Help systems structure topics hierarchically. At the top of the
hierarchy is an index or a table of contents, or both. The index and
table of contents list individual topics or categories of topics available
to the user.
Topics themselves can be related hierarchically. Each successive step
takes the user down one level in the hierarchy of the Help system
until topic information is reached. The hierarchical relationship of
Help topics determines in part how the user navigates through the
Help system.
Helpex contains an index that lists several categories of topics. Each
category includes a secondary index, which lists topics in the category
as well as the topics themselves.
Moving from the index to a topic, the user goes from the general to
the specific.
The hierarchical structure provides the user a point of reference
within Help. Users are not constrained to navigating up and down the
hierarchy; they can jump from one topic to another, moving across
categories of topics. The effect of jumps is to obscure hierarchical
relationships. For example, the Windows Help application contains a
search feature that lets the user enter a keyword into a dialog box and
search for topics associated with that keyword. The Help application
then displays a list of titles from which to choose in accessing
information that relates to the keyword.
Because users often know which feature they want help with, they
can usually find what they want faster using the search feature than
they can by moving through the hierarchical structure.
In addition to ordering topics hierarchically, you can order them in a
logical sequence that suits your audience. The logical sequence, or
browse sequence, lets the user choose the Browse button to move
from topic to topic. Browse sequences are especially important for
users who like to read several related topics at once, such as topics
covering the commands on the File menu.
Whichever structure you decide to use, try to minimize the number of
lists that users must traverse to obtain information. Also, avoid making
users move through many levels to reach a topic. Most Help systems
function quite well with only two or three levels.
Displaying context-sensitive Help topics
Windows Help supports context-sensitive Help. When written in
conjunction with programming of the application, context-sensitive
Help lets the user press F1 in an open menu to get help with the
selected menu item. Alternatively, the user can press Shift-F1 and then
click on a screen region or command to get help on that item.
Developing context-sensitive Help requires coordination between the
Help writer and the application programmer so that Help and the
application pass the correct information back and forth.
To plan for context-sensitive Help, the Help author and the
application programmer should agree on a list of context numbers.
Context numbers are arbitrary numbers that correspond to each menu
command or screen region in the application and are used to create
the links to the corresponding Help topics. You can then enter these
numbers, along with their corresponding context-string identifiers, in
the Help project file, which the Help Compiler uses to build a Help
resource file.
The context numbers assigned in the Help project file must
correspond to the context numbers that the application sends at run-time
to invoke a particular topic.
If you do not explicitly assign context numbers to topics, the Help
Compiler generates default values by converting topic context strings
into context numbers.
To manage context numbers and file information, you might want to
create a Help tracker to list the context numbers for your context-sensitive
topics.
Determining the Topic File Structure
The Help file structure remains essentially the same for all
applications even though the context and number of topic files differ.
Topic files are segmented into the different topics by means of page
breaks. When you build the Help system, the compiler uses these
topic files to create the information displayed for the user in the
applications Help window.
When choosing a file structure for your Help system, consider the
scope and content of the Help system you are planning. For example,
you could place all Help topics in a single large topic file or place
each Help topic in a separate file. Neither of these file structures is
generally acceptable. An enormous single file or too many individual
files can present difficulties during the creation of the Help resource
file.
The number of topics relates to the number of features covered by the
Help system. Consequently, you cannot make extensive changes to
one without also making changes to the other. For instance, if a
number of additional product features is added to Help, then
additional topics must be created to accommodate the new
information.
Designing the Appearance of Help Topics
How the information in the Help window appears to the user is
primarily a function of the layout of the Help topic. The Windows
Help application supports a number of text attributes and graphic
images you can use to design your Help window.
This section provides general guidelines for designing a window and
describes fonts and graphic images that Windows Help supports.
Layout of the Help text
Help text files are not limited to plain, unformatted text. You can use
different fonts and point sizes, include color and graphics to
emphasize points, present information in tables, indent paragraphs to
present complex information, and use a variety of other visual devices
to present your information.
Research on screen format and Help systems has produced general
guidelines for presenting information to users. The section
"Additional Resources" later in this chapter lists some sources of this
research. The following list summarizes the findings of these studies.
Language
Use language appropriate for the audience that you have defined.
Language that is too sophisticated for your audience can frustrate
users by requiring them to learn the definitions of unfamiliar terms
and concepts. Conversely, language that is overly simplistic may
insult your readers.
Amount of text
Use the minimum of text possible. Studies indicate that reading speed
decreases by 30% when users read online text rather than printed text.
Minimal, concise text helps users compensate for that decreased
reading speed.
Paragraph length
Use short paragraphs. Online users become overloaded with text
more easily than do readers of printed material. Breaking text into
short paragraphs helps avoid this problem.
White space
Use white space to group information visually. It makes online text
more readable. Use it liberally, while also considering the overall size
that a topic occupies on the screen. Users tend to think there is more
information on a screen than actually exists. For example, if the ratio
of white space to text is 50: 50, users perceive the ratio to be 40: 60.
Highlighting
Use highlighting judiciously. Windows Help provides a variety of
highlighting devices such as font sizes, font types, and color. Using a
few of these devices can help users find information quickly. Too
many highlighted items can decrease the effectiveness of your visual
presentation and confuse users. As with print-based documentation,
use only one or two fonts at a time.
Graphics and icons
Use graphics and icons to support the explanation of visual events.
Window Help supports the use of bitmapped graphic images. Use
appropriate images to help explain the function of icons and screen
elements in your application. Remember that graphics draw the user's
eye before the accompanying text. Be sure to crop your images to
remove distracting information. Use color images only if you are
certain that your user's systems have color capabilities. As with
context-sensitive help, consider the additional time necessary to
create accurate and meaningful graphic images. See the section
"Inserting Graphic Images" later in this chapter for more information
on placing graphics in your Help files.
Design consistency
Be rigorously consistent in your design. Users expect the appearance
of Help topics to be the same, regardless of the information
presented. Consistent titling, highlighting, fonts, and positioning of
text in the window are essential for an effective help system.
Type fonts and sizes
The Windows Help application can display text in any font and size
available to the system. When the topic files are passed to the build
process, the Help Compiler attempts to use the fonts and sizes found
in the topic files. If a font or point size cannot be matched exactly
when the Help file is displayed by Windows Help, the closest
available font and size on the users system is used.
Windows ships with only certain fonts in specific font sizes. If you
write Help files using these fonts and sizes, the displayed Help file
closely matches the printed word-processed file. Because fonts other
than those shipped with Windows may not be available on users
machines, you might want to limit your font selection to the shipped
Windows fonts.
The fonts included with Windows are:
- Courier 10, 12, 15
- Helvetica 8, 10, 12, 14, 18, 24
- Modern
- Roman
- Script
- Symbol 8, 10, 12, 14, 18, 24
- Times Roman 8, 10, 12, 14, 18, 24
Since Windows Help supports any Windows font, special symbols
such as arrows can be included in your topics by using the Symbol
font.
Graphic images
The Windows Help application allows you to embed graphics in the
Help file. Graphics can be placed and displayed anywhere on the
page.
Color graphic images can be included, provided that you use only the
available Windows system colors. If you use graphics tools that
support an enhanced color palette to create or capture images, these
images may not always display with the intended colors. And since
you cannot control the color capabilities on a user's machine, you
might want to limit your graphic images to black and white bitmaps.
Keep in mind that graphics are most effective when they contribute
to the learning process. Graphics not tied to the information are
usually distracting rather than helpful and should be avoided. See the
section "Inserting Graphic Images" later in this chapter for more
information on placing graphics in your Help files.
Additional Resources
For additional information about planning your Help system, see the
following:
- Bradford, Annette Norris. Conceptual Differences
Between the Display Screen and the Printed Page.
Technical Communication (Third Quarter 1984): 13-16
- Galitz, Wilbert O. Handbook of Screen Format Design. 3d
ed. Wellesley, MA: QED Information Sciences, Inc., 1989
- Houghton, Raymond C., Jr. Online Help Systems: A
Conspectus. Communications of the ACM 27 (February
1984): 126-133
- Queipo, Larry. User Expectations of Online Information.
IEEE Transactions on Professional Communications PC 29
(December 1986): 11-15
Creating Help Topic Files
Probably the most time-consuming task in developing a Help system
for your application is creating the Help topic files from which you
compile the Help system. Help topic files are text files that define
what the user sees when using the Help system. The topic files can
define various kinds of information, such as an index to information
on the system, a list of commands, or a description of how to
perform a task.
Creating topic files entails writing the text that the user sees when
using Help and entering control codes that determine how the user
can move from one topic to another.
The following sections describe:
- Choosing an authoring tool
- Structuring Help topic files
- Coding Help topic files
Choosing an Authoring Tool
To write your text files, you need a Rich Text Format (RTF) editor,
which lets you create the footnotes, underlined text, and
strikethrough or double-underlined text that indicate the control
codes. Your choices include, but are not limited to:
- Microsoft Word for Windows, version 1.0 or higher
- Microsoft Word for the PC, version 5.0 or higher
- Microsoft Word for the Macintosh, version 3.0 or 4.0 or
higher
- Other word processors that support RTF
Microsoft Word's RTF capability allows you to insert the coded text
required to define Help terms, such as jumps, keywords, and
definitions. If you choose an editor other than one of the Microsoft
Word products, make sure it creates Help files that work as you
intend.
Structuring Help Topic Files
A Help topic file typically contains multiple Help topics. To identify
each topic within a file:
- Individual topics are separated by hard page breaks.
- For each topic accessible via a hypertext link, use a
unique identifier or context string.
In addition, each topic can have a(n):
- Title
- List of keywords associated with it
- Build-tag indicator
- Assigned browse sequence
For information about inserting page breaks between topics, see the
documentation for the editor you are using. For information about
assigning context strings and titles to topics, see the following section.
Coding Help Topic Files
The Help system uses control codes for particular purposes:
Table 26-1 Help system control codes
Control code Purpose
Asterisk (*) footnote Build tag: defines a tag that specifies topics
the compiler conditionally builds into the
system. Build tags are optional, but they
must appear first in a topic when they are
used.
Pound sign (#) footnote Context string: defines a context string that
uniquely identifies a topic. Because
hypertext relies on links provided by
context strings, topics without context
strings can be accessed only by using
keywords or browse sequences.
Dollar sign ($) footnote Title: defines the title of a topic. Titles are
optional.
Letter K footnote Keyword: defines a keyword the user uses
to search for a topic. Keywords are
optional.
Plus sign (+) footnote Browse sequence number: defines a
sequence that determines the order in
which the user can browse through topics.
Browse sequences are optional. However, if
you omit browse sequences, the Help
window still includes the Browse buttons,
but they are grayed out.
Strikethrough Cross-reference: indicates the text the user
can choose to jump to another topic.
Underlined text Definition: specifies that a temporary or
look-up box be displayed when the user
holds down the mouse button or Enter key.
The box can include such information as
the definition of a word or phrase, or a hint
about a procedure.
Hidden text Cross-reference context string: specifies the
context string for the topic that is displayed
when the user chooses the text that
immediately precedes it.
If you are using build tags, footnote them at the very beginning of the
topic. Place other footnotes in any order you want. For information
about assigning specific control codes, see the following sections.
Assigning build tags
Build tags are strings that you assign to a topic to conditionally
include or exclude that topic from a build. Each topic can have one
or more build tags. Build tags are not a necessary component of your
Help system. However, they do provide a means of supporting
different versions of a Help system without having to create different
source files for each version. Topics without build tags are always
included in a build.
You insert build tags as footnotes using the asterisk (*). When you
assign a build tag footnote to a topic, the compiler includes or
excludes the topic according to build information specified in the
BUILD option and [BuildTags] section of the Help project file. For
information about the BUILD option, the [BuildTags] section and
the Help project file, see "Specifying build tags: the BuildTags section"
and "Specifying build topics: the Build option" in the section
"Creating the Help Project File" in this chapter.
To assign a build tag to a topic:
- Place the cursor at the beginning of the topic heading
line, so that it appears before all other footnotes for that
topic.
- Insert the asterisk (*) as a footnote reference mark.
Note that a superscript asterisk ( * ) appears next to the
heading.
- Type the build tag name as the footnote.
- Be sure to allow only a single space between the asterisk
and the build tag.
Build tags can be made up of any alphanumeric characters. The build
tag is not case sensitive. The tag may not contain spaces. You can
specify multiple build tags by separating them with a semicolon, as in
the following example:
* AppVersion1; AppVersion2; Test_Build
Including a build tag footnote with a topic is equivalent to setting the
tag to true when compared to the value set in the project file. The
compiler assumes all other build tags to be false for that topic. After
setting the truth value of the build tag footnotes, the compiler
evaluates the build expression in the Options section of the Help
project file. Note that all build tags must be declared in the project file,
regardless of whether a given conditional compilation declares the
tags. If the evaluation results in a true state, the compiler includes the
topic in the build. Otherwise, the compiler omits the topic.
The compiler includes in all builds all the topics that do not have a
build tag footnote regardless of the build tag expressions defined in
the Help project file. For this reason, you may want to use build tags
primarily to exclude specific topics from certain builds. If the compiler
finds any build tags not declared in the Help project file, it displays
an error message.
By allowing conditional inclusion and exclusion of specific topics,
you can create multiple builds using the same topic files. This saves
time and effort for the Help development team. It also means that you
can develop Help topics that help you maintain a higher level of
consistency across your product lines.
Assigning context strings
Context strings identify each topic in the Help system. Each context
string must be unique. A given context string may be assigned to only
one topic within the Help project; it cannot be used for any other
topic.
The context string provides the means to create jumps between topics
or to display look-up boxes, such as word and phrase definitions.
Although not required, most topics in the Help system have context-string
identifiers, Topics without context strings may not be accessed
through hypertext jumps. However, topics without context-string
identifiers can be accessed through browse sequences or keyword
searches, if desired. It is up to the Help writer to justify the authoring
of topics that can be accessed only in these manners. For information
about assigning jumps, see the section "Creating cross-references
between topics" later in this chapter. For information about assigning
browse sequences, see the section "Assigning browse sequence
numbers" later in this chapter. For information about assigning
keywords, see the section "Assigning keywords" later in this chapter.
To assign a context string to a Help topic:
- Place the cursor to the left of the topic heading.
- Insert the pound sign (#) as the footnote reference mark.
Note that a superscript pound sign ( # ) appears next to the
heading.
- Type the context string as the footnote.
- Be sure to allow only a single space between the pound
sign and the string. Context strings are not case sensitive.
Valid context strings may contain the alphabetic characters A - Z, the
numeric characters 0 - 9 and the period (.) and underscore (_)
characters. The following example shows the context string footnote
that identifies a topic called Opening an Existing Text File:
#OpeningExistingTextFile
Although a context string has a practical limitation of about 255
characters, there is no good reason for approaching this value. Keep
the strings sensible and short so that they're easier to enter into the
text files.
Assigning titles
Within the Help system, title footnotes perform the following
functions:
- Appear on the Bookmark menu.
- Appear in the Topics found list that results from a
keyword search. (Topics that do not have titles, but are
accessible via keywords, are listed as >> Untitled Topic<<
in the Topics found list.)
Although not required, most topics have a title. You might not assign
a title to topics containing low-level information that Help's search
feature, look-up boxes, and system messages do not access.
To assign a title to a topic:
- Place the cursor to the left of the topic heading.
- Insert a footnote with a dollar sign ($) as the footnote
reference mark.
Note that a superscript dollar sign ( $ ) appears next to the
heading.
- Type the title as the footnote.
Be sure to allow only a single space between the dollar
sign ($) and the title.
The following is an example of a footnote that defines the title for a
topic:
$ Help Keys
When adding titles, keep in mind the following restrictions:
Item Restrictions
Characters
Title can be up to 128 characters in length. The
Help compiler truncates title strings longer than
128 characters. When the user searches for a
keyword or enters a bookmark, the Help system
displays titles in a list box.
Formatting
Title footnote entries cannot be formatted.
Assigning keywords
Help allows the user to search for topics with the use of keywords
assigned to the topics. When the user searches for a topic by
keyword, Help matches the user-entered word to keywords assigned
to specific topics. Help then lists matching topics by their titles in the
Search dialog box. Because a keyword search is often a fast way for
users to access Help topics, you probably want to assign keywords to
most topics in your Help system.
Note:
You should specify a keyword footnote only if the
topic has a title footnote, since the title of the topic
appears in the search dialog when the user searches
for the keyword.
To assign a keyword to a topic:
- Place the cursor to the left of the topic heading.
- Insert an uppercase K as the footnote reference mark.
Note that a superscript K(K) appears next to the heading.
- Type the keyword, or keywords, as the footnote.
Be sure to allow only a single space between the K and
the first keyword.
If you add more than one keyword, separate each with a
semicolon.
The following is an example of keywords for a topic:
K open; opening; text file; ASCII; existing;
text only; documents;
Whenever the user performs a search on any of these keywords, the
corresponding titles appear in a list box. More than one topic may
have the same keyword.
When adding keywords, keep in mind the following restrictions:
Table 26-2 Keyword restrictions
Item Restrictions
Characters
Keywords can include any ANSI character,
including accented characters. The
maximum length for keywords is 255
characters. A space embedded in a keyword
is considered a character, permitting phrases
to be keywords.
Phrases
Help searches for any word in the specified
phrase.
Formatting
Keywords are not formatted.
Case sensitivity
Keywords are not case sensitive.
Punctuation
Except for semicolon delimiters, you can
use punctuation.
Creating multiple keyword tables
Multiple keyword tables are useful in allowing a program to look up
topics defined in alternate keyword tables. You can use an additional
keyword table to allow users familiar with keywords in a different
application to identify the matching keywords in your application.
Authoring additional keyword tables is a two-part process. First, the
MULTIKEY option must be placed in the [Options] section of the
project file.
Second, the topics to be associated with the additional keyword table
must be authored and labeled. Footnotes are assigned in the same
manner as are normal keyword footnotes, except that the letter
specified with the MULTIKEY option is used. With this version of the
Help Compiler, the keyword footnote used is case sensitive.
Therefore, care should be taken to use the same case, usually
uppercase, for your keyword footnote. Be sure to associate only one
topic with a keyword. Help does not display the normal search dialog
box for a multiple keyword search. Instead it displays the first topic
found with the specified keyword. If you want the topics in your
additional keyword table to appear in the normal Help keyword table,
you must also specify a K footnote and the given keyword.
The application for which you are developing Help can then display
the Help topic associated with a given string in a specified keyword
table. Keywords are sorted without regard to case for the keyword
table.
Assigning browse sequence numbers
In this version of Help, topics defined in browse sequences are
accessed using the Browse buttons at the top of the Help window.
Future versions of Help will not normally display browse buttons for
the user. However, if your Help resource file includes browse
sequences authored in the format described here, these versions will
support the feature by automatically displaying browse buttons for
the user.
A browse sequence is determined by sequence numbers, established
by the Help writer.
To build browse sequences into the Help topics, the writer must:
- Decide which topics should be grouped together and
what order they should follow when viewed as a group.
Help supports multiple, discontiguous sequence lists.
- Code topics to implement the sequence.
Organizing browse sequences
When organizing browse sequences, the writer must arrange the
topics in an order that makes sense to the user. Topics can be
arranged in alphabetical order within a subject, in order of difficulty,
or in a sensible order that seems natural to the application. The
following example illustrates browse sequences for the menu
commands used in a given application. The Help writer subjectively
defines the order that makes the most sense from a procedural point
of view. You may, of course, choose a different order.
SampleApp Commands
File Menu - commands: 005
New Command - file_menu: 005
Open Command - file_menu: 010
Save Command - file_menu: 015
Save As Command - file_menu: 020
Print Command - file_menu: 025
Printer Setup Command - file_menu: 030
Exit Command - file_menu: 035
Edit Menu - commands: 010
Undo Command - edit_menu: 025
Cut Command - edit_menu: 015
Copy Command - edit_menu: 010
Paste Command - edit_menu: 020
Clear Command - edit_menu: 005
Select All Command - edit_menu: 030
Word Wrap Command - edit_menu: 035
Type Face Command - edit_menu: 040
Point Size Command - edit_menu: 045
Search Menu - commands: 015
Find Command - search_menu: 005
Find Next Command - search_menu: 010
Previous Command - search_menu: 015
Window Menu - commands: 020
Tile Command - window_menu: 005
Cascade Command - window_menu: 010
Arrange Icons Command - window_menu: 015
Close All Command - window_menu: 020
Document Name Command - window_menu: 025
Each line consists of a sequence list name followed by a colon and a
sequence number. The sequence list name is optional. If the
sequence does not have a list name, as in the following example, the
compiler places the topic in a null list:
Window Menu -120
Note that the numbers used in the browse sequence example begin
at 005 and advance in increments of 005. Generally, it is good practice
to skip one or more numbers in a sequence so you can add new
topics later if necessary. Skipped numbers are of no consequence to
the Help Compiler; only their order is significant.
Sequence numbers establish the order of topics within a browse
sequence list. Sequence numbers can consist of any alphanumeric
characters. During the compiling process, strings are sorted using the
ASCII sorting technique, not a numeric sort.
Both the alphabetic and numeric portions of a sequence can be
several characters long; however, their lengths should be consistent
throughout all topic files. If you use only numbers in the strings, make
sure the strings are all the same length; otherwise, a higher sequence
number could appear before a lower one in certain cases. For
example, the number 100 is numerically higher than 99, but 100
appears before 99 in the sort used by Help, because Help is
comparing the first two digits in the strings. To keep the topics in their
correct numeric order, you would have to make 99 a three-digit
string: 099.
Coding browse sequences
After determining how to group and order topics, code the sequence
by assigning the appropriate sequence list name and number to each
topic, as follows:
1. Place the cursor to the left of the topic heading.
2. Insert the plus sign (+) as the footnote reference mark.
Note that a superscript plus sign ( + ) appears next to the
heading.
3. Type the sequence number using alphanumeric
characters.
For example, the following footnote defines the browse sequence
number for the Edit menu topic in the previous browse sequence
example:
+ commands: 010
While it may be easier to list topics within the file in the same order
that they appear in a browse sequence, it is not necessary. The
compiler orders the sequence for you.
Creating cross-references between topics
Cross-references, or jumps, are specially coded words or phrases that
are linked to other topics. Although you indicate jump terms with
strikethrough or double-underlined text in the topic file, they appear
underlined in the Help window. In addition, jump terms appear in
color on color systems. For example, the strikethrough text (double-underlined
in Word for Windows) New Command appears as New
Command in green text to the user.
To code a word or phrase as a jump in the topic file:
1. Place the cursor at the point in the text where you want
to enter the jump term.
2. Select the strikethrough (or double-underline) feature of
your editor.
3. Type the jump word or words in strikethrough mode.
4. Turn off strikethrough and select the editor's hidden-text
feature.
5. Type the context string assigned to the topic that is the
target of the jump.
When coding jumps, keep in mind that:
- No spaces can occur between the strikethrough (or
double-underlined) text and the hidden text.
- Coded spaces before or after the jump term are not
permitted.
- Paragraph marks must be entered as plain text.
Defining terms
Most topic files contain words or phrases that require further
definition. To get the definition of a word or phrase, the user first
selects the word and then holds down the mouse button or Enter key,
causing the definition to appear in a box within the Help window.
The Help writer decides which words to define, considering the
audience that will be using the application and which terms might
already be familiar.
Note
The look-up feature need not be limited to
definitions. With the capability to temporarily
display information in a box, you might want to
show a hint about a procedure or other suitable
information for the user.
Defining a term requires that you:
- Create a topic that defines the term. The definition topic
must include a context string.
- Provide a cross-reference for the definition topic
whenever the term occurs.
You don't need to define the same word multiple times in the same
topic, just at its first occurrence. Also, consider the amount of
colored text you are creating in the Help window. See "Coding
definitions," below.
Creating definition topics
You can organize definition topics any way you want. For example,
include each definition topic in the topic file that mentions the term.
Or organize all definitions in one topic file and provide the user with
direct access to it. Organizing definition topics into one file provides
you with a glossary and lets you make changes easily.
Coding definitions
After creating definition topics, code the terms as they occur, as
follows:
1. Designate the insertion point where you want to place the
term that requires definition.
2. Select the underline feature of your editor.
3. Type the term.
4. Turn off the underline feature, and select the editor's
hidden-text feature.
5. Type the context string assigned to the topic that contains
the definition of the term.
Inserting Graphic Images
Bitmapped graphic images can be placed in Help topics using either
of two methods. If your word processor supports the placement of
Windows format graphics directly into a document, you can simply
paste your bitmaps into each topic file. Alternatively, you can save
each bitmap in a separate file and specify the file by name where
you want it to appear in the Help topic file. The latter method of
placing graphics is referred to as bitmaps by reference. The
following sections describe the process of placing bitmaps directly or
by reference into your Help topics.
Creating and capturing bitmaps
You can create your bitmaps using any graphical tools, as long as the
resulting images can be displayed in the Windows environment. Each
graphic image can then be copied to the Windows clipboard. Once
on the clipboard, a graphic can be pasted into a graphics editor such
as Paint, and modified or cleaned up as needed.
Windows Help 3.0 or higher supports color bitmaps. However, for
future compatibility, you might want to limit graphics to monochrome
format. If you are producing monochrome images, you might have to
adjust manually to either black, white, or a pattern of black and white
pixels the elements of your source graphic that were originally
different colors.
When you are satisfied with the appearance of your bitmap, you can
either save it as a file, to be used as a bitmap by reference, or you can
copy it onto the clipboard and paste it into your word processor. If
you save the graphic as a file, be sure first to specify its size in your
graphics editor, so that only the area of interest is saved for display in
the Help window. The tighter you crop your images, the more closely
you can position text next to the image. Always save (or convert and
save if necessary) graphics in Windows .BMP format.
Bitmap images should be created in the same screen mode that you
intend Help to use when topics are displayed. If your Help files are
displayed in a different mode, bitmaps might not retain the same
aspect ratio or information as their source images.
Placing bitmaps using a graphical word processor
The easiest way to precisely place bitmaps into Help topics is to use
a graphical word processor. Word for Windows supports the direct
importation of bitmaps from the clipboard. Simply paste the graphic
image where you want it to appear in the Help topic. You can format
your text so that it is positioned below or alongside the bitmap. When
you save your Help topic file in RTF, the pasted-in bitmap is
converted as well and is automatically included in the Help resource
file.
Placing bitmaps by reference
If your word processor cannot import and display bitmaps directly,
you can specify the location of a bitmap that you have saved as a file.
To insert a bitmap reference in the Help topic file, insert one of the
following statements where you want the bitmap to appear in the
topic:
{bmc filename.bmp}
{bml filename.bmp}
{bmr filename.bmp}
Note
Do not specify a full path for filename. If you need
to direct the compiler to a bitmap in a location other
than the root directory for the build, specify the
absolute path for the bitmap in the [Bitmaps]
section of the project file.
The argument bmc stands for bitmap character, indicating that the
bitmap referred to is treated the same as a character placed in the
topic file at the same location on a line. Text can precede or follow
the bitmap on the same line, and line spacing is determined based
upon the size of the characters (including the bitmap character) on
the line. Do not specify negative line spacing for a paragraph with a
bitmap image, or the image may inadvertently overwrite text above it
when it is displayed in Help. When you use the argument bmc, there
is no automatic text wrapping around the graphic image. Text follows
the bitmap, positioned at the baseline.
The argument bml specifies that the bitmap appear at the left margin,
with text wrapping automatically along the right edge of the image.
The argument bmr specifies that the bitmap appear at the right
margin, with text to its left. Bitmap filenames must be the same as
those listed in the [Bitmaps] section of the Help project file.
Note
Multiple references to a bitmap of the same name
refer to the same bitmap when the Help file is
displayed. This means that bitmap references can be
repeated in your Help system without markedly
increasing the size of the Help resource file.
Managing Topic Files
Help topic files can be saved in the default word-processor format or
in RTF. If you always save your files in RTF and later need to make a
change, the word processor, as it reloads the file, may take additional
time to interpret the format. If you anticipate making numerous
changes during Help development, you might want to minimize this
delay by saving topic files in both default and RTF formats, with
different file extensions to distinguish them. The compiler needs only
the RTF files, and you have faster access to the source files for
changes. On a large project, this practice can save a considerable
amount of development time.
It's important to keep track of all topic files for the following reasons:
- To ensure that no topics are left out of the build process
- To ensure that each topic has been assigned a unique
context string
- To double-check browse sequencing within general and
specific lists
- To show keyword and title matches
- To allow writers to see where the text for each of the
topics is located
- To keep track of changes to files and the current status
- To track any other aspect of the Help development
process that you think essential
At a minimum, writers must keep track of their own topic files and
must pass the filenames to the person who is responsible for creating
the Help project file.
Building the Help File
After the topic files for your Help system have been written, you are
ready to create a Help project file and run a build to test the Help
file. The Help project file contains all information the compiler needs
to convert help topic files into a binary Help resource file.
You use the Help project file to tell the Help Compiler which topic
files to include in the build process. Information in the Help project
file also enables the compiler to map specific topics to context
numbers (for the context-sensitive portion of Help).
After you compile your Help file, the development team programs the
application so the user can access it.
The remainder of this chapter describes the following:
- Creating a Help project file
- Compiling the Help file
- Programming the application to access Help
- Help compiler error messages
Creating the Help Project File
Use the Help project file to control how the Help Compiler builds
your topic files. The Help project file can contain up to six sections
that perform the following functions:
Table 26-3 Sections of a Help project file
Section Function
[Files]
Specifies topic files to be included in the build.
This section is mandatory.
[Options]
Specifies the level of error reporting, topics to be
included in the build, the directory in which to
find the files, and the location of your Help index.
This section is optional.
[BuildTags]
Specifies valid build tags. This section is optional.
[Alias]
Assigns one or more context strings to the same
topic. This section is optional.
[Map]
Associates context strings with context numbers.
This section is optional.
[Bitmaps]
Specifies bitmap files to be included in the build.
This section is optional.
You can use any ASCII text editor to create your Help project file. The
extension of a Help project file is .hpj. If you do not use the
extension .hpj on the HC command line, the compiler looks for a
project file with this extension before loading the file. The .hlp
output file has the same name as the .hpj file.
The order of the various sections within the Help project file is
arbitrary, with one exception: under all circumstances, if an [Alias]
section is used, it must precede the [Map] section.
Section names are placed within brackets using the following syntax:
[section-name]
You can use a semicolon to indicate a comment in the project file.
The compiler ignores all text from the semicolon to the end of the line
on which it occurs.
Specifying topic files: the Files section
Use the [Files] section of the Help project file to list all topic files
that the Help Compiler should process to produce a Help resource
file. A Help project file must have a [Files] section.
The following sample shows the format of the [Files] section:
[FILES]
HELPEX.RTF; Main topics for HelpEx application
TERMS.RTF; Lookup terms for HelpEx appliction
Using the path defined in the ROOT option, the Help Compiler finds
and processes all files listed in this section of the Help project file. If
the file is not on the defined path and cannot be found, the compiler
generates an error. For more information about the ROOT option, see
the section "Specifying the root directory: the Root option" later in this
chapter.
You can include files in the build process using the C #include
directive command.
The #include directive uses the following syntax:
#include <filename>
You must include the angle brackets around the filename. The pound
sign (#) must be the first character in the line. The filename must
specify a complete path, either the path defined by the ROOT option
or an absolute directory path to the file.
You may find it easier to create a text file that lists all files in the Help
project and include that file in the build, as in this example:
[FILES] #include <hlpfiles.inc>
Specifying build tags: the BuildTags section
If you code build tags in your topic files, use the [BuildTags]
section of the Help project file to define all the valid build tags for a
particular Help project. The [BuildTags] section is optional.
The following example shows the format of the [BuildTags]
section in a sample Help project file:
[BUILDTAGS]
WINENV; topics to include in Windows build
DEBUGBUILD; topics to include in debugging build
TESTBUILD; topics to include in testing build
The [BuildTags] section can include up to 30 build tags. The build
tags are not case sensitive and may not contain space characters. Only
one build tag is allowed per line in this section. The compiler
generates an error message if anything other than a comment is listed
after a build tag in the [BuildTags] section.
Specifying options: the Options section
Use the [Options] section of the Help project file to specify the
following options:
Table 26-4 Help project file options
Option Meaning
BUILD
Determines what topics the compiler includes
in the build
COMPRESS
Specifies the compression of the Help resource
file
FORCEFONT
Specifies the creation of a Help resource file
using only one font
INDEX
Specifies the context string of the Help index
MAPFONTSIZE
Determines the mapping of specified font sizes
to different sizes
MULTIKEY
Specifies alternate keyword mapping for topics
ROOT
Designates the directory to be used for the
Help build
TITLE
Specifies the title shown for the Help system
WARNING
Indicates the kind of error message the
compiler reports
These options can appear in any order within the [Options]
section. The [Options] section is not required.
Detailed explanations of the available options follow.
Specifying error reporting: the Warning option
Use the WARNING option to specify the amount of debugging
information that the compiler reports. The WARNING option has the
following syntax:
WARNING = level
You can set the WARNING option to any of the following levels:
Table 26-5 Warning option levels
Level Information reported
1 Only the most severe warnings.
2 An intermediate level of warnings.
3 All warnings. This is the default level.
The following example specifies an intermediate level of error
reporting:
[OPTIONS] WARNING= 2
The compiler reports errors to the standard output file, typically the
screen. You may want to redirect the errors to a disk file so that you
can browse it when you are debugging the Help system. The
following example shows the redirection of compiler screen output
to a file.
HC HELPEX >errors.out
Warning
Use the DOS CONTROL+PRINT SCREEN accelerator
key before you begin your compilation to echo
errors that appear on the screen to your printer.
Press CONTROL+PRINT SCREEN again to stop
sending information to the printer.
Specifying build topics: the Build option
If you have included build tags in your topic files, use the BUILD
option to specify which topics to conditionally include in the build. If
your topic files have no build tags, omit the BUILD option from the
[Options] section.
Note
All build tags must be listed in the [BuildTags]
section of the project file, regardless of whether a
given conditional compilation declares the tags.
See the section "Creating Help Topic Files" later in this chapter for
information on assigning build tags to topics in the Help topic files.
The BUILD option line uses the following syntax:
BUILD = expression
BUILD expressions cannot exceed 255 characters in length and must
be entered on only one line. BUILD expressions use Boolean logic to
specify which topics within the specified Help topic files the compiler
includes in the build. The tokens of the language are:
Token Description
<tag> Build tag
() Parentheses
& AND operator
| OR operator
~ NOT operator
The compiler evaluates all build expressions from left to right. The
operators have the following precedence:
1. ()
2. ~
3. &
4. |
For example, if you code build tags called WINENV, APP1, and
TEST_BUILD in your topic files, you can include one of the following
build expressions in the [Options] section:
Table 26-6 Examples of build expressions
Build expression
Topics built
BUILD = WINENV
Only topics that have the
WINENV tag
BUILD = WINENV & APP1
Topics that have both the
WINENV and APP1 tags
BUILD = WINENV | APP1
Topics that have either the
WINENV tag or the APP1 tag
BUILD = ~APP1
Topics that do not have a APP1
tag
Specifying the root directory: the Root option
Use the ROOT option to designate the root directory of the Help
project. The compiler searches for files in the specified root directory.
The ROOT option uses the following syntax:
ROOT = pathname
For example, the following root option specifies that the root
directory is \BUILD\TEST on drive D:
[OPTIONS] ROOT= D:\BUILD\TEST
The ROOT option allows you to refer to all relative paths off the root
directory of the Help project. For example, the following entry in the
[Files] section refers to a relative path off the root directory:
TOPICS\FILE.RTF
To refer to a file in a fixed location, independent of the project root,
you must specify a fully qualified or absolute path, including a drive
letter, if necessary, as in the following line:
D:\HELPTEST\TESTFILE.RTF
If you do not include the ROOT option in your Help project file, all
paths are relative to the current DOS directory.
Specifying the index: the Index option
Use the INDEX option to identify the context string of the Help index.
Because the Index button gives the user access to the index from
anywhere in the Help system, you probably do not want to author
terms to jump to the index. Users access this general index either from
the Help menu of the application or by choosing the Index button
from the Help window.
Assigning a context string to the index topic in the [Options]
section lets the compiler know the location of the main index of Help
topics for the applications Help file. If you do not include the INDEX
option in the [Options] section, the compiler assumes that the first
topic it encounters is the index.
The INDEX option uses the following syntax:
INDEX = context-string
The context string specified must match the context string you assign
to the Help index topic. In the following example, the writer informs
the compiler that the context string of the Help index is
main_ index:
[OPTIONS] INDEX = main_ index
For information about assigning context strings, see the section
"Assigning context strings" earlier in this chapter.
Assigning a title to the Help system: the Title option
You can assign a title to your Help system with the TITLE option.
The title appears in the title bar of the Help window with the word
"Help" automatically appended, followed by the DOS filename of the
Help resource file.
The TITLE option uses the following syntax:
TITLE = Help-system-title-name
Titles are limited to 32 characters in length. If you do not specify a
title using the TITLE option, only the word "Help" followed by the
Help system filename is displayed in the title bar. Because the
compiler always inserts the word "Help," you should keep in mind
not to duplicate it in your title.
Converting fonts: the FORCEFONT option
You can use the FORCEFONT option to create a Help resource file that
is made up of only one typeface or font. This is useful if you must
compile a Help system using topic files that include fonts not
supported by your users' systems.
The FORCEFONT option uses the following syntax:
FORCEFONT = fontname
The fontname parameter is any Windows system font. Windows ships
with the following fonts and sizes:
- Courier 10, 12, 15
- Helvetica 8, 10, 12, 14, 18, 24
- Modern
- Roman
- Script
- Symbol 8, 10, 12, 14, 18, 24
- Times Roman 8, 10, 12, 14, 18, 24
Font names must be spelled the same as they are in the Fonts dialog
box in the Control Panel. Font names do not exceed 20 characters in
length. If you designate a font that is not recognized by the compiler,
an error message is generated and the compilation continues using
the default Helvetica font.
Note
The fontname used in the FORCEFONT option
cannot contain spaces. Therefore, Times Roman
font cannot be used with FORCEFONT.
Changing font sizes: the MAPFONTSIZE option
The font sizes specified in your topic files can be mapped to different
sizes using the MAPFONTSIZE option. In this manner, you can create
and edit text in a size chosen for easier viewing in the topic files and
have it sized by the compiler for the actual Help display. This may be
useful if there is a large size difference between your authoring
monitor and your intended display monitor.
The MAPFONTSIZE option uses the following syntax:
MAPFONTSIZE = m[-n]:p
The m parameter is the size of the source font, and the p parameter
is the size of the desired font for the Help resource file. All fonts in
the topic files that are size m are changed to size p. The optional
parameter n allows you to specify a font range to be mapped. All
fonts in the topic files falling between m and n, inclusive, are
changed to size p. The following examples illustrate the use of the
MAPFONTSIZE option:
MAPFONTSIZE=12-24:16 ;make fonts from 12 to 24 as size 16
MAPFONTSIZE=8:12 ;make all size 8 fonts as size 12.
Note that you can map only one font size or range with each
MAPFONTSIZE statement used in the Options section. If you use
more than one MAPFONTSIZE statement, the source font size or
range specified in subsequent statements cannot overlap previous
mappings. For instance, the following mappings generate an error
when the compiler encounters the second statement:
MAPFONTSIZE=12-24:16 MAPFONTSIZE=14:20
Because the second mapping shown in the first example contains a
size already mapped in the preceding statement, the compiler ignores
the line. A maximum of five font ranges can be specified in the project
file.
Multiple keyword tables: the MULTIKEY option
The MULTIKEY option specifies a character to be used for an
additional keyword table.
The MULTIKEY option uses the following syntax:
MULTIKEY = footnote-character
The footnote-character parameter is the case-sensitive letter to be
used for the keyword footnote. The following example illustrates the
enabling of the letter L for a keyword-table footnote:
MULTIKEY=L
Note
You must be sure to limit your keyword-table
footnotes to one case, usually uppercase. In the
previous example, topics with the footnote L would
have their keywords incorporated into the
additional keyword table, whereas those assigned
the letter l would not.
You may use any alphanumeric character for a keyword table except
K and k which are reserved for Help's normal keyword table. There
is an absolute limit of five keyword tables, including the normal table.
However, depending upon system configuration and the structure of
your Help system, a practical limit of only two or three may actually
be the case. If the compiler cannot create an additional table, the
excess table is ignored in the build.
Compressing the file: the Compress option
You can use the COMPRESS option to reduce the size of the Help
resource file created by the compiler. The amount of file compression
realized varies according to the number, size, and complexity of
topics that are compiled. In general, the larger the Help files, the more
they can be compressed.
The COMPRESS option uses the following syntax:
COMPRESS = TRUE | FALSE
Because the Help application can load compressed files quickly, there
is a clear advantage in creating and shipping compressed Help files
with your application. Compiling with compression turned on,
however, may increase the compile time, because of the additional
time required to assemble and sort a key-phrase table. Thus, you may
want to compile without compression in the early stages of a project.
The COMPRESS option causes the compiler to compress the system
by combining repeated phrases within the source file( s). The
compiler creates a phrase-table file with the .ph extension if it does
not find one in existence. If the compiler finds a file with the .ph
extension, it uses the file for the current compilation. This speeds
compression when not a lot of text has changed since the last
compilation.
Deleting the key-phrase file before each compilation prevents the
compiler from using the previous file. Maximum compression results
only by forcing the compiler to create a new phrase table.
Specifying alternate context strings: the Alias section
Use the [Alias] section to assign one or more context strings to the
same topic alias. Because context strings must be unique for each
topic and cannot be used for any other topic in the Help project, the
[Alias] section provides a way to delete or combine Help topics
without recoding your files. The [Alias] section is optional.
For example, if you create a topic that replaces the information in
three other topics and you delete the three, you have to search
through your files for invalid cross-references to the deleted topics.
You can avoid this problem by using the [Alias] section to assign
the name of the new topic to the deleted topics. The [Alias]
section can also be used when your application program has multiple
context identifiers for which you have only one topic. This can be the
case with context-sensitive Help.
Each expression in the [Alias] section has the following format:
context_string=alias
In the alias expression, the alias parameter is the alternate string,
or alias name, and the context_ string parameter is the context
string identifying a particular topic. An alias string has the same format
and follows the same conventions as the topic context string. That is,
it is not case sensitive and may contain the alphabetic characters A-Z,
numeric characters 0-9, and the period and underscore characters.
The following example illustrates an [Alias] section:
[ALIAS]
sm_key=key_shrtcuts
cc_key=key_shrtcuts
st_key=key_shrtcuts
;combine as keyboard shortcuts topic
clskey=us_dlog_bxs
maakey=us_dlog_bxs
;covered in using dialog boxes topic
chk_key=dlogprts
drp_key=dlogprts
lst_key=dlogprts
opt_key=dlogprts
tbx_key=dlogprts
;combine as parts of dialog box topic
frmtxt=edittxt
wrptxt=edittxt
seltxt=edittxt
;covered in editing text topic
You can use alias names in the [Map] section of the Help project file.
If you do, however, the [Alias] section must precede the [Map]
section.
Mapping context-sensitive topics: the Map section
If your Help system supports context-sensitive Help, use the [Map]
section to associate either context strings or aliases to context
numbers. The context number corresponds to a value the parent
application passes to the Help application to display a particular
topic. This section is optional.
When writing the [Map] section, you can do the following:
- Use either decimal or hexadecimal numbers formatted in
standard C notation to specify context numbers.
- Assign no more than one context number to a context
string or alias.
Note: Assigning the same number to more than one
context string generates a compiler error.
- Separate context numbers and context strings by an
arbitrary amount of white space using either space
characters or tabs.
You can use the C #include directive to include other files in the
mapping. In addition, the Map section supports an extended format
that lets you directly include C files with the .h extension. Entries
using this format must begin with the #define directive and may
contain comments in C format, as in this example:
#define context_string context_number /* comment*/
The following example illustrates several formats you can use in the
[Map] section:
[MAP]
(1)
Edit_Window0x0001
Control_Menu0x0002
Maximize_Icon0x0003
Minimize_Icon0x0004
Split_Bar 0x0005
Scroll_Bar 0x0006
Title_Bar 0x0007
Window_Border0x0008
(2)
dcmb_scr30 ; Document Control-menu Icon
dmxi_scr31 ; Document Maximize Icon
dmni_scr32 ; Document Minimize Icon
dri_scr33 ; Document Restore Icon
dtb_scr34 ; Document Title Bar
(3)
#define vscroll0x010A/* Vertical Scroll Bar*/
#define hscroll0x010E/* Horiz. Scroll Bar */
#define scrollthm0x0111/* Scroll Thumb */
#define upscroll0x0112/* Up Scroll Arrow */
#define dnscroll0x0113/* Down Scroll Arrow*/
(4)
#include <sample. h>
In the example:
(1) The first eight entries give hexadecimal equivalents for
the context numbers.
(2) The next five entries show decimal context numbers.
(3) The next five entries show how you might include
items defined in a C #include file.
(4) This entry shows a C #include directive for some
generic topics.
If context numbers use the #define directive, and the file containing
the #define statements is included in both the application code and
the Help file, then updates made to the context numbers by the
application programmers are automatically reflected in the next Help
build.
You can define the context strings listed in the [Map] section either
in a Help topic or in the [Alias] section. The compiler generates a
warning message if a context string appearing in the [Map] section
is not defined in any of the topic files or in the [Alias] section.
Note
If you use an alias name, the [Alias] section must
precede the [Map] section in the Help project file.
Including bitmaps by reference: the Bitmaps section
If your Help system uses bitmaps by reference, the filenames of each
of the bitmaps must be listed in the [Bitmaps] section of the project
file. The following example illustrates the format of the [Bitmaps]
section.
[BITMAPS]
DUMP01.BMP
DUMP02.BMP
DUMP03.BMP
c:\PROJECT\HELP\BITMAPS\DUMP04.BMP
Note
The [Bitmaps] section uses the same rules as the
[Files] section for locating bitmap files.
Compiling Help Files
After you create a Help project file, you are ready to build a Help file
using the Help Compiler. The compiler generates the binary Help
resource file from the topic files listed in the Help project file. When
the build process is complete, your application can access the Help
resource file that results.
Before initiating a build operation to create the Help file, consider the
locations of the following files:
- The Help Compiler, hc. exe. The compiler must be in a
directory from which it can be executed. This could be
the current working directory on the path set with the
PATH environment variable or a directory specified by a
full pathname, as follows:
\BIN\HC HELPEX. HPJ
- The Help project file, filename. hpj. The project file can
be located either in the current directory or specified by a
path, as follows:
\BIN\HC D:\MYPROJ\HELPEX. HPJ
- The topic files named in the Help project file, saved as
.rtf. The topic files may be located in the current
working directory, a subdirectory of the current working
directory specified in the [Files] section, or the
location specified in the Root option.
- Files included with the #include directive in the Help
project file. Since the #include directive can take
pathnames, then any number of places work for these
files.
- All bitmap files listed by reference in the topic files.
You must also place any files named in an #include directive in
the path of the project root directory or specify their path using the
ROOT option. The compiler searches only the directories specified in
the Help project file. For information about the ROOT option, see the
section "Specifying the root directory: the Root option" earlier in this
chapter.
Note
If you use a RAM drive for temporary files (set with
the DOS environment variable TMP), it must be
large enough to hold the compiled Help resource
file. If your Help file is larger than the capacity of
the available RAM drive, the compiler generates an
error message and the compilation is aborted.
Using the Help compiler
To run the Help Compiler, use the HC command. There are no
options for HC. All options are specified in the Help project file.
The HC command uses the following syntax:
HC filename.HPJ
As the compiler program runs, it displays sequential periods on the
screen, indicating its progress in the process. Error messages are
displayed when each error condition is encountered. When the Help
Compiler is finished compiling, it writes a Help resource file with an
.hlp extension in the current directory and returns to the DOS
prompt. The Help resource file that results from the build has the
same name as does the Help project file.
Compiler errors and status messages can be redirected to a file using
standard DOS redirection syntax. This is useful for a lengthy build
where you may not be monitoring the entire process. The redirected
file is saved as a text file that can be viewed with any ASCII editor.
Programming the Application to Access Help
The application-development team must program the application so
that the user can access the Windows Help application and your
Help file. The Help application is a stand-alone Windows
application, and your application can ask Windows to run the Help
application and specify the topic that Help is to show the user. To
the user, Help appears to be part of your application, but it acts like
any other Windows application.
Calling WinHelp from an application
An application makes a Help system available to the user by calling
the WinHelp function.
The WinHelp function uses the following syntax:
BOOL WinHelp (hWnd, lpHelpFile, wCommand, dwData)
The hWnd parameter identifies the window requesting Help. The
Windows Help application uses this identifier to keep track of which
applications have requested Help.
The lpHelpFile parameter specifies the name (with optional
directory path) of the Help file containing the desired topic.
The wCommand parameter specifies either the type of search that the
Windows Help application is to use to locate the specified topic or
that the application no longer requires Help. It may be set to any one
of the following values:
Table 26-7 wCommand parameter values
Value Meaning
HELP_CONTEXT
Displays Help for a particular topic
identified by a context number.
HELP_HELPONHELP
Displays the Using Help index topic.
HELP_INDEX
Displays the main Help index topic.
HELP_KEY
Displays Help for a topic identified by a
keyword.
HELP_MULTIKEY
Displays Help for a topic identified by a
keyword in an alternate keyword table.
HELP_QUIT
Informs the Help application that Help is
no longer needed. If no other
applications ask for Help, Windows
closes the Help application.
HELP_SETINDEX
Displays a designated Help index topic.
The dwData parameter specifies the topic for which the application
is requesting Help. The format of dwData depends upon the value of
wCommand passed when your application calls WinHelp. The
following list describes the format of dwData for each value of
wCommand.
Table 26-8 wCommand values and corresponding dwData formats
wCommand value
dwData format
HELP_CONTEXT
An unsigned long integer containing the
context number for the topic. Instead of
using HELP_INDEX, HELP_CONTEXT can
use the value -1.
HELP_HELPONHELP
Ignored.
HELP_INDEX
Ignored.
HELP_KEY
A long pointer to a string that contains a
keyword for the desired topic.
HELP_MULTIKEY
A long pointer to the MULTIKEYHELP
structure, as defined in WINDOWS. H. This
structure specifies the table footnote
character and the keyword.
HELP_QUIT
Ignored.
HELP_SETINDEX
An unsigned long integer containing the
context number for the topic.
Because it can specify either a context number or a keyword,
WinHelp supports both context-sensitive and topical searches of the
Help file.
Note
To ensure that the correct index remains set, the
application should call WinHelp with wCommand
set to HELP_SETINDEX (with dwData specifying
the corresponding context identifier) following each
call to WinHelp with a command set to
HELP_CONTEXT. HELP_INDEX should never be
used with HELP_SETINDEX.
Getting context-sensitive
Help Context-sensitive Help should be available when a user wants to learn
about the purpose of a particular window or control. For example, the
user might pull down the File menu, select the Open command (by
using the direction keys), and then press F1 to get Help for the
command.
Implementing certain types of context-sensitive Help requires
advanced programming techniques. These techniques are described
in the following sections.
Shift+F1 support
To implement a Shift+ F1 mode, such as in Microsoft Excel or
Microsoft Word for Windows, Helpex responds to the Shift+ F1
accelerator key by calling SetCursor to change the shape of the
cursor to an arrow pointer supplemented by a question mark.
case WM_KEYDOWN:
if (wParam == VK_F1)
{ /* turn help mode on & set help cursor */
if (GetKeyState( VK_SHIFT))
{
bHelp = TRUE;
SetCursor(hHelpCursor);
return (DefWindowProc(hWnd, message, wParam, lParam));
}
else
{
WinHelp(hWnd, szHelpFileName, HELP_INDEX, 0L);
}
}
else
if (wParam == VK_ESCAPE && bHelp)
{
/* turn help mode off */
bHelp = FALSE;
SetCursor((HCURSOR) GetClassWord(hWnd, GCW_HCURSOR));
}
break;
As long as the user is in Help mode (that is, until he clicks the mouse
or hits Escape), Helpex responds to WM_SETCURSOR messages by
resetting the cursor to the arrow and question mark combination.
case WM_SETCURSOR:
/* In help mode it is necessary to reset */
/* the cursor in response to every */
/* WM_SETCURSOR message. Otherwise, by */
/* default, Windows will reset the cursor */
/* to that of the window class. */
if (bHelp)
{
SetCursor(hHelpCursor);
break;
}
return (DefWindowProc(hWnd, message, wParam, lParam));
case WM_INITMENU:
if (bHelp)
{
SetCursor(hHelpCursor);
}
return (TRUE);
When the user is in Shift+F1 Help mode and clicks the mouse button,
Helpex receives a WM_NCLBUTTONDOWN message if the click is in a
nonclient area of the application window. By examining the wParam
value of this message, the program can determine which context ID
to pass to WinHelp.
case WM_NCLBUTTONDOWN:
/* If in help mode (Shift+ F1) then display */
/* context-sensitive help for nonclient area.*/
if (bHelp)
{
dwHelpContextId =
(wParam == HTCAPTION)?(DWORD) HELPID_TITLE_BAR:
(wParam == HTSIZE)?(DWORD) HELPID_SIZE_BOX:
(wParam == HTREDUCE)?(DWORD) HELPID_MINIMIZE_ICON:
(wParam == HTZOOM)?(DWORD) HELPID_MAXIMIZE_ICON:
(wParam == HTSYSMENU)?(DWORD) HELPID_SYSTEM_MENU:
(wParam == HTBOTTOM)?(DWORD) HELPID_SIZING_BORDER:
(wParam == HTBOTTOMLEFT)?(DWORD) HELPID_SIZING_BORDER:
(wParam == HTTOP)?(DWORD) HELPID_SIZING_BORDER:
(wParam == HTLEFT)?(DWORD) HELPID_SIZING_BORDER:
(wParam == HTRIGHT)?(DWORD) HELPID_SIZING_BORDER:
(wParam == HTTOPLEFT)?(DWORD) HELPID_SIZING_BORDER:
(wParam == HTTOPRIGHT)?(DWORD) HELPID_SIZING_BORDER:
(DWORD) 0L;
if (!((BOOL) dwHelpContextId))
return (DefWindowProc(hWnd, message, wParam, lParam));
bHelp = FALSE;
WinHelp(hWnd, szHelpFileName, HELP_CONTEXT, dwHelpContextId);
break;
}
return (DefWindowProc(hWnd, message, wParam, lParam));
F1 support
Context-sensitive F1 support for menus is relatively easy to implement
in your application. If a menu is open and the user presses F1 while
one of the menu items is highlighted, Windows, after determining that
F1 is not a valid keystroke for choosing a menu, item sends, a
WM_ENTERIDLE message to the application to indicate that the
system is going back into an idle state. You can take advantage of this
idle state by looking at the keyboard state at the time of the
WM_ENTERIDLE message.
If the F1 key is down, then you can simulate the users pressing the
Enter key by posting a WM_KEYDOWN message using VK_RETURN.
You don't really want your application to execute the Menu
command. Set a flag (bHelp= TRUE) so that when you get the
WM_COMMAND message for the menu item, you don't execute the
command. Instead, the topic for the menu item is displayed by
Windows Help.
The following code samples illustrate F1 sensing for menu items.
case WM_ENTERIDLE:
if ((wParam == MSGF_MENU) && (GetKeyState(VK_F1) & 0x8000))
{
bHelp = TRUE;
PostMessage(hWnd, WM_KEYDOWN, VK_RETURN, 0L);
}
break;
case WM_COMMAND:
if (bHelp)
{
dwHelpContextId =
(wParam == IDM_NEW)?(DWORD) HELPID_FILE_NEW:
(wParam == IDM_OPEN)?(DWORD) HELPID_FILE_OPEN:
(wParam == IDM_SAVE)?(DWORD) HELPID_FILE_SAVE:
(wParam == IDM_SAVEAS)?(DWORD) HELPID_FILE_SAVE_AS:
(wParam == IDM_PRINT)?(DWORD) HELPID_FILE_PRINT:
(wParam == IDM_EXIT)?(DWORD) HELPID_FILE_EXIT:
(wParam == IDM_UNDO)?(DWORD) HELPID_EDIT_UNDO:
(wParam == IDM_CUT)?(DWORD) HELPID_EDIT_CUT:
(wParam == IDM_CLEAR)?(DWORD) HELPID_EDIT_CLEAR:
(wParam == IDM_COPY)?(DWORD) HELPID_EDIT_COPY:
(wParam == IDM_PASTE)?(DWORD) HELPID_EDIT_PASTE:
(DWORD) 0L;
if (!dwHelpContextId)
{
Messagebox(hWnd," Help not available", "Help Example", MB_OK);
return (DefWindowProc(hWnd, message, wParam, lParam));
}
bHelp = FALSE;
WinHelp(hWnd, szHelpFileName, HELP_CONTEXT, dwHelpContextId);
break;
}
Detecting F1 in dialog boxes is somewhat more difficult than in
menus. You must install a message filter, using the WH_MSGFILTER
option of the SetWindowsHook function. Your message filter function
responds to WM_KEYDOWN and WM_KEYUP messages for VK_F1 when
they are sent to a dialog box, as indicated by the MSGF_DIALOGBOX
code. By examining the message structure passed to the filter, you can
determine the context of the F1 help, what the dialog box is, and the
specific option or item. You should not call WinHelp while
processing the filtered message, but rather post an application-defined
message to your application to call WinHelp at the first
available opportunity.
Getting Help on an item listed on the Help menu
Sometimes users may want information about a general concept in
the application rather than about a particular control or window. In
these cases, the application should provide Help for a particular topic
that is identified by a keyword rather than by a context identifier.
For example, if the Help file for your application contains a topic that
describes how the keyboard is used, you could place a Keyboard item
in your Help menu. Then when the user selects that item, your
application would call WinHelp and request that topic:
case IDM_HELP_KEYBOARD:
WinHelp(hWnd, lpHelpFile, HELP_KEY, (LPSTR)"Keyboard");
break;
Accessing additional keyword tables
Your application may have commands or terms that correspond to
terms in a similar but different application. Given a keyword, the
application can call WinHelp and look up topics defined in an
alternative keyword table. This Multikey functionality is accessed
through the WinHelp hook with the wCommand parameter set to
HELP_MULTIKEY.
Specify the footnote character for the alternative keyword table
and the keyword or phrase, via a MULTIKEYHELP structure, which is
passed as the dwData parameter in the call to WinHelp. This
structure is defined in windows.h as:
typedef struct tag MULTIKEYHELP
{
WORD mdSize;
BYTE mkKeyList;
BYTE szKeyPhrase[1];
} MULTIKEYHELP;
The following table lists the format of the fields of the
MULTIKEYHELP structure:
Table 26-9 MULTIKEYHELP field formats
Parameter
Format
mkSize
The size of the structure, including the keyword
(or phrase) and the associated key-table letter
mkKeyList
A single character that defines the footnote
character for the alternate keyword table to be
searched
szKeyPhrase
A null-terminated keyword or phrase to be looked
up in the alternate keyword table
The following example illustrates a keyword search for the word
frame in the alternate keyword table designated with the footnote
character L:
MULTIKEYHELP mk;
char szKeyword[]= frame;
mk.mkSize = sizeof(MULTIKEYHELP) + (WORD) lstrlen(szKeyword);
mk.mkKeylist= L;
mk.szKeyphrase= szKeyword;
WinHelp(hWnd, lpHelpfile, HELP_MULTIKEY, (LPSTR)& mk);
Canceling Help
The Windows Help application is a shared resource that is available
to all Windows applications. In addition, since it is a stand-alone
application, the user can execute it like any other application. As a
result, your application has limited control over the Help application.
While your application cannot directly close the Help application
window, your application can inform the Help application that Help
is no longer needed. Before closing its main window, your
application should call WinHelp with the wCommand parameter set to
HELP_QUIT, as shown in the following example, to inform the Help
application that your application will not need it again.
case WM_DESTROY:
WinHelp (hWnd, lpHelpFile, HELP_QUIT, NULL);
An application that calls WinHelp at some point during its execution
must call WinHelp with the wCommand parameter set to HELP_QUIT
before the application exits from WinMain (typically during the
WM_DESTROY message processing).
If an application opens more than one Help file, then it must call
WinHelp to quit help for each file.
If an application or DLL has opened a Help file but no longer wants
the associated instance of the Help engine (winhelp. exe) to remain
active, then the application or DLL should call WinHelp with the
wCommand parameter set to HELP_QUIT to destroy the instance of
the Help engine.
Under no circumstances should an application or DLL terminate
without calling WinHelp for any of the opened Help files. A Help file
is opened if any other WinHelp call has been previously made using
the Help filename.
The Windows Help application does not exit until all windows that
call WinHelp have called it with wCommand set to HELP_QUIT. If an
application fails to do so, then the Help application continues running
all applications that request Help terminate.
Help Compiler Error Messages
This chapter contains a list of Help Compiler error messages. Each
message is shown as it appears when the compiler encounters the
specific error. A short explanation accompanies each message to aid
you in solving the problem in your Help system. Preceding the error
message listing is a short description of the error reporting behavior
of the Help Compiler. Understanding how the compiler reports and
reacts to errors helps you debug your Help files.
The Help compiler and errors
The Help Compiler displays messages when it encounters errors in
building the Help resource file. Errors during processing of the
project file are numbered beginning with the letter P and appear as
in the following examples:
Error P1025: line... 7 of filename.HPJ : Section heading sectionname unrecognized.
Warning P1039: line... 38 of filename.HPJ : [BUILDTAGS] section missing.
Errors that occur during processing of the .rtf topic file(s) are
numbered beginning with the letter R and appear as in the following
examples:
Error R2025: File environment error.
Warning R2501: Using old key-phrase table.
Whenever possible, the compiler displays the topic number and/ or
filename that contains the error. Although topics are not numbered,
the topic number given with an error message refers to that topic's
sequential position in your rtf file (first, second, etc.). These
numbers may be identical to the page number shown by your word
processor, depending on the number of lines you assign to the
hypothetical printed page. Remember that topics are separated by
hard page breaks, even though there is no such thing as a page in
the Help system.
Messages beginning with the word Error are fatal errors. Errors are
always reported, and no usable Help resource file results from the
build. Messages beginning with the word Warning are less serious
in nature. A build with warnings produces a valid Help resource file
that loads under Windows, but the file may contain operational
errors. You can specify the amount of warning information to be
reported by the compiler. For more information on choosing
warning levels to be displayed, see the section "Specifying error
reporting: the Warning option" earlier in this chapter.
The compiler's reaction to an error is described for each error in the
listing that follows. During processing of the project file, the
compiler ignores lines that contain errors and attempts to continue
with the build. This means that errors encountered early in a build
may result in many more errors being reported as the build
continues. Similarly, errors during processing of the .rtf topic files
are reported and if not serious, the compiler continues with the
build. A single error condition in the topic file may result in more
than one error message being reported by the compiler. For
instance, a misidentified topic causes an error to be reported every
time jump terms refer to the correct topic identifier. Such a mistake is
easily rectified by correcting the footnote containing the wrong
context string.
Errors during processing of project file
P1001 Unable to read file filename.
The file specified in the project file is unreadable. This is
a DOS file error.
P1003 Invalid path specified in Root option.
The path specified by the Root option cannot be found.
The compiler uses the current working directory.
P1005 Path and filename exceed limit of 79 characters.
The absolute pathname, or the combined root and
relative pathname, exceed the DOS limit of 79 characters.
The file is skipped.
P1007 Root path exceeds maximum limit of 66 characters.
The specified root pathname exceeds the DOS limit of 66
characters. The pathname is ignored and the compiler
uses the current working directory.
P1009 [FILES] section missing.
The [Files] section is required. The compilation is
aborted.
P1011 Option optionname previously defined.
The specified option was defined previously. The
compiler ignores the attempted redefinition.
P1013 Project file extension cannot be .hlp.
You cannot specify that the compiler use a project file
with the .hlp extension. Normally, project files are
given the .hpj extension.
P1015 Unexpected end-of-file.
The compiler has unexpectedly come to the end of the
project file. There might be an open comment in the
project file or an included file.
P1017 Parameter exceeds maximum length of 128 characters.
An option, context name or number, build tag, or other
parameter on the specified line exceeds the limit of 128
characters. The line is ignored.
P1021 Context number already used in [MAP] section.
The context number on the specified line in the project
file was previously mapped to a different context string.
The line is ignored.
P1023 Include statements nested too deeply.
The #include statement on the specified line has
exceeded the maximum of five include levels.
P1025 Section heading sectionname unrecognized.
A section heading that is not supported by the compiler
has been used. The line is skipped.
P1027 Bracket missing from section heading sectionname.
The right bracket (]) is missing from the specified
section heading. Insert the bracket and compile again.
P1029 Section heading missing.
The section heading on the specified line is not
complete. This error is also reported if the first entry in
the project file is not a section heading. The compiler
continues with the next line.
P1030 Section sectionname previously defined.
A duplicate section is found in the project file. The lines
under the duplicated section heading are ignored and the
compiler continues from the next valid section heading.
P1031 Maximum number of build tags exceeded.
The maximum number of build tags that can be defined
is 30. The excess tags are ignored.
P1033 Duplicate build tag in [BUILDTAGS] section.
A build tag in the [BuildTags] section has been
repeated unnecessarily.
P1035 Build tag length exceeds maximum.
The build tag on the specified line exceeds the maximum
of 32 characters. The compiler skips this entry.
P1037 Build tag tagname contains invalid characters.
Build tags can contain only alphanumeric characters or
the underscore (_) character. The line is skipped.
P1039 [BUILDTAGS] section missing.
The BUILD option declared a conditional build, but
there is no [BuildTags] section in the project file. All
topics are included in the build.
P1043 Too many tags in Build expression.
The Build expression on the specified line has used
more than the maximum of 20 build tags. The compiler
ignores the line.
P1045 [ALIAS] section found after [MAP] section.
When used, the [Alias] section must precede the
[Map] section in the project file. Otherwise the
[Alias] section is skipped.
P1047 Context string contextname already assigned an alias.
You cannot do: a= b then a= c (A context string can have
only one alias.)
The specified context string has previously been aliased
in the [Alias] section. The attempted reassignment on
this line is ignored.
P1049 Alias string aliasname already assigned.
You cannot do: a= b then b= c (You can't alias an alias.)
An alias string cannot, in turn, be assigned another alias.
P1051 Context string contextname cannot be used as alias string.
You cannot do: a= b then c= a.
A context string that has been assigned an alias cannot
be used later as an alias for another context string.
P1053 Maximum number of font ranges exceeded.
The maximum number of font ranges that can be
specified is five. The rest are ignored.
P1055 Current font range overlaps previously defined range.
A font size range overlaps a previously defined mapping.
Adjust either font range to remove any overlaps. The
second mapping is ignored.
P1056 Unrecognized font name in Forcefont option.
A font name not supported by the compiler has been
encountered. The font name is ignored and the compiler
uses the default Helv font.
P1057 Font name too long.
Font names cannot exceed 20 characters. The font is
ignored.
P1059 Invalid multiple-key syntax.
The syntax used with a MULTIKEY option is
unrecognized. See the section "Building the Help File"
earlier in this chapter for the proper syntax.
P1061 Character already used.
The specified keyword-table identifier is already in use.
Choose another character.
P1063 Characters K and k cannot be used.
These characters are reserved for Help's normal keyword
table. Choose another character.
P1065 Maximum number of keyword tables exceeded.
The limit of five keyword tables has been exceeded.
Reduce the number. The excess tables are ignored.
P1067 Equal sign missing.
An option is missing its required equals sign on the
specified line. Check the syntax for the option.
P1069 Context string missing.
The line specified is missing a context string before an
equal sign.
P1071 Incomplete line in sectionname section.
The entry on the specified line is not complete. The line
is skipped.
P1073 Unrecognized option in [OPTIONS] section.
An option has been used that is not supported by the
compiler. The line is skipped.
P1075 Invalid build expression.
The syntax used in the build expression on the specified
line contains one or more logical or syntax errors.
P1077 Warning level must be 1, 2, or 3.
The WARNING reporting level can be set only to 1, 2, or
3. The compiler will default to full reporting (level 3).
P1079 Invalid compression option.
The COMPRESS option can only be set to TRUE or
FALSE. The compilation continues without compression.
P1081 Invalid title string.
The TITLE option defines a string that is null or contains
more than 32 characters. The title is truncated.
P1083 Invalid context identification number.
The context number on the specified line is null or
contains invalid characters.
P1085 Unrecognized text.
The unrecognizable text that follows valid text in the
specified line is ignored.
P1086 Invalid font-range syntax.
The font-range definition on the specified line contains
invalid syntax. The compiler ignores the line. Check the
syntax for the MAPFONTSIZE option.
P1089 Unrecognized sort ordering.
You have specified an ordering that is not supported by
the compiler. Contact Microsoft Product Support Services
for clarification of the error.
Errors during processing of RTF topic files
R2001 Unable to open bitmap file filename.
The specified bitmap file is unreadable. This is a DOS file
error.
R2003 Unable to include bitmap file filename.
The specified bitmap file can not be found or is
unreadable. This is a DOS file error or an out-of-memory
condition.
R2005 Disk full.
The Help resource file could not be written to disk.
Create more space on the destination drive.
R2009 Cannot use reserved DOS device name for file filename.
A file has been referred to as COM1, LPT2, PRN, etc.
Rename the file.
R2013 Output file filename already exists as a directory.
There is a subdirectory in the Help project root with the
same name as the desired Help resource file. Move or
rename the subdirectory.
R2015 Output file filename already exists as read-only.
The specified filename cannot be overwritten by the
Help resource file because the file has a read-only
attribute. Rename the project file or change the files
attribute.
R2017 Path for file filename exceeds limit of 79 characters.
The absolute pathname, or the combined root and
relative pathname, to the specified file exceed the DOS
limit of 79 characters. The file is ignored.
R2019 Cannot open file filename.
The specified file is unreadable. This is a DOS file error.
R2021 Cannot find file filename.
The specified file could not be found or is unreadable.
This is a DOS file error or an out-of-memory condition.
R2023 Not enough memory to build Help file.
To free up memory, unload any unneeded applications,
device drivers, and memory-resident programs.
R2025 File environment error.
The compiler has insufficient available file handles to
continue. Increase the values for FILES= and
BUFFERS= in your config.sys file and reboot.
R2027 Build tag tagname not defined in [BUILDTAGS] section of project file.
The specified build tag has been assigned to a topic, but
not declared in the project file. The tag is ignored for the
topic.
R2033 Context string in Map section not defined in any topic.
There are one or more context strings defined in the
project file that the compiler could not find topics for.
R2035 Build expression missing from project file.
The topics have build tags, but there is no Build=
expression in the project file. The compiler includes
all topics in the build.
R2037 File filename cannot be created, due to previous error(s).
The Help resource file could not be created because the
compiler has no topics remaining to be processed.
Correct the errors that preceded this error and recompile.
R2039 Unrecognized table formatting in topic topicnumber of file filename.
The compiler ignores table formatting that is
unsupported in Help. Reformat the entries as linear text
if possible.
R2041 Jump context_string unresolved in topic topicnumber of file filename.
The specified topic contains a context string that
identifies a nonexistent topic. Check spelling, and that
the desired topic is included in the build.
R2043 Hotspot text can't spread over paragraphs
A jump term spans two paragraphs. Remove the
formatting from the paragraph mark.
R2045 Maximum number of tab stops reached in topic topicnumber of file filename.
The limit of 32 tab stops has been exceeded in the
specified topic. The default stops are used after the 32nd
tab.
R2047 File filename not created.
There are no topics to compile, or the build expression
is false for all topics. There is no Help resource file
created.
R2049 Context string text too long in topic topicnumber of file filename.
Context string hidden text cannot exceed 64 characters.
The string is ignored.
R2051 File filename is not a valid rtf topic file.
The specified file is not an .rtf file. Check that you
have saved the topic as rtf from your word processor.
R2053 Font fontname in file filename not in RTF font table.
A font not defined in the .rtf header has been entered
into the topic. The compiler uses the default system font.
R2055 File filename is not a usable rtf topic file.
The specified file contains a valid rtf header, but the
content is not .rtf or is corrupted.
R2057 Unrecognized graphic format in topic topicnumber of file filename.
The compiler supports only Windows bitmaps. Check
that metafiles or Macintosh formats have not been used.
The graphic is ignored.
R2059 Context string identifier already defined in topic topicnumber of file filename.
There is more than one context-string identifier footnote
for the specified topic. The compiler uses the identifier
defined in the first # footnote.
R2061 Context string contextname already used in file filename.
The specified context string was previously assigned to
another topic. The compiler ignores the latter string and
the topic has no identifier.
R2063 Invalid context-string identifier for topic topicnumber of file filename.
The context-string footnote contains non-alphanumeric
characters or is null. The topic is not assigned an
identifier.
R2065 Context string defined for index topic is unresolved.
The index topic defined in the project file could not be
found. The compiler uses the first topic in the build as
the index.
R2067 Footnote text too long in topic topicnumber of file filename.
Footnote text cannot exceed the limit of 1000 characters.
The footnote is ignored.
R2069 Build tag footnote not at beginning of topic topicnumber of file filename.
The specified topic contains a build tag footnote that is
not the first character in the topic. The topic is not
assigned a build tag.
R2071 Footnote text missing in topic topicnumber of file filename.
The specified topic contains a footnote that has no
characters.
R2073 Keyword string is null in topic topicnumber of file filename.
A keyword footnote exists for the specified topic, but
contains no characters.
R2075 Keyword string too long in topic topicnumber of file filename.
The text in the keyword footnote in the specified topic
exceeds the limit of 255 characters. The excess characters
are ignored.
R2077 Keyword(s) defined without title in topic topicnumber of file filename.
Keyword(s) have been defined for the specified topic,
but the topic has no title assigned. Search Topics Found
displays "Untitled Topic" for the topic.
R2079 Browse sequence string is null in topic topicnumber of file filename.
The browse-sequence footnote for the specified topic
contains no sequence characters.
R2081 Browse sequence string too long in topic topicnumber of file filename.
The browse-sequence footnote for the specified topic
exceeds the limit of 128 characters. The sequence is
ignored.
R2083 Missing sequence number in topic topicnumber of file filename.
A browse-sequence number ends in a colon (:) for the
specified topic. Remove the colon, or enter a minor
sequence number.
R2085 Sequence number already defined in topic topicnumber of file filename.
There is already a browse-sequence footnote for the
specified topic. The latter sequence is ignored.
R2087 Build tag too long.
A build tag for the specified topic exceeds the maximum
of 32 characters. The tag is ignored for the topic.
R2089 Title string null in topic topicnumber of file filename.
The title footnote for the specified topic contains no
characters. The topic is not assigned a title.
R2091 Title too long in topic topicnumber of file filename.
The title for the specified topic exceeds the limit of 128
characters. The excess characters are ignored.
R2093 Title titlename in topic topicnumber of file filename used previously.
The specified title has previously been assigned to
another topic.
R2095 Title defined more than once in topic topicnumber of file filename.
There is more than one title footnote in the specified
topic. The compiler uses the first title string.
R2501 Using old key-phrase table.
Maximum compression can only result by deleting the
.ph file before each recompilation of the Help topics.
R2503 Out of memory during text compression.
The compiler encountered a memory limitation during
compression. Compilation continues with the Help
resource file not compressed. Unload any unneeded
applications, device drivers, and memory-resident
programs.
R2505 File environment error during text compression.
The compiler has insufficient available file handles for
compression. Compilation continues with the Help
resource file not compressed. Increase the values for
FILES= and BUFFERS= in your config.sys file and
reboot.
R2507 DOS file error during text compression.
The compiler encountered a problem accessing a disk
file during compression. Compilation continues with the
Help resource file not compressed.
R2509 Error during text compression.
One of the three compression errors— R2503, R2505, or
R2507— has occurred. Compilation continues with the
Help resource file not compressed.
R2701 Internal error.
Contact Microsoft Product Support Services for
clarification of the error.
R2703 Internal error.
Contact Microsoft Product Support Services for
clarification of the error.
R2705 Internal error.
Contact Microsoft Product Support Services for
clarification of the error.
R2707 Internal error.
Contact Microsoft Product Support Services for
clarification of the error.
R2709 Internal error.
Contact Microsoft Product Support Services for
clarification of the error.
Copyright © 1995-2003 Digital Mars. All Rights Reserved.