Microsoft Programmer's Library 1.3

home *** CD-ROM | disk | FTP | other *** search

/ Microsoft Programmer's Library 1.3 / Microsoft_Programmers_Library.7z / MPL / msc / proadv.txt < prev next >

Wrap

Text File | 2013-11-08 | 107.0 KB | 2,582 lines

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.