Users of Windows expect and deserve context-sensitive online help for all their Windows applications. All but the simplest Visual C++ applications need a custom Windows help file that lets users press F1 to obtain context-sensitive help for field entries, click a toolbar button to obtain help for a specific button, or choose Help | Contents to select a topic from the help system's opening window.
No matter how much or how little written documentation you supply with your database application, few users will take the time to read the documentation before they begin to use the application. This is especially true for decision-support applications that you design for supervisory and management personnel.
Your Visual C++ applications should be sufficiently intuitive in their operation such that all but the Windows neophyte can take full advantage of their features without employing online help. In reality, however, few Windows applications of any significance are fully comprehensible to the first-time user. Therefore, you need to create Windows help files to make sure that users employ all the features of your application and use the features in the way you intended. If you develop a database application to a written specification, the contract undoubtedly stipulates that comprehensive printed documentation is to accompany the production version of the application. Therefore, this chapter is oriented toward converting the text and graphics of your printed documentation to a help file for the application. Making your documentation do "double duty" as a help file saves time and expense.
This chapter is designed to supplement, not replace, the "Creating Help Files: Help Compiler" chapter in the Programming Tools for Windows manual that comes with Visual C++ 1.5x, the Help Compiler Guide included with Visual C++ 2.x, or the Help Author's Guide included with Visual C++ 4's Help Workshop program. In addition, programmers who have access to the Office Developer's Kit can refer to the Help Compiler Guide supplied with that product. Chapter 22, "Documenting Your Database Applications," taught you how to document the objects in your database application and prepare a data dictionary. This chapter shows you how to use several commercial software products. The non-Microsoft products described are Blue Sky Software's WinHelp Office 95, which is a number of useful products packaged together, and WexTech Systems, Inc.'s Doc-To-Help, which is used to convert your Word for Windows documentation files into a full-fledged, professional Windows help system.
Often help files are developed by people other than the programmer. This usually means that the programmer will be required to set up a system to assist the help file writers in creating the final help file. Visual C++ 4 automatically generates shell help files. This is fine if the programmer is the person who is developing the help files. If not, you might need to set up a system such as the one discussed in the following sections.
NOTE
It's usually better that someone other than the programmer write the documentation for an application. For example, I have a major Windows GIS application on the market for which I didn't write the documentation. Often the programmer isn't the best person to write the manuals and online help. Programmers often make too many assumptions about the user's ability. Furthermore, good programmers aren't always good writers.
In some organizations, the responsibility for documentation is assigned to the customer support department. They work with the product and the customers and often know which areas are the weakest and need improvement.
The help file display features of Windows are commonly referred to as the WinHelp engine. The Windows 95 help engine is quite powerful.
NOTE
Windows 95 has a very powerful and flexible help engine. This help engine has been migrated to other Windows platforms (Windows NT, for example) and will continue to be expanded upon in the future.
WINHELP.EXE is the Windows application in your \WINDOWS directory that implements the help system. Under the 32-bit versions of Windows (Windows 95 and Windows NT), the file is named WINHLP32.EXE. Under Windows 95, WINHELP.EXE is a stub program that calls WINHLP32.EXE.
Visual C++ includes features that let you assign individual help windows to forms and controls to create context-sensitive help. The interface between your Visual C++ application and your WinHelp .HLP file(s) is comprised of the following two basic elements:
The following sections describe how to create WinHelp files and how to assign context IDs to topics in order to create context-sensitive help.
NOTE
Making use of all the features that the WinHelp engine offers is beyond the scope of this book. Microsoft's Help Authoring Guide is available for downloading as HAG.ZIP in .HLP format from the Windows Users Group forum (GO WUGNET). The Help Authoring Guide also is included on the Microsoft Developer Network (MSDN) CD-ROMs.
Programmers who use AppWizard to create their applications have the option of including basic context-sensitive help. Figure 23.1 shows AppWizard's graphical programmer interface, which shows that when you add context-sensitive help, the Help menu is added automatically.
Figure 23.1. Visual C++ 4's AppWizard, including context-sensitive help.
NOTE
Figure 23.1 shows Visual C++ 4's AppWizard, which is virtually identical to the one in Visual C++ 2.x. The programmer interface of Visual C++ 1.5x is different from the one in Visual C++ 2.x, but the help files that AppWizard creates are virtually identical to those created using later versions of Visual C++.
NOTE
It's easy to convert an application's help file that was created with the 16-bit versions of Visual C++ (1.5x in particular) to 32-bit versions of Visual C++ (2.x and 4.x in particular). The final help file is actually created as a separate step outside of Visual Workbench using a batch file supplied with Visual C++ when using versions prior to Visual C++ 4.0. With Visual C++ 4's Developer Studio, when a help file is added to the project, Developer Studio correctly calls the help compiler and creates the desired help file.
When Visual C++ creates the shell for your application's help file, this shell resides in a subdirectory located in the project's directory. This subdirectory is called HLP and contains one or two .RTF files and a number of bitmap files (usually about 20 to 25) for such objects as toolbar buttons. Figure 23.2 shows a typical HLP directory.
Figure 23.2. The files created by AppWizard in the HLP subdirectory.
NOTE
Visual C++ 4 automatically creates help files (by executing the MakeHelp.Bat file) as part of the project build. You don't need to manually execute MakeHelp.Bat if you're using Visual C++ 4 and have used AppWizard to create your application with help features. Of course, if you want to manually compile the help files using MakeHelp.Bat, you can do so.
The two .RTF files are
PROJECT.HPJ is the help project file. .HPJ files are discussed later in this chapter.
Not all the help support is located in the HLP subdirectory. The project's main directory contains the batch file used to generate WinHelp files. MakeHelp.Bat, shown in Listing 23.1, actually calls the help compiler and generates the help file. This batch file is usually executed from a command-line prompt (in a DOS window), but you can create an icon or a menu shortcut from Visual C++'s Tools menu for MakeHelp.Bat. This filename never changes, so making a shortcut for Visual C++'s Tools menu would be effective for all AppWizard-created projects.
NOTE
Generally, if you delegate the help file authoring, whoever was doing the help file development would use the MakeHelp.Bat file to create the help files rather than Visual C++'s Developer Studio.
Listing 23.1. A typical MakeHelp.Bat file.
@echo off
REM -- First make map file from Microsoft Visual C++ generated resource.h
echo // MakeHelp.Bat generated Help Map file.
Used by HELP FILE DEMO.HPJ. >"hlp\Help File Demo.hm"
echo. >>"hlp\Help File Demo.hm"
echo // Commands (ID_* and IDM_*) >>"hlp\Help File Demo.hm"
makehm ID_,HID_,0x10000 IDM_,HIDM_,0x10000 resource.h >>"hlp\Help File Demo.hm"
echo. >>"hlp\Help File Demo.hm"
echo // Prompts (IDP_*) >>"hlp\Help File Demo.hm"
makehm IDP_,HIDP_,0x30000 resource.h >>"hlp\Help File Demo.hm"
echo. >>"hlp\Help File Demo.hm"
echo // Resources (IDR_*) >>"hlp\Help File Demo.hm"
makehm IDR_,HIDR_,0x20000 resource.h >>"hlp\Help File Demo.hm"
echo. >>"hlp\Help File Demo.hm"
echo // Dialogs (IDD_*) >>"hlp\Help File Demo.hm"
makehm IDD_,HIDD_,0x20000 resource.h >>"hlp\Help File Demo.hm"
echo. >>"hlp\Help File Demo.hm"
echo // Frame Controls (IDW_*) >>"hlp\Help File Demo.hm"
makehm IDW_,HIDW_,0x50000 resource.h >>"hlp\Help File Demo.hm"
REM -- Make help for Project HELP FILE DEMO
echo Building Win32 Help files
start /wait hcrtf -x "hlp\Help File Demo.hpj"
echo.
if exist Debug\nul copy "hlp\Help File Demo.hlp" Debug
if exist Debug\nul copy "hlp\Help File Demo.cnt" Debug
if exist Release\nul copy "hlp\Help File Demo.hlp" Release
if exist Release\nul copy "hlp\Help File Demo.cnt" Release
echo.
NOTE
Visual C++ 2.x's AppWizard might add an EndLocal statement to the end of the MakeHelp.Bat file. This command should cause no problems (even though it isn't currently supported by DOS). Oddly, AppWizard doesn't include an opening SetLocal statement.
Visual C++ 4 doesn't add the erroneous EndLocal statement. Instead, it adds an Echo command to the end of MakeHelp.Bat, as Listing 23.1 shows.
After you've created your project, you will compile the initial help files when you first build your project. You don't need to make any changes in these files; however, you will find that as supplied by AppWizard, the help files don't provide much help!
The AfxCore.rtf file has a number of place markers. These are marked with the characters << and >>. For example, you will need to substitute the application's name wherever the phrase <<AppName>> is found. To do this, simply use a global substitution command in Word for Windows or whichever RTF editor you're using.
Any place markers that aren't listed in the help source file are verbose enough that you will readily understand what information needs to be substituted.
WARNING
The WordPad editor that is part of Windows 95 can't be used to create help files. This is because help file topics are linked to footnotes, and WordPad doesn't support footnotes. You must use a fully functional RTF-enabled editor, such as Word for Windows, to create or modify a help .RTF file.
A WinHelp .HLP file is a compiled version of a word processing document file saved in Microsoft rich text format (RTF). Rich text format is a page description language used to exchange formatted text between document processing applications. For example, you use .RTF files to transfer Word for Windows files to the Macintosh version of Word. Most Windows word processing applications can save documents as .RTF files. Rich text format is similar in concept to Adobe's PostScript page description language, but .RTF isn't used to print documents. Figure 23.3 shows part of the .RTF version of AfxCore.rtf (the CHAPTR23\Help File Demo\hlp\AfxCore.rtf file) displayed in Notepad's window. Figure 23.4 shows the same file loaded into Word for Windows.
Figure 23.3. Part of the AfxCore.rtf WinHelp file in Notepad.
Figure 23.4. The same part of the AfxCore.rtf WinHelp file in Word for Windows.
The .RTF files that you create include a header that describes the page format, fonts, and styles in use. PostScript files contain a header that serves a similar purpose. An escape character (\) precedes page and character formatting data in .RTF files, and French braces ({}) enclose groups of formatting data and text to which the formatting applies. Most of the header information in Word .RTF files is derived from the template (.DOT file) in use when you write the document. Only a small part of the .RTF file header appears in Figure 23.3; the first few words of the text are highlighted to identify the point where the paragraph starts.
Instructions to the WinHelp engine are embedded in the .RTF file in the form of footnotes designated by footnote symbols, such as $ and #, rather than conventional footnote numbers. Topic titles are designated by $ footnotes. The context strings that uniquely identify a topic to the WinHelp engine use the # symbol. A topic is a help window that is devoted to a single subject. Topics are separated from one another in your word processing document by hard page breaks (usually created using the Ctrl-Enter key combination). Figure 23.5 shows part of a simple help topic from the HELPEX example included with the Windows Help Authoring Guide on the Microsoft Developer's Network CD-ROM.
Figure 23.5. Part of the second topic of the HELPEX.RTF file used to create HELPEX.HLP.
In Figure 23.5, Help Example Index is the topic title and ctxContents is the help context string for the topic. Hotspots are individual words or blocks of text that are formatted with the double-underline or strikethrough attribute and are followed by a help context string formatted as hidden text. When you click a hotspot, WinHelp jumps to the topic identified by the context string that follows the hotspot text. Figure 23.6 shows the first two help topic windows of HELPEX.HLP. Hotspots appear in green in help windows, so you should avoid using the green color attribute in your help text.
Figure 23.6. The first two help topic windows of HELPEX.HLP.
You can embed or link graphic objects contained in bitmap (.BMP) or vector image (.WMF) files in your WinHelp files. The easiest way to add bitmapped images to your help files is to embed the image in .BMP format in your .DOC or .RTF file using Word. However, large bitmap files usually are handled more efficiently by linking the graphic file to the WinHelp file by using its filename as a reference. Figure 23.7 shows Microsoft's logo as an embedded bitmap. Figure 23.8 shows Microsoft's logo as it appears in the final help file. To embed the bitmap (a bitmap image captured from Word for Windows' toolbar) in the .RTF document, you choose Insert | Picture in Word to display the Picture dialog box and then double-click cmdialog.bmp in the File Name list box. The {bmc cmdialog.bmp} entry below the line of text causes the CMDIALOG.BMP bitmap file to be inserted at the position of the { character.
Figure 23.7. A help topic with an embedded bitmap.
Figure 23.8. An embedded bitmap of Microsoft's logo in WinHelp.
NOTE
When you use bitmapped graphics, you might need to include a version of the bitmap file for each type of display resolution that might be employed by users of the help system. The Microsoft multiple-resolution bitmap compiler, MRBC.EXE, lets you create a single bitmap file that supports VGA, SVGA, and 8514 resolutions. It's unlikely that any users of Visual C++ database applications will be using resolutions less than standard VGA, but MRBC.EXE is useful to provide scaleable bitmaps for 640x480 (VGA), 800x600 (SVGA), and 1,024x768 (8514, XGA, or UVGA) display resolutions. It won't be long before 1280x1024 resolutions become common. Your help files should take into account the trend toward higher resolution and more colors. Many Windows database applications still run on "plain vanilla" 16-color VGA systems, but more and more users are converting to 256-color or better systems. When you convert a .BMP file with MRBC.EXE, you substitute .MRB for the .BMP extension when you refer to the file. One of the advantages of using .WMF vector image files in help files is that the Windows metafiles are device-independent.
NOTE
The term link is used in this chapter to differentiate between embedding a graphics file in the .RTF file and creating a reference to a separate graphics file with {bm? filename.ext} entries in your .RTF file. The ? placeholder determines whether the graphic is placed as a character (bmc), at the left margin (bml), or at the right margin (bmr). When you compile the help file with the WinHelp compiler, the graphic that you link is embedded into the .HLP file you create. (You don't need to supply the .BMP file along with your .HLP file.)
You can create hotspots in graphic images that you link to your WinHelp file by using the Hotspot Editor, SHED.EXE, which is included with Visual C++. (You can't add hotspots to bitmaps you embed in WinHelp .RTF files.)
NOTE
If there is no link to SHED in the Visual C++ 4 folder, you can add one. An alternative is to start SHED from a DOS command prompt window, but this really isn't efficient unless you frequently use a DOS window.
The Hotspot Editor creates an .SHG (system hypergraphic) file from .BMP, .DIB (device-independent bitmap), or .WMF files. To add hotspots to a .BMP, .DIB, or .WMF file, follow the next steps.
NOTE
The bitmap file used in this example is setup.bmp, found in Windows 95's directory. It was copied to the help project folder and saved in SHED as setup.shg.
NOTE
Because SHED isn't long-filename-compliant, you will have to select files using their short filenames.
Figure 23.9. Defining the boundaries and attributes of a hotspot in a hypergraphic (.SHG) file.
NOTE
All the hotspots in this example were defined as pop-ups. You can also define hotspots as either jumps (which would jump to a certain topic) or as a WinHelp macro that would be run when the hotspot was selected.
Figure 23.10. Pop-up help window topics for hotspots of the set up bitmap image.
Figure 23.11. The pop-up window displayed when you click the picture of the mouse in the image.
NOTE
One of the advantages of using SHED.EXE is that the Hotspot Editor compresses .BMP files. For example, setup.bmp requires 38,462 bytes of storage, whereas setup.shg occupies only 36,959 bytes and has four jumps defined.
Creating the final WinHelp .HLP file from your .RTF file and any graphics that are referenced in the .RTF file is a three-step process.
NOTE
Even though the HELPEX sample help file that is supplied on the MSDN CD is intended to be compiled with the DOS-based help compilers, using Microsoft Help Workshop will work, with only minor warnings about improper labels. It will create a valid help file.
The following three sections describe the preceding steps in detail.
Help project files, which are usually named APPNAME.HPJ, are similar in concept to Visual C++ makefiles or project files. Listing 23.2 shows the contents of the project file for the Help Example help file, HELPEX.HPJ.
Listing 23.2. Sections and entries in the HELPEX.HPJ help project file (after loading into Microsoft Help Workshop).
; This file is maintained by HCW. Do not modify this file directly. [OPTIONS] HCW=0 ; error message: ; ; R1023: Keyword(s) defined without title in page 59 ; of file helpex.rtf ; ; This message indicates that a topic will be listed in ; the Search Topics Found box as ">>Untitled Topic<<" COMPRESS=60 Hall Zeck LCID=0x409 0x0 0x0 ;English (United States) REPORT=Yes TITLE=Help Example HLP=.\helpex.hlp [FILES] helpex.rtf ; main topics [MAP] #include <helpids.h>
CAUTION
Once you've loaded an .HPJ file into Microsoft Help Workshop, you shouldn't edit the file by hand. Instead, use Microsoft Help Workshop to make changes to the help project file.
Help project files are text files that are organized into sections and are similar in structure to Windows .INI files. Table 23.1 lists the most commonly used sections of a help project file, states whether the section is required in the file, and briefly describes the section's purpose. Keywords for entries in the [OPTIONS] section also appear.
| Section of .HPJ File | Section Required? | Description | |||
| [OPTIONS] | No (but usually present) | Defines the options that control the WinHelp compilation process. Some of the more common option entries include the following: | |||
| ROOT=d:\path | Defines the path to your help source files. | ||||
| CONTENTS= | Sets the context | ||||
| ContextString | string for the index topic with the Windows 3.1 Help compiler, HC31.EXE. | ||||
| TITLE= | Sets the title for | ||||
| AppName Help | the WinHelp file, which appears in the help window's title bar. | ||||
| ICON= IconFile.ICO | Sets the icon that is displayed when the help window is minimized. | ||||
| COMPRESS=0|FALSE | Controls file compression. 0, or FALSE, means "do not compress files." 1, or TRUE, compresses the file. Compressing .HLP files saves disk space at the expense of speed in displaying help windows (due to the time required to decompress the file). HC31.EXE supports varying degrees of compression. | ||||
| WARNING=3 | Determines what errors are reported. 0 through 3 control the level of error reporting. 0 = no error reports, 1 = most-severe warnings, 2 = intermediate warning level, and 3 = report all warnings. | ||||
| REPORT=1|ON | Determines whether progress reports of the compilation are provided. 1, or ON, = report progress of compile. 0, or OFF, = no report. | ||||
| [FILES] | Yes | Specifies the help source files included in the compilation. | |||
| [BUILD] | No | Specifies topics to include in or exclude from the compiled file. | |||
| [BUILDTAGS] | No (yes if [BUILD] is specified) | Names valid build tags, allowing the selection of topics to be compiled within a file. | |||
| [CONFIG] | Only if DLL functions are called | Registers custom DLLs that have functions that are called by WinHelp RegisterRoutine macros. | |||
| [BITMAPS] | No | Specifies bitmap or .WMF files that are used in the compilation and not embedded in your WinHelp document. This section isn't required if you used the ROOT= entry in the [OPTIONS] section to specify the path to the referenced bitmap files. | |||
| [MAP] | No | Associates context strings with context ID numbers. You need a map section to use the Context ID property of Access forms and control objects. | |||
| [ALIAS] | No | Lets you assign more than one context string to a subject. | |||
| [WINDOWS] | No | Describes the main WinHelp window and any secondary window types in the help file. | |||
| [BAGGAGE] | No | Names any additional data files that are to be incorporated within the WinHelp file. | |||
Microsoft Help Workshop is a DOS application that converts .RTF files to the format required by WinHelp .HLP files, incorporates graphics files, and creates the required look-up tables for help context strings and context IDs. Select the Windows 95 Help icon (or whatever icon is assigned to the help compiler) to start Microsoft Help Workshop. Load the help project file either by selecting File | Open or by selecting from the MRU file list if the project help file was previously opened.
Figure 23.13 shows the results of compiling the Helpex.hpj file using Microsoft Help Workshop. A number of errors were flagged in the compilation stage, but the help file was generally usable for testing purposes. (However, you wouldn't want to distribute a help file with these errors.)
Figure 23.13. Compiling HELPEX.HPJ in Microsoft Help Workshop.
TIP
You can find the cause of an error (and suggested fixes) by searching the Microsoft Help Workshop help file for the error number. In Figure 23.13, the help error message HC1003 is highlighted, and the appropriate Help Author's Guide topic is displayed.
Microsoft Help Workshop can run in a noninteractive mode. This mode isn't documented by Microsoft, and programmers shouldn't need it directly. Microsoft Help Workshop is called in noninteractive mode by Visual C++ 4 when a project's help file is being rebuilt.
One of the newest and most extensive products to assist programmers in developing help files is from Blue Sky Software. This section looks at this suite of products, which form a comprehensive tool for Windows software developers who are documenting their products. WinHelp Office 95 is available at an introductory price of $599. The core of WinHelp Office 95 is the RoboHELP help development engine. WinHelp Office 95 includes the following tools:
The following sections take a quick look at each of these tools.
RoboHELP 95 turns Microsoft Word 7 for Windows 95 and 32-bit Word 6.0 and 7.0 for Windows NT into hypertext authoring tools. RoboHELP 95 includes both 32-bit and 16-bit versions of RoboHELP, thereby providing support for all versions of Microsoft Word. RoboHELP includes an Enhanced Hotspot Editor, a screen capture utility, and much more.
RoboHELP 95 is a 32-bit version of RoboHELP that turns Microsoft Word 7 for Windows 95 and Word 6 for Windows NT into high-performance hypertext authoring tools. A 16-bit version of RoboHELP is included with RoboHELP 95 to provide support for Microsoft Word 6 and Word 2 for Windows 3.x.
RoboHELP guides you through the entire process of creating help systems and electronic Hypertext documents, from standard help features such as jumps, topics, and pop-ups to advanced features such as macros, secondary windows, and colors. RoboHELP 95 supports all the new Windows 95 help features.
RoboHELP automatically converts existing documentation into a help system or vice versa. You also can import existing help systems, graphics, and documents.
RoboHELP 95 includes a variety of new and improved features specifically designed to streamline the process of creating help systems for Windows 95 and Windows NT:
An enhanced tool palette
New Windows 95 templates
A Contents tab composer
Easy creation of a-links and k-links
New help macro support
More support for Visual Basic
Multimedia support
Advanced graphic support
Authorable button support: shortcuts and see also buttons
Easy creation of What's This? context-sensitive help
SmartHelp OLE control
The new SmartHelp OLE control included in RoboHELP 95 eliminates the need to program context-sensitive help into any application developed with Visual Basic 4.0, Visual C++ 4.0, Access 95, Visual FoxPro 3.0, or other environments that support the OLE control standard.
The WinHelp Video Kit provides everything you need to integrate video and sound into Windows help systems and to create "live" video product tutorials. The WinHelp Video Kit includes a Software Video Camera, a Video Wizard, a Video Tester, a Video Player, and Video for Windows Runtime.
The Moving to WinHelp '95 Kit provides you with the tools to quickly convert Windows 3.x help systems to Windows 95 help systems. It also comes with the first book solely dedicated to Windows 95 help. This kit is intended to make the transition to Windows 95 help fast and easy.
WinHelp HyperViewer lets you give Windows 3.x help systems the look and feel of Windows 95. WinHelp HyperViewer features a powerful full-text search, multiple-topic printing, and an expandable, collapsible hypertext view of the entire help system.
The WinHelp Tool Kit is a collection of powerful tools. It includes Help-To-Word, Help-To-Source, WinHelp Inspector, WinHelp BugHunter, WinHelp Graphics Locator, WinHelp Graphics Library, and WinHelp Internet Access. The following list describes some of these tools.
WARNING
The WinHelp Tool Kit includes tools that "decompile" Windows help files into Word for Windows .DOC and .RTF files. This functionality is quite valuable when you no longer have access to the original source files, for example. However, you should be careful not to violate copyright laws by decompiling help files for products for which you have no right to do so.
With the Mastering WinHelp video, you can become productive immediately and create professional help systems with a minimum amount of effort. Mastering WinHelp also includes advanced tips for experienced users and a WinHelp sample disk for Windows 95.
The process of manually creating help files for Visual C++ applications is thoroughly documented in Microsoft's Help Compiler User's Guide and the Help Author's Guide. Today, few help-file authors write help files in the manner described in the Help Compiler User's Guide. Third-party help-file authoring applications, such as Doc-To-Help by WexTech Systems Inc. (New York) and RoboHELP 95 by Blue Sky Software (San Diego), speed the organization and writing of help files. This book assumes that most database developers possess the writing skills that are needed to prepare a better-than-adequate manual for the application. Developers who aren't authors by nature usually employ technical writers to prepare the required written documentation. Therefore, this chapter is oriented toward the design and use of text from the application manual as the basis for your application's help file(s). Almost without exception, Word for Windows is the preferred application for creating the rich text format (.RTF) files needed by the help compiler that you use to create the final WinHelp (.HLP) file. All commercial help-file generation applications are based on Word for Windows.
Doc-To-Help 2.0, which works with Word for Windows 95, allows users to create and distribute commercial-quality printed documentation and sophisticated Windows 95, 3.1, and 3.0 help files from a single source without compromise in either medium or any platform. Doc-To-Help 2.0 includes the following:
Users will also find updated versions of the Doc-To-Help Hyperformance Tools, providing Doc-To-Help Navigator, video support, and watermark support for 32-bit WinHelp. The Microsoft Windows 95, 3.1, and 3.0 help compilers are included in this package.
New to Doc-To-Help 2.0 are Topic Types. Using this feature, help authors can mark topics as conceptual, procedural, or context-sensitive. Doc-To-Help makes sure that the topics appear automatically in the correct Help window and with proper formatting. Doc-To-Help 2.0 also offers a "smart" contents tab feature, which allows the help author to place the Doc-To-Help Navigator in the Help topics contents tab. This gives help authors greater flexibility in creating and controlling the contents tab's hierarchical outline.
Doc-To-Help consists of the following components:
Doc-To-Help has a preset collection of styles that are likely to meet your needs if your client or firm hasn't already established a set of graphic-design standards. You can alter these basic styles to suit others' requirements or your own taste in layout and typography.
One of the advantages that authors of application manuals have over authors of developers' guides for software is that the application itself provides the organizational framework for your work. The structure of your application's manual is dictated by the relationship between the forms that constitute the user interface of your application. Thus, a database application manual consists of the following major sections or topics:
Figure 23.14 shows a sample Doc-To-Help document, D2HSETUP.DOC, in Word for Windows' outline mode. This help document has three heading levels; thus, D2HSETUP.DOC typifies the structure of help files for Windows applications. Writing your manual with one of Doc-To-Help's standard templates attached simplifies the help-file conversion process. Alternatively, you can convert existing manuals to Doc-To-Help's format by importing the styles contained in the standard Doc-To-Help template. The graphics shown in D2HSETUP.DOC import directly into your help file.
Figure 23.14. A Doc-To-Help manual shown in Word for Windows' outline mode.
NOTE
Don't forget that Doc-To-Help has a toolbar that may be used in Word for Windows when you're creating or modifying a help file. A programmer can save a great deal of time and effort by using toolbars.
After you've completed and printed proof copies of your application manual, you convert the manual to a Microsoft rich text format (.RTF) file. Rich text format files are text files that include embedded page-, line-, and character-formatting instructions. Doc-To-Help adds several menu choices to Word for Windows' Tools and Format menus that display special-purpose dialog boxes in which you select options for converting your manual to the required .RTF file and compiling the .RTF file to a help file. Figure 23.15 shows the dialog box for the conversion step, and Figure 23.16 shows the dialog box for the compilation step. When you click the OK button of the Reformat As Help File dialog box (shown in Figure 23.15), Doc-To-Help creates an .RTF version of the Word .DOC file and then displays the Compile dialog box. When you click the OK button of the Compile dialog box (shown in Figure 23.16), Doc-To-Help creates a help project file (.HPJ) and runs the help compiler to create the .HLP file.
Figure 23.15. The Doc-To-Help Reformat as Help File dialog box.
Figure 23.16. The Doc-To-Help Compile dialog box.
The help project file (.HPJ) tells the compiler the names and locations of the .RTF and bitmap (.BMP) files to be included in the .HLP file. The structure of .HPJ files is similar to a Windows initialization file such as MSACCESS.INI and is related to the structure of the .MAK files used by Visual Basic and C compilers. Headings are enclosed in square brackets and are followed by related entries. Here is a truncated version of the D2HSETUP.HPJ file that is automatically generated by Doc-To-Help and that creates D2HSETUP.HLP:
[OPTIONS] INDEX=HelpContents1 ROOT=C:\DOC2HELP COMPRESS=FALSE TITLE=Doc-To-Help Introduction [FILES] C:\DOC2HELP\D2HSETUP.RTF [MAP] HelpContents1 1 ; Help Contents Overview.2 2 ; Overview HowDoc.To.HelpWorks.3 3 ; How Doc-To-Help Works AnExample.4 4 ; An Example You.reInControl.5 5 ; You're In Control [BITMAPS] C:\DOC2HELP\HELP0003.BMP C:\DOC2HELP\HELP0001.BMP
NOTE
Unless you specify otherwise, the names of the .RTF, .HPJ, and .HLP files are the same as the names of the source .DOC file. The extensions change to designate the type of file.
The preceding example of a help project file includes only sections and entries that are required to compile a simple help file with five help topics and two bitmaps. The .HPJ files for complex .HLP files become quite lengthy. Compiling a large help file can take several minutes on a slow computer, especially one that doesn't have enough RAM. After compilation, the Contents window of D2HSETUP.HLP appears as shown in Figure 23.17.
Figure 23.17. The Contents window of D2HSETUP.HLP.
You can include large bitmap files, such as images captured from the forms of your application, in both your manual and the help file. The Hotspot Editor (SHED.EXE) included with Visual C++ lets you assign help context strings to control objects on your form. When the user clicks a control object, the window that explains the purpose of the control object appears. Figure 23.18 shows how to create a pop-up window that displays information about the Command Line edit control in the sample dialog box.
Figure 23.18. Creating a pop-up window.
If you use SHED.EXE to assign help context strings to the buttons and other dialog box controls of the Run dialog box that is shown in the help file, you can cause a jump to the window that deals with each of these subjects when the user clicks the control in the Run dialog box. Figure 23.19 shows the bitmap illustration from Figure 23.18 opened in SHED.EXE. You drag the mouse pointer to define a rectangular area that serves as the hotspot. Then you assign the help context string of the help topic you want to jump to. When the user double-clicks the area defined as the hotspot, the command line's help topic appears.
Figure 23.19. Adding a help context string to a bitmap with the Hotspot Editor.
Each topic window requires a help context string that the WinHelp engine (WINHELP.EXE) uses to create a jump from the Contents window to the topic window. Help context strings are footnotes that are identified by the pound symbol (#).
If you want a specific help topic to appear when the user presses the F1 key, a feature called context-sensitive help, you need to assign a unique help context ID number to each of the topic and subtopic windows of your help file. You add help entries that contain the context string and the associated help context ID number as entries in the [MAP] section of your .HPJ file.
After you create the final version of your help file, you enter the context ID number of the topic that corresponds to the form or control object in your application as the HelpContextID property of the object. To test your help, run your application under Windows.
NOTE
If you assign values to the HelpContextID property of control objects on your form, the help topic window corresponding to the HelpContextID value of the control object with the focus appears when the user presses the F1 key. If you assign a value to the HelpContextID property of the control object that receives the focus when you open the form (the first object in the tab order), F1 doesn't open the help topic window assigned to the form itself. If you want F1 to open a help topic window for the form, make sure that you assign the form's help topic ContextID value to the ContextID value of the first control object in the tab order.
With C Windows programs, you can call the WinHelp() function to display the application's help file. If you're using Windows applications designed with AppWizard, you're better off calling the MFC CWinApp::WinHelp() function. With this function, you need to specify only the command and any additional data that might be necessary.
To control the action of the WinHelp engine with Visual C++ code, you call the CWinApp::WinHelp() function when you need to change a context ID value. The syntax of the CWinApp::WinHelp() function call, which calls ::WinHelp() (the sole help function contained in the USER.EXE DLL), is as follows:
virtual void CWinApp::WinHelp(DWORD dwData, UINT fuCommand);
Here is the Windows WinHelp() function's prototype:
BOOL WinHelp(HWND hWnd, LPCSTR lpszHelpFile, UINT fuCommand, DWORD dwData);
The Windows WinHelp() function returns a BOOL value which, if nonzero, indicates that the function was successful. The arguments of the WinHelp() function are explained in the following list:
Table 23.2 describes how the data of the dwData argument changes with the value of fuCommand.
| fuCommand Constant | Value | Description |
| HELP_CONTEXT | 1 | Causes a specific help topic, identified by a long integer specified as the dwData argument, to be displayed. |
| HELP_QUIT | 2 | Notifies WinHelp that the specified help file is no longer in use and can be closed. The dwData argument is ignored. |
| HELP_INDEX | 3 | Displays the index of the specified WinHelp file, as designated by the author. The dwData argument is ignored. |
| HELP_HELPONHELP | 4 | Displays help for using the WinHelp application itself. The dwData argument is ignored. |
| HELP_SETINDEX | 5 | Sets the context number specified by the dwData argument, a long integer, as the current index for the specified WinHelp file. |
| HELP_KEY | 257 | Displays the first corresponding topic found in a search for the keyword specified by the dwData argument—in this case, a string variable. |
| HELP_MULTIKEY | 513 | Displays help for a keyword found in an alternative keyword table. The dwData argument is a data structure (user-defined data type) containing the size of the string, the letter of the alternative table, and the keyword string. |
Listing 23.3 shows the additions that you make to the Declarations section of your module to take advantage of all the features that WinHelp() offers.
Listing 23.3. Declarations needed to use the WinHelp() function.
// Call CWinApp::WinHelp() // Define global constants for fuCommand #define HELP_CONTEXT 0x1 /* Display a specified topic */ #define HELP_QUIT 0x2 /* Terminate WinHelp for application */ #define HELP_INDEX 0x3 /* Display the Help index */ #define HELP_HELPONHELP 0x4 /* Display Help on using Help */ #define HELP_SETINDEX 0x5 /* Set the current Help index */ #define HELP_KEY 0x101 /* Display a topic for keyword */ #define HELP_MULTIKEY 0x201 /* Use the alternative keyword table */ #define KEY_F1 0x70 /* Key code for Help key */
You don't need to add the constants to your source file if you want to substitute the integer values shown in Table 23.2 as the fuCommand argument when you use the WinHelp() function.
Online help is a critical component of all but the most rudimentary database applications. This statement applies not only to Visual C++ Windows database applications, but also to database front ends you create in any language. This chapter isn't meant to be a substitute for the Help Compiler Guide, nor does it cover as much information as books that are devoted to authoring WinHelp files, such as Microsoft's Help Authoring Guide. If this chapter's examples of using the commercial help-authoring tools accomplished their purpose, you'll want to acquire one of these tools to accelerate the development of online WinHelp for your Visual C++ database applications.
The next chapter, the last in this book, describes how you organize the Setup application for your Visual C++ database front ends and how to manage the distribution of your applications on diskettes.
