Full-txt srch in Help: How to do it (II)

Subject: Full-txt srch in Help: How to do it (II)
From: Patrick O'Connell <patricko -at- EICON -dot- COM>
Date: Sun, 20 Mar 1994 13:14:00 PST

My apologies to anyone and everyone who was hoping to see this sooner; the
tail end of last week was gun-to-the-head time for me, it's been a while, and
it took a lot out of me.

SO...

At the end of Part I I said (ouch! my I's! ;-) that the .IND file was an
index of most every word in your .MVB file, and was used by the FTS functions
contained in the "magic" DLLs FTENGINE.DLL, FTUI.DLL, and MVAPI.DLL.

Basically what you need to provide FTS in a WinHelp file is your usual .HLP,
but compiled with certain macro statements in the project file and a few
other things (more on those later), the .IND file, and these three DLLs. What
you Actually Need To Provide depends on the target environment you're
compiling for:

Let's assume you've gone through the requisite steps (see below) to produce
an .HLP and an .IND. For Help for NT, YOU NEED NOT SHIP THE FTS DLLS;
they're already part and parcel (in 32-bit form, of course) of the NT
operating system. For Help for garden-variety Windows, YOU WOULD HAVE TO SHIP
THE FTS DLLS. I say "would have to" because the kicker is, I don't know if
this can be done legally. When I find out, I'll let everybody know.

I do believe that provided you're a Microsoft MultiMedia Development Kit
licensee (i.e., you bought a copy of the MMDK) and develop Viewer files with
it, you can distribute Viewer and the DLLs with your .MVBs. Don't take it
from me, though; ask Microsoft, or check your Viewer package, to be sure.
Also, your developer won't be able to use standard WinHelp API calls for
jumping to the contents topic, or for context-sensitive help; there are
equivalent Viewer API calls they'll have to use, probably to functions
embedded in MVAPI.DLL.

I have only ever seen a HLP/IND pair shipped with the magic DLLs in something
provided by Microsoft itself: the FTS-enabled version of the Visual Basic
Knowledge Base. I got this monster self-extracting ZIP from ftp.microsoft.com
in the Softlib/Mslfiles directory, which I'm sure also contains a number of
other such beasts. Other examples of FTSable HLPs provided by the Redmondians
can be found in the Win32 (read Windows NT) SDK documentation: you only get
the online .HLP version (but done niiiiiice, with extractable code examples,
and everything) with the base package. You want actual bound, PAPER books?
Better get another purchase order ready!

Seriously, though, not printing paper books takes OODLES away from the
per-unit cost of any piece of software; these savings can of course be passed
on to the customer. By the way, looks like online-only help, ot at least
minimal paper docs, is part of MS's grand plan for the future of their
documentation. If your employer generally likes to follow MS's example, you
should be thinking hard about online-only docs, and for decently usable ones
you DEFINITELY want full-text searching.


NITTY-GRITTY II: GENERATING YOUR .IND FILE
------------------------------------------
As of the release of the Win32 SDK CD-ROM, specifically the version
containing support for PCs based on DEC's Alpha chip, there are two ways to
go about this.

The first one is -- you guessed it -- use Viewer. I'm not about to reiterate
the entire contents of the Viewer docs here, BUT here's a precis, with
pointers because making an .MVB is not the end goal:

1) Starting with a Help project that compiles error-free, put the
[CONFIG]-section declarations described in the Viewer docs as "required for
full-text searching" in your project file (.HPJ). Then save this file, and
also save it as same-file-with-extension-MVP (e.g., FUBAR.HPJ ==>FUBAR.MVP).

2) From the Viewer project file you've just created, remove the [MAP] and/or
[ALIAS] sections, if they're there. Actually, this may not be necessary. Try
not executing this step and see what happens!

3) Create your BAG.INI file as described in the Viewer docs and put the
[BAGGAGE] section (also described) at the end of both your .MVP and .HPJ
files.

4) As described in the Viewer docs, copy the generic .STP and the other
little-tiny-but-necessary files from where you installed Viewer and rename
'em. Microsoft's default stopword file lacks a number of stupidly
obvious words, like 4 out of the 5 W's, so you probably want to build on
what's supplied. The bigger your stopword file, the smaller your index will
be.

5) Run BUILDDOC.BAT, which compiles the Viewer file, then runs the programs
necessary to create the accompanying .IND file (AHA!).

6) Chuck the .MVB file. Do NOT chuck the .IND file. Compile your Help file,
making certain BAG.INI is in the same directory (well, if you didn't do all
of the preceding in the same directory, it's a very good idea).

7) Open your Help file with the Help engine, click the _F_ind button, and
give FTS a spin!


The second way to generate an .IND file is to get the tools and
instruction-containing .TXT files off the Win32 SDK CD-ROM and follow the
instructions. I haven't explored this method yet, but Paul Dempsey, himself a
tech writer from MS who has appeared on the WINHLP-L list, implied to me
that you basically get an only-what-you-need subset of the tools supplied
with Viewer.

This makes sense -- or at least as much sense as MS has ever made by
distributing WinHelp tools to DEVELOPERS -- since at the moment to develop
apps for NT you pretty much need the Win32 SDK anyway.

Well, that's pretty much it. Anyone who wants to is free to distribute parts
I and II of this posting in any form whatsoever, via any medium (including
archiving for anonymous FTP access), in any part of the world, and to other
galaxies and/or universes, for that matter. All I ask is that you not remove
the attribution below. If your company, or you yourself benefit from the
information it contains, you COULD send a cool postcard from your neck of the
woods to me at the snail mail address given below, OR send me an e-mail
bursting with praise and worship, but you don't have to. :-)


Happy searching!
Patrick Brian O'Connell
Intermediate tech. writer, Eicon Technology Corporation
2196 32nd Ave., Lachine, Quebec, Canada
Net: patricko -at- eicon -dot- com
Snail mail home address as of March 1994:
359 Victoria Ave. Apt. 10
Westmount, Quebec, Canada
H3Z 2N1


Previous by Author: Full-txt srch in Help: How to do it (I)
Next by Author: FTS in WinHelp: All is not as it seems!
Previous by Thread: The Other 99 Percent
Next by Thread: Help a poor student...


What this post helpful? Share it with friends and colleagues:


Sponsored Ads