The following sections are questions and answers that appear frequently in the WinHelp newsgroup, discussion list and forums. If you can't find an answer here, try posting your question to one of these WinHelp communities. If you are learning WinHelp, this section is a good resource, but you'd benefit more from books and seminars.
The following questions relate to the creation of topic (RTF) and project (HPJ) files for WinHelp. I have kept the information from the WinHelp 3.1 FAQ to the extent that it still applies to WinHelp 4.0.
Yes for WinHelp 4.0, no for WinHelp 3.1. Steve Pruitt was kind enough to compile the WinHelp 4.0 bug list, which has been maintained as the WinHelp compiler has been >
I believe a template is included with the Microsoft Windows 95 Help Authoring Kit : Guide to Creating Help Files for Windows 95 (Microsoft Professional Editions). Microsoft Word stylesheets for creating WinHelp that looks like Microsoft's are also available at a few Help Author web sites (try the KNOWware web site at www.kware.com). For more general writing guidelines, The Microsoft Manual of Style for Technical Publications is available from the Microsoft Press.
There are three ways. The first way works with Word 6.0 only, I believe:
1. Select Insert Symbol
Choose Normal Text, not Symbol font.
Select the copyright symbol
2. Hold down the Alt key and type 0169 (on the numeric keypad)
3. Insert the code {\'A9} (including the braces) in the .rtf file or your Word document.
Remember that WinHelp 3.1 and 4.0 both support the characters in the Symbol font . WinHelp 4.0 also supports the Wingdings font. In all cases, the user must have the specified font installed on their system to display the characters correctly in WinHelp.
The full-text search usually ignores topics with no title, so topics without a $ footnote won't appear in the results. Since most popup and What's This? Help topics don't require titles, removing the $ footnote is a workable solutions. I said FTS usually ignores untitled topics because the FTS options allow the user to include untitled topics.
It sounds like a simple question, but it's not. There are a number of reasons to use secondary windows, and several issues with how they're used. At some point, most authors find they need to display additional information while keeping the current information displayed. Secondary windows allow you to have multiple WinHelp windows open at one time, without having to launch another instance of WinHelp.
Other times, authors simply want to be able to display a particular type of information in a suitable window. Secondary windows allow you to control the size and positioning of windows, as well as the color of the scrolling and non-scrolling region. While you could do some of this with a main window and the PositionWindow macro, it's more convenient to use secondary windows.
For example, task help is often displayed in a long narrow window along on the right edge of the screen where it doesn't cover the application. Long, conceptual or reference topics are often displayed in a larger window. Secondary windows are also useful for graphics and tables that are too big for the main window.
Now to the how: Secondary windows are defined in the [Windows] section of the project file. Since HATs handle this task quite easily, I won't go into the syntax.
Once windows have been defined, you can specify a secondary window in macros and hotspots using the greater than sign (>) followed by the window name. This works in both WinHelp 3.1 and WinHelp 4.0.
For example, in a hotspot, using context_string>win2 (as the hidden text) would cause the topic specified by context_string to be displayed in the secondary window "win2". In the macro JumpID(`myfile.hlp>proc', `how_to_dance') would display the specified topic from "myfile.hlp" in the "proc" window.
To display a topic in a secondary window from an application, the programmer must include the window name following the help file name, just as in the JumpID macro. For example (using no particular language):
N=WinHelp(hwnd, "myfile.hlp>proc", HELP_CONTEXT, 12345)
In WinHelp 4.0, the > footnote can be added to a topic to specify a secondary window in which to display the topic when called from the index, FTS, or a related topics link (ALink or KLink macro). For jumps, macros, and calls from the application, you need to use ">window" even if the target topic has a > footnote to define its default window.
K keywords appear in the index, A keywords don't. That's the only significant difference. Use the KLink macro when you can build a related topics list using the structure of your Index. Use the ALink macro in combination with A keywords when you need to build list of related topics that don't correlate directly with the organization of the index. In other words, when you want to include specific related topics, regardless of how those topics appear in the index.
Mary Deaton has suggested using ALink macros extensively, even to replace normal jumps. That way you can specify a topic to display if the target topic doesn't exist. This can be more informative to the user than the stock "Topic Not Found" message. It's especially useful for modular help systems, where users may not have all components and help files on their system. (In this case, you can have a topic informing them that they haven't installed module X, and how they can get it.)
There's no easy way to get this done. WinHelp simply doesn't support sub- and super- script formatting. Most people resort to graphics, especially for displaying formulas. For standard superscript items like (tm), insert the symbol. If you need an inline subscript or equation, you're out of luck. Moving to HTML Help will solve this problem, if that's an option for you.
There are a number of DLLs available for launching a web browser and displaying a web page. The DLLs are good when users don't have a default browser specified. If your users are relatively up to date, you can get away with a simple macro:
ExecFile(`http://www.mysite.net/default.html',,0,)
will usually do the trick. Both Netscape and Microsoft browsers will set up the files needed to launch a URL from the command line. The ExecFile macro just takes advantage of this capability. (Hint: From the Start menu, select Run, and then enter a URL. Click OK, and your browser should launch directly to the page you specified.)
The best way to control the display of popups is to enclose the contents within a table. A single cell table works well. You can have footnotes inside a cell, although many HATs complain about this or can't do it directly. If you're using Word (or a Word-based HAT), you can create the topic normally and then add the table formatting.
An alternative to putting the footnotes in the cell is to put the footnotes in the first paragraph of the topic, followed by the table with the topic text and graphics. Then hide the first paragraph mark. When compiled, the topic will display without any extra white space. (Tip from William Meisheid)
Note: There is an absolute minimum width for a popup, at about 250 pixels.
Simple: It doesn't work. The \cb statement was never implemented by Microsoft. Ooops. In WinHelp 4.0, the SetPopupColor macro was added to give some control to authors (see HCW.HLP).
Yes on both counts. To change the color, prefix the hidden text (context string) with an asterisk (* also as hidden text). The hotspot will take the color of the hotspot text. To remove both the color and the underscore, prefix the hidden text with a percent sign (%, also hidden text). Again, the hotspot will take the color of the text. E.g., hotspot*context_string appears as a red, underlined hotspot in the compiled help.
Note: The following section was written for the original WinHelp 3.1 FAQ. To a large extent, all of this still applies to WinHelp 4.0. There was one change made that effects authors: If the user selects a non-standard color scheme in the Windows Control Panel, the background color settings in WinHelp are ignored. Always test color schemes thoroughly using a number of color schemes, including the ugly ones. [Charlie]
A certain amount of color can help the user find important information. Therefore, judicious use of color in a help system may be beneficial. The key words here, though, are "judicious" and "may".
Researchers into user interfaces seem to agree that overuse of color is significantly worse than under-use: too much color distracts the user from the message of the text, making it more difficult for them to understand what they are reading. (For those who have some experience in publishing: it's very similar to too many fonts on a page).
But there are other points, some of which are specific to PCs and the Windows WinHelp environment, that also argue against the use of colored text (or even hard-coded black!).
1. The user can set their own color scheme using Control Panel. This allows the user to choose the background color that most suits them. Hence, a help writer should NEVER assume that the background that their help text will be displayed on is white. It may, for example, be blue. If the help system contains blue text, it will be impossible to read on a blue background! And the "standard" black text is almost impossible to read on a dark blue background.
2. The user can set the color of the text of jumps and popups. If they set their jump color to, say, green, and you have green text in your help system, they WILL click on the non-jump green text. Frequently, they will click repeatedly, wondering why a new topic hasn't appeared. I have watched people do this several times (and I have done it myself).
3. You could overcome problem 1 by hard coding the color of the background as well. Most people who take this approach hard-code a white background. But a user who has changed the color of their background from the white default has probably done so for a good (to them) reason. Will they appreciate you forcing them to use a color they felt was not appropriate for them? Will you be encouraging them to use your help system? Or will you be encouraging them to look elsewhere, perhaps to a competing product which allows them to do things their way?
4. Monitors can differ markedly in their display of colors. Hence you have no way of knowing how the color scheme you carefully selected to look good on your monitor will look on the monitors of users. Two recent examples from my own experience may help explain this.
I frequently use two computers, each of which uses the same graphics card and the same driver. The monitors are different brands. Both monitors are good quality, reasonably expensive monitors. But a color scheme which looks good on one, looks atrocious on the other. The differences in the individual colors are not obvious; it is only combinations that show up the differences.
I recently wrote a program which displayed a graph (among other things). Several colors were needed for the graph, and one of the graph components I defaulted to red (though the colors were user-selectable). I ran this program on four different computers, all with different monitors. The default color scheme looked attractive (though not identical) on all monitors. I delivered the initial version of the software. The person paying for the software did not like my choice of red for the default for this graph component. When I saw the program running on their computer, I realized why. On the monitor they were using (yes, a cheap one), red was a horrible, washed out, sickly looking thing. The other colors were also different, but the red now clashed terribly with them all.
5. Don't forget that some users will probably be color-blind.
6. Different colors imply different things to different cultures, so if you want your help system to be read by people from more than one country, carefully consider any color choices you make.
And finally, you may wish to read the section on color in help systems in Chapter 4 of the Help Author's Guide, under "Formatting and Style" (Search on "Color" in the newer version of this file).
Switch to high-color mode (64K or more) and make sure all your users do the same. 256 color mode requires Windows to load palettes when displaying applications, graphics, and the desktop. Screen flashing is the result of palette changes when switching between applications. Because the desktop also has a palette, you may even see flickering simply by minimizing and restoring your help window. There's no way to completely stop screen flashes in 256 color mode.
The best way to reduce screen flickering when displaying graphics is to make sure all your graphics use the same 256 color palette. For online help, they should use the same palette as the application. It's especially important for all graphics displayed within a single topic to use the same palette. If the graphics use more that 256 colors between them, one or may graphics may not display properly at all.
There is a standard windows 256 color palette which an application may or may not use. Programs like PaintShop Pro (www.jasc.com) and PhotoShop (www.adobe.com) allow you to save palettes from, and apply palettes to, your graphics. Ulead (www.ulead.com) also has some excellent programs for managing colors and graphics. At the high-dollar end is a program called Debabelizer, which automates many of the tasks required for managing palettes in a graphics library.
This depends on the version of SHED that you're using. Most people are using the original SHED.EXE for WinHelp, which has not been updated since early WinHelp 3.1 days. To replace a graphic in this version, you must first copy it to the Clipboard. Then, with your SHG file open in SHED, select the Replace command from the Edit menu.
Pay attention to the color depth your system is using when you copy and replace graphics. Your display should be set to the minimum number of colors needed for your graphics (usually 16 or 256). If you are in high-color mode when you copy the graphics, the resulting file will use high-color (even if the original image used fewer colors).
If you can get your hands on SHED2.EXE (SHED for Viewer 2.0), MVSHED14.EXE (SHED for MediaView), you can use it for your WinHelp files. These more recent versions of SHED have an Import command on the File menu. Import allows you to replace the underlying graphic with any .BMP or .WMF file. It's also better at handling high-color graphics, and doesn't require changing your display settings when replacing bitmaps in SHG files.
First, make sure that you are using the short form of any macro commands (e.g., EF rather than ExecFile). IF you still get errors, it's usually because SHED.EXE was not updated for WinHelp 4.0, and it doesn't recognize any of the new macros. In this case, you can safely ignore the warning, provided you've checked your macro, and use the short form macros.
Paul O'Rear suggests testing and debugging macros where they'll be used in the Help file. He does this by pressing Ctrl+Shift+J while the relevant help topic is displayed. This displays a dialog box where you can enter any WinHelp macro. Enter the macro just as you would for a hotspot, including the exclamation mark. (It's a good idea to copy and paste your macro while testing). Once you've got the macro working properly, you can paste it into the RTF file or SHED.
There are several decompilers offered by HAT vendors, and also an excellent freeware utility called HelpDeco. Which one you should use depends on how much information you want to retain from the help file. If you have a HAT, check the documentation to see if you already have a decompiler.
If you don't have a decompiler, or if the one you have doesn't retain hotspots, context strings and mapping information, get the free HelpDeco. It's currently at version 2.1, which supports all versions of WinHelp and Viewer (and I believe MediaView files as well). It's available from a number of internet sites, including www.helpmaster.com and the library section at www.wextech.com.
Microsoft changed RTF slightly with the release of Word 6.0 which made it incompatible with the old help compiler. You need to get Release 505 (HC505.EXE) of the compiler.
Microsoft changed RTF again with the release of Word 8.0 (Word 97), which made it incompatible with the help compiler. You need to get version 4.02 or 4.03 of the compiler. Both are available for free. 4.02 has some bugs that were fixed in 4.02; 4.03 has some new bugs in Help Workshop, but nothing that affects compiling.
There are two possible reasons for this problem. First, because Microsoft changed the RTF export again, the standard Word 8.0 RTF is not compatible with earlier WinHelp compilers. Second, even if you are using an export filter specifically for WinHelp, there are new features in WinHelp that these compilers can't handle, such as floating text boxes.
There's some incompatibility between the WinHelp compiler's build tag handling and the way Word writes RTF tags. Certain information is lost, resulting in the error messages and formatting problems in the compiled help. A simple work around is to put two hard page breaks before topics that use build tags.
If you don't like the double-page break solution, I have a Word 7.0 macro that contains code which fixes the RTF file so that build tags are applied correctly. It's available by request (and unsupported).
This is usually limited to WinHelp 3.1 compilers and projects, although it is possible in WinHelp 4.0. There are several reasons this could be happening:
1. You can't paste bitmaps larger than 32k into a topic. The solution is to include them by reference using the \bml, \bmc, and \bmr commands.
2. You really are running out of memory. If you're using HC31 or HC30, try using HCP.
3. You don't have a TMP environment variable set in your PC's startup file. Most people already have a line in autoexec.bat that reads TEMP=C:\TEMP (or some other folder). You also need a line that says TMP=C:\TEMP (TMP=TEMP will also work).
4. You're hitting the limitations of the compiler, or of your systems. In the latter case, make sure you don't have other applications open while you compile.
Try increasing the number of file handles in your config.sys file to FILES=80 or higher. Also make sure that there is a setting in autoexec.bat that sets the variable TMP (without the E) to a valid directory (one that you have write access to, and which has sufficient space).
There are a number of causes for this, but the most common is a bulleted list that contains an item starting with a hotspot. If this is not the case, it is possible that the RTF file is corrupt. Remember that this is a warning message, and usually doesn't affect the compiled help.
These files are generated by Winhlp32.exe the first time it accesses a .hlp file, or if it detects and updated .hlp file. The .GID file is the global index to all the .hlp files that are included or linked in the CNT file. The .FTS file is the Full-Text Search index file; if more than one .HLP file is linked or indexed (specified in the .CNT file), the .FTG file is generated during the indexing process.
If these files are deleted, they will be regenerated the next time help is run (.GID only), or the Find tab is accessed and a Full-text Search index is created (.FTS and .FTG files).
WinHelp has always been more trouble-prone on NT than Windows 95. There were problems with the original Winhlp32.exe shipped with NT, and there are problems with how WinHelp is accessed by the operating system. These problems have been fixed in the NT service packs. If the problems occur on a machine that doesn't have the latest Service Pack (currently SP3), check the Microsoft Knowledge Base to see if your problem is fixed. Unless you know of a specific conflict or problem, recommend that your users keep their systems up to date with the latest Service Pack.
Yes. WinHelp has no problem running from a network, provided it's in a directory with a read-only restriction. (A Read Only restriction on the file alone is not sufficient). The read- only restriction is to ensure that WinHelp 4.0 creates the .GID, .FTS, and .FTG files locally for each user. If these files are on the network drive, they can cause problems for users that use mapped drive letters to access this directory.
Yes and No. In Windows 95 this is not a problem; on NT it is. Windows 95 is a 16/32-bit hybrid operating system. Winhelp.exe is a stub that passes all help files and related DLLs to Winhlp32.exe. Windows NT is a true 32-bit operating system, and uses a virtual 16-bit windows machine to run 16-bit applications and DLLs. (NTVDM and WOW are the processes used to simulate a Windows 95 environment within NT).
On Windows NT, 16-bit applications can only run inside the 16-bit virtual machine, they must use 16-bit help (Winhelp.exe). For that reason it's necessary to create Windows 3.1 Help for 16-bit apps that will be run on NT. You must also be careful about DLLs used with your help file. If a 16-bit DLL is used on NT, Winhelp.exe is started, even if the file is already open in Winhlp32.exe. (Some authors have heard about or seen the annoying "switching to Winhelp.exe" message, and know that the switch doesn't always succeed.)
Some HAT packages will simulate WinHelp 4.0 features with DLLs (HDK is a good choice for this, RoboHelp provides limited support), but you need to test these features thoroughly to make sure they work as expected in Windows NT.
For 32-bit applications, you can use Help Workshop to monitor WinHelp messages and check what the application is actually requesting. On Help Workshop's View menu, select WinHelp messages. Click the View menu again, and select Message options to specify how you want messages displayed.
For 16-bit applications, there is a program called HelpSpy (by Ron Burke) that monitors WinHelp messages. It may be available from some internet sites. Blue-Sky includes a program called Bug Hunter with their WinHelp Office, but it's not available separately.
You can also create your own test file: Create a help file in which the topic text matches the topic number (i.e., the topic that contains the text 123 has the map number 123). Create a topic for each map number in the range you expect. Make a copy of the test file, and give it the same name as your actual help file (don't forget to back this up). When the application calls help, the displayed topic in the test file shows the context number.
Yes. Both WinHelp 3.1 and 4.0 files can be started from the command line, using one of several switches to display a topic:
winhelp.exe [-K keyword] [-N context-number] [-I topic-id] HLP- filename
winhlp32.exe [[-H] [-G[n] [-S]] [-W window-name] [-K keyword] [-N context-number] [-I topic-id] [-P popup-id] HLP-filename]
WinHelp 3.1 uses WINHELP.EXE and WinHelp 4.0 uses WINHLP32.EXE, but the switches used to display a topic are the same. Note that Winhlp32.exe has additional switches (see command line switches in HCW.HLP), including one that's not documented. The -S switch is used with the -G switch to create the .GID file during a programs setup. Using -S hides WinHelp, so the user doesn't see the "Preparing Help file for first use" message. It should not be used with any other switch.
You can't. It's been an issue since WinHelp 3.1, and it's never been resolved. The break occurs because of the change in formatting. If you include the punctuation mark in the hotspot (perfectly valid in WinHelp), the line break will be correct.
WinHelp 4.0 is designed for modular help, with multiple files linked together to share the Help Topics dialog (that is, to display a combined contents, index, and full-text search). Unfortunately, when files aren't linked, WinHelp only displays the Help Topics from first file - the file whose GID file was accessed. The problem is that WinHelp doesn't easily switch GID files, even when you jump to another .HLP file.
John Hunt and some other users experimented with ways to get around this design so that the correct Help Topics display after an interfile jump. The two best workarounds were: 1) Use the JumpKeyword macro if possible. This forced the correct index to be used, but left the Back button working, in which case the wrong index would appear again (this time file B's index would display in file A). 2) Use an ExecFile macro to launch another help session, using the command line switches to display the desired topic. In this case Back is disabled.
Most likely you have first and second level keywords, and they appear to be out of order. This occurs because the index level separator (usually a comma or colon) is treated as part of the keyword when sorting. For example, the K footnotes in the left column below would produce Index entries shown on the right.
| K footnotes | Displayed in Index |
| K Windows | Windows |
| K Windows, opening | Windows NT |
| K Windows, closing | Windows, closing |
| K Windows NT | opening |
The workaround is to include the separator with at least one instance of the first level keyword:
| K footnotes | Displayed in Index |
| K Windows, (notice the comma) | Windows NT |
| K Windows, opening | Windows, |
| K Windows, closing | closing |
| K Windows NT | opening |
This still isn't perfect, because Windows NT should follow windows. However, it's an improvement over the split entries that appeared in the first example.
There are two possible problems here: First, under Windows NT, all 16-bit applications are run in a "Virtual DOS Machine" that simulates the behavior of 16-bit windows. This causes Winhelp.exe to be used for displaying help. If you have compiled your help using the WinHelp 4.0 compiler, the message is correct, and you should recompile your help using a WinHelp 3.1 compiler (and limit your help to WinHelp 3.1 features).
Second, there was a bug in NT where 32-bit applications could not start Winhlp32.exe if a 16-bit help was already running in Winhelp.exe. This bug will be fixed in NT 4.0 Service Pack 4; a separate fix is available for systems that have Service Pack 3. (See KB article Q169020 if it's available; it had been pulled at the time of this writing.)
The Contents tab is not based on the compiled help, but rather on the CNT file. If you didn't include the CNT file with your help, or if the user didn't install it, then the Contents file can't be displayed. Once the CNT file is copied to the same directly as the HLP, it should display the next time the help file is run.
Another possibility is that the programmer is calling a contents topic directly, rather than the Help Topics dialog. Check with the programmer to see how the Help Contents command was implemented. In WinHelp 4.0, the WinHelp API function has a new HELP_FINDER command (value = 11, or 0x0B) that specifies the Help Topics dialog box. If the programmer is still using HELP_CONTENTS, change it to HELP_FINDER.
Context sensitive help doesn't start a full WinHelp session, and as a result, jumps from a context sensitive help popup to a topic in a window don't work. The work around is to use a Jump macro instead. A JumpID or JumpContext macro forces WinHelp to start a full session for the specified HLP file (if it's not already running). Note that these workarounds sometimes fail as well.
Not without a lot of macros. By default, each window keeps its own history. Microsoft created a workaround for this solution, which you can see if you use the help in any Office 95/97 application (e.g., Word or Excel). The work around is a long macro, placed in each topic of the RTF file (except popups). If you use this macro, make sure you omit the quotes, and use the short form of all commands.
You can use QuickHelp from Altura Software (www.altura.com). QuickHelp will convert your .RTF files, .BMPs, etc and converts them into a format that is compatible with their QuickHelp interpreter. You can also use the Macintosh version of WinHelp that comes with Excel to view already made .HLP files. There is also a third party compiler available from Steve Sweet (www.sweetsteve.com) for a very reasonable price. Bristol (www.bristol.com) offers HyperHelp for Unix. HyperHelp uses your source files to compile a UNIX version of your WinHelp file. HyperHelp includes the viewer for Unix (a license fee is required for distribution).
WinHelp uses the class name MS_WINDOC for the main window when run as a standalone program however, when WinHelp is executed from the WinHelp() API function, the class name is MS_WINHELP. Also, secondary windows have the class name MS_WINSECONDARY.
Yes. These are the updated instructions (thanks to Michael Malcolm Andersen) based on the procedure that appeared in the WinHelp 3.1 FAQ:
Using the Full-Text Search Engines in WinHelp [Corrected MMA 950614]
Q: Can I add full-text search capabilities to my Windows Help file?
A: Yes. The problem is finding the tools to do it with. The full-text search engine of the Multimedia Viewer 1.0 is completely compatible with WinHelp. To create an index file from your help file, you'll need:
FORAGE.EXE
(FORAGEP.EXE)
W_SCAN.EXE
INDEX.EXE
(GETMLT.EXE)
The run-time support is in the following DLLs:
FTUI.DLL
FTENGINE.DLL
MVAPI.DLL
These were all available in the MDK (Multimedia Developer's Kit), now superseded by the Multimedia Viewer Publishing Toolkit (Viewer 2.0).
Viewer 2 also supports full-text searching, but the indexing is handled by the integrated Viewer compiler: no separate .IND file is created. The runtime DLLs are also different (MVFS2.DLL, MVFSTUI2.DLL, MVAPI2.DLL).
The Indexing programs (FORAGE, W_SCAN and INDEX) are now available in the Windows NT SDK (MSTOOLS\HLPINDEX directory), as included in the MS Developer's Library Level II CD sets. They are identical to the original Viewer 1 tools.
However, WinNT does *not* include the required 16-bit run-time DLLs, but comes instead with new 32-bit versions (FTUI32.DLL, FTENG32.DLL, MVAPI32.DLL).
The 16 bit DLLs are available from ftp.microsoft.com in some of the KnowledgeBase helpfiles (e.g. Softlib/MSLFILES/WFWG.EXE). They should also be found with any Multimedia Viewer 1.0 product (like my 1991 MS Boookshelf for Windows).
MMA: I've been told that the WFWG.EXE file mentioned above doesn't exist MMA: anymore and that the DLLs are on ftp in ftp.netcom.com in directory MMA: /pub/no/noring/WinHelp in file ftskit.zip.
Q: Suppose I have laid my hands upon the EXEs and DLLs required. What must I do next?
A: Say you have a Windows Help project called MYPRJ. First you must tell WinHelp where to find the full-text search routines. In MYPRJ.HPJ, add these lines to the [CONFIG] section:
[CONFIG]
; initialize DLLs
; RR("ftengine", "LoadFTEngine", "U") ; MMA: Not actually
needed!
; LoadFTEngine(0) ; MMA: Not actually needed!
RR("ftui", "InitRoutines", "SU")
InitRoutines(qchPath, 1)
; declare the main routines
RR("ftui", "ExecFullTextSearch", "USSS") ; MMA: Missing a
double quote!
RR("ftui", "SwitchToTopicsFound", "U")
; provide ways to use them: suit to your own taste
AddAccelerator(0x46,2,"SwitchToTopicsFound(hwndApp)")
CreateButton("btn_fts","FullText","ExecFullTextSearch(hwndAp
p,qchPath,`',`')")
Add the following line to the [BAGGAGE] section
[BAGGAGE]
bag.ini
{ Editor's Note: "bag.ini" must be all lower case. Baggage files are case sensitive. Not making it all lower case will produce errors. }
Save MYPRJ.HPJ.
"bag.ini" is a simple text file, that tells the full-text search engine the name of the index file, and whether several different help-files share one single index. The simple case is one .HLP file, one .IND file. bag.ini should look like this:
[bag.ini]
groupcount=3D1
group1=3DMYPRJ
[MYPRJ]
Title=3DMy Project
Indexfile=3DMYPRJ.IND
If you have two helpfiles that share an index:
[bag.ini]
groupcount=3D2
group1=3DMYPRJ1
group2=3DMYPRJ2
[MYPRJ1]
Title=3DMy Project I
Indexfile=3DMYPRJ.IND
[MYPRJ2]
Title=3DMy Project II
Indexfile=3DMYPRJ.IND
All the Indexfile=3D lines should be the same. You can have up to 15 groups. The same bag.ini file should be included in the baggage of all the help files.
Next you'll need a field-description file. It comes with the Viewer 1 and NT Helpindex tools (as GENERIC.FLD). If you don't have it, it's a simple textfile containing the following text:
topic [inline, search, stop]
filename [catalog, string]
address [catalog, fixed(4)]
length [catalog, fixed(4)]
topicTitle [catalog, trunc(32), string]
topicNSR [inline, search, stop]
MMA: The topicTitle line above was originally without the string parameter!
Finally there's the stop-words file. This is a text file containing words that need not be indexed, each on a separate line. Viewer 1 and NT come with GENERIC.STP, which contains a list of English words:
a
an
and
the
...
If your text is in a different language, you should provide your own .STP file. Viewer 2 comes with ready-made French and German .STP files. Since we're talking internationalization, one drawback of the Viewer 1 FTUI.DLL (solved in Viewer 2) is that the Full-Text Search dialog box is English only. Borland's Resource Workshop barfed on the dialog resource in the DLL (Did MS do this on purpose?).
OK, all is set now to create the full-text index. Viewer 1 and the NT SDK come with ready-to-run batchfiles, that in turn invoke a makefile that creates the actual index. In order the explain what's going on, we'll ignore the compexities of the makefile provided by MS.
For the simple case of one helpfile with one indexfile, you can create (or generate) a batchfile, to invoke the Help Compiler and the Indexing programs:
@ECHO OFF
hcp MYPRJ
echo.
forage /w MYPRJ.HLP
w_scan MYPRJ.ANS,MYPRJ.WRS,GENERIC.STP,GENERIC.FLD,MYPRJ.MLT,MYPRJ.LST;
rem MMA: ^^^^^^^^^ ^^^^^^^^^
rem MMA: The two files marked above should also be used in the call!
rem MMA: The MYPRJ.MLT file only contains two lines which are the title
rem MMA: from bag.ini and the name of the actual help file (see below).
index MYPRJ,,MYPRJ,GENERIC.STP,GENERIC.FLD,MYPRJ.MAP;
rem produced by FORAGE
del MYPRJ.ANS
rem produced by W_SCAN
del MYPRJ.CFG
del MYPRJ.LST
del MYPRJ.OCA
del MYPRJ.WRS
del MYPRJ.ZON
del MYPRJ.ZOS
rem produced by INDEX
del MYPRJ.MAP
rem think that covers all the garbage generated
If you have several helpfiles for which you want to create a single index, first create the .HLP files (using HC or HCP), then make the index with a batchfile like this:
getmlt bag.ini;
forage /m BAG.MLT
rem MMA: The forage line above was originally: forage /m bag.ini BAG.MLT
rem MMA: ^^^^^^^
rem MMA: The file marked above should *not* be used in the call!
w_scan MYPRJ.ANS,,GENERIC.STP,GENERIC.FLD,BAG.MLT,MYPRJ.LST;
index MYPRJ,,MYPRJ,GENERIC.STP,GENERIC.FLD,MYPRJ.MAP;
rem clean up the directory
GETMLT.EXE is a very clever program that reads a bag.ini file and produces the following output (given the bag.ini file above):
My Project I
MYPRJ1.HLP
My Project II
MYPRJ2.HLP
It needs two arguments (name of bag.ini and name of output .MLT file), but will only accept one (hey! let's make it interactive!). If I didn't have a program to generate all of this FTSearch stuff automatically, I'd even prefer to make the .MLT file by hand!
That's it. You should now have a file MYPRJ.IND to go with your help file(s). When you distribute the help file(s), just make sure that you include the .IND file, and the FTUI, FTENGINE and MVAPI DLLs.
Michael Malcolm Andersen, Andersen Development
E-mail: mma@datashopper.dk
Web: http://www.datashopper.dk/~mma/
There are a number of issues here. First, check with the programmer to see how the Help Contents command was implemented. In WinHelp 4.0, the WinHelp API function has a new HELP_FINDER command (value = 11, or 0x0B) that specifies the Help Topics dialog box. If the programmer is still using HELP_CONTENTS or HELP_INDEX, change it to HELP_FINDER.
If the programmers are attempting to use the HELP_TAB function, they should be notified that the documentation is incomplete and/or incorrect. From what we can tell it, works like this:
Programmers must define the command HELP_TAB = 0x000F (decimal 15). Then, to use the HELP_TAB command with the WinHelp API function, the dwData value (as integer) seems to work as follows:
If there are custom tabs defined, a value of 1 calls the first custom tab, 2 the second custom tab, etc. To call the standard tabs, use -3 for Contents tab, -2 for the Index tab, and -1 for the Find tab.
Calling HELP_TAB with any value greater than or equal to zero to a help system that has no custom tabs will always bring up the Contents tab.
In macros you can use the undocumented TAB (integer) macro (as discovered by Paul O'Rear): 0 displays Find tab, If there are any Custom tabs: 1 displays first custom tab, 2 displays second custom tab, etc. Any integer greater than the actual number of custom tabs displays the TOC tab.