COPYRIGHT

Simple Search
Copyright 2001 London Perl Mongers, All rights reserved

LICENSE

This script is free software; you are free to redistibute it and/or
modify it under the same terms as Perl itself.

URL

The most up to date version of this script is available from the nms
script archive at <http://nms-cgi.sourceforge.net/>

SUMMARY

Simple Search is a simple search engine that performs a quick search of
a website and displays links to files containing the text search for.

FILES

In this distribution, you will find four files:

search.pl   - The Simple Search Perl script.
README      - This file.  Instructions on how to configure and install
              Simple Search.
search.html - A sample HTML file demonstrating how to use Simple Search.
MANIFEST    - List of files included with the Simple Search distribution.

CONFIGURATION

There are a number of variables that you can change in search.pl which
alter the way that the program works.  $basedir and $baseurl are the two
most important variables, and must be altered to refer to your website.

    $DEBUGGING

        For debugging and/or testing purposes set this variable to 1;
        otherwise set it to 0.  When set to 1, errors will be output
        to the browser (however, this is a security risk, therefore it
        should not be set to 1 when the script is ready for public use).

    $emulate_matts_code

        Simple Search offers some facilities that are not present in the
        original MSA Simple Search:  if this variable is set to 1 then
        the program will work in a way that is similar to the MSA one, if
        it is set to 0 then the extra facilities will become available.

    $basedir

        This is the base directory (where each search will start);
        hence it should encompass everything you want searched.
        Files and directories you want blocked from the search should
        be placed in the @blocked array (described below); everything
        else will be searched.  The base directory and all directories
        below it (that you want searched) must be world readable and
        executable.  For example, this variable might be set to
        /home/larry/public_html/articles

    $baseurl

        This is the base URL, which is the URL relative to $basedir
        (mentioned above).  This variable will be used in generating
        links (URLs) relative to the files found containing the text
        search for.  For example, this variable might be set to
        http://www.webhost.com/~larry/articles

    @files

        This array contains the files to be searched.  There are a few
        special symbols you can use to describe those files.

            *   The star is a wildcard symbol.  It matches zero or more
                characters.  For example, '*.html' would match all files
                ending with '.html', while a single '*' would match every
                file.

            /   The forward slash is a directory delimiter.  It is used
                to separate directories of a single path.

            .   The period is used to indicate a file extension (usually
                an acronym used to identify the contents of a file).  For
                example, a file with the '.html' suffix usually contains
                HTML (the language used to write webpages).

        All files with a listed file extension that contain the text
        searched for will be displayed in the result of the search.

    $title

        This is the title that will be displayed on the search results
        page, and it will also be used as the text of the link intended
        to point back to your main webpage.

    $title_url

        This variable is intended to be set to the URL of your main web-
        page.  The associated hypertext will be the value of $title, and
        it will be displayed on the results page so that users can link 
        back to the search page (to perform another search).

    $search_url

        The URL of search.html. This is included on the results page
        so that users can link back to the search page to perform a new
        search.

    @blocked

        This is an array of files that will be blocked.  Full names,
        relative to $basedir are needed.  These files will NEVER show up
        in any search results.  If $emulate_matts_code is set to 0 then
        this may contain regular expressions to match the files to be
        blocked.

    @subdirs

        This is an array of sub-directories beneath $basedir that you
        might want to restrict your search to - see the description of
        the 'directory' CGI form parameter below for more information.
        This variable is only used if $emulate_matts_code is set to 0.

    $no_prune

        If $emulate_matts_code is set to 0 and and this is set to 1 then,
        rather than having to specify each level of sub-directory you want
        to search in @files, the search will go down into the sub-directories.
        If you do set this you probably want to be more careful of what you
        put in @blocked so that you are only searching in the things that
        you want.

    $style

        Used for script generated messages.  This should probably be the
        same as the one that you use for all the other pages.  This should
        be a local absolute URI fragment.  Set $style to '0' or the emtpy
        string if you don't want to use style sheets.

    $charset

        The name of the character set to use for the output document.
       
        
INSTALLATION

Simple Search is installed simply by copying the file search.pl into
your cgi-bin directory.  If you don't know the location of your cgi-bin
directory, then please ask your system administrator.

Depending on how the HTTP server is configured, you may need to rename
search.pl to search.cgi.  Again, your system administrator will know if
this is the case.

You will probably need to turn on execute permissions to the file
search.pl.  If you have shell access to the HTTP server, you can do this
by running the command `chmod +x search.pl` from the command line.
If you don't have command line access then there will probably be an
equivalent function (to change file mode) in your file transfer program.

Simple Search will scan and search all directories and subdirectories
from a start point (defined by $basedir).  There are 4 different
parameters that can be passed to it:  case, bool, and terms.

    case

        This parameter defines whether a search will be case-sensitive or
        case-insensitive.  The default is case-insensitive.

    bool

        If there is more then one term in the search query, this parameter
        defines whether the terms AND'ed or OR'ed.  The default is OR.

    terms

        This parameter contains the terms that will be searched.

    directory

        This optional parameter will only be used if $emulate_matts_code
        is set to 0.  It is the zero based index into the configuration
        variable @subdirs which allows you to specify an alternate
        starting subdirectory for your search: this might be useful if
        you have the content on your site arranged in categories by
        directory.  You will probably want to use a drop-down list so
        that users of Simple Search don't need to know the numbers.

See the search.html file bundled with the Simple Search distriubtion for
an example of how to fully construct a form to use with simple search.
As an example, a small form can be embedded into a page using a construct
similar to the following:

    <form method="post" action="/cgi-bin/search.pl">
        <input type="text" name="terms" size="40" />
        <input type="submit" />
    </form>

SUPPORT

For support with Simple Search please email:

    <nms-cgi-support@lists.sourceforge.net>
