Re: Full text search in WinHelp file

[Matt Abe <MATTA -at- LEONARDO -dot- LMT -dot- COM>]

Fellow TECHWR-Lers:

There have been a couple of inquiries about this topic on this list.
A comprehensive answer appeared on the WINHLP-L list, but as far as I
know, not on this list. So here it is.

BTW, HDK provides a redistributable DLL with its product that allows
full-text search. They also have a product called Hypershelf that
provides search capabilities across multiple Help documents.

Regards,

Matt Abe


------- Forwarded Message Follows -------

Date sent:      Thu, 15 Dec 1994 14:53:06 +1200
Send reply to:
                "Windows Help Compiler (WINHELP) Discussion List"
 <WINHLP-L%HUMBER -dot- BITNET -at- UBVM -dot- cc -dot- buffalo -dot- edu>
From:           Stefan Olson <stefan -at- OLSON -dot- MANAWATU -dot- GEN -dot- NZ>
Organization:   Olson Software
Subject:        Re: Full text search in WinHelp file
Originally to:  Winhlp-L -at- Admin -dot- HumberC -dot- ON -dot- CA
To:             Multiple recipients of list WINHLP-L
 <WINHLP-L%HUMBER -dot- BITNET -at- UBVM -dot- cc -dot- buffalo -dot- edu>

In <gate -dot- Ny5DXc1w165w -at- olson -dot- manawatu -dot- gen -dot- nz> "McMahon, Mick"
 <MMcMahon -at- VCRPMAP -dot- TELECOM -dot- COM -dot- AU> writes:
>I may have missed this thread, but can I do a full text search in a WinHelp
>file?
>A recent posting (since deleted-oops), listed files available on
>microsoft.com
> that gave full text search abilities.  Is this only in MM viewer or will it
>work on WinHelp files? If so what were those files?

This is taken from the WinHelp FAQ:
[6-1-2] Using the Full-Text Search Engines in WinHelp

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).


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")
LoadFTEngine(0)
RR("ftui", "InitRoutines", "SU")
InitRoutines(qchPath, 1)
; declare the main routines
RR("ftui", ExecFullTextSearch", "USSS")
RR("ftui", "SwitchToTopicsFound", "U")
; provide ways to use them: suit to your own taste
AddAccelerator(0x46,2,"SwitchToTopicsFound(hwndApp)")
CreateButton("btn_fts","FullText","ExecFullTextSearch(hwndApp,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=1
group1=MYPRJ
[MYPRJ]
Title=My Project
Indexfile=MYPRJ.IND

If you have two helpfiles that share an index:

[bag.ini]
groupcount=2
group1=MYPRJ1
group2=MYPRJ2
[MYPRJ1]
Title=My Project I
Indexfile=MYPRJ.IND
[MYPRJ2]
Title=My Project II
Indexfile=MYPRJ.IND

All the Indexfile= 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)]
topicNSR [inline, search, stop]

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:


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.  Viewer1 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,,GENERIC.STP,GENERIC.FLD,,MYPRJ.LST;
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.ini BAG.MLT
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.

--
------------------------------------------------------------------------
   Stefan Olson               Internet Mail: stefan -at- olson -dot- manawatu -dot- gen -dot- nz
   Olson Software                Compuserve: 100352,1315
   Ask about Help Writer's Assistant for Windows - the visual
   and easy way to write Windows Help files.
   (HWA10_1.ZIP and HWA10_2.ZIP on ftp.cica.indiana.edu)
   ----
   I have to pay for email so please ask before sending large messages.
------------------------------------------------------------------------