
HINDEX V1.0, 05-NOV-2003 (updated 21-OCT-2004 with Itanium support)
  Copyright (c) 2003, 2004, Michael D. Duffy.  All rights reserved.

 ABSTRACT:

   This program will search an OpenVMS online HELP library file for a 
   keyword and report which help entries contain it.  The search is
   case-insensitive.

 DEVELOPMENT ENVIRONMENT:

   This program was developed using Compaq C V6.4-005 on OpenVMS VAX V7.3.
   It has also been built and tested on OpenVMS Alpha V7.3 using Compaq
   C V6.5-001-48BCD.  No source code modifications were required between
   The VAX and Alpha versions.  On 21-OCT-2004, this program was built
   successfully with no modifications on Itanum (HP c X7.1-056 on OpenVMS
   IA64 E8.2)

 TO BUILD:

   Compile and link the program:

     $ cc helpindex    
     $ link helpindex

   [Note: As downloaded from the freeware archive, the HINDEX kit includes
    object files and a command procedure to link them, for those users
    who may not have access to HP C. VAX, Alpha ("AXP") and Itanium
    ("IA64") versions are provided, and you must rename the files as
    appropriate (e.g., "$ rename hindex.vax_obj hindex.obj")]

   Optionally modify the HINDEX.CLD File:  Change the IMAGE line to specify 
   the proper disk and directory for your system.  Otherwise, the command
   procedure SETUP.COM will set the logical name HINDEX_DIR to be the current
   default directory, and perform the SET COMMAND automatically.

 TO RUN:

   $ set command hindex  ! Or add to system-wide command tables
   $ hindex searchstring [optional-qualifiers]

   Optional Qualifiers (all qualifiers are global.)

     /LIBRARY=filename   Specifies that the program should search a help 
                         library other than the default of 
                         sys$help:helplib.hlb.

     /WINDOW=(x,y)       Controls how many help text lines will be displayed
                         surrounding the line in which a match was found.
                         "x" specifies the number of preceeding lines,
                         while "y" specifies the number of subsequent lines.
                         If you omit /WINDOW, only the line(s) containing
                         the match will be shown.

     /NOWINDOW           Specifies that no help text lines at all should
                         be displayed.  Only matching level headings will
                         be shown.

     /DEBUG=number       Sets the internal debugging level.  Trace messages 
                         are enabled at various debugging levels.  This
                         feature is including for the convienience of
                         any programmers who wish to modify this program.

     /INCLUDE=(module, module [...])
                         Defines a list of modules in the help library
                         that will be searched.  If used, only the
                         listed modules will be searched.  All others
                         will be skipped.  If both /INCLUDE and /EXCLUDE
                         are specified, /INCLUDE will take precedence.
                         Example:  /INCLUDE=(TYPE, WAIT)  This specifies
                         that only the TYPE and WAIT top-level help
                         topics will be searched.

     /EXCLUDE=(module, module [...])
                         Specifies that all modules in the library
                         will be searched except those listed.  
                         If both /INCLUDE and /EXCLUDE are specified,
                         /INCLUDE will take precedence.  Example:
                         /EXCLUDE=(CC, HINTS)  This specifies that
                         the CC and HINTS top-level help topics will
                         be skipped and all others will be searched.

     /EXTRA              Controls whether an "extra" heading level is
                         displayed.  Some help text records begin at
                         the first byte.  Of these, some are appropriate
                         to be treated as another sub-level, and some
                         are not.  This qualifier, if present, requests
                         that such records will be included in headings.
                         Futute versions of this program will be smart 
                         enough to tell the difference and take the 
                         appropriate action automatically.

     /LISTMATCH=[EXACT,ABBREVIATED]
                         Controls whether values supplied with /INCLUDE
                         and /EXCLUDE must be spelled out fully
                         (/LISTMATCH=EXACT) or may be abbreviated
                         (/LISTMATCH=ABBREVIATED) in order to match a
                         module name.  The default is ABBREVIATED.

 PRIVILEGES REQUIRED:

   This program requires no elevated privileges.

 KNOWN PROBLEMS AND RESTRICTIONS:

   No problems are known at this time, but there is a restristion:

   This program looks for keywords, not phrases.  Do not attempt to use
   a phrase enclosed in quotes, as in:

        $ HINDEX "DCL Command"

   The quotation marks will become part of the search string and fail
   to match occurances.  If you were to modify the source to strip
   the quotation marks, the program would still fail to locate the phrase
   if it were to span lines in the help library.  A future version may
   remove this restriction.

 CONTACTING THE AUTHOR

   Comments, suggestions, and questions about this software can be directed 
   to the author.  At the time of this writing, the author may be contacted
   at duffy@process.com.  Also, Duffy regularly monitors the comp.os.vms
   newsgroup.  

 COPYRIGHT NOTICE:

   This software is COPYRIGHT  2003 MICHAEL D, DUFFY. ALL RIGHTS RESERVED. 
   Permission is granted for not-for-profit redistribution, provided
   all source and object code remain unchanged from the original distribution,
   and that all copyright notices remain intact.  You may modify your own 
   copy of the source code for your individual use, but you may not
   redistribute it.

 DISCLAIMER

   This software is provided "AS IS".  The author, Michael Duffy, 
   the archive maintainer, Hunter Goatley, and Process Software make no 
   representations or warranties with repsect to the software and 
   specifically disclaim any implied warranties of merchantability or 
   fitness for any particular purpose.

