                    Hindsite.btm  version 1.0
 
                      copyright Bob Larson 
                        blarson@uiuc.edu 
                        20 December 1993


                              INDEX
OVERVIEW
REQUIREMENTS
INSTALLATION
     copying files
     configuring cache-c.btm
     configuring hs.btm
     alias definitions
USING HINDSITE
   Refreshing the cache
   Command completion
   History recall
BUGS, WARNINGS, and LIMITATIONS
ACKNOWLEDGEMENTS
COMMUNICATIONS

                            OVERVIEW
   
   Hindsite is pair of 4dos (c) batch files which provide several
useful functions, including:

   *  Command completion.  Enter a partial command name on the
      command line, and hindsite will display a window with
      commands which the partial name could complete to.  This
      includes internal commands, aliases, and external     
      programs.  4dos extended wildcards are fully supported. 
      Scroll through the window, select the command you want, and
      you will be returned to the command line with the completed
      command.

   *  Command correction.  Misspell a command, and instead of
      receiving a "Unknown command" response, hindsite will display
      a window of command names to select from. Select the correct
      command, and you will be returned to the command line with
      all arguments intact.  

   *  Hindsite also provides for csh-type history recall.
      Entering "!!" on the command line will recall the last
      command, and entering "!xyz" will recall the last
      command which started with "xyz".  Other forms of
      command recall available in csh are not currently
      implemented in hindsite.

   Hindsite consists of two 4dos .btm programs:

   cache-c.btm: 
      Creates a cache file of the names of internal commands,
   alias, and executable files in directories accessible by the
   path environment variable. The names of files with executable
   extensions can optionally be included in the cache.  Keystroke
   aliases are not included in the cache, and the set of internal
   commands to be included in the cache is user defined.

   hs.btm:     
      Invoked by the unknown_cmd alias introduced with version 5.0
   of 4dos.  It is a batch file which is only executed when an
   attempt is made to execute a command which 4dos is unable to
   run.  When a correct command is executed, hindsite is not
   executed at all.  When executed hs.btm will attempt to match the
   command name with those listed in the cache file and/or files in
   the current or specified directory.
 
                          REQUIREMENTS

   *  4dos version 5.0 or greater
   *  Kstack.com, the 4dos keystack stuffing program, must be
      loaded into memory.
   *  One of a variety of grep programs is required by Hindsite.
      Grep is a program similar to the find.com, but more powerful.

      Several grep programs are readily available, some of which
      are free.  Grep and egrep have been tested and verified to
      work.  Fgrep and sgrep will not work without modification of
      hs.btm 
   *  An included companion program, cache-c.btm must first be
      executed before hindsite is operated.  Cache-c.btm creates a
      cache file containing command, alias and external program
      names which hindsite uses. 
   *  Cache-c.btm requires a sorting program. This can either be
      the sort program distributed with ms-dos, or preferably, a
      sort program which has the ability to remove copies of
      duplicate lines.  An example of such a program is a port of
      the unix sort program. 
 
   *  For those with Internet access, all of the required programs
      are available from Simtel mirror sites, in the msdos/gnuish
      directory as well as the msdos/textutil directory.

                          INSTALLATION
      
   Several steps are required to install hindsite, including
defining aliases and configuring both hs.btm and cache-c.btm
so they can find required or optional external programs. 
Configuring hs.btm and cache-c.btm is done by setting environment 
variables within the batch files. Most variables are used to 
point to external programs; these must point to the program itself,
and NOT TO AN ALIAS!  Within these batch files aliases are temporarily
disabled.  Please follow the instructions below.

                          Copying Files

   Copy cache-c.btm and hs.btm to a directory included in your path
variable.  Both programs use one environment variable, %cmd_list,
which contains the path and name of the cache file.  %cmd_list can
be set by one of three methods:

   1) Use the set command prior to use of cache-c.btm or hs.btm. 
      The set command can be issued from the command line or can be
      placed in autoexec.bat or 4start.bat.

   2) Specify the name of the cache file on the cache-c.btm command
      line:
               cache-c e:\cmd.lst

      Cache-c.btm will then set the value of the %cmd_list
      variable. If both methods 1) and 2) are used, option 2) will
      take precedence.

   3) If neither option 1) or 2) are used, cache-c.btm will create
      a file unique file and set %cmd_list on it's own.  The file
      will be placed in the directory pointed to by the %temp
      variable if it is set, or in the current directory otherwise.


                     Configuring cache-c.btm

   Cache-c.btm must be configured so that it will know if external
programs are to be used.  Near the beginning of hs.btm is a
subroutine "config", where all options are selected.  There are
four environment variables set in config, which the user can change
the value of as follows:

   Variable: _sort_prog
   Default: _sort_prog=sort 

      _sort_prog holds the path and name of the program used to
   sort the command cache.  You can also specify options as
   required.  For example, to use the unix sort program in the
   directory tools on drive c:, specify that the sorting should be
   case-insensitive, and that copies of duplicate lines be removed,
   change the variable to read:

         set _sort_prog=c:\tools\sort -f -u

      If you opt to use the sort program supplied with ms-dos, no
   options are needed. Just make sure you set the next variable,
   _sort_unique,  to "y".


   Variable:  _sort_unique
   Default:  _sort_unique=y

      If _sort_unique holds the value "y" or "Y", a subroutine in
   cache-c.btm will be used to remove duplicate entries in the
   command cache.  If set to any other value, cache-c.btm will
   assume that this has already been done by  the sorting program. 
   Having this done by the sorting program is highly recommended,
   as the subroutine in cache-c.btm is very slow.

   Variable: _sed_prog
   Default: not set, commented out by "REM"

      Set this variable to the path and name of the stream editor
   program sed.exe, if you have it.  In the default condition, a
   subroutine in cache-c.btm will edit the alias names to make them
   suitable for the command cache.  Again, sed works much faster
   and is recommended.  

   Variable: exes
   Default: exes=*.com;*.exe;*.bat;*.btm;

      exes contains the extensions of files which will be included
   in the cache when cache-c.btm searches all directories in the
   path variable.

Internal Commands:

      At the very end of cache-c.btm is a list of 4dos internal
   commands which will be added to the cache.  This list may be
   added to or deleted from as desired.

                       Configuring hs.btm

      hs.btm requires one environment variable, which specifies the
   name and location of the grep program.  It is located in the main
   routine near the start of the file.

   Variable: _grep_prog
   Default: _grep_prog=grep

      You can change this to specify the location and options of
   the grep program you use.  To use the gnuish egrep in directory
   tools on drive c, with the option to make the search case
   insensitive, change it to:

         set _grep_prog=c:\tools\egrep -i

                        Alias definitions

   Hs.btm is invoked by the unknown command alias.  Before defining
this alias, please be sure that the necessary  modifications to
cache-c.btm and hs.btm have been made, and that cache-c has been
executed so that a cache file exists.  Define the unknown_cmd
carefully;  if it can not find hs.btm, it will enter an infinite
loop and cause a stack overflow error.  The following is the format
I suggest for the unknown_cmd alias (but entered on one line):

alias `unknown_cmd=iff %_batch == 0 then^c:\hs^else^echo Unknown
command`

   With this alias defined, hs.btm will be invoked whenever 4dos
is unable to find a command, alias, or external program, unless
the error occurred from within a batch file.  4dos will
automatically
pass the bad command line to hs.btm.

   You may optionally define other aliases for invoking hs.btm. 
For command completion, I find the following key alias to be
useful:

      alias @@f5=**

   This will invoke hs.btm with whatever was on the command line,
even if the command line was empty. It is also handy if you want to
complete a command, but the part you have typed is another command
e.g., you want to complete the command dirsort, and have only typed
in "dir".

Users can define other aliases to invoke hs.btm, as long as they
pass the command and it's arguments (if any) to hs.

                         USE OF HINDSITE

Refreshing the cache:

   If you use hindsite on a regular basis you will probably want to
put cache-c.btm in your autoexec.bat file.  Unless it is the last
command, make sure you use the "CALL" command to execute it, or the
rest of autoexec.bat will not be executed.  Cache-c.btm can be
rerun at anytime to update the cache file to account for changes in
the path variable or if you add or delete aliases.  At present the
only option is to completely recreate the cache file.  If the
recommended sed and sort programs are used, however, this is not a
very time consuming operation.  Whenever the cache file is
refreshed it is unnecessary to explicitly define the location of
the cache file; it will already be set in the %cmd_list environment
variable.  

Command completion:

   Two different pop up windows are used by hindsite.  The
circumstances  which cause each window to appear are described
below.  One window contains command names (internal, alias, and
programs on the path) from the cache file, and will have the 
title "Commands".  The commands in this window are sorted
alphabetically.  It is possible to distinguish what type each
command
is.  External command will be lower-case and have extensions,
aliases will be lower-case and not have extensions, and internal
commands will be upper-case and not have extensions.  

   The other window is the file completion window.  It is the same
window which is displayed when you hot the F7 key, and is titled
"Files".

   Which window pops up depends on the command line hindsite is
given, where it finds matches, and how many matches it finds.  The
following list the how hindsite will act under different
situations:

1) Command completion when no path is specified:

   In this case hs.btm will attempt to match the command line with
commands listed in the cache file.  4dos wildcards are fully
supported.  If an extension is specified, only names with the
extension will match, and no aliases and internal commands will
match.  The actions taken by hindsite depend on the number of 
matches:

0 match: Exit, restore the original command line, position the
         cursor in the "home position" on the command line, and
         invoke the 4dos filename completion window              
         (normally f7).

1 match: Return the completed filename.

>1 match:Pop-up the command window with matching commands. The user
         can select the desired command, which will exit and return
         the user to the modified command line. If the user does
         not select a command, hindsite will act as if no commands
         match (i.e., pop up the filename completion window).

2) Command completion when a path is specified:

         Hindsite will assume the intended command is an external
         program in the specified directory.  It will exit and pop-
         up the filename completion window.

History recall:

         Two forms of history recall are implemented.  "!!" will
         recall the last command, and !!search_string will recall
         the last command which matches the search_string.  Any
         arguments following !! or !search_string will be added to
         the end of the recalled command.

   For history recall hindsite will use the history log file if
available, otherwise it will dump the history stack to a file and
read that.  Use of the history log should be quicker, but how much
so will vary from system to system.   Note that unless you have a
"histcopy = Y" directive in your 4dos.in file, the last command in
the history stack which matches search_string may not be the most
recent one executed.  

                 BUGS, WARNINGS and LIMITATIONS

   Hindsite will not act properly if it tries to complete a command
when there is a redirection or piping symbol on the command line. 
4dos handles these before passing the command line to hs.btm.  Even
if hindsite completes the command, the pipe or redirection will
have already failed.  

Environment variables on the original command line will be expanded
after command completion.
   
   A different situation occurs with aliases.  Preceding a command
with a "*" to prevent alias expansion doesn't work with hindsite.
In the current version the "*" is interpreted as a wildcard.

                        ACKNOWLEDGEMENTS 

   Robert Chung (chung@qal.berkeley.edu) originated the idea of
using a disk-based command cache.

   Peter T. Breuer (ptb@dit.upm.es) tested an early version and
providing useful feedback.

                         COMMUNICATIONS

   I would appreciate receiving any feedback, bug reports, wish
lists etc.  The address blarson@uiuc.edu should be good at least
through mid-1995.  After that, blarson@prairienet.org might
be a better bet.  

     Oh, and BTW, hindsite version 1.0 is freeware.