PCjs Machines
Home of the original IBM PC emulator for browsers.
MS Professional Advisor - Library Reference
The following document is from the Microsoft Programmer’s Library 1.3 CD-ROM.
Microsoft Professional Advisor - LIBRARY REFERENCE
────────────────────────────────────────────────────────────────────────────
Microsoft (R) Professional Advisor - LIBRARY REFERENCE
────────────────────────────────────────────────────────────────────────────
FOR MS (R) OS/2 and MS-DOS (R)
OPERATING SYSTEMS
MICROSOFT CORPORATION
Information in this document is subject to change without notice and does
not represent a commitment on the part of Microsoft Corporation. The
software described in this document is furnished under a license agreement
or nondisclosure agreement. The software may be used or copied only in
accordance with the terms of the agreement. It is against the law to copy
the software on any medium except as specifically allowed in the license or
nondisclosure agreement. No part of this manual may be reproduced or
transmitted in any form or by any means, electronic or mechanical, including
photocopying and recording, for any purpose without the express written
permission of Microsoft.
RESTRICTED RIGHTS: Use, duplication, or disclosure by the U.S. Government is
subject to restrictions as set forth in subparagraph (c)(1)(ii) of the
Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
or subparagraphs (c)(1) and (2) of Commercial Computer Software
─Restricted Rights at 48 CFR 52.227-19, as applicable.
Contractor/Manufacturer is Microsoft Corporation, One Microsoft Way,
Redmond, WA 98052-6399.
(C) Copyright Microsoft Corporation, 1990. All rights reserved.
Printed in the United States of America.
Microsoft, MS, MS-DOS, CodeView, and QuickC
are registered trademarks of Microsoft Corporation.
Apple and Macintosh are registered trademarks of Apple
Computer, Inc.
IBM is a registered trademark of International Business
Machines Corporation.
Document No. LN18160-0990
OEM D/0711-1Z
10 9 8 7 6 5 4 3 2 1
Introduction
Chapter 1 The Help Database
1.1 QuickHelp ASCII
1.1.1 Formatting Flags
1.1.2 Cross-References
1.1.3 QuickHelp Example
1.2 Minimally Formatted ASCII
1.3 Unformatted ASCII
1.4 RTF ASCII
1.4.1 RTF Example
1.4.2 Local Contexts
1.5 Physical Database Organization
1.5.1 Concatenated Order
1.5.2 Decompressed Topic Format
1.6 The Encoding Process
Chapter 2 Text Structure and Conventions
2.1 Authoring the Help Database
2.1.1 QuickHelp Format
2.1.2 RTF Format
2.2 Hotspots and Cross-References
2.3 Topic Commands
2.4 Cross-Reference Commands
2.5 Context Conventions
2.5.1 Contexts Covered by Convention
2.5.2 Required Contexts
2.5.3 Recommended Contexts
2.5.4 Product-Specific Contexts
2.6 Hierarchical Contexts
2.7 Environment Support
Chapter 3 The HELPMAKE Program
3.1 HELPMAKE Options
3.1.1 Encoding Options
3.1.2 Other HELPMAKE Options
Chapter 4 Applications Interface
4.1 Defining the Interface
4.2 Base File Management
4.3 Context String Management
4.4 Topic Look-Up and Decompression
4.5 Context Maneuvering
4.6 Topic Display
4.7 Cross-References
4.8 Utility
4.9 Help Engine Callbacks
4.10 Interface Usage
Chapter 5 Size and Performance
5.1 Help Engine
5.2 HELPMAKE.EXE
Glossary
Introduction
────────────────────────────────────────────────────────────────────────────
The Microsoft(R) Professional Advisor Library Reference contains information
about the help library supplied with Microsoft C products. There are several
advantages to using the Advisor Help Library.
Speed and Maneuverability - The help desired by the user must be available
quickly, with a minimum of user decisions and selections. To achieve this
goal, the Advisor Help Library supports cross-referencing, context
sensitivity, preserves previous help activity, and flexible help-text
organization.
Modification - Users and/or application developers need to be able to add
help text to the help system and modify existing help text to suit their
applications and environments. To meet this need, a maintenance utility
performs both compression and decompression of help files. Also, the Advisor
Help Library provides the ability to read uncompressed ASCII text as a help
file.
Integration - The help text presented must be available to outside
applications. The Advisor Help Library provides support routines necessary
to allow the application to access this valuable help text.
Size - It is important to create help files that take up minimal disk space
but do not at the same time severely impact look-up speed. The Advisor Help
Library provides three compression algorithms to reduce disk space and meet
speed requirements.
The Advisor Help Library includes the following files:
File Name Description
────────────────────────────────────────────────────────────────────────────
HELPMAKE.EXE Bound Help-File-Maintenance Utility.
MSHELP.DLL OS/2 help engine in DLL form.
MSHELP.LIB OS/2 help engine export library.
MHELP.LIB Medium-model help engine.
MHELPH.LIB Medium-model help engine using
handle:offset.
LHELP.LIB Large-model help engine.
WHELPP.LIB SS!=DS help engine, protected mode.
WHELPR.LIB SS!=DS help engine, real mode.
HELP.H Help engine include file. All
applications should
use this.
MSHELP.DEF .DEF file for applications that can use
it.
SHELP.LIB Small-model help engine.
────────────────────────────────────────────────────────────────────────────
NOTE
The pages that follow use the term "OS/2" to refer to the OS/2
systems─Microsoft Operating System/2 (MS(R) OS/2) and IBM(R) OS/2.
Similarly, the term "DOS" refers to both the MS-DOS(R) and IBM Personal
Computer DOS operating systems. The name of a specific operating system is
used when it is necessary to note features that are unique to the system.
────────────────────────────────────────────────────────────────────────────
Chapter 1 The Help Database
────────────────────────────────────────────────────────────────────────────
There are four types of format text for the topical contents of the help
database:
ASCII Format Description
────────────────────────────────────────────────────────────────────────────
QuickHelp Default source format for compressed
databases
Minimally formatted Can be either compressed or read
directly from the help engine
RTF An alternate source for the compressed
database
Unformatted For use directly by the help engine
1.1 QuickHelp ASCII
QuickHelp uses "dot" commands and embedded formatting characters to convey
information to HELPMAKE. For example:
.context
Each topic is preceded by one or more .context commands that indicate the
context string for the following topic text up to the next .context line.
More than one .context command may be specified for a single topic, if no
topic text is placed between them. For more information on topic commands,
see Section 2.3 in Chapter 2, "Text Structure and Conventions."
1.1.1 Formatting Flags
The following flags may be embedded in the text to change the attributes of
the topic text:
Formatting Flag Action
────────────────────────────────────────────────────────────────────────────
\b or \B Bold
\i or \I Italic
\p or \P Plain
\u or \U Underline
\v or \V Invisible
The flags \b, \i, \u and \v are toggles, turning on and off their respective
attribute. They may be combined. The \p flag turns off all attributes.
The backslash character also escapes the character which follows it, that
is,
\b
indicates the toggling of the bold attribute, while
\\b
places a " \b" into the actual text.
Lines are truncated to the specified width in characters (which defaults to
76); flags affecting the attribute do not count towards the 76-character
limit. When "/T" is specified, lines beginning with the specified
application's control character or "." are truncated at 255, regardless of
the width specification.
1.1.2 Cross-References
Cross-references are embedded in one of two ways:
1. Invisible text, immediately following a space-delineated word,
generates a cross-reference whose text is the invisible text and whose
hotspot is the entire word.
2. An anchor, signified by " \a", followed by normal text, which is then
followed by invisible text, generates a cross-reference whose text is
the invisible text and whose hotspot is all text between the anchor
and the beginning of the invisible text.
1.1.3 QuickHelp Example
The following is an example of a help database containing a single entry
using QuickHelp format:
.context #define
Syntax: #define <identifier> <substitution-text>
#define <identifier> [(<parameter-list>)]
<substitution-text>
Replaces all subsequent cases of \bidentifier\p with the
substitution-text.
If \bparameter-list\p is given after \bidentifier\p, each occurrence
of \bidentifier\p (\bparameter-list\p) is replaced with a version
of \isubstitution-text\p modified by substituting actual
arguments for formal parameters.
1.2 Minimally Formatted ASCII
Uncompressed, minimally formatted ASCII help files can be used at run time
at the cost of slower searches and larger help files. Unformatted ASCII
files are a fixed width and may not contain highlighting or
cross-references.
The help file is a sequential series of topics, each preceded by one or more
unique context definitions. Each context definition should be on a line of
its own, beginning with ">>." Subsequent lines up to the next context
definition constitute the topic text. For example:
>>#define
Syntax: #define <identifier> <substitution-text>
#define <identifier> [(<parameter-list>)]
<substitution-text>
Replaces all subsequent cases of identifier with the substitution-text.
If parameter-list is given after identifier, each occurrence of identifier
(parameter-list) is replaced with
a version of substitution-text modified by substituting actual arguments
for formal parameters.
The minimally formatted ASCII help file must begin with ">>." Since the
first topic in such a database must start with a context definition line
anyway, this allows for limited error checking to ensure that the referenced
file is indeed an ASCII help file.
Minimally formatted ASCII files do not support non-default attributes or
cross-references.
1.3 Unformatted ASCII
Fully unformatted ASCII files may be cross-referenced by other help files.
When referenced, the entire ASCII file is treated as a single help topic. No
formatting information may be present in such a file, and color may not be
used. The file is returned by the help engine "as is." Such a file has no
physical "next" or "previous."
1.4 RTF ASCII
In this format, the database is formatted in a subset of RTF to support
special attributes. RTF syntax outside of the understood subset is ignored
and stripped out by HELPMAKE. RTF generated by other programs such as
Microsoft Word 4. x, Microsoft Word for the Apple(R) Macintosh(R), or
Word-RTF can be used directly. This allows help authors to write and format
directly in these word processors.
HELPMAKE recognizes the subset of RTF listed below:
RTF Code Action
────────────────────────────────────────────────────────────────────────────
\plain Reset to default attributes. On most
screens this is unblinking normal
intensity.
\b Bold. This is displayed as intensified
text.
\i Italic. Displayed as reverse video.
\v Hidden text. Hidden text is used for
cross-reference information and some
application-specific communications, and
is not displayed.
\ul Underline. Represented as blue text on
adapters which do not support
underlining.
\par End of paragraph.
\pard Reset paragraph formatting to defaults.
\fi Paragraph first line indent.
\li Paragraph left indent.
\line New line (not new paragraph).
\tab Tab character.
Topics may be paragraph-broken. HELPMAKE formats the text to a fixed width
at compression time.
Each entry in the database source consists of one or more context strings,
followed by topic text. The sequence ">>" at the beginning of any paragraph
denotes the beginning of a new help entry. Subsequent text within that
paragraph constitutes the keyword. If the immediately following paragraph
begins with ">>," it also defines a context string for the same topic text.
Subsequent paragraphs, up to the next paragraph beginning with ">>",
constitute the topic text associated with those contexts.
1.4.1 RTF Example
The following is an example of a help database containing a single entry
using minimal RTF text:
{\rtf0
>> #define \par
Syntax:\tab #define <identifier> <substitution-text>
\par
\tab #define <identifier>[(<parameter-list>)] <substitution-text>
\par
\par
Replaces all subsequent cases of {\b identifier} with the
substitution-text.
If {\b parameter-list} is given after {\b identifier}, each occurrence
of
{\b identifier} ({\b parameter-list} ) is replaced with a version
of
{\i substitution-text} modified by substituting actual arguments for
formal parameters. \par
}
The result, referenced by the context string #define:
Syntax: #define <identifier> <substitution-text>
#define <identifier>[(<parameter-list>)] <substitution-text>
Replaces all subsequent cases of identifier with the substitution-text.
If parameter-list is given after identifier, each occurrence
of identifier (parameter-list) is replaced with a version
of substitution-text modified by substituting actual
arguments for formal parameters.
Note that the bold attributes in this example are shown as underline.
1.4.2 Local Contexts
In RTF, QuickHelp, and minimal ASCII formats, certain context strings may be
defined as local contexts, being "local" to the help file. Then these
context strings may not be looked up by HelpNc, but instead may be used only
as the target of embedded cross references in the text.
Local contexts are encoded just like normal contexts, except that they begin
with the at-sign character (@). The actual strings following the at sign are
discarded by HELPMAKE during compression. Cross-references to local contexts
are then encoded in the help file in a more compact form.
Local contexts provide the following advantages:
■ Space savings. The context strings are not preserved and hence are not
carried in the help file's context string table. Cross-references to
local contexts do not reference the actual context string, but instead
are encoded in a smaller, 3-byte format.
■ Access restriction. You cannot mistakenly ask for help on what would
be a local context string.
The following restrictions also apply:
■ Local contexts must be resolvable within a single help file. HELPMAKE
produces warnings if a local context is cross-referenced, but never
defined in the help file being created.
■ Topics which are the targets of local contexts can be accessed in only
two ways: as the target of a cross-reference or by physical or
historical relative movement in the help file (Next, Previous, or
Back).
For example:
.context normal
This is a normal topic, accessible by the context string "normal."
[button\v@local\v] is a cross-reference to the following topic.
.context @local
This topic can be reached only by physical previous or next, a
historical
backup, or by the cross-reference in the previous topic.
1.5 Physical Database Organization
The physical database consists of several pieces, as outlined below:
+-----
| Header
+-----
| Topic Index
+-----
| Context Strings
+-----
| Context Map
+-----
| Keyphrase Table
+-----
| Huffman Decode Tree
+----
| Compressed Topic Text
+----
| File Title
+----
Help files may also be concatenated together so that the above pattern is
repeated. For example,
COPY FOO.HLP/B + BAR.HLP/B + YOU.HLP/B MONDO.HLP/B
This command creates a single help file called MONDO.HLP, which consists of
the three component help files: FOO, BAR, and YOU. This file, when opened by
the help engine, counts as three files against the engine's open file limit.
In most other respects, it acts exactly like a single help file.
1.5.1 Concatenated Order
The next several sections explain the pieces in the order in which they
physically appear in a concatenated help database.
Header - Identifies the help file and contains data relating to the content
of the file. It is described by the following C structure:
typedef struct {
ushort wMagic;
ushort wSignature;
ushort wFlags;
ushort appChar;
ushort cTopics;
ushort cContexts;
ushort cbWidth;
ushort cPreDef;
uchar fname[14];
ushort reserved[2];
ulong posTbl[9];
ulong fsize;
} header;
where the following information is called out by the left-hand column:
Header Data Description
────────────────────────────────────────────────────────────────────────────
wMagic A word that identifies this as a help
file.
wSignature A word that identifies the "owner" or
application that uses this help file.
wFlags A word that contains the following
flags:
Bit Action
────────────────────────────────────────────────────────────────────────────
0 Set if context look-up is to
be case sensitive.
1 Set if the file is locked
and cannot be
decompressed.
appChar Application-specific character,
controlling access to certain line of
help text. (See the /A parameter to
HELPMAKE.) 0xff if not set.
cTopics A count of entries in the topic index.
cContexts A count of context strings.
cbWidth The fixed width encoded by HELPMAKE, if
one was specified. If zero, the data
must be formatted to the display width
by the application.
cPreDef Count of predefined contexts.
fname The original file name created by
HELPMAKE. This is used to identify
individual help files which have been
concatenated into larger help files.
posTbl A table of file positions for the
various fields in the database:
File Description
Position
────────────────────────────────────────────────────────────────────────────
0 File offset of the topic
index.
1 File offset of the context
strings.
2 File offset of the context
map.
3 File offset of the keyphrase
table;
0 if keyphrase compression
was
not performed.
4 File offset of the Huffman
decode
tree; 0 if Huffman encoding
was
not performed.
5 File offset of text of the
first topic.
6 File offset of file title.
7-8 Reserved.
9 Size of help file in bytes.
Topic Index - A table of file positions for each topic contained in the
help file. Topic #n's file position can be found in the nth
entry in this table. In addition,
the size in bytes of any compressed topic can be determined by the
difference between two successive file positions.
Context Strings - An array of strings which map to context numbers in the
following
context map. These strings are used for topic look-up when no predefined
context number has been assigned.
Context Map - A mapping of context numbers to topic numbers. This allows
context numbers to be somewhat arbitrarily assigned, by an outside
piece of software, such as a parser, and then mapped to sequential
topic numbers.
Keyphrase Table - Table of strings used in keyphrase decompression.
Huffman Decode Tree - The tree used to decompress Huffman encoded data.
Compressed Topic Text - The compressed text for the actual topic data,
preceded by
a 1-word count of bytes in the uncompressed topic.
File Title - The title or name specified with the /N command at compression
time.
1.5.2 Decompressed Topic Format
Each line of the decompressed topic is formatted as follows:
+--------+----------------------+
| cbText | ASCII Text.......... |
+-------------------------+-----+--+----------------+
| cbInfo | Attr Info | 0ffffh | Cross-Ref Info |
+-------------------------+--------+----------------+
.
.
Topic information appears in the following order:
Topic Data Description
────────────────────────────────────────────────────────────────────────────
cbText Byte. Length in bytes, plus one, of the
ASCII text which follows.
ASCII Text Text of the line. All characters are
displayable.
CR-LF characters have no special meaning.
cbInfo Word. Length in bytes plus two of the
attribute and cross-reference
information that follows.
Attr Info Information describing the attributes
associated with the preceding line.
These are formatted as attribute
index/byte-count-byte pairs with
attribute 0ffh indicating the end.
Attribute indexes are bytes whose bits
represent the following attributes:
Bit Attribute
────────────────────────────────────────────────────────────────────────────
0 Bold
1 Italic
2 Underline
Thus, attribute indexes can range in
value from 0 -7, representing various
combinations of the above.
Cross-Ref Info Definition of the "hotspots" contained
in the line and what they
cross-reference to. Each hotspot is
formatted as:
+------+------+-----------+
|cols|cole|cross-ref|
+------+------+-----------+
where format information breaks down as
follows:
Definition Description
────────────────────────────────────────────────────────────────────────────
cols Byte. Starting column of
hotspot.
cole Byte. Ending column of the
hotspot (inclusive).
cross-ref ASCIIZ string. Context which
the
hotspot cross-references to.
Either
a null-terminated ASCII
string or a
"local context" (a 3-byte
internal
data structure, the first
byte of
which is zero).
1.6 The Encoding Process
The HELPMAKE utility makes several passes on the data when encoding source
files into help-file format. The amount of compression to be performed is
optional and is specified when HELPMAKE is run.
HELPMAKE passes are described below.
1. In the first pass, extraneous encoding information is stripped from
the file and remaining formatting information is converted to an
internal form. Local context references and definitions are collected.
2. During the second pass, local context references are resolved. If
enabled, the text is also run-length encoded. All runs of 4 to 255
identical characters are replaced with a flag, the character, and a
repetition count. During this pass the context strings are collected.
If keyphrase compression is enabled, the encoded text is analyzed for
keyword/phrase frequency.
3. If keyphrase compression is enabled, the following pass replaces all
space-saving occurrences of keyphrases with a flag byte and a byte
index. If Huffman encoding is enabled, character frequency of the
output is analyzed for Huffman tree construction.
4. If Huffman encoding is enabled, a following Huffman pass encodes the
topic text.
5. The next-to-last pass builds file topic and compression tables in
their final form in preparation for writing to the output file.
6. In the final pass, the actual help file is written. The help-file
header, topic index, context string table, context map, keyphrase
table, and Huffman tree are all written to the help file, followed by
the compressed topic text.
As noted above, once compressed, multiple help files can be manually
concatenated to produce single help files.
Chapter 2 Text Structure and Conventions
────────────────────────────────────────────────────────────────────────────
Common structures and conventions ensure that help files for one application
will make sense when viewed using another. This information goes beyond the
context-string and topic-text mapping functions of the help engine itself.
This chapter outlines organizational conventions and approaches that should
be followed by applications that provide maximally cross-compatible help
files.
2.1 Authoring the Help Database
The help engine is a data-retrieval tool that imposes no real restrictions
on the content and format of the help text. The HELPMAKE utility and
additional display routines and conventions, however, make certain
assumptions about the format of help text. This section provides some help
authoring guidelines.
2.1.1 QuickHelp Format
When using QuickHelp format, a text editor would be used. QuickHelp format
also lends itself to relatively easy automated translation from other
document forms.
Help text source is a sequential series of topics, each preceded by one or
more unique context definitions. In QuickHelp format, each topic begins with
one or
more ".context" lines defining the context strings which map to the topic
text. Subsequent lines up to the next ".context" constitute the topic text.
For example:
.context #define
Syntax: #define <identifier> <substitution-text>
#define <identifier> [(<parameter-list>)]
<substitution-text>
Replaces all subsequent cases of \bidentifier\p with the
substitution-text.
If \bparameter-list\p is given after \bidentifier\p, each occurrence
of \bidentifier\p (\bparameter-list\p) is replaced with a version
of \isubstitution-text\p modified by substituting actual arguments
for formal parameters.
See Chapter 1 for a detailed discussion of QuickHelp.
2.1.2 RTF Format
When using RTF format, authoring can take place using a word processor or
other tool capable of generating RTF output. Mac WORD, Microsoft Word 4.x,
and Word-RTF (a tool that converts Word format files to RTF) are all
alternatives.
In RTF, each context definition should be in a paragraph of its own,
beginning with ">>." Subsequent paragraphs up to the next context definition
constitute the topic text. For example:
{\rtf0
>> #define \par
Syntax:\tab #define <identifier> <substitution-text>
\par
\tab #define <identifier>[(<parameter-list>)] <substitution-text>
\par
\par
Replaces all subsequent cases of {\b identifier} with the
substitution-text.
If {\b parameter-list} is given after {\b identifier}, each occurrence
of
{\b identifier} ({\b parameter-list} ) is replaced with a version
of
{\i substitution-text} modified by substituting actual arguments for
formal parameters. \par
}
In these examples, the context string #define relates to the topic text
which follows it. The topic text contains embedded bold and italic text. See
Chapter 1 for a detailed discussion of RTF format.
2.2 Hotspots and Cross-References
Cross-references are included as invisible text. A word or an anchored
phrase, known as a hotspot, followed by invisible text, constitutes a
cross-reference. For example:
.context EXE2BIN
EXE2BIN
Convert .EXE file to Binary-Image File
\bPurpose\b
Converts an executable file in the .EXE\vexe_format\v format to a
memory image file in binary format. The EXE2BIN utility is supplied
with the MS-DOS distribution disks.
In this example, the word ".EXE" in the first line of the paragraph is the
hotspot. It cross-references to "exe_format." A mouse click or other form of
selection with the cursor on any of the letters of ".EXE" brings up the help
topic whose context was "exe_format." The invisible text "exe_format" is not
actually displayed.
When the desired hotspot crosses more than one word, an anchor is used:
Converts an executable file in the \a.EXE format\vexe_format\v
to a memory image file in binary format. The EXE2BIN utility is
supplied with the MS-DOS distribution disks.
In this case, the hotspot consists of the entire phrase ".EXE format."
Anchored hotspots must be contained on a single line.
The invisible cross-reference text is formatted as one of the following:
Text Command Action
────────────────────────────────────────────────────────────────────────────
context_string Results in the help topic associated
with the arbitrary context string being
displayed. For example, "exe_format"
results in the help topic associated
with that context being displayed.
@context_string Causes the help topic associated with
the local context string to be displayed.
As defined in a previous section, local
contexts must be defined in the same
help file that they are referenced in.
filename! Causes the entire file referenced to
be treated as a single topic to be
displayed. For example, the command
"$INCLUDE:stdio.h!" would search the
INCLUDE environment variable for STDIO.H,
and display it as a single help topic.
filename!context_string Same as "context_string" above, except
that only the help file "filename" is
searched. If not already open, it is
searched for, either on the path or
explicit environment variable, and
opened. For example, the command
"$INIT:mep.hlp!assign" would search for
"mep.hlp" on the INIT environment
variable, and bring up the topic
associated with "assign."
!cmd A cross-reference command. These
commands are discussed in Section 2.4.
2.3 Topic Commands
Topic commands embedded into the help text provide additional control
information to the application displaying help. The commands are contained
on a single line which is not considered part of the help text, and is not
displayed to the user, but is embedded into the help text source.
With the exception of ".context" and ".comment," topic commands take two
forms: an "English" version used in the help source code (dot command), and
a shortened version actually placed in the encoded help file and understood
by the application displaying help (colon command). English versions of the
commands are automatically converted by the HELPMAKE program to the single
character versions (or back) on encode (or decode).
Note that ":" is replaced by whatever application-specific character is
specified to HELPMAKE using the /A parameter. Applications writers should
support only the ":" commands listed below. Help-file authors should be
concerned with only the English "." forms of the commands discussed in Table
2.1.
Table 2.1 HELPMAKE Topic Commands
╓┌─────────────────────────────────────┌─────────────────────────────────────╖
Command Action
────────────────────────────────────────────────────────────────────────────
Command Action
────────────────────────────────────────────────────────────────────────────
.context context string Required.
.category string number Contains the category name the
:cstring number current function is in, and its
position in the list of functions.
The .category name is used by the
QuickHelp Topic command, which
brings up the list of topics that
the current topic is part of. This
is done by fetching the category
name, which is a .list-type topic,
and finding where the current topic
is within the list of topics.
If the help topic being displayed at
the time of a request is for
"h.contents" (the table of contents),
applications may divert the search
to the .category string of the
Command Action
────────────────────────────────────────────────────────────────────────────
to the .category string of the
currently displayed topic.
The .category command, if present,
must precede all displayable help
text. If not supported by an
application, this command should be
ignored.
.command Indicates that the topic text is not
:x a displayable help topic, and should
not be displayed to the user. Used
to precede script topics, and other
internal information.
The .command command, if present,
must precede all displayable help
text. Should be supported by all
applications. (If a next or previous
Command Action
────────────────────────────────────────────────────────────────────────────
applications. (If a next or previous
operation encounters a topic
containing this command, the topic
should simply be skipped.)
.comment text Used in the source file to specify a
comment line which will not be
placed into the database (i.e.,
HELPMAKE removes this line). This is
used by help authors to comment
their source code so that it can be
maintained by other authors without
having the text go into the database.
This can be particularly valuable
when documenting cross-
references that have commands (i.e.,
you can insert a .comment and say
what the cross-reference is supposed
to do).
Command Action
────────────────────────────────────────────────────────────────────────────
to do).
Since the comments are not preserved
in the compressed file, they cannot
be restored via decompression.
.execute cmd Executes the specified
:ycmd cross-reference command. This
command is executed at the time the
line is encountered while the
application is processing the topic
for display. All cross-reference
commands are valid, even though not
all make sense. This command may
appear anywhere in a topic.
If not supported by an application,
this command should be ignored.
Command Action
────────────────────────────────────────────────────────────────────────────
.file filename Normally used by an internal release
:ffilename of the database to point to the
location of the source file. The
private build of QuickHelp along
with a macro command in MEP
can make it possible to load the
source file with two keystrokes.
If not supported by an application,
should be ignored.
.freeze ## Indicates that the next ## lines
:z ## which follow are to be "frozen" as
the top line(s) on the help screen.
This is typically used to freeze a
row of cross-reference buttons at
the top of a help topic which might
be scrolled.
Command Action
────────────────────────────────────────────────────────────────────────────
be scrolled.
The .freeze command, if present,
must precede all displayable help
text. If not supported, should be
ignored.
.mark text [##] Defines a "mark" immediately
:mtext [##] preceding the following line of text.
An optional number, indicating
column location, may also be
included. Can be referenced by
Advisor Script commands (see Section
2.4), usually to indicate that
display of a particular topic begins
at the marked line, rather than the
first line.
.mark names are unique (local) to
Command Action
────────────────────────────────────────────────────────────────────────────
.mark names are unique (local) to
each topic. If not supported by an
application, should be ignored.
.length # Specifies the initial length of the
:l# topic when displayed. Applications
that can resize the window in which
help is displayed should attempt to
resize so that # number of lines are
displayed.
The .length command, if present,
must precede all displayable help
text. If not supported by an
application, should be ignored, and
the application must support a
reasonable default window or screen
size.
Command Action
────────────────────────────────────────────────────────────────────────────
.list Indicates that the current topic
:i contains a list of topics. This will
cause a highlighted line to be
displayed. You can select a topic by
moving the highlighted line over the
desired topic, and then pressing the
ENTER key. The first word of the
line will be used as the topic
string to search for.
If not supported by an application,
the topic should
be displayed as any other help topic
(i.e., .list can be ignored).
.next context string Indicates that the physically next
:>context string topic should be looked up using the
supplied context string, rather than
Command Action
────────────────────────────────────────────────────────────────────────────
supplied context string, rather than
getting the actual next topic. This
is used to skip large blocks of
.command or .popup topics quickly.
The .next command, if present, must
precede all displayable help text.
.previous context string Tells the help system to look up the
:<context string physically previous topic using the
supplied context string rather than
get the actual previous topic. This
is used to skip large blocks of
.command or .popup topics quickly.
.paste paste-name Begins a paste section, with the
:ppaste-name name appearing in QuickHelp's Paste
menu. If not supported by an
application, should be ignored.
Command Action
────────────────────────────────────────────────────────────────────────────
application, should be ignored.
The .paste command, if present, must
precede all displayable help text.
.end Ends a paste section. If not
:e supported by an application, this
command should be ignored.
.popup Indicates to QuickHelp that the
:g current topic is not to be loaded as
a normal, scrollable topic. Instead
the number of lines in the current
topic is counted, and a box is
created with the topic displayed
within it. As soon as you press a
key or click the mouse button, the
popup box will go away. If you have
already loaded QuickHelp, the
Command Action
────────────────────────────────────────────────────────────────────────────
already loaded QuickHelp, the
previous topic is displayed.
When QuickHelp is first run, it
attempts to find a topic from the
word underneath the cursor. If that
topic is a popup topic, QuickHelp
displays the popup box, then returns
without displaying its main window.
The .popup command, if present, must
precede all displayable help text.
If not supported by an application,
the topic can be displayed normally.
.ref [string], [string], ... Contains a list of comma-separated
:r[string], [string], ... topics (i.e., functions and
structures) that appear in the
Reference menu, and will be
Command Action
────────────────────────────────────────────────────────────────────────────
Reference menu, and will be
preloaded by the PreLoad thread. If
not supported by an application,
this command should be ignored.
.topic topic name If not supported by an application,
:ntopic name this command should be ignored, and
no title or name displayed.
────────────────────────────────────────────────────────────────────────────
2.4 Cross-Reference Commands
Cross-reference commands extend hotspots beyond simply moving around in help
information. These commands actually carry out actions in response to user
selection.
Typically, when a hotspot is selected by the user of the help system, the
associated invisible text or "cross-reference" is simply "looked-up" as
another help request, and its associated topic displayed. A cross-reference
command (usually prefixed by an exclamation point) contains instead an
instruction to be carried out by the host application.
The executable command, or in some cases the command class, is defined by
its first character. Uppercase alphabetic and special character commands are
broadly classified as "Advisor Script Commands," and potentially applicable
to all help systems. Lowercase characters are used to define commands or
command classes of restricted applicability.
These commands are discussed in Table 2.2.
Table 2.2 HELPMAKE Cross-Reference Commands
╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Command Class
────────────────────────────────────────────────────────────────────────────
>string Indirection. The rest of the command is
Command Class
────────────────────────────────────────────────────────────────────────────
>string Indirection. The rest of the command is
a context string which should be looked
up, and whose topic contents should be
executed, line by line, as a series of
Advisor Script Commands. Such a topic is
referred to as a script topic. The
initial exclamation point is not present
on the commands contained within a
script topic.
space The rest of the command string should be
executed visibly by the operating system.
For example, "! DIR" causes the
operating system to print the contents
of the current directory.
! The rest of the command string should be
executed invisibly by the operating
system. For example, "!!COPY FILEA FILEB"
Command Class
────────────────────────────────────────────────────────────────────────────
system. For example, "!!COPY FILEA FILEB"
causes the operating system to copy
FILEA to FILEB, with no visible output.
B Back. The application is to redisplay
the previously viewed help topic. May be
ignored if the historical backtrace list
is exhausted, or if historical backtrace
is not supported by the application.
C Context. The rest of the command string
is a context string to be retrieved and
immediately displayed. (Intended for use
within script topics.) This is
equivalent to a traditional
cross-reference that does not begin with
a "!."
D Delay. The rest of the command string is
Command Class
────────────────────────────────────────────────────────────────────────────
D Delay. The rest of the command string is
an ASCII encoded number, which is the
number of tenths of a second to delay.
When executed, the application simply
delays that much time before continuing.
(Intended for use within script topics.)
Hsx1,y1, x2,y2 Highlight. The rest of the command
specifies a region, and a highlighting
state "s" is replaced by either "E" to
enable highlighting on the region, or "D"
to disable. The highlighted region is
from the upper left corner specified by
(x1,y1) to the lower right corner
specified by (x2,y2). All coordinates
are one-based. The actual visual effect
of highlighting is left up to the
application; however, reverse video is
the commonly accepted result.
Command Class
────────────────────────────────────────────────────────────────────────────
the commonly accepted result.
K Wait for any keystroke before proceeding.
Kkey Wait for specific keystroke before
proceeding; "key" is replaced by the key
name. Beep until correct key is entered.
Kkey text Wait for specific keystroke before
proceeding; "key" is replaced by the key
name. Display "text" if wrong key is
entered.
Mtext Mark. Position current topic such that
the line marked by "text" is the first
line displayed. (See topic commands for
a description of marked text.)
Ptext text Position. Combination of .context and
Command Class
────────────────────────────────────────────────────────────────────────────
Ptext text Position. Combination of .context and
.mark commands. The second "text" string
is a context looked up and immediately
displayed. The first "text" string is a
mark at which the display of the topic
should begin.
b Specific to Basic.
c Specific to C.
CQ.HB Used in Microsoft QuickC(R) version 2.0.
Indicates that the previously viewed
help topic should be redisplayed.
(Executes the QuickC version 2.0 "Help
Back" command.) This is equivalent to
the Advisor Script Command "back" listed
above, and should also be supported by
applications requiring compatibility
Command Class
────────────────────────────────────────────────────────────────────────────
applications requiring compatibility
with C and QuickC help files.
d Specific to the Microsoft CodeView(R)
debugger.
m The command is specific to the Microsoft
Editor and/or Programmer's WorkBench
(PWB). The command is an editor macro
string, which is executed.
q Specific to the QuickHelp utility.
────────────────────────────────────────────────────────────────────────────
2.5 Context Conventions
Certain contexts are defined by convention across multiple product lines.
The intent is that multiple products can access the same types of help in
the same manner, while also providing mechanisms for truly product-specific
help to be readily identified as such.
Constructed context strings are kept small, to avoid unnecessary growth of
the context string table in each help file. In addition, many utilities
using the help system will display the context strings associated with help
topics. These conventions also define characteristics which allow such
utilities to present more intelligent information.
2.5.1 Contexts Covered by Convention
Context strings beginning with "x." (where "x" is an arbitrary character,
and "." is a period) are defined to be "internal" or "constructed" help
context strings. They are unlikely to be explicitly requested, and you may
in fact be prevented from entering contexts of this form.
The following "lead" characters are defined:
Character Definition
────────────────────────────────────────────────────────────────────────────
h Generic help. Prefixes miscellaneous
help contexts that may be constructed or
otherwise hidden from the user. For
example, a "contents" menu item would
cause a reference to "h.contents."
m Menu items. Contexts that relate to
product menu items are further defined
by their accelerator keys (for example,
the Open selection on the File menu is
referenced by "m.f.o").
d Dialogs. Dialogs are assigned a number,
and the help context string is
constructed by "d." and the ASCII text
number (for example, "d.12").
e Error numbers. Products that support the
uniform error numbering scheme used
within languages would reference those
by prefixing the error number with "e."
(for example, "e.c1234").
! Indicates a cross-reference command, as
defined in Table 2.2.
2.5.2 Required Contexts
The following contexts should be provided in all help files:
Context Description
────────────────────────────────────────────────────────────────────────────
h.default This is the "most-default" help screen,
generally displayed in response to
pressing F1 at the "top level" in most
applications.
h.notfound This is the help-text applications
display when a search for a particular
context fails. Can be an index, topical
list, or general help. Applications may
alternately present error messages when
help cannot be found.
h.pg1 Indicates the help text that is
logically the first "page" in the file.
Used by some applications in response to
a "go to the beginning" request in help
manipulation.
h.pg$ Indicates the help text which is
logically the last "page" in the file.
This is used by some applications in
response to a "go to the end" request in
help manipulation.
2.5.3 Recommended Contexts
The following contexts are not mandatory, but if used, should be of the
following defined forms:
Context Description
────────────────────────────────────────────────────────────────────────────
h.contents Help-file table of contents. In addition,
the context string contents may also be
used by itself to allow direct reference
by the user.
h.index Help-file index. In addition, the
context string index may also be used by
itself to allow direct reference by the
user.
h.pg# Specific page number. "#" is replaced
with the page number of interest.
Care should be taken to maintain "common" usage when writing help that is
referenced from context strings such as these, since other applications may
access them in this manner.
2.5.4 Product-Specific Contexts
When multiple products use the same naming mechanisms for the same
operations, confusion can arise when one product help file is made available
for use by another product. For example, search order might be the only
factor determining which product's help appears when a request for help is
made from a File:Open menu and multiple product help files are available.
All products would reference the context string "m.f.o" by convention, and
it would be in both help files.
As defined elsewhere, contexts can be prefixed by a file name. The original
help-file file names are also embedded in each help file, and preserved
regardless of what you rename the help file. This allows product-specific
contexts to be dereferenced by prefixing the original help-file name to the
context string.
For example, in PWB, QB.HLP, QC.HLP, and PWB.HLP are available. All have a
"m.f.o" context entry. When you request help on the File:Open menu, however,
PWB prefixes that string with "pwb.hlp!", creating "pwb.hlp!m.f.o" which
completely specifies that the help comes from the PWB help file.
2.6 Hierarchical Contexts
Hierarchical context strings should be manufactured by concatenating context
strings with period separators to form longer context strings. For example:
cc.error.c1876
could represent help relating to a C compiler error number c1876. The
application could manufacture a help look-up request based on its current
state, such as currently viewing errors on a C compiler, where c1876 is the
currently viewed error.
For space reasons, it may also be advisable to shorten contexts as much as
possible, when the context string will never be seen by the user. This is
the shortened example:
c.e.1876
It is important to note that the help engine does not infer anything from
the fact that the context string may be viewed elsewhere as a concatenated
hierarchy. Only a help topic whose entire context string matches exactly
will correspond to such a request.
2.7 Environment Support
File names used within the help engine may include explicit path
specifications or explicit environment variable specifications, or it may
default to being opened on the PATH environment variable. The support for
each of these is provided by the client application. For example:
Path Description
────────────────────────────────────────────────────────────────────────────
c:\lib\qb.hlp Explicit path
$INCLUDE:qb.hlp Explicit environment variable
qb.hlp Implicit PATH search
Applications may also elect to support the HELPFILES environment variable
that specifies the help files to be used. When used, the syntax of this
variable should be
SET HELPFILES=QB.HLP;QC.HLP;CV.HLP
This example instructs applications to use the three help files, QB.HLP,
QC.HLP, and CV.HLP, in that order. This may be overridden within the
application.
Chapter 3 The HELPMAKE Program
────────────────────────────────────────────────────────────────────────────
HELPMAKE is a general support program that manipulates help files. It can
dump a help file to RTF text format for editing, and compress an RTF,
QuickHelp, or modified ASCII formatted text file into help-file format.
HELPMAKE is a distributed utility; further documentation is available in the
C 6.0 Compiler or Microsoft QuickC 2.0 Compiler products. Use HELPMAKE when
you want to modify Microsoft-supplied help or to compress user-supplied help
files.
3.1 HELPMAKE Options
The syntax for HELPMAKE is as follows:
HELPMAKE { /E[n] [/Ac] [/C] [/L] [/N name] [/Sn] [/Wwidth]
| /D[U|S] | /H }
[/T][ [/V[n» [/Odestfile] sourcefile(s)
At least one source file and either the "/E" (for Encode) or "/D" (for
Decode) must be present.
3.1.1 Encoding Options
When encoding (/E) to create a help file, the /O parameter must be present.
Multiple source files may be specified, including wild cards.
The optional n parameter on /E indicates the amount of compression to take
place. Successive powers of two indicate various compression techniques to
use, as in the following list:
╓┌─────────────────────┌─────────────────────────────────────────────────────╖
Parameter Technique
────────────────────────────────────────────────────────────────────────────
0 No compression
1 Run-length compression
2 Keyword compression
4 Extended keyword compression
8 Huffman compression
For example, to use both run-length and keyword compression, specify /E3.
The default is all compression-selected.
Mixing the types of compression allows HELPMAKE to be maximally fast while
developing help files, or at the user's option when used in the field.
3.1.2 Other HELPMAKE Options
Other options that apply when encoding are listed below:
╓┌───────┌─────────────────────────────────┌─────────────────────────────────╖
Option Action
────────────────────────────────────────────────────────────────────────────
/A Specifies the
application-specific control
character
for the file. This is used with
the HelpGetCells, HelpGetLine,
and HelpGetLineAttr calls to
ignore lines that begin with
this character. This feature
allows you to embed control
information into the help topics.
Option Action
────────────────────────────────────────────────────────────────────────────
information into the help topics.
Such information can then be
automatically stripped out by
other applications without
determining the format.
/C Indicates that the context
strings for this help file are
case sensitive. All look-ups at
run time are case sensitive if
this switch has been set.
/W When specified, indicates the
fixed width of the resulting
help text, in characters. The
default value is 76. When
HELPMAKE is run to encode RTF
source, HELPMAKE automatically
formats the text to this width.
Option Action
────────────────────────────────────────────────────────────────────────────
formats the text to this width.
When used with QuickHelp or
Minimal ASCII, lines are
truncated to this width.
/L Locks the generated file so that
it cannot be decoded by HELPMAKE
later.
/Sn Specifies the type of input
file:
Option File Type
1 RTF ASCII
2 QuickHelp ASCII (default)
3 Minimally formatted (>) ASCII
Option Action
────────────────────────────────────────────────────────────────────────────
3 Minimally formatted (>) ASCII
/N Specifies a "name" or title for
the help files, subsequently
available to applications via
the HelpGetInfo interface.
Multiple word titles may be
enclosed in quotes.
/D Decodes a help file. The
destination file need not be
present, in which case the help
file is decoded to standard
output. Help files are decoded
into QuickHelp ASCII format.
Option Effect
/DS "Decode split." Splits a
Option Action
────────────────────────────────────────────────────────────────────────────
/DS "Decode split." Splits a
concatenated help file back into
its component files. No actual
decoding is done, as the
resulting help files, written to
their original file names (as
encoded in each help-file header)
remain compressed.
/DU "Decode unformatted." Creates a
plain ASCII text file from a
help file. All formatting
information, such as color and
cross-referencing, is lost
except for .context statements.
/T Translates between topic
commands in "English"
dot-command form, and the terser
Option Action
────────────────────────────────────────────────────────────────────────────
dot-command form, and the terser
form. See the section in Chapter
2 on topic commands for more
details. This switch is valid in
both encoding and decoding.
/H Causes HELPMAKE to display a
summary of usage and exit.
Chapter 4 Applications Interface
────────────────────────────────────────────────────────────────────────────
The embedded help library provides the following functionality to client
applications:
■ Help-file location and multiple file management (Open, Close)
■ Context look-up and help topic retrieval
■ Browsing functions (Next, Back)
■ Display utilities
4.1 Defining the Interface
The help "engine" is a library of database tools that control retrieval of
text based on reference words (context strings), indexes (context numbers),
or position. The applications interface is to this help engine. This section
defines the help engine's procedural interface. The engine handles the
decompression of the help file and physical file I/O.
Term Definition
────────────────────────────────────────────────────────────────────────────
Convention All routines are FAR PASCAL.
Pointers All pointers are FAR.
"nc" type An unsigned long "context number." All
referenceable keywords or phrases
(contexts) map to context numbers. A
context number identifies both the
source help file and the help context
itself.
"f" type A Boolean.
"PB" type A "pointer to a buffer." In most
versions of the help engine, this is a
far pointer (void far *). In
handle-based versions of the engine,
this is a long, containing a memory
handle in the upper word, and an offset
in the lower word. The memory handle is
passed to HelpLock for dereferencing,
and the offset is then added to the
result to form the actual physical
memory address used by the help engine.
4.2 Base File Management
HelpOpen
nc pascal far HelpOpen (char far *lpszName)
Given a help-file name, this function opens a help file and returns an
initial context, or an error code on failure. Up to 25 help files can be
open at a time. The application-provided routine OpenFileOnPath is used to
open the file; typically that routine uses the PATH environment variable to
locate the file.
The value returned by HelpOpen, if less than HELPERR_MAX (defined in
HELP.H), is an error code that displays the reason the file could not be
opened.
Concatenated help files count against the upper help-file limit once for
each concatenated portion. The initial context returned is the context for
the first physical topic in the help file. HelpOpen itself does not attempt
to automatically append any extension to the file name.
HelpClose
void pascal far HelpClose (nc ncCur)
Given a context, this function closes the help file associated with it and
deallocates all associated memory. Calling with ncCur of zero closes all
open help files.
4.3 Context String Management
HelpNc
nc pascal far HelpNc (char far *lpszContext, nc ncInitial)
Given a pointer to a context string, this function looks up the word and
returns its nonzero context number. This can be used as a Boolean, returning
FALSE if a help entry does not exist for that context string.
Here, ncInitial is the context from which the search for the help topic
begins. This context references a particular help file and help topic, and
the search commences there.
Where concatenated help files are used and ncInitial references something
other than the first of the concatenated files, those preceding it are not
searched. Similarly, if ncInitial references a help context in the middle
of the help file, those contexts preceding it will not be searched.
The initial context returned by HelpOpen (which references the first topic
in the file), should be saved and used for this call.
Context strings are of the form
[filename!][context]
where filename is the help file containing the cross-reference and allows
cross-references to cross help files. The help file is located at reference
time by using HelpOpen, and thus is located on the PATH; context is the
context string to be referenced. If no context is present, then filename!
must be present, and the file is assumed to be unformatted ASCII and to
contain the entire topic.
Context strings may also be of an internal form returned by HelpXref. See
HelpXref in Section 4.7 for more details.
HelpNcCmp
nc pascal far HelpNcCmp (char far *fpszContext,nc ncInitial,
f (pascal far *lpfnCmp) (uchar far *,
uchar far *, ushort, f, f));
Like HelpNc, when given an ASCII string, this function determines the
context number of that string. HelpNcCmp uses a caller-supplied comparison
routine; lpfnCmp is a far pointer to the comparison routine that takes the
following parameters:
Parameter Description
────────────────────────────────────────────────────────────────────────────
fpsz1 Far pointer to string 1. Normally the
constant string being "looked up."
fpsz2 Far pointer to string 2. This is usually
a string in the help file's string table
(compressed) or an actual segment of the
help file (formatted ASCII) being
searched.
cbCmp Maximum number of bytes to compare.
Normally the strings above are
zero-terminated, and this value is
passed as 255. In ASCII files, this
value may represent the number of bytes
in the second string actually being
compared. This value can be used as a
max comparison count, regardless of file
type.
fCase TRUE if search is to be case insensitive.
This is the setting of the case
sensitivity flag in the help file being
processed.
fTerm TRUE if special termination processing
is allowed. In this case, if any white
space is encountered in the second
string when NULL is found in the first,
a match is declared.
HelpSzContext
f pascal far HelpSzContext (char far *pBuffer, nc ncCur)
Given a context and a pointer to a buffer, this function places the first
context string associated with that help topic in the buffer and returns
TRUE on success.
The format of the string is as described for HelpNc, except that the
file-name part is always present (but does not include any leading path).
The file-name part references the original file name created by HELPMAKE,
not the current open file name if the help file was renamed, or if the file
was concatenated with other help files.
4.4 Topic Look-Up and Decompression
HelpNcCb
unsigned pascal far HelpNcCb (nc nContext)
Given a context number, this function returns the size in bytes of the
compressed topic.
HelpLook
unsigned pascal far HelpLook (nc nContext, PB pbDest)
Given a context number, this function places the topic text into the passed
buffer, which must be of sufficient size. HelpLook returns count of bytes in
an uncompressed topic or zero on error.
HelpDecomp
f pascal far HelpDecomp (PB pbTopic, PB pbDest, nc ncContext)
Given a compressed topic as returned by HelpLook (above) and its context
number, this function decompresses it into the destination buffer. The
decompressed text in the destination buffer is prefixed by the following
topic header structure:
typedef struct {
uchar appchar;
uchar linchar;
uchar filetype;
ushort reserved[2];
} topichdr;
where uchar is defined as follows:
Character Description
────────────────────────────────────────────────────────────────────────────
appchar The character specified by the /A switch
when the help file was created by
HELPMAKE.
linchar Line-removal character. Lines beginning
with this character are ignored by the
HelpGet routines described in Section
4.6.
filetype The type of file that the topic came
from. Values are:
0 Unformatted ASCII
1 Minimally formatted ASCII
3 Fully compressed
reserved Reserved for use by the HelpGet routines
(see Section 4.6).
Access to this data structure is currently present for compatibility only
(see HelpCtl for manipulation of the linchar byte). HelpDecomp returns
TRUE on error.
4.5 Context Maneuvering
HelpNcNext
nc pascal far HelpNcNext (nc ncCur)
Given a context, this function returns the context number for the next help
topic, or NULL on catastrophic failure.
HelpNcPrev
nc pascal far HelpNcPrev (nc ncCur)
Given a current context, this function returns the context number for the
"physically previous" help topic in the help file, or NULL on catastrophic
failure.
This function is present for those applications that present a "previous"
function in a physical, rather than historical, manner.
HelpNcRecord
void pascal far HelpNcRecord (nc ncCur)
The HelpNcRecord function records a context number in the help engine
backtrace list. Numbers are not automatically recorded by the help engine,
but must be explicitly recorded by client applications. This routine and
HelpNcBack (below) maintain a Last In First Out (LIFO) list of context
numbers used to maintain the historical backtrace list.
HelpNcBack
nc pascal far HelpNcBack ()
Given a current context, this function returns the context number for the
"historically previous" help topic. These are the context numbers previously
saved by calls to HelpNcRecord.
HelpNcUniq
nc pascal far HelpNcUniq (nc ncCur);
The HelpNcUniq function transforms a context number into a context number
guaranteed unique for each topic in the file. That is, given that many
context strings (and hence many context numbers) may map to the same topic,
HelpNcUniq transforms all the context numbers that refer to a particular
topic into the same context number. The information on the context string
originally used is lost. This function returns NULL on any error.
4.6 Topic Display
Help text returned by the help engine contains encoding information. The
following routines are provided to aid interpretation.
HelpGetCells
int pascal far HelpGetCells (ushort ln ,int cbMax , PB pbDst,
uchar far *pbTopic, uchar far *prgAttr)
HelpGetCells interprets the help file's stored format and returns character
and attribute information a line at a time.
Character Description
────────────────────────────────────────────────────────────────────────────
ln The one-based line number to return.
cbMax The maximum number of bytes to transfer.
pbDst A pointer to the destination.
pbTopic A pointer to the topic text.
prgAttr A pointer to array of character
attributes. Internal attribute indexes
are mapped to physical attributes
through this table.
Returns number of characters transferred, or -1 if that line does not exist.
HelpGetLine
ushort pascal far HelpGetLine (ushort ln, ushort cbMax,
char far *pszDst, PB pbTopic);
This function interprets the format of a topic previously read and
decompressed and returns ASCII text a line at a time.
The HelpGetLine function places characters into pszDst up to cbMax-1 for the
line specified by ln in the help topic pointed to by pbTopic. The line is
zeroterminated and the function returns the number of characters placed in
buffer.
HelpGetLineAttr
ushort pascal far HelpGetLineAttr (ushort ln, ushort cbMax,
LINEATTR far *rgAttrs,
PB pbTopic);
This function fills rgAttrs buffer with line attributes for a line defined
by ln. A line attribute is a word containing an attribute index followed by
count of characters of the attribute.
LineAttr STRUC
LA_attr dw ? ;color attribute
LA_cb dw ? ;count of chars
;with attribute
LineAttr ENDS
The array rgAttr may be terminated by an attribute of FFFF. Alternatively,
if cb is FFFF, the attribute is used for the rest of the line. cbMax is the
maximum size for the rgAttr buffer, and the function returns 0 if the buffer
is too small for attributes; otherwise, it returns nonzero.
HelpcLines
int pascal far HelpcLines (PB pbTopic);
This function returns the number of text lines in the topic pointed to by
pbTopic.
4.7 Cross-References
HelpXRef
char far * pascal far HelpXRef (PB pbTopic, hotspot far *photspot)
Given a row, column (in the hotspot structure defined below), and topic,
this function returns a pointer to a cross-reference string. pbTopic is the
pointer to the topic text, and photspot is a pointer to a hotspot structure
to update.
The HelpXRef function returns a far pointer into the topic text of a
cross-reference string and updates the contents of the hotspot structure. It
returns NULL if no cross-reference exists for that line.
A "hotspot" structure defines the position of an embedded cross-reference,
defined as follows:
typedef struct {
ushort line; /* the topic line with an xref */
ushort col; /* the starting column of xref */
ushort ecol; /* the ending column of xref */
uchar far *pXref; /* pointer to xref string */
} hotspot;
────────────────────────────────────────────────────────────────────────────
IMPORTANT
The cross-reference string can take either of two forms: a normal,
nullterminated ASCII string, or a three-byte data structure whose first byte
is NULL. It is important that the first byte be checked before copying the
string, because normal string copy routines will not copy the three-byte
data structure correctly. (The three-byte data structure is a
cross-reference to a "local context.")
────────────────────────────────────────────────────────────────────────────
HelpHlNext
f pascal far HelpHlNext (int cLead, PB pbTopic,
hotspot far *photspot);
This function locates the next cross-reference in the help topic. Given a
starting position in the passed hotspot structure, HelpHlNext locates either
the next physical cross-reference, or the next reference beginning with a
particular character (case insensitive); it locates either forward or
backward.
One of the following can be cLead:
NULL The next hot-link searching forward from
the specified position is returned.
-1 The next hot-link searching backward
from the specified position is returned.
char If positive and non-NULL, the next
hot-link following the specified
position whose on-screen keyword begins
with the character cLead is returned (
cLead must be uppercase).
-char If negative and not -1, the next
hot-link before the specified position
whose on-screen keyword begins with the
character -cLead is returned (cLead
must be uppercase).
Here, pbTopic is a pointer to the topic text; photspot is a pointer to a
hotspot structure to receive information; line and col indicate a
starting point.
The HelpHlNext function returns TRUE if a cross-reference is found or if a
hotspot structure is updated; it returns NULL if no such cross-reference.
4.8 Utility
HelpCtl
void pascal far HelpCtl (PB pbTopic, flag);
Here, pbTopic is a pointer to the topic text about to be retrieved. If the
flag is TRUE, HelpGetLine (and family) subsequently returns all lines of
text in the topic. If the flag is FALSE, HelpGetLine returns only those
lines that do not begin with the application-specific control character, as
specified by the /A parameter to HELPMAKE when the file was compressed.
(HelpGetLine "and family" refers to all line-retrieval, cross-reference, and
line-counting routines that operate on the decompressed topic text.)
────────────────────────────────────────────────────────────────────────────
NOTE
HelpCtl is provided to clarify the speed-optimization behavior in these
routines. The current method in most applications is to replace a character
in the topic header (setting it to FF) prior to calling the line-retrieval
routines, which confuses the optimization. This new interface hides the
internal data structures that would otherwise also be modified.
────────────────────────────────────────────────────────────────────────────
HelpGetInfo
int pascal far HelpGetInfo (struct helpinfo far *fpDest,
int cbDest);
This utility copies a helpinfo structure relating to the specified nc to
the specified buffer. Here, cbDest is the maximum length of the data to be
copied. If HelpGetInfo cannot copy the data because the buffer is too small,
it returns the required buffer size. Otherwise, it returns 0, indicating
success.
HelpInit
void pascal far HelpInit (void)
This call initializes data internal to the help engine. It should be called
once, at program startup.
────────────────────────────────────────────────────────────────────────────
NOTE
This function is used only in versions of the help library that do not have
preinitialized data. For convenience, all libraries distributed outside of
Microsoft have initialized data (this function is not included).
────────────────────────────────────────────────────────────────────────────
HelpShrink
void pascal far HelpShrink (void)
When called, this function causes the help engine to free all memory whose
data can be regenerated. This frees up indexes and keyword tables loaded
from help files. The next help access can cause one or more of these tables
to be reloaded. If there are no open help files, the engine has no memory
allocated, and this call does nothing.
4.9 Help Engine Callbacks
The help engine requires some support from the application environment for
file and memory management.
In the discussions below, "mh" is an unsigned short memory handle. "DOS
only" indicates that the call is used only in those versions of the help
engine that are run under MS-DOS, and not in OS/2-specific versions.
Because of the limitations of some client applications, memory management
within the help engine is such that the engine holds no locked memory when
an allocation is performed.
HelpAlloc
mh pascal far HelpAlloc (ushort cbMem)
This function allocates a block of memory. The memory may be movable, and
outside of the default data segment. HelpAlloc returns NULL on failure, or
if cbMem is 0. DOS only.
HelpDealloc
void pascal far HelpDealloc (mh)
This function deallocates a block of memory. DOS only.
HelpLock
char far * pascal far HelpLock (mh)
This function returns a far pointer to the base of the memory referenced by
the handle. In the case of movable memory, the memory is also locked. If the
memory handle passed is invalid or NULL, NULL should be returned. DOS only.
HelpUnlock
void pascal far HelpUnlock (mh)
This function unlocks the memory referenced by the handle. DOS only.
OpenFileOnPath
fhandle pascal far OpenFileOnPath (char *fname, f fWrite);
The file name is of the following form:
[$ENVVAR: | path]filename.ext
If Then
────────────────────────────────────────────────────────────────────────────
$ENVVAR: is present The file does not exist in the current
directory; it should be located on the
path-formatted environment variable
specified.
path is not present The file does not exist in the current
directory; it should be located on the
PATH environment variable.
path is present The file is simply opened. DOS only.
ReadHelpFile
ulong pascal far ReadHelpFile (int fhandle, ulong fpos, char
far *pData, ushort cbBytes);
ReadHelpFile reads cbBytes of data, placing it beginning at pData from
the file whose handle is fhandle, beginning at file offset fpos. It
returns the number of bytes read.
If cbBytes is zero, then the routine should return the size in bytes of
the referenced file. DOS only.
HelpCloseFile
void pascal far HelpCloseFile (int fhandle)
This function closes the file whose handle is passed. DOS only.
Callback Notes
Each call by an application to HelpOpen results in a call by the engine to
OpenFileOnPath if the file referenced is not already open. CloseFile will
not be called until a HelpClose operation is performed on that file.
To reduce the number of concurrently open file handles (for applications
which support multiple simultaneous help files), the handle returned by
HelpOpen (and used by ReadHelpFile and CloseFile) should be a "virtual"
handle. Also, some form of currently open file "handle caching" should be
performed. By keeping only the most recently accessed file physically open
at the DOS level, and by closing or opening when a request against a new
virtual handle is made, the help system can be guaranteed to only have one
file handle open at a time.
4.10 Interface Usage
For simple context-string-to-help-topic-text retrieval, the following steps
outline the process. Assume that the help file has been opened via HelpOpen:
1. Call HelpNc to get a context number for the string on which help is
desired.
2. Call HelpNcCb to determine the amount of memory required by the
compressed topic. If appropriate, allocate this memory.
3. Call HelpLook to retrieve the compressed topic from the help file.
This call also returns the size of the uncompressed topic. If
appropriate, allocate this memory.
4. Call HelpDecomp to decompress the topic text. Once completed, the
memory for the compressed topic text may be deleted.
5. Call HelpGetCells or HelpGetLine and HelpGetLineAttr to extract the
topic text and formatting information one line at a time.
Given any valid context number returned by the help engine, you can also:
1. Call HelpNcNext to get the context number for the next sequential
topic in the file.
2. Call HelpNcPrev to get the context number for the previous sequential
topic in the file.
3. Use HelpNcRecord and HelpNcBack to manage a history list of context
numbers.
Chapter 5 Size and Performance
────────────────────────────────────────────────────────────────────────────
5.1 Help Engine
The help engine itself varies in size based on functions used (and hence
linked in) and on memory model or environment selected. In general, it
ranges in size from 4K to 6K of code. In addition, the application requires
around 4K of code to interface the help engine to its own environment.
The help engine maintains 104 bytes of static data. All other data is
allocated dynamically, based on the number of help files being opened. For
each help file open, 115 bytes of dynamic memory is allocated. This memory
is not freed until the file is actually closed with the HelpClose function.
Note also that concatenated files count separately. That is, each
concatenated portion counts as a single separate file.
When accessing a help file, several tables are read in from the actual help
file. These tables are discardable under most circumstances by calling
HelpShrink. The tables vary in size based on the size of the help file
itself. The information in Table 5.1 presents the relevant numbers for the
file QC.HLP, a file shipped with QuickC 2.0, and some indication of what
each is dependent on.
At decompression time, the Keyphrase and Huffman tables must be resident in
memory simultaneously. This is checked by the engine. In all other cases,
HelpShrink may be called during HelpAlloc to discard unneeded or rebuildable
memory.
At decompression time, memory is also required for both the compressed and
decompressed topic texts.
Table 5.1 QC.HLP File Information
╓┌────────────────┌────────────────┌─────────────────────────────────────────╖
Type Size (in Bytes) Description
────────────────────────────────────────────────────────────────────────────
File size 355,940 Dependent on all of the tables below,
plus the volume of help actually
provided. File size has no bearing on
the memory requirements of applications.
Topic index 3,084 Four times the number of help topics in
the file. QC.HLP has 771 topics.
Context strings 4,700 Total length of all context strings
Type Size (in Bytes) Description
────────────────────────────────────────────────────────────────────────────
Context strings 4,700 Total length of all context strings
supported by the help file.
Context map 1,168 Two times the number of context strings
supported. QC.HLP has 584 context
strings.
Keyphrase table 8,087 Number plus 2,048 actually allocated at
decompression time. This table is
proportional to the size of the
compressible key phrases identified in
the file at compression time. This is
limited to 1,024 words, but the
individual words may be of arbitrary
length.
Huffman table 1,024 Occasionally smaller than this, but in
most cases quickly growing to this size.
It is never larger.
Type Size (in Bytes) Description
────────────────────────────────────────────────────────────────────────────
It is never larger.
────────────────────────────────────────────────────────────────────────────
5.2 HELPMAKE.EXE
HELPMAKE.EXE is a bound program around 60K in size. It requires 256K
available memory to run. When compressing, it requires free disk space up to
2.5 times the size of the input file(s).
Glossary
────────────────────────────────────────────────────────────────────────────
Advisor
The Microsoft Advisor is the name given to the help system as actually
implemented in many Microsoft language products.
Application-Specific Character
A character agreed upon by the applications developer and help-file author
that signifies that the rest of the line following it is a topic command
line, and not a line of actual help text to be displayed. Specified to
HELPMAKE using the /A parameter.
Context
A keyword or phrase which is recognized by the help system and relates to a
topic.
Context Map
A table which maps a context number to a topic index.
Context Number
A number in the range 1-32,767 that uniquely identifies a context.
Cross Reference
A string associated with a "hotspot" or location in displayed help text.
When activated, the cross-reference string may reference another help
context or help file, or it may cause the application to take some other
kind of action.
Cross-Reference Command
A context string which, when looked up by the application, usually in
response to a hotspot selection, does not cause additional help to be
retrieved. Instead it executes a DOS command or causes some other
application-specific action to occur.
Dot Command
English form of topic command used within QuickHelp-formatted databases.
Executable Context
See Cross-Reference Command.
Executable Cross-Reference Command
See Cross-Reference Command.
Help Database
The single compressed file output by HELPMAKE. Also, that single help file,
when concatenated with others.
Help File
A collection of one or more help databases that constitutes a single
physical file. Also, a single minimally formatted ASCII file.
Help Item
See Topic.
Help Screen
An application-provided window on a single topic. A help screen should be
scrollable to allow viewing of the entire topic, should it exceed the size
of a single screen.
Hotspot
The location in topic text to which a cross-reference has been attached.
Hotspots are normally highlighted in some fashion when displayed, and define
areas within the displayed topic that activate the cross-reference when
selected.
Keyphrase
A word or phrase extracted from the help text and replaced by a token during
compression.
Label
See Context String.
Local Context
A context that has no associated context string in the help file, and is
referenced only by a hotspot elsewhere in the same help file.
Node
See Topic.
Node Name
See Context String.
RTF
Rich Text Format. An ASCII text format for storing documents and their
formatting information.
Script Topic
A topic whose contents are executable cross-reference commands.
Topic
The text displayed as a help entry. May be up to 64K of encoded text.
Topic Command
A control line embedded into help text which contains control information or
instructions for the application displaying help, as opposed to help text to
be displayed.
Topic Index
A number corresponding to a sequential topic entry in the help file. Also,
the table that maps these numbers to actual file positions.