Searching a Collection of files

   Gn has two mechanisms to allow the user to create a small menu
   consisting of those items on a large menu whose files contain a
   particular search term. The first of these is described in this
   section. This method has the advantage of being much easier for the
   maintainer but will become slow if there are too many files being
   searched or the files are too large. It is appropriate if the number
   of files you wish to search is, say, less than 100 and the files
   themselves are at most a few hundred kilobytes (of course this depends
   on your particular hardware and your mileage may vary). If you have a
   large number of files or very large files, then using WAIS indexing
   may be a better choice. This is described in a separate document "The
   Waisgn User's Guide."
   
   In the remainder of this section we will describe the grep-like
   builtin search capabilities of gn. The example _gn_ server on
   hopf.math.nwu.edu there has a top level menu item which is called
   "Full text search of _gn_ documentation." When a user selects this
   item the client will prompt for a search term and then return a menu
   of all the available files in the documentation directory which
   contain the search term. The searches are case insensitive. In fact
   they use grep like regular expressions (see the UNIX man page for
   grep(1)). The searching is not done by actually invoking the UNIX grep
   program, however. Gn has its own builtin regular expression code.
   
   This feature is enabled by putting two entries in appropriate menu
   files. The first looks like this:

     Name=Documentation for the GN server
     Path=1s/docs

   
   
   This is just a minor modification of the normal entry for the
   directory "docs" which contains the documentation files we want to
   make available by _gn_. The only difference is that the path is
   "1s/docs" instead of "1/docs". The "s" that we are making the
   directory searchable, i.e. giving permission to run grep like searches
   of all the files which are listed in the menu file for the docs
   directory. Of course, docs must be a directory in the _gn_ hierarchy
   and it must contain a .cache file allowing files to be served by _gn_
   in the usual way.
   
   As yet, however, we have no menu item for the search. This is achieved
   with the second menu item:

     Name=Full text search of GN documentation
     Path=7g/docs

   
   
   The "7" indicates that this is a search type and the "g" indicates
   that this is a "grep" type search. In this example docs is a directory
   in the _gn_ root directory, but it could be lower in which case we
   would have the line Path=7g/foo/bar/docs. Both of these menu items
   might, as in this example, go in the same menu, but this is not
   necessary. You might, for example, want to have the "Full text search
   of _gn_ documentation" item occur in the menu which lists the
   documentation files, rather than menu which lists the documentation
   directory. Or you might want to have it occur in both menus, which is
   fine. This menu item can occur in any menu of your _gn_ hierarchy.
   But, of course, the "Documentation for the _gn_ server" menu item is
   corresponds to the physical directory "docs", so it must be in the
   menu corresponding to the directory containing "docs". In this example
   that is the _gn_ root directory.
   
   You can also do full text grep-like searches through any collection of
   directories (instead of a single directory) but it requires a little
   trick. Here's how you do it.
   
   In the directory whose menu you want to contain the search item (let's
   call it dir1) create a new directory (call it newdir). Take the menu
   files from all the directories you want to search, concatenate them
   into a single file and make it the menu file in newdir. Run mkcache on
   this concatenated menu file to produce a .cache file in newdir. Now in
   the menu file in dir1 put the follow entry:

     Name=Search a bunch of files from mulitple directories
     Path=7g/dir1/newdir

   
   
   then make a new .cache from this menu file. That's all there is to it.
   If you want also to have a menu visible to users showing all the files
   in the multiple directories you can add an item

     Name=List of a bunch of files from mulitple directories
     Path=1s/dir1/newdir

   
   
   to the dir1/menu file. But this isn't necessary.
   
   These searches are fairly efficient because _gn_ contains its own
   regular expression matching routines rather than externally calling
   the grep function. Regular expressions which the user can enter as
   search terms are essentially the same as those allowed by grep (see
   the man page grep(1)) with the addition of the special character ~
   which matches word boundaries.
   
.