

                             HFIND Version 1.0

                          Highlighting text FINDer



        HFIND is Shareware (see below).  This means you must pay for
        it if you continue to use it after a trial period.


   Description:

        HFIND's function is straightforward:  find text in text files.
        The reason you should choose HFIND over all those other text
        finders is simple.  HFIND highlights the text you were looking
        for when it displays the line in which the text was found.

        Especially if you use your PC's 50-line mode (included), it can
        be hard to see what you were looking for in a crowded screen
        full of search results.  HFIND highlights what it found in one
        of several ways.  

        If you use ANSI.SYS (or equivalent, see next section), the
        search target is indicated within its line by bright yellow
        text.  If ANSI.SYS is not present, the target is indicated
        by surrounding arrows.


   Installation:

        Put HFIND.EXE (and L50.COM if you wish, see below) in a
        directory in your path.  I keep a directory called UTIL on
        C: for just such goodies as HFIND and L50.


   Running the program:

        Now just type something like:

                hfind the readme.txt

        HFIND will display all the lines in this file that contain
        the text "the".  These may be contained within other words,
        or alone, HFIND is not particular.  (It is, however, picky
        about upper/lower case unless you tell it otherwise with the
        -i switch (see below)).  If there is more than one occurrence
        of the target in a line, only the first is highlighted.


   Details (if you forget these, just type HFIND for a quick view):

     Command line:

        HFIND [switches] expression filespec


     Switches (optional):
        -c : print only filename and (C)ount of the matching lines
                in each file

        -l : print only the names of the files that contain matching
                (L)ines

        -n : print the line (N)umber of each matching line before it

        -i : (I)gnore target's case

        -h : print filename with each output line (no mnemonic)

        -q : (Q)uiet, no highlighting even if available

        -f <filename> : the regular expression(s) are taken from the
                (F)ile whose name follows (the space between -f and
                filename is needed).  For example, HFIND TARGETS.LST
                *.TXT will find any of the targets listed in
                TARGETS.LST in all files with the extension TXT.
                The target file may contain targets separated by
                "|" or on separate lines.  Don't use enclosing quotes
                within the target file.

        Switches may be combined for brevity. For example,

           HFIND -nif targ *.c

        will ignore case, print line numbers, and take targets from the
        file "targ" when searching through all files *.c.

     Expression:
        An expression is a series of characters which may be enclosed
        in double-quotes.  For simple targets with no special characters,
        the quotes are optional.

        In order to include spaces in the target on the command line,
        you must enclose the entire expression in quotes (or use \s,
        see below).  Otherwise, DOS will treat each part as a separate
        command.

        The following characters have special meaning in an expression:

           .   - any character (wildcard)
           "   - a pair of these encloses the target expression
           \   - next character literal.  Used when looking for
                   otherwise special characters, e.g. to find a
                   period, enter "\.", to find a \, use "\\".
           \s  - space
           \t  - tab
           \n  - new line
           ^   - beginning of line
           $   - end of line
           *   - an expression followed by * matches 0 or more 
                   of that expression, e.g.  "ho*" matches "h",
                   "ho", "hoo", "hooo"...

           []  - surrounds a list of possible characters, case sensitive,
                   quotes required.  E.g. "[aeiou]" (quotes required)
                   finds any vowel
           -   - makes a range of letters or numbers within []s
                   E.g. "[a-f]" will find one of the first six letters
           ^   - when first within [] means any character BUT those listed
                   E.g. "a[^b]c" will not find 'abc', but will find
                   'aac', 'acc', 'adc'...

           |   - used only as an OR between targets, e.g. "yes|no" looks
                   for both "yes" and "no" and will print a line with each
                   if found.  Requires the surrounding quotes when used on
                   command line.

           any other character is taken literally.

        These can be combined willy-nilly to build the exact target you
        need.  Here is an example:

           HFIND -n "^[a-z][a-z]*[\s\t]*.*([^;]*)[^;]*$" *.c

        will produce a list of functions in a C program (try it!).


     Filespec:
        A single specification of file(s) to search in, pathname and
        wildcards are allowed, e.g. C:\TEXT\D*.T??.  Filenames are not
        case sensitive.


Special Requirements:

        In order to see the yellow highlighting (as opposed to the
        target being surrounded by arrow characters) some form of
        ANSI escape sequence processor must be installed.

        The traditional version, ANSI.SYS, is provided with DOS.  It
        is found in the DOS subdirectory and must be installed by
        CONFIG.SYS.  A line something like:

                DEVICE=C:\DOS\ANSI.SYS

        must be included.  See your DOS documentation for details.

        In addition, there are several products available that are
        faster/smaller/fuller/better than DOS's ANSI.SYS.  Some of
        these are PC Magazine's ANSI.COM, FANSI-CONSOLE, NANSI,
        NNANSI, VANSI, QUIKANSI...  These are available on bulletin
        boards, the Internet, from friends and coworkers...

        I use ANSI.COM from PC Magazine.  I have found, though, that
        my computers prefer that it not be loaded high.  (If you 
        don't know what that means, you needn't worry).


Suggestions:

        Since DOS has special meaning for the greater-than and less-
        than characters <> and the pipe character |, you must use the
        enclosing quotes if you are looking for them.

        If you wish to redirect HFIND's output to a file for further
        processing (or HFINDing), it is best to use the -q option.
        If you do not, the resulting file will contain the pointer
        characters.  This may affect further processing.

        If your search results in more than a screenful of results,
        you may wish to pipe the output through MORE.  This will
        cause the printout to pause at each screenful, waiting for
        you to press a key.  This is how this is done:

                HFIND targetstuff files | more

        MORE is a DOS command which should be in your path.  MORE,
        however, seems to defeat ANSI's processing (i.e. HFIND does
        not detect its presence).  So HFIND's results are indicated
        with the special characters instead of with the color yellow.


Files:
        HFIND.EXE   - the executable program
        README.TXT  - this file with registration form
        FILE_ID.DIZ - short description of the program
        L50.COM     - utility to set screen to 50 lines (type MODE 80
                             to return to 25 lines)


Shareware:

        Shareware distribution gives users a chance to try software 
        before buying it. If you try a Shareware program and continue 
        using it, you are required to register it.

        Copyright laws apply to both Shareware and retail software, and 
        the copyright holder retains all rights, with a few specific 
        exceptions as stated below. Shareware authors are accomplished 
        programmers, just like retail authors, and the programs are of 
        comparable quality. (In both cases, there are good programs and 
        bad ones!) The main difference is in the method of distribution. 
        The author specifically grants the right to copy and distribute 
        the software, either to all and sundry or to a specific group. 
        For example, some authors require written permission before a 
        commercial disk vendor may copy their Shareware. 

        Shareware is a distribution method, not a type of software. You 
        should find software that suits your needs and pocketbook, 
        whether it's retail or Shareware. The Shareware system makes 
        fitting your needs easier, because you can try before you buy. 
        And because the overhead is lower, prices are lower also. 
        Shareware has the ultimate money-back guarantee -- if you don't 
        use the product, you don't pay for it. 


Distribution:

        You are free to distribute this package only if all of the above 
        files are kept intact and are distributed together, and no fee, 
        charge or other compensation is accepted or requested without the 
        expressed written permission of Robert B. Peck. 

        Shareware disk vendors may NOT CHARGE a fee for HFIND. However 
        you may include HFIND on a diskette/CD-ROM for which you charge a 
        nominal distribution fee. The purchaser of said diskette must be 
        informed in advance that the fee paid to acquire the diskette 
        does NOT relieve said purchaser from paying the Registration Fee 
        for HFIND if said purchaser uses HFIND.

        Operators of electronic bulletin board systems (Sysops) may post 
        HFIND for downloading by their users without written permission. 
        A fee may be charged for access to the BBS as long as no specific 
        fee is charged for  downloading HFIND. 


Warranty and Limitation of Liability:

        HFIND is supplied as it is without any warranty of any kind, 
        either expressed or implied, including without limitation the 
        warranties of merchantability and of fitness for any purpose. In 
        no event shall Robert B. Peck be liable for any damages 
        whatsoever, including direct, indirect, incidental, consequential, 
        loss of business profits or special damages, from the use of 
        HFIND.  In no case shall Robert B. Peck's liability exceed the 
        license fees paid for the right to use the licensed software. 


Evaluation and Registration:

        HFIND is not free software.  This license allows you to use
        this software for evaluation purposes without charge for a
        period of 30 days starting at your first use.  If you use
        this software after the 30 day evaluation period, a
        registration fee is required. 

        In return for your registration, you will receive a 3.5" disk
        with the next version of HFIND on it (determined by need for
        updates and success of the program).  You will also be
        supporting the Shareware concept as well as contributing to
        the author's wellfare.

        So, register and tell me what you want to see in the next version.


Registering HFIND:

        Cost:
          1 copy         $10
          2-10 copies    $ 8
         11-35 copies    $ 7
         more than 50    negotiable

        Payment may be made in cash, money order or check, in US funds,
        payable and sent to:

          Robert B. Peck
          1005 Hollycrest Dr.
          Champaign, IL   61821-4205

          (email bpeck@prairienet.org)

        Use the following order form.  Please print clearly.

HFIND HFIND HFIND HFIND HFIND HFIND HFIND HFIND HFIND HFIND HFIND 


        Number of copies at $10 ea. _____
          OR
        Number of copies at $ 8 ea. _____
          OR
        Number of copies at $ 7 ea. _____

        Total cost: _________________________

        Name: _____________________________________________________

        Company: __________________________________________________

        Address: __________________________________________________

        City / State / Zip: _______________________________________

        Country: __________________________________________________

        Daytime Phone: ____________________________________________

        E-Mail address: ___________________________________________

        Which version of HFIND do you have ________________________

        How did you find HFIND ____________________________________

        How can future versions of HFIND help you better?










        Comments, good or bad:










HFIND HFIND HFIND HFIND HFIND HFIND HFIND HFIND HFIND HFIND HFIND

