15 March 1999

       Description of SRE-http's "find best file matches" INTERPRETable addon

The MTCHFILE facility of SRE-http is used when a request selector does
not match a resource on your server.  That is, when no file can be found
that matches the requested file.  Its purpose is to present the client
with a list of "best matches" that she can then select.

These best matches are determined by looking at files in the directory
that the "selector" points to, and using a simple pattern matching
algorithim to determine what are the best matches.  Basically,
the more a file name looks like the name portion of the request selector,
the better a match it is.  


Usage:

   MTCHFILE.RXX is an "INTERPRETable" addon for SRE-http -- it is designed to be
   used in a
       <!-- INTERPRET FILE MTCHFILE.RXX -->
   "server side include" keyphrase.

  In particular, it is designed to be used in  "virtual not_found_url" files.
  An example of this  MTCHFILE.SHT.

  Thus, to use MTCHFILE (assuming that D:\www is your Goserve data directory):
     a) copy MTCHFILE.SHT to D:\www
     b) set NOT_FOUND_URL='virtual=mtchfile.sht' (use the SRE-http 
        configurator, or edit INITFILT.80). 
        (for details on NOT_FOUND_URL, see INITFILT.DOC)
        
  That's it!  Try to hit your site with a "misspelled" URL, and see what 
  happens.

  Once you are convinced that it works, you'll probably want to edit 
  MTCHFILE.SHT -- say, by adding a link to your "home page".


  
Discussion:

  By default, MTCHFILE.RXX produces a list of five "links", with
  each of the 5 items preceeded by a <LI>.

  For example, if your misspelled selector is /SAMPLES/GUDE.HTM, 
  then MTCHFILE.RXX might generate:

    <li><a href="/samples/guide.htm">guide.htm</a> <em>(41)</em>
    <li><a href="/samples/guideg.htm">guideg.htm</a> <em>(37)</em>
    <li><a href="/samples/guidetoc.htm">guidetoc.htm</a> <em>(33)</em>
    <li><a href="/samples/range.htm">range.htm</a> <em>(27)</em>
    <li><a href="/samples/dosearch.htm">dosearch.htm</a> <em>(26)</em>


  Note that the numbers in parenthesis are "scores", with a score of 100
  representing a perfect match.

  This default setup is designed to be used with an HTML list. For example,
  in your MTCHFILE.SHT, you could include:

     <p>Some possible matches:
     <ol>
        <!-- INTERPRET MTCHFILE.RXX -->
     </ol>

  Using the above example, this would display the following (pretend the 
  file names are clickable links):

    Some possible matches:

       1.guide.htm (41) 
       2.guideg.htm (37) 
       3.guidetoc.htm (33) 
       4.range.htm (27) 
       5.dosearch.htm (26) 


Can I prevent files from being displayed?
   
   Yes, any file named in the DIR_EXCLUSION parameter will NOT be displayed (and
   you can use * wildcard in filenames you include in the DIR_EXCLUSION list).
   Furthermore, any subdirectory named in DIR_EXCLUSION will NOT be checked
   (* wildcards are not supported for subdirectory names).

   Note that filenames (and subdirectories) are "relative" to a directory -- they
   should NOT be specified with path information (see INITFILT.DOC, or DIR.DOC,
   for a discussion of the DIR_EXCLUSION parameter).


What if the directory does not match?
 
   If the selector does not match to an existing directory, MTCHFILE.RXX will
   strip subdirectory names until if finds an existing directory.  The 
   usual virtual directory matches are attempted; with the final case
   (a / for a directory) always mapping to the GoServe data directory.

   For example (assuming the GoServe data directory is D:\WWW):
     a) if the requested selector is /SAMPLES/GROP10/TEST/PRICES.HTML
     b) D:\WWW\SAMPLES exists, but NOT D:\WWW\SAMPLES\GROP10
  then,
     MTCHFILE will look for (in order)
        D:\WWW\SAMPLES\GROP10\TEST
        D:\WWW\SAMPLES\GROP10
        D:\WWW\SAMPLES
     Since D:\WWW\SAMPLES exists, MTCHFILE will compare PRICES.HTML against
     all filenames in D:\WWW\SAMPLES. 

    Note that selectors that point to virtual directories work the same way --
    though the "ulimate" directory will always be the GoServe data directory. 
        

Configuring MTCHFILE

  You can modify the behavior of MTCHFILE by including "arguments". 
  The full syntax of MTCHFILE is:

      <!-- INTERPRET MTCHFILE.RXX  nshow, prefix, noscore, altname -->
 
  The 4 arguments are optional, and are:
       nshow = number of "best matches" to show. The default is 5
       prefix = string to place before matches. The default is <LI>
       noscore = if 1, then suppress display of the score
       altname = instead of matching the request selector, match altname

  Thus:

     <p>Some possible matches:
     <br>
        <!-- INTERPRET MTCHFILE.RXX 3, <BR> --*  ,1 -->
     <br>
  might return:

       Some possible matches:
       -- * guide.htm 
       -- * guideg.htm  
       -- * guidetoc.htm 
   
   
  The "altname" argument is somewhat odd -- if you use it, MTCHFILE.RXX is
  not dynamic.  However, there is a trick you can use: use an ALTNAME of 
  ?n, where is a number that points to the "nth" option following the
  ? in the selector (where options are seperated by & characters).

  Thus, 
    a) if the selector is /test/trymtch?samples/forh.doc
    b) if /test/trymtch.sht contains
         
      <!-- INTERPRET MTCHFILE.RXX  5, <li>, 0 , ?1 -->
     
   Then MTCHFILE.RXX will find the best matches to samples/forh.doc