home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1995 November / PCWK1195.iso / inne / podstawy / dos / 4dos / 4uzytki / 4dhs10.exe / HINDSITE.TXT < prev    next >
Text File  |  1993-12-20  |  15KB  |  352 lines
  1.                     Hindsite.btm  version 1.0
  2.  
  3.                       copyright Bob Larson 
  4.                         blarson@uiuc.edu 
  5.                         20 December 1993
  6.  
  7.  
  8.                               INDEX
  9. OVERVIEW
  10. REQUIREMENTS
  11. INSTALLATION
  12.      copying files
  13.      configuring cache-c.btm
  14.      configuring hs.btm
  15.      alias definitions
  16. USING HINDSITE
  17.    Refreshing the cache
  18.    Command completion
  19.    History recall
  20. BUGS, WARNINGS, and LIMITATIONS
  21. ACKNOWLEDGEMENTS
  22. COMMUNICATIONS
  23.  
  24.                             OVERVIEW
  25.    
  26.    Hindsite is pair of 4dos (c) batch files which provide several
  27. useful functions, including:
  28.  
  29.    *  Command completion.  Enter a partial command name on the
  30.       command line, and hindsite will display a window with
  31.       commands which the partial name could complete to.  This
  32.       includes internal commands, aliases, and external     
  33.       programs.  4dos extended wildcards are fully supported. 
  34.       Scroll through the window, select the command you want, and
  35.       you will be returned to the command line with the completed
  36.       command.
  37.  
  38.    *  Command correction.  Misspell a command, and instead of
  39.       receiving a "Unknown command" response, hindsite will display
  40.       a window of command names to select from. Select the correct
  41.       command, and you will be returned to the command line with
  42.       all arguments intact.  
  43.  
  44.    *  Hindsite also provides for csh-type history recall.
  45.       Entering "!!" on the command line will recall the last
  46.       command, and entering "!xyz" will recall the last
  47.       command which started with "xyz".  Other forms of
  48.       command recall available in csh are not currently
  49.       implemented in hindsite.
  50.  
  51.    Hindsite consists of two 4dos .btm programs:
  52.  
  53.    cache-c.btm: 
  54.       Creates a cache file of the names of internal commands,
  55.    alias, and executable files in directories accessible by the
  56.    path environment variable. The names of files with executable
  57.    extensions can optionally be included in the cache.  Keystroke
  58.    aliases are not included in the cache, and the set of internal
  59.    commands to be included in the cache is user defined.
  60.  
  61.    hs.btm:     
  62.       Invoked by the unknown_cmd alias introduced with version 5.0
  63.    of 4dos.  It is a batch file which is only executed when an
  64.    attempt is made to execute a command which 4dos is unable to
  65.    run.  When a correct command is executed, hindsite is not
  66.    executed at all.  When executed hs.btm will attempt to match the
  67.    command name with those listed in the cache file and/or files in
  68.    the current or specified directory.
  69.  
  70.                           REQUIREMENTS
  71.  
  72.    *  4dos version 5.0 or greater
  73.    *  Kstack.com, the 4dos keystack stuffing program, must be
  74.       loaded into memory.
  75.    *  One of a variety of grep programs is required by Hindsite.
  76.       Grep is a program similar to the find.com, but more powerful.
  77.  
  78.       Several grep programs are readily available, some of which
  79.       are free.  Grep and egrep have been tested and verified to
  80.       work.  Fgrep and sgrep will not work without modification of
  81.       hs.btm 
  82.    *  An included companion program, cache-c.btm must first be
  83.       executed before hindsite is operated.  Cache-c.btm creates a
  84.       cache file containing command, alias and external program
  85.       names which hindsite uses. 
  86.    *  Cache-c.btm requires a sorting program. This can either be
  87.       the sort program distributed with ms-dos, or preferably, a
  88.       sort program which has the ability to remove copies of
  89.       duplicate lines.  An example of such a program is a port of
  90.       the unix sort program. 
  91.  
  92.    *  For those with Internet access, all of the required programs
  93.       are available from Simtel mirror sites, in the msdos/gnuish
  94.       directory as well as the msdos/textutil directory.
  95.  
  96.                           INSTALLATION
  97.       
  98.    Several steps are required to install hindsite, including
  99. defining aliases and configuring both hs.btm and cache-c.btm
  100. so they can find required or optional external programs. 
  101. Configuring hs.btm and cache-c.btm is done by setting environment 
  102. variables within the batch files. Most variables are used to 
  103. point to external programs; these must point to the program itself,
  104. and NOT TO AN ALIAS!  Within these batch files aliases are temporarily
  105. disabled.  Please follow the instructions below.
  106.  
  107.                           Copying Files
  108.  
  109.    Copy cache-c.btm and hs.btm to a directory included in your path
  110. variable.  Both programs use one environment variable, %cmd_list,
  111. which contains the path and name of the cache file.  %cmd_list can
  112. be set by one of three methods:
  113.  
  114.    1) Use the set command prior to use of cache-c.btm or hs.btm. 
  115.       The set command can be issued from the command line or can be
  116.       placed in autoexec.bat or 4start.bat.
  117.  
  118.    2) Specify the name of the cache file on the cache-c.btm command
  119.       line:
  120.                cache-c e:\cmd.lst
  121.  
  122.       Cache-c.btm will then set the value of the %cmd_list
  123.       variable. If both methods 1) and 2) are used, option 2) will
  124.       take precedence.
  125.  
  126.    3) If neither option 1) or 2) are used, cache-c.btm will create
  127.       a file unique file and set %cmd_list on it's own.  The file
  128.       will be placed in the directory pointed to by the %temp
  129.       variable if it is set, or in the current directory otherwise.
  130.  
  131.  
  132.                      Configuring cache-c.btm
  133.  
  134.    Cache-c.btm must be configured so that it will know if external
  135. programs are to be used.  Near the beginning of hs.btm is a
  136. subroutine "config", where all options are selected.  There are
  137. four environment variables set in config, which the user can change
  138. the value of as follows:
  139.  
  140.    Variable: _sort_prog
  141.    Default: _sort_prog=sort 
  142.  
  143.       _sort_prog holds the path and name of the program used to
  144.    sort the command cache.  You can also specify options as
  145.    required.  For example, to use the unix sort program in the
  146.    directory tools on drive c:, specify that the sorting should be
  147.    case-insensitive, and that copies of duplicate lines be removed,
  148.    change the variable to read:
  149.  
  150.          set _sort_prog=c:\tools\sort -f -u
  151.  
  152.       If you opt to use the sort program supplied with ms-dos, no
  153.    options are needed. Just make sure you set the next variable,
  154.    _sort_unique,  to "y".
  155.  
  156.  
  157.    Variable:  _sort_unique
  158.    Default:  _sort_unique=y
  159.  
  160.       If _sort_unique holds the value "y" or "Y", a subroutine in
  161.    cache-c.btm will be used to remove duplicate entries in the
  162.    command cache.  If set to any other value, cache-c.btm will
  163.    assume that this has already been done by  the sorting program. 
  164.    Having this done by the sorting program is highly recommended,
  165.    as the subroutine in cache-c.btm is very slow.
  166.  
  167.    Variable: _sed_prog
  168.    Default: not set, commented out by "REM"
  169.  
  170.       Set this variable to the path and name of the stream editor
  171.    program sed.exe, if you have it.  In the default condition, a
  172.    subroutine in cache-c.btm will edit the alias names to make them
  173.    suitable for the command cache.  Again, sed works much faster
  174.    and is recommended.  
  175.  
  176.    Variable: exes
  177.    Default: exes=*.com;*.exe;*.bat;*.btm;
  178.  
  179.       exes contains the extensions of files which will be included
  180.    in the cache when cache-c.btm searches all directories in the
  181.    path variable.
  182.  
  183. Internal Commands:
  184.  
  185.       At the very end of cache-c.btm is a list of 4dos internal
  186.    commands which will be added to the cache.  This list may be
  187.    added to or deleted from as desired.
  188.  
  189.                        Configuring hs.btm
  190.  
  191.       hs.btm requires one environment variable, which specifies the
  192.    name and location of the grep program.  It is located in the main
  193.    routine near the start of the file.
  194.  
  195.    Variable: _grep_prog
  196.    Default: _grep_prog=grep
  197.  
  198.       You can change this to specify the location and options of
  199.    the grep program you use.  To use the gnuish egrep in directory
  200.    tools on drive c, with the option to make the search case
  201.    insensitive, change it to:
  202.  
  203.          set _grep_prog=c:\tools\egrep -i
  204.  
  205.                         Alias definitions
  206.  
  207.    Hs.btm is invoked by the unknown command alias.  Before defining
  208. this alias, please be sure that the necessary  modifications to
  209. cache-c.btm and hs.btm have been made, and that cache-c has been
  210. executed so that a cache file exists.  Define the unknown_cmd
  211. carefully;  if it can not find hs.btm, it will enter an infinite
  212. loop and cause a stack overflow error.  The following is the format
  213. I suggest for the unknown_cmd alias (but entered on one line):
  214.  
  215. alias `unknown_cmd=iff %_batch == 0 then^c:\hs^else^echo Unknown
  216. command`
  217.  
  218.    With this alias defined, hs.btm will be invoked whenever 4dos
  219. is unable to find a command, alias, or external program, unless
  220. the error occurred from within a batch file.  4dos will
  221. automatically
  222. pass the bad command line to hs.btm.
  223.  
  224.    You may optionally define other aliases for invoking hs.btm. 
  225. For command completion, I find the following key alias to be
  226. useful:
  227.  
  228.       alias @@f5=**
  229.  
  230.    This will invoke hs.btm with whatever was on the command line,
  231. even if the command line was empty. It is also handy if you want to
  232. complete a command, but the part you have typed is another command
  233. e.g., you want to complete the command dirsort, and have only typed
  234. in "dir".
  235.  
  236. Users can define other aliases to invoke hs.btm, as long as they
  237. pass the command and it's arguments (if any) to hs.
  238.  
  239.                          USE OF HINDSITE
  240.  
  241. Refreshing the cache:
  242.  
  243.    If you use hindsite on a regular basis you will probably want to
  244. put cache-c.btm in your autoexec.bat file.  Unless it is the last
  245. command, make sure you use the "CALL" command to execute it, or the
  246. rest of autoexec.bat will not be executed.  Cache-c.btm can be
  247. rerun at anytime to update the cache file to account for changes in
  248. the path variable or if you add or delete aliases.  At present the
  249. only option is to completely recreate the cache file.  If the
  250. recommended sed and sort programs are used, however, this is not a
  251. very time consuming operation.  Whenever the cache file is
  252. refreshed it is unnecessary to explicitly define the location of
  253. the cache file; it will already be set in the %cmd_list environment
  254. variable.  
  255.  
  256. Command completion:
  257.  
  258.    Two different pop up windows are used by hindsite.  The
  259. circumstances  which cause each window to appear are described
  260. below.  One window contains command names (internal, alias, and
  261. programs on the path) from the cache file, and will have the 
  262. title "Commands".  The commands in this window are sorted
  263. alphabetically.  It is possible to distinguish what type each
  264. command
  265. is.  External command will be lower-case and have extensions,
  266. aliases will be lower-case and not have extensions, and internal
  267. commands will be upper-case and not have extensions.  
  268.  
  269.    The other window is the file completion window.  It is the same
  270. window which is displayed when you hot the F7 key, and is titled
  271. "Files".
  272.  
  273.    Which window pops up depends on the command line hindsite is
  274. given, where it finds matches, and how many matches it finds.  The
  275. following list the how hindsite will act under different
  276. situations:
  277.  
  278. 1) Command completion when no path is specified:
  279.  
  280.    In this case hs.btm will attempt to match the command line with
  281. commands listed in the cache file.  4dos wildcards are fully
  282. supported.  If an extension is specified, only names with the
  283. extension will match, and no aliases and internal commands will
  284. match.  The actions taken by hindsite depend on the number of 
  285. matches:
  286.  
  287. 0 match: Exit, restore the original command line, position the
  288.          cursor in the "home position" on the command line, and
  289.          invoke the 4dos filename completion window              
  290.          (normally f7).
  291.  
  292. 1 match: Return the completed filename.
  293.  
  294. >1 match:Pop-up the command window with matching commands. The user
  295.          can select the desired command, which will exit and return
  296.          the user to the modified command line. If the user does
  297.          not select a command, hindsite will act as if no commands
  298.          match (i.e., pop up the filename completion window).
  299.  
  300. 2) Command completion when a path is specified:
  301.  
  302.          Hindsite will assume the intended command is an external
  303.          program in the specified directory.  It will exit and pop-
  304.          up the filename completion window.
  305.  
  306. History recall:
  307.  
  308.          Two forms of history recall are implemented.  "!!" will
  309.          recall the last command, and !!search_string will recall
  310.          the last command which matches the search_string.  Any
  311.          arguments following !! or !search_string will be added to
  312.          the end of the recalled command.
  313.  
  314.    For history recall hindsite will use the history log file if
  315. available, otherwise it will dump the history stack to a file and
  316. read that.  Use of the history log should be quicker, but how much
  317. so will vary from system to system.   Note that unless you have a
  318. "histcopy = Y" directive in your 4dos.in file, the last command in
  319. the history stack which matches search_string may not be the most
  320. recent one executed.  
  321.  
  322.                  BUGS, WARNINGS and LIMITATIONS
  323.  
  324.    Hindsite will not act properly if it tries to complete a command
  325. when there is a redirection or piping symbol on the command line. 
  326. 4dos handles these before passing the command line to hs.btm.  Even
  327. if hindsite completes the command, the pipe or redirection will
  328. have already failed.  
  329.  
  330. Environment variables on the original command line will be expanded
  331. after command completion.
  332.    
  333.    A different situation occurs with aliases.  Preceding a command
  334. with a "*" to prevent alias expansion doesn't work with hindsite.
  335. In the current version the "*" is interpreted as a wildcard.
  336.  
  337.                         ACKNOWLEDGEMENTS 
  338.  
  339.    Robert Chung (chung@qal.berkeley.edu) originated the idea of
  340. using a disk-based command cache.
  341.  
  342.    Peter T. Breuer (ptb@dit.upm.es) tested an early version and
  343. providing useful feedback.
  344.  
  345.                          COMMUNICATIONS
  346.  
  347.    I would appreciate receiving any feedback, bug reports, wish
  348. lists etc.  The address blarson@uiuc.edu should be good at least
  349. through mid-1995.  After that, blarson@prairienet.org might
  350. be a better bet.  
  351.  
  352.      Oh, and BTW, hindsite version 1.0 is freeware.