Help Compiler GuideHelp Compiler Guide Microsoft CorporationInformation in this document is subject to change without notice. Companies, names, and data used inexamples herein are fictitious unless otherwise noted, No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation. 1993 Microsoft Corporation, All rights reserved. FoxPro, Microsoft, MS, and MS-DOS are registered trademarks, and Microsoft Access and Windows. are trademarks of Microsoft Corporation in the United States and other countries. Birieve is a registered trademark of Novell, Inc Intel is a registered trademark of Intel Corporation. Novell isa registered trademark of Novell, Inc. Document No, DBSO618-0293 Printed in Ireland 03iii Contents Introduction xi Document Conventions xii Chapter 1 Introduction to the Help System 1 Features of the Windows Help System | Elements of a Help System 2 Tools 2 Source Files 3 How the Elements Fit Together 4 Creating a Help System 4 How Help Appears to the User 6 Topics 6 Pop-Up Windows 7 Secondary Windows 8 How Help Appears to the Developer 9 Skills Needed to Create a Help System 10 Chapter 2 Planning the Help System 11 Defining Your Audience 12 Planning for Novice Users 12 Planning for Intermediate and Advanced Users 12 Planning for All Types of Users 12 Planning the Content of the Help System 13 Planning the Help Menu of Your Application 13 Planning Contents Screens 13 Planning for Keyword Lists and Index Topics 14 Planning the Structure of Help Topics 14 Structuring Topics Into a Hierarchy 14 Structuring Topics for Search Access 15, Structuring Topics in Sequences 16 Planning Context Sensitivity 16 Creating Context References 17 Assigning Context References 17 Default Context Numbers 17 Tracking Context References 17v Contents Determining the Topic File Structure 18 Choosing a File Structure for Your Help System 18 Choosing the Number of Topics 18 Designing Help Topics 19 Topic Length 19 Using Jumps and Pop-Up Windows in Topics 20 Designing the Text 20 Consistency 20 Language 20 Paragraph and Text Length 21 White Space 21 Highlighting 21 Fonts and Font Sizes 21 Designing Graphics 22 Using Color 23 Effects of Color 23 Strategies for Using Color 24 Managing Help Topic Files 24 Keeping Track of Files and Topics 25 Creating a Help Tracker 25 Contents of a Help Tracker 25 Sample Help Tracker 26 ‘More Information About Planning Help 26 Chapter’3 Creating the Topic Files 27 Choosing an Authoring Tool 27 Structuring Help Topic Files 28 Coding Help Topic Files 29 Coding Context Strings 30 Coding Titles 31 Coding Keywords 32 Creating Multiple Keyword Tables 33 Browse Sequences 34 Organizing Browse Sequences 34 Coding Browse Sequences 36 Assigning Build Tags 36Linking Topics with Jumps and Pop-Up Windows 37 Jumps Between Topics 37 Jumps to Topics in Another Help File 39 Jumps toa Secondary Window 39 Combining Jumps 39 Jumps to Pop-Up Windows 40 Creating Definition Topics 40 Creating a Nonscrolling Region 41 Chapter 4 Creating Graphics for Help 45 Graphic Formats 45 Creating Bitmaps 46 Creating Metafiles 46 Adding Graphics to Topic Files 47 Including Graphics Directly 47 Advantages 48 Disadvantages 48 Including Graphies by Reference 49 Advantages 50 Di Creating a Graphic Reference 50 Aligning Graphics as Characters 51 Aligning Graphics at the Left Margin 51 Aligning Graphics at the Right Margin 52 Using Graphic References as Hot Spots 52 Creating Hypergraphics 53 Using the Hotspot Editor 54 The Hotspot Editor Window 55 Opening Graphics 55 Adding Hot Spots to Graphics 57 Defining Hot Spot Attributes 58 The Attributes Dialog Box 58 Selecting Hot Spots 60 Moving Hot Spots 61 Resizing Hot Spots 61 Setting Preferences 62 \dvantages 50 Contents vvi Contents Creating Multiple Resolution Bitmaps 63 Including .MRB Files in a Help File 63 Using MRBC_ 64 Performing Preprocessing Checks 64 Starting the Conversion Process 65 Chapter 5 Creating Help Macros 67 Running Help Macros 67 Running Macros When Opening a Help File 68 Running Macros When a User Enters a Topic 68 Running Macros From a Hot Spot 69 Rules for Coding Help Macros 69 Using DLL Calls as Help Macros 70 Macro Command Reference 71 About 71 AddAccelerator (AA) 72 Annotate 72 Appendltem 73 Back 74 BookmarkDefine 74 BookmarkMore 74 BrowseButtons 75 ChangeButtonBinding (CBB) 76 ChangeltemBinding (CIB) 77 CloseWindow 77 Contents 78 CopyDialog 78 CopyTopic 78 CreateButton (CB) 79 Deleteltem 80 DeleteMark 80 DestroyButton 81 DisableButton (DB) 81 Disableftem (D1) 82 EnableButton (EB) 82 Enableltem (EI) 83 ExecProgram (EP) 83 Exit 84 FileOpen 84Contents vii FocusWindow 84 GoToMark 85 HelpOn 85 History 85 IfThen 86 IfThenElse 86 Insertltem 87 InsertMenu 88 IsMark 89 JumpContents 89 JumpContext (JC) 90 JumpHelpOn 90 Jumpld (JI) 91 JumpKeyword (IK) 91 Next 92 Not 92 PopupContext (PC) 92 Popupld (PI) 93 PositionWindow (PW) 94 Prev 95 Print 95 PrinterSetup 95 RegisterRoutine (RR) 96 SaveMark 97 Search 97 SetContents 98 SetHelpOnFile 98 Virtual-Key Codes 99 Chapter 6 Building the Help Files 103 Creating the Help Project File 104 Section List 104 Specifying Topic Files 105 Specifying Options 106 BMROOT Option 107 BUILD Option 108 COMPRESS Option 109 CONTENTS Option 110 COPYRIGHT Option 110Contents ERRORLOG Option 110 FORCEFONT Option 111 ICON Option 111 LANGUAGE Option 111 MAPFONTSIZE Option 11] MULTIKEY Option 112 OPTCDROM Option 113 REPORT Option 113 ROOT Option 113 TITLE Option 114 WARNING Option 114 Sample OPTIONS Section 115 Specifying Build Tags 115 Specifying Alternate Context Strings 116 Mapping Context-Sensitive Topics 117 Including Bitmaps by Reference 119 Customizing Help 119 Defining Window Attributes 120 Using External Files 122 Sample Project File 12 Compiling the Help File 124 Building a Help File 125 Building Large Help Files 127 Building Separate Topic Files 127 Chapter 7 Testing and Debugging Help Files 129 Debugging the Help File 129 Displaying Error Messages on the Screen 130 Warning Message Reporting 130 Redirecting Errors toa File 131 Testing the Built Help File 132 Help Compiler Error Messages 132 Interpreting Error Messages 132 Error Message Categories 132 File Errors 133 Project-File Errors 135 Syntax Errors 135, General Section Errors 137 Alias and Map Section Errors 138 Windows Section Errors 138Contents ix Options Section Errors 140 BUILDTAG Footnote and Expression Errors 144 Macro Errors 145 Context String Errors 146 Footnote Errors 147 Topic Title Errors 148 Keyword Errors 148 Build Tag Errors 149 Entry Macro Errors 149 Topic File Errors 149 Miscellaneous Errors 151 Chapter 8 Programming Your Application for Help 153 Programming a Microsoft Access Application for Help 154 ‘The HelpFile Property 154 The HelpContextID Property 155 Mapping HelpContextID Values 1 Programming a Microsoft FoxPro Appli Set HelpTo 156 Set Topic To 156 Programming a Visual Basic Application for Help 157 The HelpFile Property 157 Specifying a Path and File Name 157 Specifying a File Name Only 158 The HelpContextID Property 158 Mapping HelpContextID Values 159 Using the WinHelp Function in an Application 159 ‘The WinHelp Funetion 160 Using the WinHelp Funetion in Microsoft Access and Visual Basic 160 Using the WinHelp Function in Microsoft FoxPro 160 The hWnd Parameter 162 The IpzFileName Argument 162 The wCmd Parameter 162 The dwData Parameter 163 The Multikey Table 164 Accessing Additional Keyword Tables 164 Quitting Help 165 Glossary 167 ation for Help 155xi Introduction This manual, the Microsoft Help Compiler Guide, serves as a reference for writers and developers of online Help systems for the Microsofts Windows™ operating system and applications developed using Microsoft Access™, FoxProo, Visual Basic™, and other Microsoft products. The Microsoft Help Compiler Guide also defines some specific rules you need to follow when creating a Help system for any single application. For that reason, some sections include step-by-step procedures, while others suggest general methods. To illustrate these concepts and procedures, the chapters use sample screens and text from the online Help for IconWorks, a Visual Basic application. Juded with the Help Compiler are: * HC31.EXE, the Windows Help Compiler version 3.1. «= HC3IERR, error messages for the Windows Help Compiler version 3.1. «= SHED.EXE, the Segmented Hypergraphics Editor version 3.5, = SHED.HLP, the Help file for the Segmented Hypergraphics Editor version 3.5, = MRBC.EXE, the Multiple Resolution Bitmap Compiler version 1.1 = Source files for ICONWRKS.HLP, the Help file for leonWorks. = Sample project text files.Help Compiler Guide Document Conventions This document uses the following typographic conventions, Example of convention Description WinHelp, ByVal, include, MULTIKEY BackColor, Click, Debug object context-sensitive sectionname, dwData lexpressionlist {While Until) Syntax error CFILES] Hinclude Readout. Text = “This should be “> on one line. ; Covered in Dialog Boxes. WINI P.TXT, HELP_QUIT ‘Words in bold with the initial letter capitalized indicate language-specific Keywords and options with special meaning in Microsoft Access, FoxPro, Visual Basic, and Microsoft C professional development system, Names of properties, events, and special objects appear with the initial letter capitalized. In text, italic letters are used for defined terms, usually the first time they occur in the book. Italics are also used occasionally for emphasis. In syntax, italic letters indicate placeholders for information you supply. In syntax, items inside square brackets are optional. In syntax, braces and a vertical bar indicate a mandatory choice between two or more items. You must choose one of the items unless all of the items are also enclosed in square brackets. This font is used for variables and error messages. ‘This font is also used for code. ‘The line-continuation character (** ) indicates that code continued from one line to the next in the book should be typed all on one line in the window in which you center code. A semicolon introduces comments. These lines are ignored when the Help Compiler is running Words in all capital letters indicate file ‘names and commands specific to the Help Compiler.Introduction xiii Example of convention Description ENTER, SHIFT+F1 HOME Graphical User Interface (GUI) ‘Small capital letters are used for the names of keys and key sequences, such as ENTER and CTRL#R. (Key names in online Help have only the initial letter capitalized.) The key names correspond to the names on the IBMe Personal Computer keyboard. Other ‘machines may use different names. A plus sign (+) between key names indicates a combination of keys. For example, SHIFT+F1 means to hold down the SHIFT key while pressing the FI key. Other navigational keys are referred to by their specific names. Acronyms are usually defined the first time they are usedCHAPTER 1 Introduction to the Help System You can add professional polish to your applications and make them easier to use by adding a Help system. A Help system gives users access to online information that teaches them how to use your application Contents + Features of the Windows Help System = Elements of a Help System = Creating a Help System = How Help Appears to the User = How Help Appears to the Developer = Skills Needed to Create a Help System Sample Help and Project Files Many of the examples in this book are taken from the Help and project files for IconWorks, a sample application developed using Visual Basic. If you installed the sample applications, you'll find these files in the (SAMPLES subdirectory of the Microsoft Access, FoxPro, or Visual Basic directory. (The IconWorks application, ICONWRKS.MAK. is included only with Visual Basic.) Features of the Windows Help System With the Help Compiler you can create a system of online Help for users of your application, Windows Help version 3.1 or the WinHelp application (WINHELP-EXE), displays the compiled Help system. The WinHelp application provides: = Text with multiple fonts, font sizes, and colors. = Graphics, including bitmaps with multiple resolutions and metafiles created in Windows = Macros that automate or extend the operation of the Help system.2 Help Compiler Guide = Hot spots, which are mouse-sensitive areas you create to provide users with jumps that link topics of information, pop-up windows that display additional text, and macro commands that you add to the Help system. = Segmented hypergraphics (graphics with one or more hot spots). = Secondary windows for presenting related information, = Keyword s ‘arch capability that guides a user to specific information. With the Help Compiler and related tools, you can produce Help files that take advantage of all these features. Elements of a Help System Tools ‘A Help system consists of one or more Help files that contain text and graphics needed to communicate information about your application online. Each Help file contains one or more topics a reader can select by clicking hot spots, using the keyword search, or browsing through topics in any order you determine, ‘This chapter introduces you to the tools and various source files you might use to create Help files. Subsequent chapters discuss how you create and compile the source files into a Help file you can display with the WinHelp application ‘There are three tools to assist you in creating a Help file. The following table briefly describes these tools. Tool Description Help Compiler ‘Compiles the topic and graphic files specified in the Help (HC3LEXE) project file into a Help file according to the directions given in the Help project file. A successfully compiled Help file can then be displayed in the WinHelp application. Hotspot Editor Opens bitmaps or metafiles to define hot spots within the (SHED.EXE) graphics. These hot spots link the graphic to topics in the Help file. Multiple-Resolution Compiles bitmaps of different screen resolutions into a single Bitmap Compiler file, Ifa bitmap of that resolution was compiled into the (MRBCEXE) multiple-resolution bitmap (.MRB), the WinHelp application can then display the graphic at the reader's screen resolution,Chapter 1 Introduction to the Help System 3 Source Files The following table describes the different source files you might use to create a Help file. ‘Type of source file File extension ‘Topic file Help project file Bitmap file Metafile Hypergraphie Mubtiple-resolution bitmap file RTF HPI BMP. WME SHG MRB Contains text for the Help file and codes needed to link topics together. Also contains graphics or codes needed to include graphics. You can use one or more topic files to create a Help file. At least one topic file is required to create a Help file. Text in topic files must be in rich text format (RTF). Required to create a Help file. Contains a list of text and graphic files needed for the Help file. Also contains macro and secondary window definitions, as well as instructions used by the Help Compiler to control the compile process. You use only one project file for each Help file created. Text in a Help project file must be in ASCH format. Contains a single graphie in Windows bitmap format, such as a screen image from the application or a bullet in text. You can use one or more bitmap files in a Help file. Bitmap files are optional. Contains a single graphic in Windows metafile format, such as a diagram or other graphic created by a drawing program, You ‘can use one or more metafiles in a Help file Metatiles are optional Contains a bitmap or metafile graphic produced by SHED.EXE, to which you have added one or more hot spots using the Hotspot Editor. You can use one or more hypergraphics in a Help file. Hypergraphies are optional. Contains more than one version of the same bitmap at different screen resolutions compiled into a single file. Multiple- resolution bitmaps must be produced by MRBC._EXE. You can use more than one ‘multiple-resolution bitmap in a Help file, Multiple-resolution bitmaps are optional4 Help Compiler Guide How the Elements Fit Together Figure 1.1 shows the relationship between the tools and the different source files as they work together to create a Help file. \ Fx Topic File Help Compiler comok >| Compies (RTF) (HCSLEXE) Holp File QB Topic Fle a (rr) = uns in DOS - — = runs in WINDOWS Graphics iakiea (BMP or tte Pesotten We) itmap Compiler (WRBC.EXE) re 1.1 ‘The elemes Creating a Help System The process of creating a Help system consists of several primary tasks. This section identifies these tasks and indicates the order in which you should do them. > To create a Help system for an application 1. Gather information for the Help topics. 2. Plan the Help system. Chapter 2, “Planning the Help System,” describes considerations you should keep in mind when planning your Help system. 3. Write the text for the Help topics. 4. Enter all required control codes into the text files. Control codes determine how the user moves around the Help system. Chapter 3, “Creating the Topic Files,” describes these codes in detail.Chapter 1 Introduction to the Help System 5 5. Create graphics for the Help system, if needed. Chapter 4, “Creating Graphics for Help,” describes how to create graphics for visual appeal and hypergraphics that link information in the Help system. 6. Create macros for the Help system, if needed, Macros can improve a Help system by providing faster access to many Help features. Chapter 5, “Creating Help Macros,” describes how to create macros and provides reference information for all Help macro commands. 7. Build the Help source files. Create the Help project (.HPJ) files that are necessary to compile topic files into finished Help (HLP) files. Chapter 6, “Building the Help Files,” describes how to create Help project files and compile Help source files. 8. Test and debug the Help system. Chapter 7, “Testing and Debugging Help Files,” describes how to test and debug Help source files. The chapter also defines Help Compiler error messages. 9. Program the application so it can access the Help system. Chapter 8, “Programming Your Application for Help,” describes how to prepare your application to use the Help system, Figure 1.2 shows the general work flow in the development of a Help system, Gather infomation about the application, ¥ uline the Help system and create list of opis. y We reins Gre pati Ere oil ctes ne wae Creawraces | i v Create the project files and ‘compile source fies. v Test and debug the Help system, v Paganyor sopleaton sees Hel, Figure 1.2. Work flow diagram6 Help Compiler Guide How Help Appears to the User Topics To the user of your application, the Help system appears to be part of the application and to consist of text and graphics displayed in the Help window. The Help application interprets and displays the elements of your Help file—text, pictures, hypertext links, and keyword search index—and lets the user explore the contents of the file. Note Except for adding notes and bookmarks, users can only view a compiled Help file: they can’t change the actual content or structure of the Help file. 1 of information in a Help file is the topic. A topic is a vell- contained body of text and graphics, similar to a page in a book. Unlike the page, however, a topic can hold as much information as you require. If there is more information in a topic than the Help window can display, scroll bars appear to let the user scroll through the information, Figure 1.3 illustrates the Help window that appears when the user asks for Help, in this case with IconWorks. ‘The primary u File Edit Bookmark Help ee ce a B rvs tp cones ‘The Contes ats Help JetorlconWorks. Use he scralltarto 629 antes natcurenty isle in he Help window | Totsomn howto use Help press #1 orchoose Using Hel om the Help menu | Editor somands ond cows mu Ee Figure 1.3 IconWorks Help windowChapter 1 Introduction to the Help System 7 Pop-Up Windows Some topics contain hot spots that a reader can use to get definitions of terms or s of information. By clicking the dotted underlined word, or jump, the user can read the information in a pop-up window, which appears in an overlapping box or window that “pops up” until the reader clicks the mouse again or presses any key. Figure 1.4 includes a pop-up window with a list of shortcut keys. = TeonWorks Help cE ile Edit Bookmark Help Editor: Shortcut Keys Click amen nameta let the shoreutkeys for menus nthe lconWorksedtor [ File Menu Storieut Keys To choose Press _| Seve SHIFT save As Fe ext ALF Figure 1.4 Pop-up window Jumps are cross-references to related topics. When the user clicks a jump, the Help window switches to a screen displaying different information, such as a description of the new topic. See Chapter 3, “Creating the Topic Files,” for details about displaying topics in pop-up windows or creating jumps between topics.a Help Compiler Gi Secondary Windows Another way to display additional information without leaving the topic in the main Help window is to use a secondary window. Secondary windows are opened with a hot spot; they have a title bar and scroll bars, but no menu bar. They remain open until closed by the reader, whether or not the main Help window is open. Secondary windows are useful for glossaries, procedures, examples, sample code, indexes, alphabetic lists, or other information the user may want to have available with or without the main Help window. Figure 1.5 shows the secondary window used to display a glossary in the IconWorks Help file. = TeonWorks Help File Edi Bookmark Help “The Coments ists stele ntie Help Term Ds tion Toleem how touse| Color Palette Prtolthe IconWorks Editor window whore you can selectcolrs fo crea an con Editor Dithered Now-solid color cated by peters of sod color dots “Tre window in conWerks where you ean Frosedues icovwns Fe Figure L5 Secondary window You define the characteristics of a secondary window in the Help project file. See “Defining Window Attributes” in Chapter 6, “Building the Help Files,” for details about defining secondary windows. See Chapter 3, “Creating the Topic Files,” for details about displaying a topic in a secondary windowChapter 1 Introduction to the Help System 9 How Help Appears to the Developer To the developer, the Help system is a group of topic files—text files that include special formatting codes. Figure 1.6 illustrates part of the source text, in draft mode, for the IeonWorks Help file. ||” W*inciesnls tog) Editor: Commands and Tao! 1 Toor modtstlCickne pth he Er wo ou wanton me be Sea igure 1.6 Topic file To create this topic, you must write the text, format it, and insert codes using underlined and hidden text and footnotes. Footnotes in the text contain linking information required by the Help Compiler. Chapter 2, “Planning the Help tem,” discusses formatting considerations. Chapter 3, “Creating the Topic iles,” describes how to create topics and enter the special control codes that the Help system uses. From a programming perspective, WinHelp is a stand-alone application in Windows that the user can run like any other application. However, applications can provide context-sensitive Help so that users can get Help on a particular topic directly by pressing Fl, instead of scrolling through the main Help menu. Your application can also call the WinHlelp function to ask Windows to run the WinHelp application. It can also specify which topic to display in the Help window. Chapter 8, “Programming Your Application for Help,” discusses how to program your application to call WinHelp and display specific topics.10 Help Compiler Guide Skills Needed to Create a Help System Because the WinHelp application integrates text and graphics, you might use many skills during the creation of a Help file—document analysis, writing, editing, graphic design and production, programming in Windows, and compili This document assumes you have this expertise or work with others who do. The actual skills necessary to create the topic files are much simpler. Still, you should know: = How to work with Microsoft MS-DOS" (using commands, editing files, and navigating across directories), = How to work with the Microsoft Windows graphical environment. = How to use Microsoft Word for Windows (or other RTF editor).1" CHAPTER 2 Planning the Help System The initial task for the Help writer is to gather information for the Help topics; the second task is to develop a plan for the Help system. This chapter discusses planning the Help system for a particular application Contents = Defining Your Audience = Planning the Content of Your Help System = Plan ig the Structure of Help Topics = Planning Context Sensitivity * Determining the Topic File Structure = De = Managing Help Topic Files ning Help Topics = More Information About Planning Help ‘You may want to make your plan explicit with a design document that includes an outline of Help information, a diagram of the structure of topics, and samples of the various kinds of topics your Help system will include. Keep in mind that context-sensitive Help requires increased development time, especially for the programmer.2 Help Compiler Guide Defining Your Audience Your audience determines the type of information Help system and how you present that information. you make available in your Users of Help systems might be classified in the following ways. User Background Computer novice ‘Completely new to computing. Application novice Some knowledge of computing, but new to your kind of application. For example, if you are providing Help for a spreadsheet program, the application novic be familiar only with word-processing packages. Application intermediate Knowledgeable about your kind of application. Application expert Extensive experience with your kind of application Planning for Novice Users Novice users need help learning tasks and getting acquainted with the interface, ‘These users require topics that define new, application-specitic terminology, or that offer conceptual and task-oriented information, Planning for Intermediate and Advanced Users Sophisticated users occasionally seek help with a procedure or term, but most often need to refresh their memory of statements and functions. The expert user tends to either look up reference information or seek help only with statement or function syntax, keyboard equivalents, and shortcut keys. (The preceding statement is especially true for users of, for example, a language Help system.) Planning for All Types of Users There are no rules for determining the overall content of your Help system. If you are providing a Help system for all types of users, you may want to document menu commands, procedures, definitions of new terms, features, functions, and all other relevant aspects of your application. Let the definition of your audience guide you when deciding what information to include in your topics. Carefully consider the decision to implement context-sensitive Help. Because context-sensitive Help demands a close working relationship between the Help writer and the application programmer, the development time required to create a successful Help system increases significantlyChapter2_ Planning the Help System 3 Planning the Content of the Help System You should create topics that are numerous and specific enough to provide your users with all the help they need. Your topics should be concise, but together they should cover the breadth of the application. Always remember, too, that reading from a screen strains a reader's eye faster than reading the same information on a printed page, so keep topics brief. Help systems should include: = A Help menu, = Contents screens * Keyword lists and indexes. * Individual Help topics. Planning the Help Menu of Your Application A good Help menu includes the following core selections: = Contents = Search = About Other Help menu selections provide additional benefits to the user of your application, If you include any of these features, place them between the Search for Help selection and About the Application: = Index (full alphabetic index) = Keyboard Guide + How to Use Help Do not use separator bars between the initial navigational entries on your Help menu (“Contents,” “Search,” or “Index”), Planning Contents Screens ‘The purpose of the main contents screen is to provide an overview of the contents of the Help system and to give clear, logical paths to information. It should work like the table of contents in a book. Sub-level Contents Screens Sub-level contents screens open paths from the main contents to individual topics. Category entries on the main contents screen jump to sub-level contents screens that either list Help topics in that category or display other sub-level contents screens,"4 Help Compiler Guide Guidelines Here are some guidelines you should follow when planning contents screens: = Entries can be listed under several different category headings. For example, reference entries and procedural entries can be separated. = Entries are presented by category, as either text jumps or graphic hot spots. List entries in a logical order (for example, by learning-path, by frequency of use, or alphabetically) = Your list should include no more than 10 entries. Avoid having more than 15 entries, if possible. If your list is longer than 15 entries, try to break it up with headings or into more than one contents screen. = Avoid deeply nested sub-levels so the user doesn’t have to jump more than wo or three times to display a Help topic. = On contents screens with entries that jump to individual Help topics, avoid long scrolling lists of entries. Planning for Keyword Lists and Index Topics Keyword lists and index topics are navigational aids used with contents scr ‘The keyword list and index topics should be similar to each other and work like a book index. Planning the Structure of Help Topics ‘One of the first things you should do when planning a Help system is to identity the topics that you want to appear in the system, and then decide how you want to organize those topics into a usable structure, Whatever structure you decide to use, try to minimize the number of lists that users must jump through to obtain information. Also, avoid making users move through multiple levels to reach a topic. Most Help systems function quite well with only two or three levels. ‘The sample Help file, ICONWRKS.HLP, incorporates all of the structural approaches described in this section and can serve as an example for your own Help system. Structuring Topics Into a Hierarchy Many Help systems structure topics hierarchically, that is, topics are arranged into a ranked tree structure. At the top of the hierarchy is an index, or a table of contents, or both. The index and table of contents list individual topics or categories of topics available to the user.Chapter 2 Planning the Help System 5 Topics themselves can be related hierarchically. Each successive step takes the user one level down in the hierarchy of the Help system until the user reaches diserete and specific topic information. The hierarchical relationship of Help topics determines in part how the user navigates through the Help system. 2.1 illustrates one possible hierarchy. Procedures Commands | Toolbox. | | Examples. l Topic Topic Topic Topic Topic Topic Topic Topic Topic Topic Topic Figure 2.1 Example of a Help hierarchy Moving from the index to a topic, the user goes from the general to the specific The hierarchical structure provides a point of reference within Help Structuring Topics for Search Access Users are not constrained to navigate up and down the hierarchy; they can jump laterally from one topic to another, moving across categories of topics. The effect of jumps is to bypass the hierarchical structure. For example, the WinHelp application (WINHELP.EXE) contains a Search feature that lets the user type a keyword into a dialog box to search for topics associated with that keyword, WinHelp then displays a list of topics from which to choose to access information that relates to the keyword. If users know the feature with which they need help, they can usually find the information faster by using the Search feature, rather than moving through the hierarchical structure. For more information about the Search feature, see “Coding Keywords” in Chapter 3, “Creating the Topic Files.”16 Help Compiler Guide Structuring Topics in Sequences In addition to ordering topics hierarchically, you can order them in a logical sequence that suits your audience. The logical sequence, or browse sequence, lets the user choose the Browse buttons to move from topic to topic. Browse sequences are especially important for users who like to read several related topics at once, such as the topics covering the commands on the File menu, or a series of sequential steps leading to the completion of a task, such as copying a le, For more information about browse sequences, see “Browse Sequences” in Chapter 3, “Creating the Topic Fi Planning Context Sensitivity WinHelp supports context-sensitive Help. When written in conjunction with programming the application, context-sensitive Help lets the user press FI for help on the item that currently has the focus. Ina Visual Basic application named IconWorks, for example, if the user chooses the Paint command from the Tools menu and then presses F1, IconWorks starts the Help system and displays the information shown in Figure 2 TeonWorks Help Bile Edit Bookmark Help ones] & Editor: Tools: Paint Too! “nis 80 pants pile nthe etn 0 accordingto he selected bush site To use the Pointtoa cick he mouse inthe ed send drags begin pining | Fu Toot Thietocltile «closed aree with he color eelacted inthe Color Pelee To usethe Filtool lickin ne area tobe ills. The area wil be fled wit the color selected inh ColorPelete The Filtclis adjacent pels which ae the seme colores the staring cl br aree wih a dihered color ether ar Sols col the weeutwil be @ checkerboard pater Line Toot ‘This tool crows straightines, ‘To ueethe Line tool dickin he ediing ere to anchor one end athe line, Dragthe mouse unt the mouse reaches the te end of he Ine you wort to draw, Release the mouse butonto craw he ine miheicon The wh othe ine conescondsto the curent bush ate’ The col ofthe ines he color selected nthe ole Palate To haw a horzontal vettesl or dkagensline. hold down the SHIFT kay as you drag the mouse re 2.2. Help exampleChapter 2 Planning the Help System 7 Creating Context References Developing context-sensitive Help requires that the Help writer and the application programmer agree on a list of context references so that WinHelp and the application pass the correct information back and forth, A context reference is unique number or string that corresponds to a particular object in the application; for example, to a menu command, form, control, or screen region. You can assign context references arbitrarily, but you should not change them afterward. You use context references to create links between the application and the corresponding Help topies. You enter context references and their corresponding context strings in the Help project file (.HPJ), which the Help Compiler uses to build a Help file. The section “Creating the Help Project File” in Chapter 6, “Building the Help Files.” provides details on how to create a Help project file. Assigning Context References You can provide context-sensitive help for an object by assigning it a context reference. How you assign context references, the objects to which you can assign them, and whether you use numbers or strings depend on the product you used to develop your application. The context references assigned in the Help project file should correspond to the context references that the application sends at run time to invoke a particular topic. For more information on assigning context references, see Chapter 8, “Programming Your Application For Help.” Default Context Numbers If you do not explicitly assign context numbers to topics, the Help Compiler generates default values by converting topic context strings into context numbers. For more information on context-sensitive Help and context strings, see “Mapping Context-Sensitive Topics” in Chapter 6, “Building the Help Files.” Tracking Context References To manage context references and file information, you may want to create a Help tracking file. For information about using a tracking file, see “Creating a Help Tracker” later in this chapter.8 Help Compiler Guide Determining the Topic File Structure Topic files are source files that contain the text, graphics, and hidden codes that are compiled into the Help system. Although the number and content of topic files differ between Help systems, their structure is consistent. Each file holds one or more topics separated by page breaks. Figure 2.3 shows this basic file structure for the hierarchy shown in Figure 2.1 RTF Topic Files a Procedures Commands Toolbox Examples Topic Topic Topic ] | Topic Page ages | |___ Paget | Page t Topic Topic Topic Pag02 Page 2 Page Topic Topic Topic Pages| | Page Page 3 Topic Pago Topic Page 5 Figure 2.3. Help topic file structure Choosing a File Structure for Your Help System When choosing a file structure, consider the scope and content of the Help system you are planning. For example, you could place all Help topics in a single topic file, as in the IconWorks topic file, or you could place each Help topic in a separate file. For large projects, these extremes may create tracking and debugging problems. Most projects use several topic files, dividing the contents by subject or writer. Choosing the Number of Topics The number of topics relates to the number of features covered by the Help system. You cannot make extensive changes to the application without making changes to your Help system. For instance, if additional product features are added to the application, then additional topics must be created in your Help system to describe them.Chapter 2 Planning the Help System 19 Figure 2.4 illustrates the file structure of a Help system. The number of topies and topic files is limited to simplify the diagram. Links between topics through jumps appear as arrows. Topic File Topic File Topic File tex ei (Sic tis) (Heb tos Index item 1 | INDEX ITEM 1 | SUBJECT 1 Index item 2 Subject Subject 2 —} | | End of fle Page break Page break —_| + inpexitem2 | _—wf susuect2 ‘Subject 3 Subject 4 1 Endo fle End of file Topic File (Hee toi —] SUBJECT 3 Page break > SUBJECT 4 Endotfie Figure 2.4 Help file structure showing jumps Designing Help Topics How information in the Help window appears to the user is primarily a function of the layout of the Help topic. WinHelp supports a number of text attributes and graphic images you can use to design your Help window Topic Length Optimally, a Help topic is one, or, at most, two screens long. A screen is defined ‘as approximately one-half the width of a maximized window and 15-20 lines long.20 Help Compiler Guide You can minimize topic length by breaking information into smaller categories, using multiple-column lists of topies, o creating pop-up and secondary windows for subordinate information. Using Jumps and Pop-Up Windows in Topics Avoid using too many pop-up windows on a single screen because th the screen hard to read. For example, if you use pop-up windows for definitions, each definition should pop up only once, the first time the word appears, An exception to this may occur in long topics, where an author includes a second definition for users who have scrolled past the first. Avoid using jumps in running text that replace the topic in the main Help window. If you must use a jump in running text, consider using a secondary window so that the original topic remains displayed in the main Help window Designing the Text Help text files are not limited to plain, unformatted text. You can use different fonts and font sizes, include color and graphics to emphasize points, indent paragraphs to present complex information, and use a variety of other visual devices to present your information. Research on screen format and Help systems has produced the following general guidelines for presenting information to users. Consistency Keep the finished Help system in mind when planning. For example, develop a strategy for using secondary windows that can be used consistently throughout the Help system. Decide whether you will use pop-up windows only for definitions of terms or for notes or tips. 100. Make these decisions based on the needs of your audience, but be rigorously consistent in your design. Users expect Help topics to have the same appearance, regardless of the information presented. Consistent titling, highlighting, fonts, and text positioning is essential to an effective Help system. Language Use language that is appropriate for the audience you have identified. Language that is too sophisticated can frustrate users by requiring them to learn the definitions of unfamiliar terms and concepts. Consider changes you might have to make if your application has an international audience. Certain visual elements that communicate well in your country might be misunderstood by users in other countries.Chapter 2_ Planning the Help System a Paragraph and Text Length Use short paragraphs. Online users become overloaded with text more easily than readers of printed material. Breaking your text into short paragraphs helps avoid this problem, Use a minimum of text. Reading speed for online text decreases by 30 percent compared to printed text. Concise text helps compensate for this decreased reading speed. White Space Use white space to isolate information visually and to make online text more readable. Use it liberally, but consider the overall space a topic will occupy on the screen. Users tend to think there is more information on a screen than actually exists, For example, if the ratio of white space to text is 50:50, users perceive it to be 40:60. Whenever possible, work with a graphic designer to plan white space, color, leading, and other visual elements. Highlighting Use highlighting techniques judiciously. WinHelp provides a variety of highlighting devices, including fonts, font sizes, and color. Careful highlighting can help users find information quickly. Using too many devices confuses the! Use only one or two fonts at a time. Fonts and Font Sizes ‘WinHelp can display text in any font and size available to the Help system. When you compile the topic files, the Help Compiler (HC31.EXE) tries to use the fonts and sizes found in the topic files. If a font or font size cannot be matched exactly, the Help system uses the closest available font and font size on the user’s system. Windows version 3.1 provides three types of fonts: = Bitmap fonts in specific sizes designed for the resolution of the user's system = TrueTypee fonts that can be scaled to almost any size and that work for both screen display and printer output. * Vector fonts designed for use with plotters. If you write Help files using the fonts and sizes included with Windows 3.1, the fonts displayed in the Help file will closely match those seen in the editor or word processor. Because fonts other than those shipped with Windows 3.1 may not be available on a user's machine, you might want to limit your font selection to those that ship with Windows 3.12 Help Compiler Guide Bitmap Fonts The bitmap fonts included with Windows 3.1 au = Courier (10, 12, 15 points). * MS Sans Serif (8, 10, 12, 14, 18, 24 points). = MS Serif (8, 10, 12, 14, 18, 24 points) = Symbol (8, 10, 12, 14, 18, 24 points). TrueType Fonts ‘The TrueType fonts included with Windows 3.1 are * Arial (normal, bold, italic, and bold-italic). * Courier (normal, bold, italic, and bold-italic). = Times New Roman (normal, bold, italic, and bold-italic). = Symbol. Vector Fonts The vector fonts included with Windows 3.1 are: = Modern. = Roman = Script. Since WinHelp supports any font in Windows 3.1, you can use the Symbol font to include special symbols such as arrows in your topic files. Designing Graphics Use graphics to help explain visual events, but remember that graphics attract a user’s eye faster than text. Crop your images to remove distracting information. WinHelp supports the use of bitmaps and Windows metafile graphic formats. Graphics can be placed and displayed anywhere on the screen. Text can appear next to the graphic or below it, as shown in Figure 2.5,Chapter 2 Planning the Help System 23 Using Color ne File EdKt Bookmark Help [Eontents] Search [sock [uistoy [oresson] << [>] ee 1 shown below To open he Cistom Color Poet, RGD Valine Selected :¢ a VET green (6), and ue ©) @ Figure Help grap! Graphics are most effective when they contribute to understanding. Graphics not tied to the information ean be distracting rather than helpful, and should be avoided. For more information on placing graphics into your Help files, see Chapter 4, “Creating Graphics for Help.” Color graphic images can be included, provided you use only the system colors available with Windows 3.1. If you use graphics tools that support an enhanced color palette to create or capture images, these images may not always be displayed with the intended colors. Remember that much less detail and subtlety of color is available online than in print, and poor use of color can even cause user eyestrain, Effects of Color When designing the “look” of your Help system, you should consider the visual impact of color, For example, color attracts the eye and adds emphasis. Items of the same color appear related, while items in different colors appear to belong to separate groups. Different colors have different associations for people and cultures. Don’t rely on color to convey a particular meaning. Red, for example, implies “warning” in one culture and “happiness” in another.24 Help Compiler Guide Add color to your Help files with extreme care. Overuse of color actually makes information more difficult to process because the user slows down to think about what the different color means, In particular, avoid adding color to text because it is difficult to read, and its meaning may be easily confused with green hot spots in text. Since green is the color used to indicate jump or pop-up hot spots in text, avoid using green for anything else. Strategies for Using Color Use color to convey information about structure, such as grouping or hierarchy, rather than to imply a particular meaning or use as decoration. However, don’t depend on color alone to communicate structure. The user’s monitor may not have color or may not correctly display colors. Some users may be color disabled. Design for VGA colors as a best-case scenario. Avoid the brighter colors of the Windows 16-color palette because bright colors can cause after-images, complementary (opposite) colors appear to vibrate, and both can cause eyestrain. If you must use colored text, use strong contrast. Do not put light text on a light background or bright text, like bright-green, on a bright background, like magenta. Is helpful to use color for the hidden text coding in the source files. Colored text stands out and makes it easier to debug and localize the topic files Managing Help Topic Files Help topic files can be saved in the default word-processor format or in RTF (rich-text format). If you always save your files in RTF, and later need to make a change, the word processor may take additional time to convert the format as it reloads the file. Since you will make numerous changes during the Help development process, you may want to minimize this delay by saving topic files in default format. Before you compile the Help file, however, it must be saved in RTF.Chapter 2 Planning the Help System 25 Keeping Track of Files and Topics Itis important to keep track of all topi les. A tracl g system should: = Ensure that no topics are left out of the build process = Ensure that each topic is assigned a unique context string. = Double = Show keyword and title matches. check browse sequencing within general and specific lists. = Let writers see where the text for each topic is located. = Keep track of changes to files and their current status. Track any other aspect of the Help development process that you think is, essential At minimum, writers need to keep track of their own topic files and relay the file names to the person responsible for creating the Help project file, Creating a Help Tracker While it is very helpful to track topic files throughout the development cycle, you may use any tracking tool that suits your needs. You can maintain a current list of topics in an ASCII text file, in a Microsoft Excel worksheet, oF in a Microsoft Access or FoxPro database Contents of a Help Tracker When you or another writer creates a topic, update the Help tracking file to reflect the change. The contents of the tracking file are not rigidly defined but can contain entries for the file name, context string, title, browse sequence, and keywords for each topic. You may want to include optional information, such as date created, status, and author. How you organize this information is entirely up to you. If your application implements context-sensitive Help, you may want to keep track of the context-sensitive information as well. This information is necessary only if you are assigning context references to topics in the Help project file.6 Help Compiler Guide Sample Help Tracker The sample file TRACK.DOC shown in Figure 2.6 illustrates how the tracker might be organized for the Help system topics. The example shows both Help. menu and context-sensitive Help entries for the topic files, Typically, the same topics that the user accesses when choosing commands from the Help menu can be accessed by the context-sensitive Help feature. Ot view Insert Format —Taois Table (DE GES SEE & ‘Window Help ‘Calpe Heb ahCaepiap te 0051 — —Feweweay | = i He eT Towieroesboc vgn baaox —Oaeborg reise Heb Cnr CHa cormand Sere Trcormarsbutoes 19 Connied Baars OF canes BEGET Tein, Yi Figure 2.6 Help tracker file More Information About Planning Help For additional information about planning your Help system, see the following source Bradford, Annette Norris. “Conceptual Differences Between the Display Screen and the Printed Page.” Technical Communication (Third Quarter 1984): 13-16. Galitz, Wilbert 0. Handbook of Screen Format Design. 3d ed. Wellesley, MA: QED Information Sciences, Inc., 1989. Houghton, Raymond C., Jr, “Online Help Systems: A Conspectus.” Communications of the ACM 27 (February 1984): 126-133. Queipo, Larry. “User Expectations of Online Information.” [EEE Transactions on Professional Communications PC 29 (December 1986): 11=15. Horton, William K. Designing & Writing Online Documentation: Help Files to Hypertext. New York: John Wiley & Sons, Inc., 1990.7 CHAPTER 3 Creating the Topic Files Help topic files are text files that define what the user sees when using the Help system, Topic files can include an index, information on the system, a list of commands, or a description of how to perform a task Creating topic files involves writing the text that the user sees when using Help. and then entering control codes that determine how the user moves from one topic to another. Contents * Choosing an Authoring Tool «= Structuring Help Topic Files = Coding Help Topic Files * Linking Topics with Jumps and Pop-Up Windows * Creating a Nonserolling Region Choosing an Authoring Tool To write your text files, you'll need a text editor or word processor that saves files in rich-text format (RTF). Your choices include, but are not limited to: + Microsoft Word for Windows™, version 1.0 or later, + Microsoft Word MS-DOS» Series, version 5.0 or 5.5. * Microsoft Word Macintoshe Series, version 3.0 or 4.0. * Other word processors that support RTF. With the Microsoft Word RTF capability, you can insert the coded text that defines Help terms, such as jumps, keywords, and pop-up definitions. If you choose an editor other than one of the Microsoft Word products, make sure it creates Help files that work as you intend them to work28 Help Compiler Guide Structuring Help Topic Files A Help topic file typi within a file: ly contains multiple Help topics. To identify each topic = Topics are separated by hard page breaks. = Each topic has a unique identifier, or context string. = Each topic can have a title. = A topic can have a list of keywords attached to it, These keywords are used to access information quickly using the Search feature. = Each topic can have a build-tag indicator. = Any topic can be assigned a browse sequence. igure 3.1 illustrates part of the Help topic file for the sample Visual Basie application, IeonWorks eet = a Table Window ae Pi inccaras tne) Editor: File Manuf 5 Newt Shconmand ews the eing westotat areuiton. Tharewican pean th cron lected re cadiaet + Tete ay snesved cranny sec! he Ne comma leona sks ‘iEchroe canons an eats asig wea ste carey sco sn She Tee tatamed * EDITOR FLE MENU Note For information about inserting page breaks between topics, see the documentation for the editor you are using. For information about assigning context strings and titles to topics, see the following sections in this chapter.Chapter 3. Creating the Topic Files 29 Coding Help Topic Files ‘The Help system uses control codes for particular tasks, as described in the following table. Control code Name Purpose Pound sign (#) Context string Defines a context string that uniquely footnote identities a topic, Because hypertext relies on links provided by context strings, topics without context strings can be displayed only with keywords or browse sequences Dollar sign ($) Title Defines the title of a topic. Titles are optional. footnote They appear in @ list box when you use the Search feature. Letter “K” footnote Keyword Defines a keyword with which the user searches for a topic. Keywords are optional. Plus sign (+) footnote Browse Defines a sequence that determines the order sequence in which the user can browse through topics. number Browse sequences are optional Asterisk (*) footnote Build tag Defines a tag that specifies topics the Help ‘Compiler builds into the system conditionally. Build tags are optional, but when they are used, they must appear first in a topic, Strikethrough or Jump text Indicates the text the user ean choose to jump double-underlined to another topic: text Underlined text Definition Specifies that a temporary or “pop-up" window be displayed when the user clicks the ‘mouse button or presses ENTER. Hidden text Context string Specifies the context string for the topic that will be displayed when the user selects the text that immediately precedes it. The following sections in this chapter describe how to assign these control codes toa topic. Note If you use build tags, footnote them at the very beginning of the topic. After the initial build tag footnote, footnotes can be placed in any order30 Help Compiler Guide Coding Context Strings Context strings identify each topic in the Help system. Each context string must be unique—it can be assigned to only one topic within the Help project (PJ) fil. Assigning a context string gives a topic an identifier that you ean use to create jumps to that topic or to display it in a pop-up window. Although the Help ‘Compiler can successfully compile topics that don’t have a context string, the user of the Help system can’t display them unless they contain keywords or are part of a browse sequence. To assign a context string to a Help topic 1. Place the insertion point to the left of the topic heading, 2. Insert the pound sign (#) as the footnote reference mark Note that a superscript pound sign (*) appears next to the heading. the footnote. Type the context strin Be sure to allow only a single space between the pound sign (#) and the string. Context strings are not case sensitive and cannot include spaces, Valid context strings may contain the alphabetic characters A~Z, the numeric characters 0-9, and the period (,) and underscore (_) characters. The following context-string footnote identifies a topic called “Opening an Existing Text File” # openingTextFile Although a context string has a practical limitation of 255 characters, you should keep the strings short so they are easier to enter into the text files. ‘You can assign a topic additional context strings by placing them in various locations throughout the topic. When the user clicks a hotspot that is coded to one of the additional context strings, WinHelp jumps to the specified location in the topic. For example, in a alphabetic list of commands or any index-style list, you can use ahypergraphic in a nonserolling region at the beginning of the topic and add a context string in front of each uppercase letter. When users click a letter in the graphic, the jump takes them to that letter in the list.Chapter 3 Creating the Topic Files El Coding Titles In the WinHelp application, the title of a topic can appear: = At the beginning of the topic. = Inthe Bookmark menu, if the topic contains a bookmark. = In the Search dialog box, if the topic contains keywords. To place the title at the beginning of the topic, type it as the first paragraph. You must define code for the title in a footnote for the title to appear correctly in the Bookmark menu and the Search dialog. Although the Help Compiler doesn't require that a topic have a title foomote, only those topics in the main Help window or a secondary window that do have a title footnote appear correctly in the Bookmark menu. > To assign a title to a Help topic 1, Place the insertion point to the left of the topic heading. 2. Insert a footnote with a dollar sign () as the footnote reference mark. Note that a superscript dollar sign () appears next to the heading. 3. Type the title as the footnote. Be sure to allow only a single space between the dollar sign (S) and the title. The following example shows a footnote that defines the title for a topic: 5 Help Keys When adding titles, keep in mind the following restrictions. Item Restrictions Characters Titles can be up to 128 characters in length. The Help Compiler truncates title strings longer than 128 characters. The Help system displays titles in a list box when the user searches for a keyword or enters a bookmark. Formatting Do not format title Footnote entries32 Help Compiler Guide Coding Keywords With the WinHelp application, a user can search for topics using keywords assigned to those topics. WinHelp lists matching topics by their titles (as defined in the title footnote) in the Search dialog box. The keyword search facility serves the same purpose as the index in a book. Because a keyword search is often the fastest way for users to access Help topics, you'll probably want to assign keywords to most topics in your Help system. Note You should specify a keyword footnote only if the topic has a title footnote, since the title of the topic appears in the Search dialog box when the user searches for the keyword, Topics that do not have titles but that are accessible through keywords are listed as >>Untitled Topic<< in the list at the bottom of the Search dialog box. > Toassign a keyword toa Help topic 1, Place the insertion point to the left of the topic heading. 2, Insert an uppercase K as the footnote reference mark, Note that a superscript K (K) appears next to the heading. 3. Type the keyword, or keywords, as the footnote. Be sure to allow only a single space between the K and the first keyword. If you add more than one keyword, separate them with a semicolon (;). ‘The following is an example of keywords for a topic: K openzopening: text filesASCIIzexisting:text only:documents: When the user performs a search on any of these keywords, the corresponding titles appear in a list box. A keyword may appear in more than one topic. When adding keywords, keep in mind the following restrictions. Item Restrictions Characters ‘Keywords can use any ANSI character, including accented characters. The maximum length for keywords in a single topic is 255 characters. Phrases, as well as individual words, can be keywords, since a space embedded in a key phrase is considered a character. Phrases Help searches for any word in the specified phrase, Formatting Keywords are unformatted,Chapter 3 Creating the Topic Files 33 Item Restrictions Case sensitivity Keywords are not case-sensitive; however, in the Search, dialog box they appear just as they are typed in the source file, Punctuation Except for semicolons, you can use punctuation just as in printed indexes. Creating Multiple Keyword Tables Multiple keyword tables let you define additional lists of keywords in a Help file Your application can display these keyword tables using the WinHelp function. You can use this feature to provide context-sensitive Help for special words in your application, For example, Visual Basic uses multiple keyword tables to provide Help on Visual Basic reserved words when the user presses Fi. With multiple keyword tables, users familiar with keywords from a different application can find matching keywords in your application. Writing additional keyword tables is a two-part process. First, the MULTIKEY option must be placed in the [OPTIONS] section of the Help project file. (See “MULTIKEY Option” in Chapter 6, “Building the Help Files.”) Second, you must write and label the topics to be associated with the additional keyword table. Footnotes are assigned in the same manner as the normal keyword footnotes, except that the letter specified with the MULTIKEY option is used. The keyword footnote is not case-sensitive, Be sure to associate only one topic with each multiple keyword. The WinHelp application doesn’t display the normal Search dialog box for a multiple keyword search. Instead, it displays the first topic found with the specified keyword. If you want the topics in your additional keyword table to appear in the Search dialog box, you must define the same keyword using the “K” footnote in the topic Program your application to display the Help topic associated with a given string in a specified keyword table. Keywords are sorted without regard to case for the keyword table. For information on the parameters passed by the application to call a topic found in an alternate keyword table, see “Accessing Additional Keyword Tables” in Chapter 8, “Programming Your Application for Help.”34 Help Compiler Guide Browse Sequences With the Browse Forward (>>) and Browse Back (<<) buttons on the toolbar in WinHelp, a user can move through topics in a linear fashion, as in reading a book. The order the user follows when moving from topic to topic is called a browse sequence. A browse sequence is determined by codes established by the Help writer. To plan browse sequences in Help topics 1. Group topics and arrange them in a logical sequence within each group. Code topics to implement the sequence. 3. Test the sequence in a build to make sure it is logical. Note WinHelp version 3.1 doesn’t automatically provide Browse Forward (>>) and Browse Back (<<) buttons. If your Help file includes one or more browse sequences, you must use the BrowseButtons() macro so the user can browse forward and backward Organizing Browse Sequences When organizing browse sequences, arrange the topics in an order that makes sense to the reader. You can organize topics into a browse sequence: = Inalphabeti l order, by subject. = From the least complex or difficult to the most complex or difficult. «= For topics describing menu selections, from the top of the menu list to the bottom. Browse codes have two parts: group and order. Both are sorted by their ASCII values. The order can be numeric or alphabetical. The following example shows browse sequences for the menu commands for a given application. The Help writer has organized the topics that describe the menu selections into two browse 's, one sequence for each menu. You may, of course, choose a differentChapter Creating the Topic Files 35 SampleApp Commands File Menu - commands :005 New Command - file menu:005 Open Command - file menu:010 Save Command - file menu:@15 Save As Command - file menu:020 Print Conmand - file menu:025 Printer Setup Command - file menu:030 Exit Command - file_menu: 035 Edit Menu - commands:010 Undo Command - edit menu:025 Cut Command - edit_menu:01 Copy Command - edit menu:@1@ Paste Command - edit_menu:@20 Clear Conmand - edit _menu:0a5 Select A11 Command - edit men: Word Wrap Command - edit menu: Type Face Command - edit_menu:! Point Size Command - edit meni Each line consists of a group name followed by a colon and an order string. The group name is optional. If the sequence does not have a group name, as in the following example, the Help Compiler places the topic in a “null” list: Window Menu - 120 Note The numbers used in the browse sequence example begin at 005 and advance in increments of 005. Generally, when using numbers in order strings, it is good practice to skip one or more numbers in a sequence so that, if necessary, you can add new topics later. Skipped numbers are of no consequence to the Help Compiler; only their order is significant Order strings establish the order of topics within a browse group. Order strings can consist of any alphanumeric characters. During the compiling process, strings are sorted using the ASCH sorting technique, not a numeric sort Both the group and order portions of a sequence can be several characters long, If you use only numbers in the order strings, make sure the strings are all the same length; otherwise, a higher sequence number could appear before a lower one. For example, the number 100 is numerically higher than 99, but 100 will appear before 99 in the sort used by Help, because Help is sorting by ASCII value. To keep the topics in their correct numeric order, make 99 a three-digit string: 099. To browse through the topics in alphabetical order by title, use the topic title as the order string.36 Help Compiler Guide Note If you use only letters in the order strings, make sure you use all uppercase or all lowercase letters; otherwise, they won't appear in alphabetical order. For example, “Time Series” appears before “Timer” because “S” is uppercase, even though “r” comes before “S.” Coding Browse Sequences After determining how to group and order topics, code the browse sequence by assigning the appropriate group name and order string to each topic. To assign a browse sequence code to a Help topic 1. Place the insertion point to the left of the topic heading, 2. Insert the plus sign (+) as the footnote reference mark. Note that a superscript plus sign (*) appears next to the heading. 3. ‘Type the group name, a colon, and the order string as the footnote, (Remember that a group name is optional.) The following footnote defines the browse sequence number for the Edit menu topic in the preceding browse sequence example: * commands :010 Assigning Build Tags Build tags are strings you assign to a topic that the Help project file can specify to include or not include in a build, Build tags can be made up of any alphanumeric characters and are not case-sensitive. A tag may not contain spaces within the string. You can specify multiple build tags by separating them with a semicolon @). Each topic can have one or more build tags. Build tags are not a necessary component of your Help system; however, they do provide a means of supporting different versions of a Help system without having to create different source files for each version. Topics without build tags are always included in a build, along With all tagged topics not expressly excluded from that particular build in the build expression. You insert build tags as footnotes, using the asterisk (*), When you assign a build- ag footnote to a topic, the Help Compiler includes or excludes the topic according to information specified in the BUILD option and [BUILDTAGS] section of the Help project file. For information about the BUILD option, the [BUILDTAGS] section, and the Help project file, see Chapter 6, “Building the Help Files.”Chapter 3 Creating the Topic Files 7 > To assign a build tag to a Help topic 1. Place the insertion point at the beginning of the topic heading line, so that it precedes all other footnotes for that topic Insert the asterisk (*) as the footnote reference mark. Note that a superscript asterisk (*) appears next to the heading. 3. Type the build-tag name as the footnote. Be sure to allow only a single space between the asterisk (*) and the build tag: * AppVersioni; AppVersion2; Test Build Note All build tags must be declared in the Help project file The Help Compiler includes topies that do not have a build-tag footnote in alll builds, regardless of the build-tag expressions defined in the Help project file. For this reason, you may want to use build tags primarily to exclude specific topics from certain builds. If the Help Compiler finds any build tags not declared in the Help project file, it displays an error message. By allowing conditional exclusion of specific topics, you can create multiple builds using the same source files. This saves the Help writing team time and also allows you to maintain a higher level of consistency across your product lines. Linking Topics with Jumps and Pop-Up Windows The context strings you code in the topics of a topic file give you a way to link those topics together. Without linking, the topics in a Help file would be isolated islands of information; a reader would have no means to travel from one topic to another. Of course, keywords and browse sequences provide additional routes through the topics in a Help file. But the most convenient way of linking topi to create hot spots that enable readers to jump between topics or display a pop-up window. Jumps Between Topics Jumps between topics in the WinHelp application serve a purpose similar to cross-references in a book. These jumps consist of specially coded text or graphics that cause the WinHelp application to display another topic in the main Help window. Jumps appear underlined in the Help window, and green on color monitors, For example, the strikethrough text (double-underlined in Word for Windows) New Command appears as New Command in green text to the user.Help Compiler Guide > To code a word or phrase as a jump in the topic file 1. Place the insertion point at the place in the text where you want to enter the jump term. 2, Select the strikethrough (or double-underline) feature of your editor 3. Type the jump word or words in strikethrough mode. 4, Turn off strikethrough and select the editor’s hidden text feature. Type the context string assigned to the topic that is the target of the jump. When coding jumps, keep the following in mind: = No spaces can occur between the strikethrough (or double-underlined) text and the hidden text. = Spaces before or after the jump term are not permitted. = Be careful not to format paragraph marks accidentally as hidden text. Figure 3.2 shows a topic in the IeonWorks Help file with jumps to other topics defined, Gn View _Insert Table Window Help 3) GE} 4 ‘tone ews bre) IeonWarks Help Cont ' The Centers as Heb tepcs veal lero, Usethe clos oni a cue vide potent Toleumhowto vest. pss Fo choose ang Hep ham he Heber : Ears OXTOR. COMMAS Sataabggeb om sevecanne Eoredasitbtron Ppacst + ‘ amet viewer. COMMA Jump Samataavewen KevEnSAO® text) easusivewtn recon nnn susietiniaszanon ies "ane eanwhaing) Editor Commands and Tootet Taw ma shah th pct otf vind jou wart orem mere abot 9 [sc Tal & Tee Context sting ofthe destination topic Figure 3.2 IconWorks Help topic with jumps definedChapter 3 Creating the Topic Files 39 dumps to Topics in Another Help File ‘The Help system you design may consist of more than one Help file. In these cases, you may want to jump from a topic in one Help file to a topic in another Help file. By providing extra information in the hidden text of the jump code, you can jump between Help files. Use this syntax to create jumps between Help files: Lump texicontextstring@d:\path\file. hip The double-underlined text is the hot spot clicked by the reader to jump to the new topic. The remaining text in the syntax is formatted as hidden text. As with a jump to another topic in the same Help file, the context string of the new topic immediately follows the hot spot text. To jump to another file, follow the context string with the @ symbol and then the path and file name of the Help file containing the new topic. You can provide just a file name if you want to use a relative path. If you create jumps from one Help file to another, keep in mind that when the user jumps to a different file, the only way to return to the first Help file is by using the Back button, the History list, or through an explicit jump that calls the first file. (The Contents and Browse buttons work only within the confines of the current Help file.) Jumps to a Secondary Window When you create a jump to another topic, the WinHelp application assumes you want to display the topic in the main Help window. But you can code the jump to display the new topic in a secondary window. Use this syntax to code a jump that displays a topic in a secondary window Lump textcontextstring>windowname The syntax is similar to the syntax used to jump to a topic in another Help file Immediately following the context string of the new topic is a greater than (>) sign followed by the name of the secondary window. See “Defining Window Attributes” in Chapter 6, “Building the Help Files,” for more information about defining names for secondary windows. Combining Jumps You can combine a jump to a topic in another Help file and a jump to a secondary window using this syntax: Lump textcontextstring @ d:\pathyfile.hlp>windowname40 Help Compiler Guide Jumps to Pop-Up Windows ‘Some topics contain words or phrases that may be unfamiliar to the user. To get the definition of a word or phrase, the user selects the word and then clicks the mouse button or presses the ENTER key, causing the definition to appear in a pop- up window within the Help window. You decide which words to define considering the audience that will be using your application and the terminology that may be new or specific to the application. Note Pop-up windows need not be limited to definitions, although it’s important to keep the text brief, since the main purpose of a pop-up window is to display definitions or notes that don’t distract the reader from the main topic. For the same reason, pop-up windows should not include information the user needs to do the task at hand. ing a term requires that you: = Create a topic that defines the term. The definition topic must include a context string. See “Coding Context Strings” earlier in this chapter. = Provide a jump for the definition topic where you want the definition to appear. See the following section, “Creating Definition Topics.” Creating Definition Topics Definition topics are created just like any other topic, although you probably won't provide search access with keywords To create a definition topic 1. Place the insertion point where you want to place the term that requires definition. 2. Select the underline feature of your editor. 3. Type the term. 4, Turn off the underline feature, and then select the editor's hidden-text feature. 5. Type the context string assigned to the topic that contains the definition of the term.Chapter 3. Creating the Topic Files a Figure 3.3 contains the definition of hot spots that display a pop-up window and one of the topics. Pop-up text Context string of the pop-up topic Tne Taols Table _ Window Help 2 ils) 9} aT eas peruto ress me Stan fis : + Tbncbukt too) sndsSTATUS JON BLES (brcbuletbne) Hausen sly TATUS MOUSE POSE (tre buettop) Undone TATUS UNDO. JCONTY fPectetine) —— Mauedutoacnaa alle HOUSE RUTTONSY icon Boxes Pop-up {Pelt teint crore kent The-cntnes seve ior es topic ‘bme be te) Display icone cpantot ein. casks can ad upto sitions a one ne au on spenkonby aogpngtien fam re Veet Sv uporgthaneca fac Ices cater sdectedcmn nth ouwe tener Daina ss eo coe tara eee t EEE SEMIS tate petbiid —LesngTmaoM toners duet | “sede # Daadutsrarus.oonn Figure 3.3 Pop-up window hot spots and topic Creating a Nonscrolling Region Ifa topic contains more text or graphics than will fit in the main Help window, the WinHelp application provides scroll bars to let the reader scroll through the information. By default, all text and graphics scroll when the scroll bars appear. But you can have certain text or graphics that you want to remain in place while the rest of the topic scrolls, You can create a nonscrolling region to contain information that you don’t want to scroll. ‘The nonscrolling region always appears at the head of a topic, When the reader scrolls the topic, only the information below the nonscrolling region scrolls. You can place text and graphics in the nonscrolling region. The text and graphics can contain hot spots to jump to other topics, display a pop-up window, or run a Help macro.2 Help Compiler Guide The default appearance of the nonscrolling region is a white background separated from the scrollable region by a black line. You can change the background color of the nonscrolling region by creating a definition for the main window in the Help project file. See “Defining Window Attributes” in Chapter 6, Building the Help Files.” Figure 3.4 shows the nonscrolling region in a topic in the IconWorks Help file. Notice that it contains both text and graphics as well as a different background color. Nonscrolling region 5 Pi Edit Bookmark Help. | | 8 Editor: Edit Menu ‘Undo “Thi commend removes any changes tem the isn since the te you changed editing tals or selected enotiericon_ Once you selec e new oa) or another icon rom he Sinus Area the Undo ‘commend cannotremeve he ckenges medo nthe eding ea. The Undo icon buton nthe Stas fea cisploys te condton he icon wil uno you sslectthe Undo commend cut “This command copiesthe pation ofthe ading alae you selactothe Clipboard and clears the || selected area tote curemt scrasn colar The Cut command does not work you move the pot the con you selectbelore cating You mustroselect te area you wantto cuthen usethe Cut commend. copy “Ths command cops the povion a heeding erea you select the Cippoard. The eding areas hotafected The Copy eorinnand does nator you give the pet oMhe cony/aueelectBetor= ‘omyingst Youmustreselectihe area you wentta Gathen use he Copy commend Paste “This command ince the contents of he Cipboard es @ selected group of pis inthe upper comer of he edting erea, You cen then move the selected pals anywhere nthe edna aes before pacing thm inthe curentican, Te pasta the eelecson into he icon, cick he mouse envhre [af Figure 3.4 Nonscrolling region in the IeonWorks Help file ‘The nonscrolling region is useful for displaying information that you don’t want users to lose when they scroll the file. For example, the topic from the IeonWorks Help file shown in Figure 3.4 contains the title of the topic. When the user scrolls to read the entire topic, the title always remains in viewChapter 3. Creating the Topic Files 43 > To create a nonscrolling region in a topic 1. Select the paragraphs that belong in the nonscrolling region. The nonscrolling region must be the first paragraphs in the topic. Format the selected paragraphs with a “Keep With Next” paragraph attribute See the documentation for your editor or word processor to determine how to apply this attribute. If you want to change the background color of the nonscrolling region, define the nonscrolling colors in the [WINDOWS] section of the Help project (.HPJ) file45 CHAPTER 4 Creating Graphics for Help ‘You can increase clarity and add interest to a Help system by using graphics. This, chapter describes some easy ways to add graphic images to Help files Contents = Graphics Formats = Adding Graphics to Topic Files = Creating Hypergraphies = Creating Multiple Resolution Bitmaps Graphic Formats You can include four types of graphics in your Help system. The following table describes each type. Graphic format Description Bitmap A bitmap defines an image as a pattern of dots (pixels). A bitmap has the file extensions BMP or .DIB. Also called paint-type or raster graphics. Metafile A metafile defines an image as coded lines and shapes. A metafile has the file extension .WME. Only files that are compatible with Microsoft Windows version 3.0 of later ¢ be included in the Help file, Also called draw-type or ve graphics. Hypergraphie A bitmap or metafile to which you add hot spots with the the Hotspot Editor (SHED.EXE). A hypergraphie has the file extension SHG. Muhiple-resolution A bitmap compiled from several bitmaps with different bitmap sereen resolutions by the Multiple Resolution Bitmap ‘Compiler (MRBC.EXE). A multiple-resolution bitmap has the file extension MRB.Help Compiler Guide iphics incorporated in the WinHelp application must use one of these four formats. ‘The WinHelp application limits paragraphs (text plus graphics) to 64K in size. If possible, avoid creating large graphics or including large graphics in the same paragraph with text Note This chapter assumes you' ve already identified or prepared the images you want to include in your Help system. If you need information about preparing graphics, see the documentation for the graphics application you are using. Be sure to follow those guidelines when creating graphics for Help files. Creating Bitmaps Each bitmap you create must be saved as a separate file. This section assumes that your bitmaps have 16 or fewer colors. If you don’t use Microsoft Paintbrush™ to create your bitmaps, the color palette in your paint program should have no more than 16 colors. Create bitmaps in the same screen resolutions (EGA, VGA, VGA+, or 8514) that you want the WinHelp application to use when it displays the topics that contain the bitmaps. If you plan to use the Help file at only one screen resolution, you can create bitmaps for that resolution only. With the Multiple Resolution Bitmap Compiler (MRBC.EXE), you can create a single bitmap file that displays correctly at more than one screen resolution, See the section, “Creating Multiple Resolution Bitmaps,” later in this chapter for more information about creating multiple-resolution bitmaps. Creating Metafiles Using metafiles for graphics can result ina smaller Help file size than using bitmaps, because metafiles are typically much smaller files than bitmaps. Metafiles are device independent and therefore do not have to be created for different display resolutions as bitmaps do.Chapter 4 Creating Graphics for Help a7 The WinHelp application can use metafiles created by most drawing applic including CorelDRAW! and Micrografx Designer™. Metafiles created by some drawing applications do not strictly adhere to the Windows metafile format. Such metafiles do not display correctly in the compiled Help file. If you are not sure whether a metafile will display correctly in your Help file, open the metafile in the Hotspot Editor (SHED.EXE). If the metafile is displayed correctly in the Hotspot Editor, it will be displayed correctly in a compiled Help file. Adding Graphics to Topic Files ‘There are two methods for including graphics in a Help file: = Place the bitmap or metafile directly in the topic file. —Or- * Place a bitmap or metafile reference in the topic file. Each of these methods has advantages and disadvantages. Use the following information to help you decide which method to use when including graphics in your Help file Including Graphics Directly The easiest way to place a graphic into a Help topic file is to import the graphic or metafile directly from the Windows Clipboard into Word for Windows. Then you can paste the graphic where you want it to appear in the Help topic file. You can format your text so that it is positioned below or alongside the graphic. When you save the Help topic file in rich-text format (RTF), the pasted bitmaps and metafiles are automatically included in the Help file. Note Word for Windows allows you to include bitmaps or met the Help topic file. s directly inHelp Compiler Guide Figure 4.1 shows a topic from the IconWorks Help file with a bitmap pasted directly into the Help topic file. 5 Tools Table =n ma 1) 2s) aes) 1H ise anks ne) Editor Defining Colors 1 aie cousin he Calon Cola Pate hou. Te open th into Cab alt, dole ‘eksge Cols Pactom fot or ot see! he Gone emma! one Cok mee, Meer he Eat vad aes aes Gano Car ae ron 8 Sl ‘AT C= ICE Cae] Eaospmcavacs — tims we coucodal Gl aeen(GandtivelBlekaens these denetshase ates — Figure 4.1 A map pasted directly into a topic file Advantages These are the advantages of including graphics directly in the Help topic file: = You can see th raphic whenever you work in the Help topic file: = You don’t have to enter the graphic location in the Help project file. Disadvantages ‘These are the disadva ages of importing graphics directly into a Help topic = You can use only Word for Windows to author topic files. = You can use only inline graphics (those treated the same as a character). This limits the ways you can display text and graphics in your Help file. For example, you cannot wrap text around an inline graphic. © Graphics inserted in a Word for Windows document increase the time needed to scroll or save the topic file. * You modify it in you Windows. not change the graphic inside Word for Windows. Instead, you must aphics application and then reimport it into Word forChapter 4 Creating Graphics for Help 49 = You cannot paste hypergraphics (graphics created with the Hotspot Editor) in topic files. = Including the same graphic directly at multiple locations in the topic file adds multiple copies of the graphic to the compiled Help file, thus increasing its size. Including Graphics by Reference To insert a graphic into a topic by reference, you include special text that tells the WinHelp application the name of the bitmap file or metafile and how to position it with respect to text, To position a graphic by reference, make the following changes to the topic and project files: = Enter the reference text in the topic file where you want the graphic to appear. = Enter the location of the graphic file in the Help project (.HPJ) file. Figure 4.2 shows a topic file from the IconWorks Help file with several bitmaps included by reference. Bitmap references The conan te mend coon he bs Het ode 9 +1 oc cnmks toe) Editor Status Areast Uewnyournsce te Eterna moves ane Ham he Ico mole deo hem lero cel ce ors apn een ‘rnaghlattnn evrdon Th oie Sas tea eae Sa clay th snc Doce, neces yo och ‘eratoresply Sas Sa 8 : Tes + fhe bette) oni STATUS CON BONES [ome deterp) Maan Talus MOUSE POS (ietuettee) — Ualemedapatarus N00. CON Mase Buu crs a3, MOUSE_BUTTONSY Nes conor skconbuves, The em bates eve tefl es Figure 4.2. Bitmaps included by reference in a topic file50 Help Compiler Guide Advantages These are the advantages of including graphics y reference: * You can author your Help file with any text editor that produces RTF files. = You have the widest range of options for displaying text and graphics in your Help file. For example, you can treat the graphic as a character, or you can \wrap text around the left or right edge of the graphic. = You can change the graphic as often and as much as you like without having to reimport it into the Help topic file. The references are pointers to the graphic files. The Help Compiler inserts the actual graphics only when you compile the Help file. = You can use hypergraphies (created with the Hotspot Editor) in your topie files. Hypergraphics can be included only by reference = Including the same graphic by reference at multiple locations in a topic file adds only one copy of the graphic in the compiled Help file Disadvantages These are the disadvantages of including graphics by reference: = You can’t see the graphic when you work in the topic file. = You have to enter the locations of the graphic files in the Help project file Although this is a very simple task, any mistakes will cause errors when you compile the Help file. Creating a Graphic Reference Use the following syntax to create references to graphics not directly included in a topic file: {command filename} The following table lists the three commands you can use in a graphic reference. Command Description bine Aligns the graphic in the topic as a character. The compiled Help file contains a single copy of the graphic data separate from the text bmi Aligns the graphic at the left margin; text wraps along the right edge of the graphic. The Help file contains a single copy of the graphic data separate from the text. bmr Aligns the graphic at the right margin; text wraps along the left edge of the graphic. The Help file contains a single copy of the graphic data separate from the text.Chapter 4 Creating Graphics for Help 51 The filename given in the graphic reference includes only the file name, not the full path of the file. The Help project (.HPJ) file contains all the path information for graphics included by reference. Aligning Graphics as Characters ‘The Help Compiler treats a graphic inserted with a bme reference as a character. After compiling the Help file, graphics aligned as characters appear on the baseline of the type at the location of the reference command. Because the graphic is positioned as text, any paragraph formatting applied to the paragraph also applies to the graphic. Text appearing above and below the graphic does not wrap around the graphic, but the size of the graphic may increase the line space between the line containing the graphic and the preceding line in the text. Note Don’t specify negative line spacing for a paragraph that has a bme graphic reference. If you do, the graphic might appear on top of the paragraph when the WinHelp application displays the topic. One good use of a graphic as a character is a bullet or other special symbol that appears in the text. The IconWorks Help file uses a small bitmap (BULLET.BMP) for the bullet in bulleted lists: {bme bultet.bmp} Indicates the current icon with a square border. {bme bullet.bmp) Displays the actual size of the icons being edited Aligning Graphics at the Left Margin The Help Compiler places a bml graphic along the left margin. Text wraps automatically along the right edge of the image. Text is aligned with the upper- tight corner of the graphic, so any white space saved at the top of the affects the way text appears in relation to the graphic. Placing the Reference at the Beginning of a Paragraph Normally, bmi references should be placed at the beginning of a paragraph. This ensures proper wrapping of text around the right edge of the graphic. The following example shows a typical bmi reference: {bm] name.bmp}Paragraph text follows the bitmap reference... Note Do not put any space characters between the bmi reference and the paragraph text unless you want the first line of text to appear indented from the rest of the text that wraps along the right edge of the graphic.52 Help Compiler Guide Placing the Reference at the End of a Paragraph You can also put a bl reference at the end of a paragraph, as shown in this example: ss-Paragraph text precedes the bitmap reference. (bml name. bmp) When you code a bmi reference this way, WinHelp wraps the text up to the end of, the paragraph, and then displays the graphic. After you compile the Help file, the graphic appears under the text and to the left Aligning Graphics at the Right Margin ‘The Help Compiler places a bmr graphic along the right margin. Text automatically wraps along the left edge of the image. Text is aligned with the upper-left corner of the graphic, so any white space saved at the top of the image fects the way text appears in relation to the graphic, Placing the Reference at the Beginning of a Paragraph Normally, bmr references should be placed at the beginning of a paragraph. This ensures proper wrapping of text around the left edge of the graphic. For example, the IconWorks Help file uses a bmr reference to display a hypergraphic with the interface of the IeonWorks Editor window bmr iwedit.shg)Click the part of the Editor window you want to know > more about. Note Do not put any space characters between the bmr reference and the paragraph text unless you want the first line of text to appear indented from the left margin of the topi Placing the Reference at the End of a Paragraph You can also put a bmr reference at the end of a paragraph, as in this example: -.Paragraph text precedes the bitmap reference. (bmr name.bnp} When you code a bmr reference this way, WinHelp wraps text up to the end of the paragraph, and then displays the graphic. After you compile the Help file, the graphic appears under the text and to the right. Using Graphic References as Hot Spots ‘You can do more with graphics in your Help file than simply display them. The WinHelp application allows you to use graphics as hot spots. This means you can use graphics, such as icons or buttons, as jumps to particular topics or as hot spots for pop-up windows or Help macros.Chapter 4 Creating Graphics for Help 53 > To code a graphic reference as a jump or hot spot for a pop-up window 1. Enter the graphic reference (bme, bmi, or bmr) in the topic where you want the jump. at the place Be sure you have already created the topie (and its context string) that will appear in the pop-up window. Select the entire graphic reference, including the file name and opening and closing braces. 3. Format the graphic ret —0r- Format the graphic reference as underlined text to create a hot spot for a pop- up window nce as double underlined text to create a jump. 4, Type the context string of the destination topic for the jump immediately following the graphic reference. 5. Format the context string as hidden text > To code a graphic reference as a hot spot for a macro 1. Enter the graphic refer want the macro. ‘nce (bme, bml, or bmr) in the topic file where you Select the entire graphic reference, closing braces. \cluding the file name and opening and Format the graphic reference as double underlined text. 4. Immediately following the graphic reference, type an exclamation point (!) followed by the macro, with its parameters, that you want WinHelp to run When the user selects this hot spot. 5. Format the context string as hidden text. Creating Hypergraphics Multiple hot spots can make the graphics in your Help file more useful. The preceding section, “Using Graphic References as Hot Spots,” shows how to create a single hot spot in a graphic. To create more than one hot spot within a single graphic, however, you must create a hypergraphic54 Help Compiler Guide A hypergraphic is a graphic (bitmap or metafile) with embedded hot spots that users can click to: = Jump to another Help topic. = Display a pop-up window * Activate a Help macro. = Activate routines in external dynamic-link libraries (DLLs). Using the Hotspot Editor You create hypergraphics with the Hotspot Editor. This tool can open a bitmap (BMP), a device-independent bitmap (.DIB), or a Windows metafile (WMP), and add hot spots to the existing graphic, It then saves the graphic as a hypergraphic (SHG) file. Because the Hotspot Editor is not a drawing or painting program, you must create the actual graphic outside the Hotspot Editor, Once you save a graphic as a hypergraphic using the Hotspot Editor, you cannot open the graphic again with a drawing or painting program. > To create a hypergraphic 1. Open a bitmap or metafile in the Hotspot Editor. 2. Draw hot spot locations in the graphic. 3 Define attributes for each hot spot in the graphic. - Save the graphic as a hypergraphic. Once you define the hot spots, the graphic is ready to be included in topic files for compiling into a Help file. The Hotspot Editor will load any Windows bitmap (.BMP) or device-independent bitmap (.DIB) created by a Windows-based draw or paint program, such as Windows Paintbrush. If you are using Windows Paintbrush, you can save the image file in one of the following formats: = Monochrome bitmap = 16-color bitmap = 256-color bitmap = 24-bit bitmap The Hotspot Editor also works with metafiles (WME) that are compatible with Windows 3.0 or higher.Chapter 4 Creating Graphics for Help 55 The Hotspot Editor Window Because the Hotspot Editor is a multiple-document interface (MDI) window, you can edit several graphics at the same time. Each graphic you open appears in a separate document window. The status bar at the bottom of the Hotspot Editor window displays brief descriptions of the currently selected menu or command as well as attribute information for the currently selected hot spot. Figure 4.3 shows the Hotspot Editor window Edit Window Help Figure 4.3 The Hotspot Editor window When you select a hot spot, the status bar displays the following information for that hot spot: = Context st + Binding type = Binding attribute = Hot spot identifier * Bounding box coordinates Opening Graphics Before you can add hot spots to a graphic with the Hotspot Editor, create an image file and then open it in the Hotspot Editor. you must56 Help Compiler Guide > To open a graphic file in the Hotspot Editor 1. From the File menu, choose Open. The Open dialog box appears. If the file is in the current directory, select the file name in the Files list box. The current directory is shown below the Filename text box. Double-clicking the two periods [..] at the top of the Directories box shows the files and directories located one level closer to the root directory Or- If the file is not in the current directory, double-click the directory you want in the Directories box. Then select the name of the file in the Files box. The Hotspot Editor displays in the Files box only those files whose extensions match the supported file formats 3. Choose OK. Instead of using the Files and Directories boxes to open a file, you can type the complete path in the Filename text box and click OK. Figure 4.4 shows a captured screen imas in the Hotspot Editor. from the IeonWorks application opened Figure 4.4 A bitmap opened in the Hotspot EditorChapter 4 Creating Graphics for Help or The Hotspot Editor records the last four files you have opened. Their paths and file names appear at the bottom of the File menu. To reopen a file you have already opened in the Hotspot Editor, open the appropriate file name from the File menu. Adding Hot Spots to Graphics Afier opening a graphic in the Hotspot Editor, you can create hot spots that link to topics, pop-up windows, or macros. When you compile with the Help Compiler, the hot spots you define become part the completed Help file. A hot spot can be any rectangular area within the graphic. You draw hot spots on the graphic as you would draw a rectangle in a Windows-based drawing or painting program, > To draw a hot spot 1. Click the loc hot spot. jon on the graphic where you want to anchor one corner of the 2, Drag the mouse until the rectangle encloses the area you want to define as the hot spot The box stretches from the anchor point to the position of the mouse and expands and contracts as you move the mouse. 3. When you are satisfied mouse button. the size of the hot spot rectangle, release the After you release the mouse button, the hot spot rectangle displays eight sizing handles, indicating that it is the currently selected hot spot. You can use the sizing handles to resize the rectangle. The IconWorks application uses a hypergraphic in its Help file. This hypergraphic (IWEDIT.SHG) is a bitmap of the IconWorks Editor window. Figure 4.5 shows. the hot spots defined for the names on the menu bar of the IeonWorks Editor.58 Help Compiler Guide =[ file Eat Window Help lle ||Esit| View, [Tools| [Jeans [C Hot spots defined ||| formenus in the Menu Bar Figure 4.5 Hot spots defined in an TeonWorks hypergrap! Defining Hot Spot Attributes After creating a hot spot, you must define its attributes. These attributes for a hot spot determine what happens when a reader clicks the hot spot. After creating a hot spot, use the Attributes dialog box to define its attributes. The Attributes Dialog Box ‘The Attributes dialog box contains binding information for each hot spot you define. Figure 4.6 shows the Attributes dialog box. es ee) ee] ‘ion: [42—]botom [At Figure 4.6 The AttributesChapter 4 Creating Graphics for Help 59, ‘The following table describes the options in the Attributes dialog box. Field Description Context string Specifies binding information for the hot spot, in the form of either a context string or a macro. Type Indicates the type of action to be taken when the user selects the hot spot. You can define the hot spot to jump to another topic, display a topic in a pop-up window, or run a Help macro. Attribute Specifies whether the hot spot is visible or invisible in the Help window, Hot spots are always visible in the Hotspot, Exitor. Hotspot ID Specifies a unique identifier for the hot spot. The hot spot name is used intemally by the Hotspot Editor and helps you identify hot spots in the Select dialog box more easily. The Hotspot Editor automatically assigns an incremental number to the hot spot name; however, you can type in your own unique name. Bounding box Display the coordinates for the hot spot rectangle: left, right, coordinates top, and bottom. The coordinates are measured in pixels and are restricted to the size of the graphic image. To define attributes for a hot spot 1. Create the hot spot or select it. 2. Click the hot spot with the right mouse button to display the Attributes dialog box. 3. For a jump or pop-up window, enter the context string for the destination jump or pop-up window topic in the Context String box. Or- For a Help macro, enter the macro in the Context String box. (For more information, see Chapter 5, “Creating Help Macros.”) 4. Choose the type of hot spot you want to create from the Type list: Jump, Pop- up, or Macro. 5. Choose Visible or Invisible for the binding attribute. If you want to make the hot spot region visible to users, cl the Attribute list,60 Help Compiler Guide 6. If you want to change the default name assigned to the hot spot, edit the hot spot identifier. 7. If you want to change the size or location of the hot spot, edit the bounding, box coordinates. 8. Choose OK. The attributes defined for the hot spot now appear in the Hotspot Editor status bar. Selecting Hot Spots You must select a hot spot before you can move it, cut or copy it to the Clipboard, delete it, or modify its attributes. When a hot spot is selected, it displays eight handles, which you can use to resize the rectangle. To select a hot spot with the mouse, you can click the hot spot with the left mouse button or press TAB or SHIFT#TAB until you select the hot spot you want To select a hot spot using the Select command 1, From the Edit menu, choose Select. The Select dialog box appears. All of the hot spots defined for the hypergraphic appear in the Hotspots box. By default, the Hotspot Editor will not select a hot spot in the list box unless one is selected before you choose the Select command. Then the Hotspot Editor highlights the identifier of the currently selected hot spot. Select a hot spot name from the Hotspots box ‘The Hotspot Editor displays the binding information for the selected hot spot name. 3. Choose the Select button. The hot spot show: selected, eight sizing handles to indicate that the hot spot is For more information on the Select command, search for Sefect in the Hotspot Editor Help,Chapter 4 Creating Graphics for Help 61 Moving Hot Spots Resizing Hot After you create a hot spot, you can move it anywhere within the graphic. To move a hot spot 1. Select the hot spot. 2. Point to the center of the selected hot spot. The pointer changes to a hand pointer, indicating that the hot spot can be moved. 3. Press and hold down the left mouse button. The hot spot sizing handles disappear and the hot spot can be dragged to any location. 4. Move the hot spot to where you want it, and then release the mouse button. The sizing handles reappear to indicate the hot spot is selected, 5. Click the mouse button outside the hot spot to fix the hot spot in its new position, Note If the client area is the same size or larger than the image area, the Hotspot Editor will not allow you to move the hot spot outside the hypergraphic image area. If the client area is smaller than the image area (that is, the client area shows scroll bars), then the Hotspot Editor scrolls in the direction of the attempted move if a hot spot crosses the edge of the client area. Spots The eight sizing handles on a hot spot allow you to change the size of a hot spot the same way you change the size of a window. To resize a hot spot 1. Select the hot spot. 2. Point to the sizing handle on the border or corner that you want to change. ‘The pointer changes to a two-headed arrow 3. Drag the sizing handle until the rectangle is the size you want. If you drag a side handle, the rectangle changes size only on the side of the border you drag. If you drag a comer, the two adjoining sides that form the corner change size at the same 4. Release the mouse button.62 Help Compiler Guide Setting Preferences Whenever you define a hot spot, the Hotspot Editor uses the binding information and hot spot identifier stored in the Preferences dialog box (Preferences command, Edit menu). Figure 4.7 shows the Preferences dialog box. a as ‘ye (tno [a] Avan re] | [Coes] Hotspot [Hotpot Figure 4.7 The Preferences dialog box If you want to change these default values, you can edit them. Setting your own preferences for hot spot attributes can save you time and effort when creating hypergraphics that require settings different from the Hotspot Editor's internal defaults, The following table shows the default settings for each of the Preferences options. Field Default entry Context string Empty Type Jump Attribute Invisible Hotspot ID Hot spot > To change the Hotspot Editor preferences 1. From the Edit menu, choose Preferences, 2. Type a context string or macro in the Context String box. The context string you enter will be the binding string for every hot spot created with this preference. 1. Choose the binding type. Choose Visible or Invisible for the binding attribute. Enter a hot spot name ‘This entry affects only the hot spot name. The Hotspot Editor will continue to assign numbers incrementally to each new hot spot created, 4. Choose OK. ‘The Hotspot Editor assigns the attributes you entered to subsequent hot spots created with these preferences.Chapter 4 Creating Graphics for Help 63 Creating Multiple Resolution Bitmaps When the WinHelp application displays bitmaps, it must first determine whether the bitmap file contains resolution data about the bitmap image. If the file does contain resolution data about the image, WinHelp either displays the bitmap at the current display resolution, if the display and bitmap resolution match, or the application resizes the bitmap to match the resolution of the display. If the bitmap file doesn't contain resolution data, WinHelp uses the default resolution for VGA display resolution, If the resolution of the bitmap does not match the resolution of the display monitor, or if WinHelp must stretch a bitmap to display it, the bitmap doesn’t appear as it did when it was created. To compensate for differences between the resolutions of bitmaps and the display, use the Windows Multiple Resolution Bitmap Compiler (MRBC). ‘The MRBC lets you create bitmaps with different resolutions (CGA, EGA, VGA. or 8514) and combine them into a single graphic that can be compiled into a Help file. When the WinHelp application encounters a multiple-resolution bitmap, or an MRB file created by MRBC. it cycles through the stored resolutions and selects the bitmap that most closely matches your display. MRBC supports CGA, EGA, VGA, and 8514 resolutions. Note The .MRB output file cannot be edited or viewed by using any existing graphics program and therefore has no value outside the WinHelp application. Including .MRB Files in a Help File You include .MRB files in a Help file by referencing them in an RTF source file. The syntax for an .MRB bitmap reference is the same as for other bitmaps, Bitmap type Source file syntax Inline MRB bitmap (bme bitmap.mrb) Left-aligned .MRB bitmap (bt bitmap.mrb) Right-aligned .MRB bitmap (bme bitmap.mrb)64 Help Compiler Guide Using MRBC MRBC can be run from the command line in either of two modes: interactive or silent. Interactive mode is used when input is wanted or required. Silent mode is used for batch processing and automated builds. Use the following syntax for ‘compiling multiple-resolution bitmaps: ibe [/s] namel.bmp [name2.bmp...namen.bmp] The following table defines the parameters of this syntax. Parameter Defi ion is Specifies silent mode. Ifthe /s switch is used, MRBC determines the resolution of each bitmap based on the first character of the bitmap extension. If the Js switch is not used, MRBC prompts the user for the resolution of each bitmap. name], name2..namen Specifies the names of the bitmaps to be included in the .MRB file. These files can be bitmaps, metafiles, or hypergraphies. Bitmap paths can be either relative or absolute, Relative paths are relative to the user's current directory The output file MRBC has the same file name as the first bitmap on the command line (NAME1.BMP) but with an .MRB extension. All output files are written into the current directory. Performing Preprocessing Checks Before starting the conversion process, MRBC performs certain preprocessing checks. First, it checks the existence and format of each bitmap listed on the command line. If any bitmap listed is not found or is in an invalid format, MRBC stops processing and displays an error message.Chapter 4 Creating Graphics for Help 65 Starting the Conversion Process If the command-line entry passes the two preprocessing checks without errors, the conversion process begins. If the /s switch is not used, you are prompted to give the monitor type for each of the bitmaps. In the prompt message, the bitmap names are displayed on the command line with no path, a relative path, or an absolute path. For example, if you type: mrbc c:\bitmaps\vga\menul .bmp :\bitmaps\ega\menu2. bmp and the preprocessing checks are passed successfully, MRBC displays the following messages: Please enter the monitor type for the bitmap Please enter the monitor type for the bitmap bi tmap\vga\menul .bmp :\bi tmap\ega\menu2. bmp You supply the appropriate response—VGA and EGA respectively. MRBC then creates the output file and writes it to the current directory Note The valid monitor types are CGA, EGA, VGA, and 8514. If you enter a monitor-type option that is not recognized, MRBC displays a warning message reminding you of valid entries for the monitor type. MRBC supports only these four monitor types. Atrun time, WinHelp selects the best possible bitmap for your display. In addition to resolution, WinHelp uses color as a selection criterion, Therefore, it is recommended that you include both color and monochrome bitmaps in the same MRB file to ensure compatibility with both monitor types. Note MRBC does not check for valid matches between bitmap resolution and the entered option. For example, if you enter VGA for an EGA graphic, MRBC accepts it and marks it as a VGA bitmap. When the bitmap is displayed on a VGA monitor, however, it will not appear as originally authored. For that reason, it is important to check .MRB bitmaps on the target monitors to ensure that they are correctly displayed.66 Help Compiler Guide Ifthe /s switch is used, the conversion process takes place without your input. Instead, MRBC uses the first character of the input file extension to determine the bitmap resolution, The following table shows how the extensions are mapped. First character Example MRBC interpretation c (bitmap.cbmy CGA bitmap, E (bitmap.cbm) EGA bitmap v (bitmap.vbm) VGA bitmap 8 (bitmap.8bm) 8514 bitmap other (bitmap.bmp) VGA bitmap For example, if you type: mirbe /s house.vga house.ega house.cga house. 8xx MRBC will create an MRB file named HOUSE.MRB that consists of VGA, EGA, CGA, and 8514 bitmaps. Note As in interactive mode, MRBC does not check for valid matches between bitmap resolution and the entered option. It is your responsibility to match the correct extensions with the correct display resolutions. In both interactive and silent modes, MRBC accepts the asterisk (*) and question mark (?) as wildcards for the file names. In some cases, the drawing tool that creates bitmaps stores the resolution in the bitmap file. MRBC checks all bitmap files to determine whether the resolution is specified. If MRBC finds the resolution specified in the bitmap files, it uses the resolution you specify instead of the existing graphic resolution, and then displays an informative warning message. This warning message appears only when the conversion is performed in interactive mode.67 CHAPTER 5 Creating Help Macros This chapter describes each of the Windows Help (WinHelp) macros, which you can use to customize the way the WinHelp application works with your Help files, Contents = Running Help Macros = Rules for Coding Help Macros = Using DLL Calls as Help Macros = Macro Command Reference = Virtual-Key Codes Running Help Macros WinHelp macros allow you to customize your WinHelp application. You can add and remove custom buttons and menus, change the function of buttons and menu items, execute applications from within Help, and execute functions from external dynamic-link libraries (DLLs). For example, the lconWorks Help file contains macros that add a Glossary button to the toolbar of the main Help window. When the user clicks the Glossary button, the glossary topic appears in a secondary window Help macros can be run = When WinHelp first opens a Help file. When the user selects a particular topic in the Help file. * When the user chooses a button, menu item, or hot spot containing a macro.68 __Help Compiler Guide Running Macros When Opening a Help File Ifa macro appears in the [CONFIG] section of the Help project file (HPI), WinHelp runs that macro when it first runs the Help file. If there is more than one macro listed in the [CONFIG] section, WinHelp runs them in the order in which they are listed. The [CONFIG] section of the Help project file for the IeonWorks Help file contains two macros: cBi"g) ossar: BrowseButtons() "RGlossary", IC iconwrks hip>glossary", *GLOSSARY*)") The first macro defines a new button called Glossary in the toolbar; when clicked, this button displays the glossary topic in a secondary window. The second macro places the buttons that control browse sequences in the toolbar. Note WinHelp version 3.1 doesn’t automatically provide Browse Forward (>>) and Browse Back (<<) buttons. If your Help file includes one or more browse sequences, you must use the BrowseButtons() macro so the user can move forward or backward. See “Customizing Help” in Chapter 6, “Building the Help Files,” for more information about coding a Help macro in the Help project file. Running Macros When a User Enters a Topic Ifa Help macro is authored in a topic footnote, WinHelp runs that macro automatically whenever the user jumps to the topic. Macros that control Help buttons, menus, or menu items remain in effect until the user quits WinHelp or opens a new Help file. A user can jump to a topic by = Clicking a jump to the topic. = Clicking the Back button or a browse button. = Selecting the topic from the history list or keyword search list. (For more information on how to use Help file menus, please see the Microsoft Windows User's Guide.)Chapter 5 Creating Help Macros 69, Running Macros From a Hot Spot Help macros can also be run from hot spots within a topic. WinHelp runs a hot spot macro whenever the user chooses the hot spot containing that macro, WinHelp continues displaying the topic while it runs the macro, unless the macro causes a jump to another topic. A hot spot containing a macro is formatted like any other hot spot. The text or bitmap reference used for the macro is formatted as double-underlined text, and the maero (preceded by an exclamation point) is formatted as hidden text. See “Linking Topics with Jumps and Pop-Up Windows” in Chapter 3, “Creating the Topic Files.” for more information about coding jumps in a topic. Rules for Coding Help Macros Authors must follow these rules when coding Help macros: = Macros are not case-sensitive, so you can type the macro using the capitalization shown in the reference or any other capitalization convention you choose. = Separate each macro in a string by a semicolon(:) if a single macro string may include more than one Help macro. = Specify empty spaces in a macro string by placing the surrounding text in quotation marks. = Insert special characters in a quotation-marked string prefaced by a backslash. Special characters include double quotation marks ("), opening and closing single quotation marks (* ), and backslashes (\). Note The single opening quotation mark is different from the single closing quotation mark. The single opening quotation mark (*) is paired with the tilde (~) above the TAB key on extended keyboards; the single closing quotation mark (’) is the same as the apostrophe.70 Help Compiler Guide * Quotation marks may be either matching double quotation marks or a pair of single opening and closing quotation marks, You cannot use double quotation marks inside a string already enclosed in double quotation marks. Use single opening and closing quotation marks instead. For example, CreateButton( {me btn”, "ATine™, “ExecPragram(“clock”, 0)") is invalid because the string cock uses double quotation marks within the double quotation marks used for the ExeeProgram macro. The following example corrects the error by enclosing ¢1ock in single quotation marks: CreateButton(™time_bti a") » "BTime", "“ExecProgram( “clock = Macros may be included within other macros. In other words, a macro can be used as a parameter value for another macro. = As \gle macro must be 512 or fewer characters in length. Using DLL Calls as Help Macros If you are a C programmer and have created a DLL for use with WinHelp, you can use calls to functions in the DLL as Help macros, provided you register the function in the Help project file. To register the DLL function, enter a WinHelp RegisterRoutine macro in the [CONFIG] section of the project file. ‘The RegisterRoutine macro has the following format: RegisterRoutine(“DLLname”, “functionname”, “formatspec") The DLLname is the file name for the DLL, and the functionname is the function you want to use as a Help macro. The formatspec is a string of format specifiers that give the formats of arguments to the function. WinHelp checks the format string to make sure it matches the function prototype defined in the DLL. (For a complete list of format specifiers and examples, see the RegisterRoutine macro later in this chapter.) In effect, the RegisterRoutine macro gives you the power to extend WinHelp with your own DLLs. Once you have registered a DLL function with WinHelp, you can create menu items or macro buttons that execute the function. In this way, you can offer specialized capabilities to users of your Help file that are not available in the standard WinHelp applicationChapter'5 Creating Help Macros n Macro Command Reference This section lists Help macros alphabetically and provides the following ‘information. Heading Information Macro Name of the macro and its abbreviation, lable, enclosed in parentheses. Use the abbreviation in place of the macro name in the syntax. Syntax ‘Syntax and parameters required for each macro, For information about the typographic conventions used in syntax descriptions, see “Document Conventions” in the Introduction. Parameters Descriptions of parameters to the macro. Example Example of the macro. Comments, Information about preferred or restricted uses for the macro. About Syntax Parameters Comments This macro displays the About Help menu) box (same as the About command on the About() None Use of this macro in secondary windows is discouraged.n Help Compiler Guide AddAccelerator (AA) Syntax Parameters Example Comments This macro assigns a Help macro to a shortcut key (or key combination) so that the macro is run when the user presses the shortcut key(s). AddAccelerator(key, shiftstare, “macro”) Argument Definition key ‘The Windows virtual-key value. For a list of the the section, “Virtual-Key Code: keys, see. * later in this chapter. shiftstate A number specifying the combination of ALT, SHIFT, and CTRL keys used with the shortcut key: 0 (none), 1 (SHIFT), 2 (CTRL), 3 (SHIFT+CTRL), 4 (ALT), 5 (ALT+SHIFT), 6 (ALTSCTRL), of 7 (SHIFT+ALT+CTRL) macro ‘The Help macro or macro string that is run when the user presses the shortcut key(s). The macro must appear in quotation marks. Multiple macros in a string must be separated by semicolons (;). The following macro starts the Windows Clock program (provided in Windows version 3.1) when the user presses ALT+SHIFT+CTRLHES: AddAccelerator(@x73, 7, "ExecProgram(*clock.exe’, 1)") ‘The Help macro that is run by Add Accelerator might not work in secondary windows, or its use may be discouraged if the macro it runs is prohibited or discouraged in secondary windows. Check the usage notes for the macro before using AddAccelerator to run it in a secondary window. Annotate Syntax Parameters Comments This macro displays the Annotation dialog box (s on the Edit menu). Annotate() ime as the Annotate command None Use of t is macro in secondary windows is discouraged. If the Annotate macro is run from a pop-up window, the annotation is attached to the topic that contains the hot spot to the pop-up window.Chapter 5 Creating Help Macros 73 Appenditem ‘Syntax Parameters Example Comments This macro appends a menu item to the end of a menu you create with the InsertMenu macro. Appendltem(“menuid”, “itemid”, “itemname”, “macro”) Argument Definition menuid ‘Name used in the InsertMenu macro to create the menu. ‘This name must appear in quotation marks, The new item is appended to this menu. itemiad ‘Name that WinHelp uses internally to identify the menu item. This name is case-sensitive and must appear in quotation marks, Use this name in the Disableltem or Deleteltem, you want to disable or remove the item, or change the operations that the item performs in certain topics. itemname ‘Name that WinHelp displays on the menu for the item. This name is case-sensitive and must appear in quotation marks. Within the quotation marks, place an ampersand (&) before the character used as the macro’s keyboard access key macro Help macro or macro string that is run when the user chooses the menu item. The name must appear in quotation marks. Multiple macros in a string must be separated by semicolons ©. The following macro appends a menu item labeled “Tools” to a menu that has an identifier “mnu_books” AppendItem(*nnu books", "mnu tools", "&Tools we “First_topic'y") "JIC tools.h1p* Choosing the menu item causes a jump to a topic with the context string “first_topic” in the TOOLS.HLP file. WinHelp ignores this macro it is run in a secondary window Make sure that the keyboard access keys you assign to menu items are unique. If you assign a key that conflicts with other menu access keys, WinHelp displays the error message, Unable to add item, and ignores the macro.a Help Compiler Guide Back Syntax Parameters Comments ‘This macro displays the previous topic in the Back list. The Back last 40 topics the user has displayed since starting WinHelp. t includes the Back() None WinHelp ignores this macro if it is run in a secondary window. If the Back m: cro is run when the Back list is empty, WinHelp takes no action BookmarkDefine Syntax Parameters ‘Comments This macro displays the Define dialog box (same as the Define command on the Bookmark menu), BookmarkDefine() None Use of this macro in secondary windows is discours If the BookmarkDefine macro is run from a pop-up window, the bookmark is attached (o the topic that invoked the pop-up window. BookmarkMore Syntax Parameters Comments This macro displays the More dialog box (same as the More command on the Bookmark menu). The More command appears on the Bookmark menu if the user has defined more than nine bookmarks. BookmarkMore() None Use of this macro in secondary windows is discouraged.Chapter 5 Creating Help Macros 5 BrowseButtons Syntax Parameters Example Comments ‘This macro adds the Browse Back (<<) and Browse Forward (>>) buttons to the toolbar in WinHelp. BrowseButtons() None ‘The following macros in the .HPJ file cause the Clock button to appear immediately before the two browse buttons on the toolbar: CreateButton("aclock”, “ExecPragram( clock", @) BrowseButtons() ) WinHelp ignores this macro if it is run in a secondary window. If the BrowseButtons macro is used with one or more CreateButton macros in the [CONFIG] section of the HP! file, the order of the browse buttons on the WinHelp toolbar is determined by the order of the BrowseButtons macro in relation to the other macros listed in the [CONFIG] section. Note WinHelp version 3.1 doesn’t automatically provide Browse Forward (>>) and Browse Back (<<) buttons. If your Help file includes one or more browse sequences, you must use the BrowseButtons() macro so the user can move forward or backward.76 Help Compiler Guide ChangeButtonBinding (CBB) Syntax Parameters Example Comments This macro assigns a Help macro to a Help button. ChangeButtonBinding; “buttonid”, “buttonmacro”) Argument Definition buttonia Identifier assigned to the button in the ereatebutton macro or, for a standard Help bution, one of the following predefined bution identifiers: btn_contents (Contents) btn_seareh (Search), btn_back (Back), btn_history (History), bin_previous (<<), or btn_next (>>). The button identifier must appear in quotation marks. butionmacro Help macro run when the user chooses the button, The macro ‘must appear in quotation marks. The following macro changes the function of the Contents button so that choosing it causes a jump to the Table of Contents topic (identified by the context string ct_contents”) in the DICT.HLP file: ChangeButtonBinding("btn_contents", “Jumpld(*dict.hip*. ‘ “dict _contents")") WinHelp ignores this macro if it is run in a secondary window.Chapter 5 Creating Help Macros 7 ChangeltemBinding (C18) Syntax Parameters Example Comments This macro assigns a Help macro to an item that you add to a WinHelp menu using the Appenditem macro. ChangeltemBinding(“itemid”, “itemmacro”) Argument Definition itemid Identifier assigned to the item in the AppendItem macro, ‘The item identifier must appear in quotation marks, itemmacro Help macro that is run when the user selects the item. The macro must appear in quotation marks. The following macro changes the menu item identified by “time_item” so tha arts the Windows Clock program: ChangeltemBinding("time_iten®, "ExecProgram(*clock’, @)") WinHelp ignores this macro if it is run in a secondary window CloseWindow Syntax Parameters Example ‘Comments This macro closes the specified window, which is either the main WinHelp window or a secondary window CloseWindow( “windowname") Argument Definition windowname The name of the window to close. The name “main” is reserved for the primary Help window. For secondary windows, the window name is defined in the [WINDOWS] section of the HPI file, This name must appear in quotation marks. ‘The following macro closes the secondary window “keys”: CloseWindow("keys”) If the window does not exist, WinHelp ignores the macro.78 Help Compiler Guide Contents Syntax Parameters Comments ‘This macro displays the contents topic in the current Help file. The contents topic is defined by the CONTENTS option in the [OPTIONS] section of the Help project file. Contents() None If the project file does not have a CONTENTS option, the contents topic is the first topic in the first topic file specified in the Help project file. CopyDialog Syntax Parameters Comments This macro displays the Copy dialog box (same as the Copy command on the Edit menu). CopyDialog() None Use of this macro in secondary windows is discouraged. CopyTopic Syntax Parameters Comments This macro copies all the text in the currently displayed topic onto the Windows Clipboard CopyTopie() None Use of this macro in secondary windows is discouraged. This macro copies text only; it does not copy bitmaps or any other images in the Help topic.Chapter 5 Creating Help Macros 79 CreateButton (CB) Syntax Parameters Example Comments This macro adds a new button to the WinHelp toolbar, CreateButton( “buttonid”, “name”, “macro") Argument Definition butioniad Name that WinHelp uses internally to identify the bution This name must appear in quotation marks. Use this name in the DisableButton or DestroyButton macro if you want to remove or disable the button, or in the ChangeButtonBinding macro if you want to change the Help macro that the button runs in certain topics. name The text that appears on the button. This name must appear in quotation marks. To designate a letter as a keyboard access key for this button, place an ampersand (8) before a letter in this text, The button name is case-sensitive and can contain up to 29 characters, beyond which the name is clipped. ‘macro Help macro or macro string that is run when the user chooses the button. The macro must appear in quotation marks. Multiple macros in a macro string must be separated by semicolons (:) The follo\ with the context string chosen: 1g macro creates new button labeled “Ideas” that jumps to a topic lirectory” in the IDEAS.HLP file when the button is CreateButton("btn_ideas”, “&Ideas", “Jumpld(“{deas.hip", “directory*) WinHelp ignores this macro if itis run in a secondary window. WinHelp allows a maximum of 16 authored buttons. It allows a total of 22 buttons, including the standard browse buttons, on the toolbar. If the BrowseButtons macro is used with one or more CreateButton macros in the [CONFIG] section of the .HPJ file, the order of the browse buttons on the WinHelp toolbar is determined by where the BrowseButtons macro is listed in relation to the other macros in the [CONFIG] sectior80 Help Compiler Guide Deleteltem This macro removes a menu item that was added using the Appendltem macro. ‘Syntax Deleteltem( “itemid”) Parameters Argument: Definition itemid ‘The item identifier string used in the Appendltem macro. ‘The item identifier must appear in quotation marks. Example The following macro removes the menu item “Tools” appended in the example for the AppendItem macro: Deleteltem("nnu_tools") Comments WinHelp ignores this macro if it is run in a secondary window DeleteMark This macro removes a text marker added with the SaveMark macro. Syntax DeleteMark( “markertext”) Parameters ‘Argument Definition markertext Marker text specified in the SaveMark macro. The marker text must appear in quotation marks. Example The following macro removes the marker “Managing Memory” from the Troubleshooting Help file: DeleteMark("Managing Memory”) Comments If the marker does not exist when the DeleteMark macro is run, WinHelp displays a Topic not found error message,Chapter5 Creating Help Macros at DestroyButton Syntax Parameters Comments: This macro removes a button added with the CreateButton macro, DestroyButton(“buttonid”) Argument Definition bustonid Identifier assigned to the button in the CreateButton macro, ‘The button identifier must appear in quotation marks. The button identifier cannot duplicate an idemtifier used for one of the standard Help buttons. (See the ChangeButtonBinding macro for a list of these identifiers.) WinHelp ignores this macro if it is run in a secondary window. DisableButton (DB) Syntax Parameters Comments This macro disables and dims a button added with the CreateButton macro. DisableButton(“buttonid”) Argument Definition buttonid Identifier assigned to the button in the CreateButton macro. The button identifier appears in quotation marks. WinHelp ignores this macro if it is run in a secondary window A button disabled by the DisableButton macro cannot be used in the topic until an EnableButton macro is run,2 Help Compiler Guide Disableltem (Dl) Syntax Parameters Comments ‘This macro disables and dims a menu item added with the Appendltem macro. Disableltem/“irenid") Argument Definition itemid Identifier assigned to the menu item in the Appenditem ‘macro. The item identifier must appear in quotation marks. WinHelp ignores this macro if itis run in a secondary window. A menu item disabled by the DisableItem macro cannot be used in the topic until an Enableltem macro is run. EnableButton (EB) Syntax Parameters Comments is macro re-enables a button disabled with the DisableButton macro. EnableButtony “buttonid”) Argument Defi buttonid Identifier assigned to the button in the CreateButton macro. ‘The button identifier must appear in quotation marks. WinHelp ignores this macro if itis run in a secondary window.Chapter 5 Creating Help Macros ES Enableltem (El) syntax Parameters Comments ‘This macro re-enables a menu item disabled with the Disableltem macro. Enableltem(“itemid") Argument Definition itemid Identifier assigned to the menu item in the AppendItem macro. The item identifier must appear in quotation marks. WinHelp ignores this macro if it is run in a secondary window. ExecProgram (EP) Syntax Parameters Example ‘This macro runs a Windows—based application ExeeProgram( “commandline”, displaystate) Argument Definition commandline ‘Command line for the application to be executed. The ‘command line must appear in quotation marks. WinHelp searches for this application in the current directory, followed by the Windows directory, the user's path, and the directory of the currently displayed Help file. displaystate ‘A value indicating how the application is shown when. executed. A value of 0 indicates normal, 1 indicates minimized, and 2 indicates maximized. normal window The following macro runs the Windows Clock program it size! ExecPragram("clock.exe", 0)4 Help Compiler Guide Exit Syntax Parameters This macro exits the WinHelp applica menu). tion (same as the Exit command on the File Exit() None FileOpen Syntax Parameters Comments This macro displays the Open dialog box (same as the Open command on the File menu) FileOpen) None Use of this macro in secondary windows is discouraged. FocusWindow Syntax Parameters Example Comments ‘This macro changes the focus to the specified window, which is either the main WinHelp window or a secondary window. FocusWindow( “windowname") Argument Defi jon windowname The name of the window to have the focus. The name “main” is reserved for the primary Help window. For secondary windows, the window name is defined in the [WINDOWS] section of the .HPJ file. This name must appear in quotation marks. The following macro changes the focus to the secondary window “keys” FocusWindow("keys”) If the window does not exist, WinHelp ignores the macro.Chapter 5 Creating Help Macros 85 GoToMark syntax Parameters Example This macro jumps to a marker set with the SaveMark macro. GoToMark(“markertext”) Argument Definition markertext Marker text specified in the SaveMark macro, The marker text must appear in quotation marks. ‘The following macro jumps to the marker “Mana Troubleshooting Help file: 12 Memory” in the GoToMark("Managing Memory") HelpOn Syntax Parameters This macro displays the Using Help file for the WinHelp application (same as the Using Help command on the Help menu). HelpOn() None History Syntax Parameters Comments This macro displays the Windows Help History window, which shows the last 40 topics the user has viewed since opening a Help file in WinHelp. Tt has the same effect as choosing the History button on the WinHelp toolbar. History() None WinHelp ignores this macro if itis run in a secondary window86 Help Compiler Guide IfThen syntax Parameters Example ‘This macro runs a Help macro if a given marker exists. It uses the IsMark macro to make the test. IfPhen(sMark(“markertext"), “macro”) Argument Definition ‘markertext Marker text tested by the IsMark macro, The marker text ‘must appear in quotation marks. macro ‘The Help macro or macro string that is run if the marker exists. The macro must appear in quotation marks. Multiple macros in a macro string must be separated by semicolons (;). The following macro jumps to the topic with the context string “man_mem” if a marker named “Managing Memory” has been set by the SaveMark macro: IfThen(IsMark("Managing Memory"), "J1(*trb.hip*, “man_mem*)") IfThenElse syntax Parameters Example ‘This macro runs one of wo Help macros, provided a marker exists. It uses the IsMark macro to make the test. IfThenElse(IsMark(“markertext”), “macrol”, “macro2”) Argument Definition markertext Marker text tested by the IsMark macro. The marker text must appear in quotation marks. macro}, macro2 WinHelp runs macro! if the marker exists and macro? if it does not, Both macros must appear in quotation marks, Multiple macros in either macro string must be separated by semicolons (). The following macro jumps to the topic with the context string “man_mem” if a marker named “Managing Memory” has been set by the SaveMark macro. If the marker does not exist, it jumps to the contents screen for the TRB.HLP file: IfThen€IseCIsMark("Managing Memory"), “JIC trb.np", “man_men*)", > “JumpContents(°TRB.HLP")")Chapter 5 Creating Help Macros 87 Insertltem Syntax Parameters Example Comments ‘This macro inserts a menu item at a given position on an existing menu. The menu can be either one you create with the InsertMenu macro or one of the standard WinHelp menus. Insertltem(“menuid”, “itemid”, “itemname”, macro”, position) Argument Definition menuid Either a standard WinHelp menu name or the name used in| the InsertMenu macro to create the menu. Standard menu names are mnu_file (File menu), mnu_edit (Edit menu), mnu_bookmark (Bookmark menu), and mau_helpon (Help menu). The menu identifier must appear in quotation matks The new item is inserted into this menu. itemid Name that WinHelp uses internally to identify the menu item. ‘The item identifier must appear in quotation marks. Use this name in the Disableltem or Deleteltem macro if you want to remove or disable the item, or change the operations that the item performs in certain topics. itemname Name that WinHelp displays on the menu for the item. This name is case-sensitive and must appear in quotation marks. Within the quotation marks, place an ampersand (&) before the character used for the item’s keyboard access key. ‘macro Help macro or macro string that is run when the user chooses the menu item. The macro must appear in quotation marks. Multiple macros in a string must be separated by semicolons O. position An integer specifying the position in the menu where the new item will appear. Position 0 is the first or topmost position in the menu, The following macro inserts a menu item labeled “Tools” as the third item on a menu that has an identifier “mnu_books”: InsertItem("nnu_books' “first_topic')", 3) mnu_tools", "&Tools", "JI(*tools.hip", Selecting the menu item causes a jump to a topic with the context string “first_topic” in the TOOLS.HLP file. WinHelp ignores this macro if itis run in a secondary window. Make sure that the keyboard access keys you assign to menu items are unique. If you assign a key that conflicts with other menu access keys, WinHelp displays the error message Unable to add item and ignores the macro.88 Help Compiler Guide InsertMenu ‘This macro adds a new menu to the WinHelp menu bar. Syntax InsertMenu(“menuid”, “menuname”, menuposition) Parameters Argument Definition menuid ‘Name that WinFelp uses intemally to identify the menu. The ‘menu identifier must appear in quotation marks, Use this identifier in the Appenditem macro to add commands to the ment ‘menuname Name for the menu that WinHelp displays on the menu bar. This name is case-sensitive and must appear in quotation marks. Within the quotation marks, place an ampersand (8&) before the character used for the menu's keyboard access key. ‘menuposition Number telling WinHelp which position on the menu bar the new menu name will have. Positions are numbered from left to right, with position 0 being the leftmost menu. Example ‘The following macro adds a menu named “Utilities” to WinHelp: InsertMenu("menu utiI", “kUtilities", 3) ‘The label “Utilities” appears as the fourth menu on the WinHelp menu bar. The user presses “ALT+U" to display the menu and its commands. Comments WinHelp ignores this macro if it is run in a secondary window Make sure that the keyboard access keys you assign to menus are unique. If you assign a key that conflicts with other menu access keys, WinHelp displays the error message Unable to add menu and ignores the macro,Chapter 5 Creating Help Macros 89 IsMark syntax Parameters Example Comments This macro determines whether a marker set by the SaveMark macro exists. It is used as a parameter to the conditional macros IfThen and IfThenElse. IsMark(“markertext") Argument Definition markertext Marker text tested by the IsMark macro. The IsMark macro returns a True value if the mark exists and a False value if it does not. The marker text must appear in quotation marks. The following macro jumps to the topic with the context string “man_mem” if a marker named “Managing Memory” has been set by the SaveMark macro: 1fThen( IsMark("Managing Memory"), "JI(*trb.hlp*, “man_mem*)") ‘The Not macro can be used to reverse the results of the IsMark macro. JumpContents Syntax Parameters Example Comments This macro jumps to the contents topic of a specified Help file, The contents topic is indicated by the CONTENTS option entry in the [OPTIONS] section of the HPI file, JumpContents/ “filename”) Argument Definition filename ‘The name of the destination file for the jump. The file name must appear in quotation marks. If WinHelp cannot find this file, it displays an error message and does not perform the jump, The following macro jumps to the contents topic of the PROGMAN.HLP file: JumpContents("PROGMAN. LP") Ifthe CONTENTS option is not specified, WinHelp jumps to the first topic in the Help file, WinHelp ignores this macro if it is run in a secondary window.90 Help Compiler Guide JumpContext (JC) Syntax Parameters Example “This macro jumps to a topic identified by a context number. The context is, identified by an entry in the [MAP] section of the .HPS file, " contextnumber) JumpContext(“filenan Argument Definition filename “The name of the destination file for the jump. The file name ‘must appear in quotation marks. If WinHelp cannot find this file, itdisplays an error message and does not perform the jump. contexinumber Context number of the topic in the destination file, The context number must be mapped in the destination Help file's [MAP] section, If the context number does not exist or cannot be found in the [MAP] section, WinHelp jumps to the contents topic or the first topic in the file instead, and displays an error message. (For more information about context numbers, see “Creating Context Numbers” in Chapter Planning the Help System.”) The following macro jumps to the topic mapped to the context number 801 in the PROGMAN.HLP file: JumpContext ("PROGMAN.HLP", 801) JumpHelpOn Syntax Parameters Example Comments This macro jumps to the contents topic of the Using Help file. The Using Help file is either the default WINHELP.HLP file or the Help file designated by the SetHelpOnFile macro in the [CONFIG] section of the HPJ file. (For more information, see the SetHelpOnFile macro later in this section.) JumpHelpOn0) None The following macro jumps to the contents topic of the designated Using Help file: ‘JumpHe1 pon) If WinHelp cannot find the specified Help file, it displays an error message and does not perform the jump.Chapter § Creating Help Macros 4 Jumpld (Jl) Syntax Parameters Example This macro jumps to the topic with the specified context string in the Help file, Jumpld/ “filename”, “contextstring”) Argument: Definition filename Name of the Help file (.HLP) containing the context string, ‘The file name must appear in quotation marks. If WinHelp does not find this file, it displays an error message and does not perform the jump. contextstring Context string of the topic in the destination file. The context string must appear in quotation marks. Ifthe context string does not exist, WinHelp jumps to the contents topic for that file instead. The following macro jumps to a topic with “second_topic” as its context string in the Help file SECOND. HLP: Jumpid("second. ht second_topic") JumpKeyword (JK) Syntax Parameters Example This macro opens the indicated Help file (HLP), searches through the K keyword table, and displays the first topic containing the keyword specified in the macro, JumpKeyword( “filename”, “keyword”) Argument. Definition filename “The name of the LHLP file that contains the desired keyword table. The file name must appear in quotation marks. If this, file does not exist, WinHelp displays an error message and does not perform the jump. keyword ‘The keyword that the macro searches for. The keyword must appear in quotation marks. If WinHelp finds more than one match, it displays the first matched topic. If it does not find any matches, it displays a “Not a keyword” message and the contents topic of the destination file. The following macro oper the Help file CLOCK.HLP: the first topic that has “hands” as an index keyword in JumpKeyword("clock.hip", “hands")92 Help Compiler Guide Next Syntax Parameters Comments This macro displays the next topic in the browse sequence for the Help file. It has the same effect as choosing the Browse Forward (>>) button. Next() None If the current topic is the last of a browse sequence, this macro does nothing. WinHelp ignores this macro if it is run in a secondary window Not Syntax Parameters Example This macro reverses the True or False result returned by the IsMark macro. It is, used along with the IsMark macro as a parameter to the conditional macros IfThen and IfThenElse. Not(IsMark(“markertext”) Argument Definition markertext Marker text tested by the IsMark macro. The Not macro returns a False value if the mark exists or a True value if it does not. The marker text must appear in quotation marks. The following macro jumps to the topic with context string “Expanded Memory” if a marker named “Managing Memory” has not been set by the SaveMark macro: IfThen(Not(IsMark ("Managing Nemor; “ Memory")") d), “JIC trb.hip', “Expanded PopupContext (PC) Syntax This macro displays a topic identified by a context number. The context is identified by an entry in the [MAP] section of the .HPJ file. PopupContext( “filename contexinumber)Parameters Example Chapter 5 Creating Help Macros Argument Definition filename The name of the file that contains the topic to be displayed in the pop-up window. The file name must appear in quotation marks. If WinHelp cannot find this file, it displays an error message. contextnumber Context number of the topic to be displayed in the pop-up window. The context number must be mapped in the [MAP] section of the specified Help file. If the context number does not exist or cannot be found in the MAP] section, WinHelp displays the contents topic or the first topic in the file instead, (For more information about context numbers, see “Mapping Context-Sensitive Topies” in Chapter 6, “Building the Help Files.”) The following macro displays in a pop-up window the topic mapped to the context number 801 in the file PROGMAN.HLP: PopupContext("progman.hip", 801) Popupld (PI) Syntax Parameters Example This macro displays a topic from a specified file in a pop-up window Popupla( “filename”, “contextstring”) Argument Definition filename The name of the file that contains the pop-up window topic. The file name must appear in quotation marks. If this file does not exist, WinHelp displays an error mess contextstring Context string of the topic in the destination file, The context string must appear in quotation marks. If the requested context string does not exist, WinHelp displays the contents topic or the first topic in the file in the pop-up window. (For more information, see “Coding Context Strings” in Chapter 3, “Creating the Topic Files.”) ‘The following macro displays in a pop-up window a topic identified by the context string “second_topic” in the file SECOND.HLP: Popupld("second.hip", "second topic")94 Help Compiler Guide PositionWindow (PW) Syntax Parameters Example Comments This macro sets the size and position of the main Help window or an existing secondary window Position Window(xcoord, ycoord, width, height, windowstate, “windowname”) Argument Definition xcoord, yeoord X and Y coordinates of the upper-left window comer. Positions are defined in terms of WinHelp’s 1024 x 1024 coordinate system, width, height Gives the default width and height of the window. Window sizes, like positions, are defined in terms of WinHelp’s coordinate system, windowstate Specifies how the window is sized. This parameter is 0 for normal size and I for maximized. If the parameter is 1, WinHelp ignores the xcoord, yeoord, width, and height parameters, windowname The name of the window to position, The name “main” is reserved for the primary Help window. For secondary windows, the window name is defined in the [WINDOWS] section of the -HPJ file. This name must appear in quotation marks. The following macro positions the secondary window “Samples” in the upper-left corner (100, 100) with a width and height of 500 (in WinHelp coordinates): PositionWindow(100, 100, 5@0, 5@@, 8, “Samples”) If the window to be positioned does not exist, WinHelp ignores the macro.Chapter 5 CreatingHelp Macros 95 Prev Syntax Parameters Comments This macro displays the previous topic in the browse sequence for the Help file. It has the same effect as choosing the Browse Back (<<) button. Prev() None If the currently displayed topic is the first topic of a browse sequence, this macro does nothing. WinHelp ignores this macro if itis run in a secondary window. Print ‘Syntax Parameters Comments “This macro sends the currently displayed topic to the printer. Print) None ‘This macro should be used only to print topics in windows other than the main Help window. For example, it can be used to print topics displayed in secondary windows, provided the user doesn’t have a dialog box open at the time of printing. Use of this macro in secondary windows is discouraged. PrinterSetup Syntax Parameters Comments This macro displays the Print Setup dialog box (same as the Print Setup command on the File menu). PrinterSetup() None Use of this macro in secondary windows is discouraged.6 Help Compiler Guide RegisterRoutine (RR) Syntax Parameters Example This macro registers a function within a DLL as a Help macro. Registered functions can be used in macro hot spots or footnotes within topic files, or in the [CONFIG] section of the .HPJ file, just as standard Help macros are used. RegisterRoutine(“DLLname", “functionname”, “formatspec”) Argument Definition DLLname The file name of the DLL being called. The file name must appear in quotation marks. If WinHelp cannot find the DLL, it displays an error message and does not perform the call. fimetionname ‘The name of the function to be executed in the designated DLL. The function name must appear in quotation marks. formatspec A string specifying the formats of parameters passed to the funetion. The format string must appear in quotation marks. Characters in the string represent C parameter types: “u” for unsigned short, “U” for unsigned long, “i” for short int, “I for ong int, “s” for string (near ehar *), “S” for string (far char *), or “v” for void. WinHelp automatically makes sure these formats match the parameter types specified in the function prototype. The following DLL call registers a routine “RetString” in the DLL named HELPLIB.DLL. RetString takes arguments of types far char *, short int, and unsigned long. Regi sterRoutine("HELPLIB™, “RetString™, "S~iU")Chapter 5 Creating Help Macros 97 SaveMark Syntax Parameters Example Comments This macro saves the location of the currently dit associates a text marker with that loc used to jump to this location layed topic and file and ion. The GoToMark macro can then be SaveMark( “markertext”) Argument Definition markertext ‘Text used to identify the topic location. The marker text must appear in quotation marks, and it must be unique. If the same text is used for more than one marker, WinHelp recognizes only the most recently entered marker. The following macro saves the marker “Managing Memory” in the current topic in the Troubleshooting Help file: SaveMark("Managing Memory") In addition to GoToMark, WinHelp offers the following other macros for use with text markers: = DeleteMark removes any defined marker. = IsMark tests whether a given marker has been set in the Help file. Not negates the result of this test. = IfThen and IfThenElse run one or more Help macros if a given marker has been set. These use the IsMark (and optional Not) macro to test whether the marker is set ‘Text markers are not saved if the user exits and then restarts WinHelp. Search Syntax Parameters Comments This macro displays the dialog box for the Search button, which allows users to search for topics using keywords defined in K footnotes. It has the same effect as choosing the Search button, Search() None WinHelp ignores this macro if itis run in a secondary window.98 Help Compiler Guide SetContents ‘Syntax Parameters Example This macro designates a specific topic as the contents topic within the Help file. SetContents; “filename”, contextnumber) Argument Definition filename The name of the Help file that contains the desired contents topic. The file name must appear in quotation marks. If WinHelp cannot find the file, it displays an error message and does not perform the jump. contextnumber Context number of the topic in the specified file. The context ‘number must be mapped in the [MAP] section of the destination Help file. If the context number does not exist or cannot be found in the [MAP] section, WinHelp displays an error message. The following macro sets the topic mapped to the context number 801 in the PROGMAN.HLP file as the contents topic: SetContents("PROGHAN.HLP”, 801) After running this macro, pressing the Contents button causes a jump to the specified topic. SetHelpOnFile Syntax Parameters Example Comments ‘This macro designates the specific Help file that replaces WINHELP.HLP, the default Using Help file in the Windows environment SetHelpOnFile( “filename”) Argument Definition filename ‘The name of the replacement Using Help file. The file name ‘must appear in quotation marks. If WinFfelp cannot find this file, it displays an error message. ‘The following macro sets the Using Help file as MYHELP.HLP: SetHel pOnFite("myhelp. hip") If this macro appears within a topic in the Help file, the replacement file is set after execution of the macro. If this macro appears in the [CONFIG] section of the HPI file, the replacement file is set when the Help file is opened.Virtual-Key Codes Chapter § Creating Help Macros ‘The following list shows the symbolic constant names, hexadecimal values, and descriptive information for Microsoft Windows virtual-key codes. Virtual-key codes are used to assign a shortcut key or key combination to a macro, (For ning shortcut keys or key combinations, see the AddAccelerator macro earlier in this chapter.) The codes are listed in numeric more information on ass 99 order. Name Value Description VK_CANCEL 03H Used for control-break processing + OSH-OTH Undefined VK_BACK 08H BACKSPACE key VK_TAB 09H TAB key + OAH-OBH Undefined VK_CLEAR cH CLEAR key VK_RETURN opi RETURN key VK_SHIFT 10H SHIFT key VK_CONTROL WH CTRL key VK_MENU 12H ALT key VK_PAUSE 13H PAUSE key VK_CAPITAL 14H CAPITAL key + 15H-19H Reserved for Kanji systems + 1AH Undefined VK_ESCAPE IBH ESC key + ICH-IFH Reserved for Kanji systems VK_SPACE 20H SPACEBAR VK_PRIOR 21H PGUP key VK_NEXT 22H PGDN key VK_END 23H END key VK_HOME 24H HOME key VK_LEFT 25H LEFT ARROW key VK_UP 26H UP ARROW key VK_RIGHT 27H RIGHT ARROW key VK_DOWN 28H DOWN ARROW key VK_SELECT 29H SELECT key + 2AH OEM specific VK_EXECUTE 2BH EXECUTE key100 Help Compiler Guide Name Value Description VK_SNAPSHOT 2CH PRINT SCREEN key for Windows version 3.0 and later VK_INSERT 2DH INS key VK_DELETE 26H DEL key VK_HELP 2FH HELP key VK_0 30H Okey VK 31H key VK2 32H 2 key VK3 33H 3key VK 34H key V5 35H Skey VK6 36H 6key VK7 37H They VK 8 38H Skey vK_9 39H Okey + 3AH-40H Undefined VKA 4H Akey VK _B OH Bey VK_C 43H Chey VK_D 44H Dkey VK_E 45H Ekey VKF 46H Fkey VK 4TH Gkey VKH 48H Hkey VKA 49H key VK 4AH Jkey VK_K 4BH K key VKL 4cH Lkey VK_M 4DH M key VK_N 4EH N key VkK_0 4FH Okey VK_P 50H Pkey VK.Q SiH Qkey VKR 52H Rkey VK_S SoH S keyChapter 5 Creating Help Macros 101 Name Value Deseription VKT S4H Tkey VK_U SSH Ukey VK_V SoH Vkey VK_W STH Wey VK_X 58H X key VK_Y 59H Y key VK Z SAH Zkey + SBH-SFH Undefined VK_NUMPADO or Numeric key pad 0 key Vk_NUMPADI 61H Numeric key pad 1 key VK_NUMPAD2 oH Numeric key pad 2 key VK_NUMPAD3 63H Numeric key pad 3 key VK_NUMPAD4 64H Numeric key pad 4 key VK_NUMPADS 65H Numeric key pad 5 key VK_NUMPAD6 66H Numeric key pad 6 key VK_NUMPAD7 7H Numeric key pad 7 key VK_NUMPADS 68H Numeric key pad 8 key VK_NUMPAD9 oH Numeric key pad 9 key VK_MULTIPLY AH Multiply key VK_ADD BH Add key VK_SEPARATER CH Separater key VK_SUBTRACT opi Subtract key Vk_DECIMAL EH Decimal key VK_DIVIDE OFH Divide key VK FI 70H Fi key VK_F2 71H F2 key VK_F3 TH F3 key VK Fa 73H F4 key VK_FS 74H FS key VK_F6 75H F6 key VK_F7 76H F7 key VK_F8 77H FS key VK_F9 78H FY key VK_FLO 79H Flo key VKFIL 7AH FIl key402 Help Compiler Guide Name Value Description VK FI2 7BH FIZ key VK_FI3 7CH FI3 key VK_FI4 7DH Fit key VK FIS 7EH FIS key VK FI6 7EH Flokey + 80H-87H OEM specific + 88H-8FH Unassigned VK_NUMLOCK 90H NUM LOCK key + oun OEM specific + 92H-BOH Unassigned + BAH-COH OEM specific + CIH-DAH Unassigned + DBH-E4H OEM specific + FSH Unassigned + E6H OEM specific + ETH-ESH Unassigned + EOH-FSH OEM specific + FOH-FEH Unassigned103 CHAPTER 6 Building the Help Files Afier the topic files for your Help system have been written, you are ready to create a Help project file and run a build to test it. The Help project file contains all the information the Help Compiler needs to convert Help topic files into a binary Help resource file. You use the Help project file to tell the Help Compiler which topic files to include in the build process. Information in the Help project file also lets the Help Compiler map specific topics to context numbers. Contents = Creating the Help Project File = Specifying Topic Files = Specifying Options = Specifying Build Tags = Specifying Alternate Context Strings = Mapping Context-Sensitive Topics = Including Bitmaps by Reference = Customizing Help + Defining Window Attributes = Using External Files = Sample Project File = Compiling the Help File104 Help Compiler Guide Creating the Help Project File Section List You use the Help project file to control how the Help Compiler creates a Help file from your topic files. You can use any text editor to create your Help project file, but you must save the file as unformatted text (ASCI). The extension of a Help project file is .HPJ. If you do not use the extension .HPJ on the command line, the Help Compiler looks for a Help project file with this extension in the current directory before loading the file. The Help output file (.HLP) will have the same name as the Help project file (.HPJ) file. The Help project file contains up to nine sections, each of which specifies information about the source files to compile or directives for the Help Compiler to follow at compile time. Section names are placed within square brackets using the following syntax: [sectioname| You can use a semicolon to indicate a comment in the Help project file. The Help Compiler ignores all text from the semicolon to the end of the line on which it occurs. Note. The order of the various sections within the Help project file is unimportant, with one exception: if an [ALIAS] section is used, it must precede the [MAP] section The following table describes each of the sections you may create in a Help project file. Section Description [OPTIONS] Specifies options that control the build process. This section is optional. If itis used, it should be the first section listed in the Help project file so that the options will apply during the entire build process. [FILES] Specifies topic files to be included in the build. This section is required. (BUILDTAGS] Specifies valid build tags. This section is optional. [CONFIG] Specifies author-defined menus and buttons used in the Help file and registers dynamic-link libraries (DLLs) and DLL functions used as macros within the Help file. This section is required if the Help file uses any of these features.Chapter 6 Building the Help Files 105 Section Description [BITMAPS] Specifies bitmap files to be included in the build, This section is not required if the Help project file lists a path for bitmap files in the [OPTIONS] section using the BMROOT or ROOT option. See “Specifying Options” later in this chapter for details. IMAP} Associates context strings with context numbers. This section is optional [ALIAS] Assigns one or more context strings to the same topic. This section is optional. [WINDOWS] Defines the characteristies of the primary Help window and types of secondary windows used in the Help file. This section is required if the Help file uses secondary windows, [BAGGAGE] Lists files that are to be placed within the Help file's HLP file (which contains its own file system). This section is optional. Specifying Topic Files Use the [FILES] section of the Help project file to list all topic files that the Help. Compiler should process to produce a Help resource file. A Help project file must have a [FILES] section. ‘The following CallHelp sample shows the format of the [FILES] section: CFILEST CALLHELP.DOC —; Main topics for CallHelp application Note that since CallHelp is a small project, all topics are listed in the same file. Using the path defined in the ROOT option, the Help Compiler finds and processes all files listed in this section of the Help project file. If the file is not on the defined path and cannot be found, the Help Compiler generates an error. For more information about the ROOT option, see the ROOT Option later in this chapter. You can include other list files in the build process with the #include directive (the #include directive is used as it is in C language). The #inelude directive uses the following syntax: #inelude You must include the angle brackets around the file name, The pound sign (#) has to be the first character in the line. The file name must specify a complete path, either the path defined by the ROOT option or an absolute directory path to the file,106 Help Compiler Guide You may find it easier to create a text file that lists all files in the Help project and include that file in the build, as in this example: [FILES] include Specifying Options ‘The [OPTIONS] section includes options that control how a Help file is built and what feedback the build process displays. If this section is included in the Help project file, it should be the first section listed so that the options will apply during the entire build process. This section can include the following options. Option Description BMROOT Designates the directory where the Help Compiler can find the bitmap files used in bme, bml, and bmi references in the Help topic files. BUILD Determines which topics to include or exclude in the build, COMPRESS ‘Specifies what type of compression to use during the build. Specifies the context string of the contents topic for a Help file. COPYRIGHT. Adds a unique copyright message for the Help file to the About dialog box ERRORLOG Puts compilation errors in a file during the build FORCEFONT Forces all authored fonts in the RTF topic files to appear in a different font when displayed in the Help file ICON ‘Specifies that the icon file to be displayed when the Help file is minimized. LANGUA Specifies a different sort ordering for Help files authored in a Scandinavian language, MAPFONTSIZE, Maps a font size in the RTF file to a different font size in the compiled Help file. MULTIKEY Specifies an alternate keyword table for mapping topics. OLDKEYPHRASE Designates whether the Help Compiler should use the existing key phrase table or create a new one during the build.Chapter 6 Building the Help Files 107 Option Description OPTCDROM Optimizes the Help file for CD-ROM use. REPORT Controls the display of messages during the build process, ROOT Designates the directories used to locate topic and data files listed in the Help project file. TITLE Specifies the text that is displayed in the title bar of the Help window when the file is open. WARNING Indicates the level of error message reporting the Help ‘Compiler displays during the build. These options can appear in any order within the [OPTIONS] section. The [OPTIONS] section is not required Detailed explanations of each of these options follow. BMROOT Option ‘The BMROOT option designates the directory where the WinHelp application looks for bitmap files specified in bme, bml, and bmr references. This option uses the following syntax: BMROOT = pathname|, pathname] Each pathname can specify a drive and full path. If the Help project file has a BMROOT option, you don’t need to list bitmap files in the [BITMAPS] section If the Help project file doesn’t have a BMROOT option, WinHelp looks for bitmaps in the directories specified by the ROOT option. If the Help project file doesn’t have a ROOT option, or if the ROOT option doesn’t specify the directory containing the bitmap files, you must list the file name for each bitmap in the [BITMAPS] section of the Help project file. For example, the following entry specifies that bitmaps reside in the \HELP\BMP. directory on drive C and the \GRAPHICS\ART directory on drive D: (oPTronsy BMROOT = C:\HELP\BMP, D: \GRAPHICS\ART108 Help Compiler Guide BUILD Option ‘The BUILD option specifies whether topics containing build tags are included or excluded in a build. Use this option only if the RTF topic files have build tags. The BUILD option line uses the following syntax: BUILD = expression The expression is a logical statement that specifies which topics to include or exclude in the build. The logical symbols used in an expression appear as follows in order of importance: Symbol Description oO Parentheses & AND operator | OR operator ~ NOT operator tag Build tag ‘The Help Compiler evaluates all build expressions from left to right using the following precedence rules: xpressions within parentheses are evaluated first. Expressions with a logical NOT (-~) are evaluated next. = Expressions with a logical AND (&) are evaluated next. = Expressions with a logical OR (|) are evaluated next. For example, if you code DEMO, MASTER, and TEST_BUILD build tags in your topic files, you can include any one of the following build expressions in the [OPTIONS] section. Example ‘Topics Built BUILD = DEMO ‘Only topics that have the DEMO tag or topics with no tags. Topies that have both the DEMO and the MASTER build tags, or topics with no tags. Topics that have either the DEMO tag or the MASTER tag, or topics with no tags. BUILD = (DEMO | MASTER) & Topics that have either the DEMO or the TEST_BUILD MASTER build tags and that also have the ‘TEST_BUILD tag, or topics with no tags, MASTER “Topics that do not have a MASTER tag or topics with no tags. BUILDChapter 6 Building the Help Files 109 COMPRESS Option The COMPRESS option specifies the level of compression for the build: no compression, a medium level of compression (approximately 40%), or a high level of compression (approximately 50%). Depending on the degree of compression requested, the build uses either block compression or block and key= phrase compression. = Block compression works by compressing the topic data into predefined units known as blocks. + Key-phrase compression works by combining repeated phrases found within the source file(s). The Help Compiler creates a phrase-table file with the PH extension if it doesn’t find one. If the Help Compiler finds a file with the .PH extension, it uses that file for the current compilation. Because the .PH file speeds the compression process when the text hasn’t changed significantly since the last compilation, you might want to save the phrase file if you compile the same Help file several times with compression. You will get maximum compression, however, if you delete the .PH file before starting each build. The following forms of the option specify no compression: COMPRESS = NO COMPRESS = FALSE COMPRESS = 0 ‘The following form of the option specifies medium compression: COMPRESS = MEDIUM The following forms of the option specify high compression (block and key- phrase): COMPRESS = YES COMPRESS = TRUE COMPRESS = 1 COMPRESS = HIGH110 Help Compiler Guide CONTENTS Option ‘The CONTENTS option identifies the context string of the highest-level or “home” topic (usually a Table of Contents or index within the Help file). Users access this topic by choosing the Contents button. If the [OPTIONS] section does not include a CONTENTS option, the Help Compiler assumes that the contents topic is the first topic it encounters in the first listed topic file in the [FILES] section of the Help project file. ‘The CONTENTS option uses the following syntax: CONTENTS = contextstring The following example tells the Help Compiler that the context string of the contents topic for this Help file is “main_contents”: CONTENTS = main_contents COPYRIGHT Option The COPYRIGHT option places custom text in the About dialog box of WinHelp. This option has the following syntax: COPYRIGHT = copyrightnotice The placeholder copyrightotice usually contains the copyright information you ‘want to display for users of your Help file, although you can use this option to provide a version number or other information. The notice is displayed immediately following the Microsoft Help copyright notice in the About dialog box, and can contain from 35 to 75 characters. ERRORLOG Option The ERRORLOG option displays error messages on the screen during the build. It also writes the messages to a file at the same time. This option has the following syntax ERRORLOG = errorfilename ‘The errorfilename can be an absolute path, or relative path if you want the file to be written to some directory other than the Help project root directory For example, the following code would write all errors during the build to the file HLPBUGS.TXT file in the Help project root directory. ERRORLOG = HLPBUGS. TXTChapter 6 Building the Help Files 1 FORCEFONT Option The FORCEFONT option creates a Help file that displays text in only one font. This option is useful if you must compile a Help file with topic files that include fonts not supported by your user's system. The FORCEFONT option has the following syntax: FORCEFONT = foniname Font names must be spelled as they appear in the Fonts dialog box in the Microsoft Windows Control Panel. These font names do not exceed 20 characters in length. If you designate a font that the Help Compiler does not recognize, WinHelp uses the Helvetica font as the default font for the Help file. ICON Option ‘The ICON option identifies the icon file to display when the user minimizes the WinHelp application. This option has the following syntax ICON = iconfile The iconfile is the file name of the .ICO bitmap file. This file must be created in an application such as IeonWorks LANGUAGE Option The LANGUAGE option changes the sort ordering in the Search keyword list box to something other than English alphabetic ordering. This option uses the following syntax: LANGUAGE = languagename Since WinHelp 3.1 supports only one language sort ordering other than English, the languagename parameter must be “scandinavian” if you use this option. MAPFONTSIZE Option ‘The MAPFONTSIZE option maps font sizes specified in your topic files to different sizes when displayed in the Help window. This means you can use one font size in your topic files and have the Help Compiler change it to an appropriate size for the actual Help file display This option is especially useful if there is a significant size difference between your authoring monitor and your intended display monitor, as there is between screen fonts on the Apple» Macintosh™ and Microsoft Windows,112 Help Compiler Guide The MAPFONTSIZE option uses the following syntax: MAPFONTSIZE = m|-n|:p The m argument is the size of the source font, and the p argument is the size of the desired font for the Help file. All fonts in the topic files that are size m are changed to size p. The optional argument, n, allows you to specify a font range to be mapped. All fonts in the topi ling between m and n, inclusively, are changed to size p. The following examples illustrate the use of the MAPFONTSIZE option MAPFONTSIZE = 8:12 : make all 8 pt. fonts come out 12 pt. MAPFONTSIZE = 12-24:16 ; make fonts from 12 to 24 pt. come out 16 pt. You can specify up to five font ranges in the [OPTIONS] section of the Help project file; however, you can map only one font size or range with each MAPFONTSIZE statement. And, if you use more than one MAPFONTSIZE statement, the source font size or range specified in subsequent statements cannot overlap previous mappings. For instance, the following mappings would generate an error when the Help Compiler encountered the second statement: MAPFONTSIZE = 12-24:16 MAPFONTSIZE = 14:20 Because the second mapping statement contains a size already mapped in the preceding statement (14-point font falls within the 12- to 24-point range), the Help Compiler will ignore the second line MULTIKEY Option The MULTIKEY option specifies the footnote character to use for an additional keyword table. This option uses the following syntax: MULTIKEY = foomotecharacter The foomotecharacter argument is the case-sensitive letter used for the keyword footnote. The following example illustrates how to enable the letter L for a keyword table footnote: MULTIKEY = L Note Be sure to limit your keyword table footnotes to one case, usually uppercase. In the previous example, topics with the footnote L would have their keywords incorporated into the additional keyword table, whereas those assigned the lowercase letter | would not.