NAME
    File::Where - find the absolute file for a program module; absolute dir
    for a repository

SYNOPSIS
     #######
     # Subroutine interface
     #  
     use File::Where qw(pm2require where where_dir where_file where_pm where_repository);

     $program_module                  = is_module(@program_modules);
     @program_modules                 = dir_pms( $dir );
     @program_modules                 = program_modules( $dir, 'file_flag', @dirs);
     $file                            = pm2require($pm);
     @program_modules                 = repository_pms($repository);

     $abs_file                        = where($relative_file);
     $abs_file                        = where($relative_file, \@path);

     ($abs_file, $inc_path, $rel_fle) = where($relative_file)
     ($abs_file, $inc_path, $rel_fle) = where($relative_file, \@path);

     $abs_dir                         = where($relative_dir, '', 'nofile'); 
     $abs_dir                         = where($relative_dir, \@path, 'nofile'); 

     ($abs_dir, $inc_path, $rel_dir)  = where($relative_dir, '', 'nofile');
     ($abs_dir, $inc_path, $rel_dir)  = where($relative_dir, \@path, 'nofile');

     $abs_dir                         = where_dir($relative_dir); 
     $abs_dir                         = where_dir($relative_dir, \@path; 
     $abs_dir                         = where_dir($relative_dir, @path; 

     ($abs_dir, $inc_path, $rel_dir)  = where_dir($relative_dir);
     ($abs_dir, $inc_path, $rel_dir)  = where_dir($relative_dir, \@path);
     ($abs_dir, $inc_path, $rel_dir)  = where_dir($relative_dir, @path);

     $abs_file                        = where_file($relative_file);
     $abs_file                        = where_file($relative_file, \@path);
     $abs_file                        = where_file($relative_file, @path);

     ($abs_file, $inc_path, $rel_fle) = where_file($relative_file)
     ($abs_file, $inc_path, $rel_fle) = where_file($relative_file, \@path)
     ($abs_file, $inc_path, $rel_fle) = where_file($relative_file, @path)

     $abs_file                        = where_pm($pm); 
     $abs_file                        = where_pm($pm, \@path);
     $abs_file                        = where_pm($pm, @path);

     ($abs_file, $inc_path, $require) = where_pm($pm);
     ($abs_file, $inc_path, $require) = where_pm($pm, \@path);
     ($abs_file, $inc_path, $require) = where_pm($pm, @path);

     $abs_dir                         = where_repository($repository);
     $abs_dir                         = where_repository($repository, \@path);
     $abs_dir                         = where_repository($repository, @path);

     ($abs_dir,  $inc_path, $rel_dir) = where_repository($repository);
     ($abs_dir,  $inc_path, $rel_dir) = where_repository($repository, \@path);
     ($abs_dir,  $inc_path, $rel_dir) = where_repository($repository, @path);

     #######
     # Class interface
     #
     $program_module                  = File::Where->is_module(@program_modules);
     @program_modules                 = File::Where->dir_pms( $dir );
     @program_modules                 = File::Where->program_modules( $dir, 'file_flag', @dirs);
     $file                            = File::Where->pm2require($pm);
     @program_modules                 = File::Where->repository_pms($repository);

     $abs_file                        = File::Where->where($relative_file);
     $abs_file                        = File::Where->where($relative_file, \@path);
     $abs_dir                         = File::Where->where($relative_dir, '', 'nofile'); 
     $abs_dir                         = File::Where->where($relative_dir, \@path, 'nofile'); 

     ($abs_file, $inc_path, $require) = File::Where->where($relative_file)
     ($abs_file, $inc_path, $require) = File::Where->where($relative_file, \@path)
     ($abs_dir, $inc_path, $rel_dir)  = File::Where->where($relative_dir, '', 'nofile');
     ($abs_dir, $inc_path, $rel_dir)  = File::Where->where($relative_dir, \@path, 'nofile');

     $abs_dir                         = File::Where->where_dir($relative_dir); 
     $abs_dir                         = File::Where->where_dir($relative_dir, \@path; 
     $abs_dir                         = File::Where->where_dir($relative_dir, @path; 

     ($abs_dir, $inc_path, $rel_dir)  = File::Where->where_dir($relative_dir);
     ($abs_dir, $inc_path, $rel_dir)  = File::Where->where_dir($relative_dir, \@path);
     ($abs_dir, $inc_path, $rel_dir)  = File::Where->where_dir($relative_dir, @path);

     $abs_file                        = File::Where->where_file($relative_file);
     $abs_file                        = File::Where->where_file($relative_file, \@path);
     $abs_file                        = File::Where->where_file($relative_file, @path);
 
     ($abs_file, $inc_path, $require) = File::Where->where_file($relative_file)
     ($abs_file, $inc_path, $require) = File::Where->where_file($relative_file, \@path)
     ($abs_file, $inc_path, $require) = File::Where->where_file($relative_file, @path)

     $abs_file                        = File::Where->where_pm($pm); 
     $abs_file                        = File::Where->where_pm($pm, \@path);
     $abs_file                        = File::Where->where_pm($pm, @path);

     ($abs_file, $inc_path, $require) = File::Where->where_pm($pm);
     ($abs_file, $inc_path, $require) = File::Where->where_pm($pm, \@path);
     ($abs_file, $inc_path, $require) = File::Where->where_pm($pm, @path);

     $abs_dir                         = File::Where->where_repository($repository);
     $abs_dir                         = File::Where->where_repository($repository, \@path);
     $abs_dir                         = File::Where->where_repository($repository, @path);

     ($abs_dir,  $inc_path, $rel_dir) = File::Where->where_repository($repository);
     ($abs_dir,  $inc_path, $rel_dir) = File::Where->where_repository($repository, \@path);
     ($abs_dir,  $inc_path, $rel_dir) = File::Where->where_repository($repository, @path);

DESCRIPTION
    From time to time, an program needs to know the abolute file for a
    program module that has not been loaded. The File::Where module provides
    methods to find this information. For loaded files, using the hash %INC
    may perform better than using the methods in this module.

SUBROUTINES
  is_module

     $program_module = is_module(@program_modules);

    The "is_module" subroutine determines if a *$module* is present in a
    list of modules "@modules". The detemination is case insensitive and
    only the leading characters are needed.

  dir_pms

     @program_modules = dir_pms( $dir );

    The "dir_pms" subroutine returns the "@program_modules" in directory
    "$dir".

  program_modules

     @program_modules = program_modules( $dir, '$file_flag', @dirs);

    The "program_modules" subroutine returns the program_modules in the dir
    "File::Spec-"catdir($dir,@dirs) with an empty 'file_flag'; otherwise
    with a 'file_flag', "$dir" is a file specification and "program_modules"
    subroutine only uses the directory portion of "$dir".

  repository_pms

     @program_modules = repository_pms($repository);

    The "repository_pms" returns the "@program_modules" in "repository". A
    repository is the a program module name that corresponds to a directory.
    For example, a repository for "File::Where" is "File".

  pm2require subroutine

     $file = pm2require($pm_file)

    The *pm2require* method/subroutine returns the file suitable for use in
    a Perl "require" for the "$pm" program module.

  where subroutine

    The where subroutine is the core subroutine call by where_file,
    where_dir, where_pm and where_repository.

    When $no_file is absent, 0 or '', the where subroutine performs as
    established for the "where_file" subroutine; otherwise the where
    subroutine performs as established for the "where_dir" subroutine.

    The differences is that the "where" syntax only accepts a reference to
    an array path while the "where_dir" and "where_file" accept both a
    reference to an array path and an array path.

  where_dir subroutine

    When $nofile exists and is non-zero, the "find_in_include"
    method/subroutine looks for the "$relative_dir" under one of the
    directories in the "@path" ("@INC" path if "@path" is '' or 0) in the
    order listed in "@path" or "@INC". When *find_in_include* finds the
    directory, it returns the absolute file "$absolute_dir" and the
    directory "$path" where it found "$relative_dir" when the usage calls
    for an array return; otherwise, the absolute directory "$absolute_dir".

    When the "@path" list of directores exists and is not '' or 0, the
    "where_dir" subroutine/method searches the "@path" list of directories
    instead of the "@INC" list of directories.

  where_file subroutine

    When $nofile is '', 0 or absent, the "find_in_include" method/subroutine
    looks for the "$relative_file" in one of the directories in the "@path"
    ("@INC" path if "@path" is absent, '' or 0) in the order listed in
    "@path" or "@INC". When *find_in_include* finds the file, it returns the
    absolute file "$file_absolute" and the directory "$path" where it found
    "$file_relative" when the usage calls for an array return; otherwise,
    the absolute file "$file_absolute".

    When the "@path" list of directores exists and is not '' or 0, the
    "where_file" subroutine/method searches the "@path" list of directories
    instead of the "@INC" list of directories.

  where_pm subroutine

    In an array context, the *where_pm* subroutine/method returns the
    "$absolute_file", the directory "$inc_path" in "@INC", and the relative
    "$require_file" for the first directory in "@INC" list of directories
    where it found the program module "$pm"; otherwise, it returns just the
    "$absolute_file".

    When the "@path" list of directores exists and is not '' or 0, the
    "where_pm" subroutine/method searches the "@path" list of directories
    instead of the "@INC" list of directories.

  where_repository subroutine

    An repository specifies the location of a number of program modules. For
    example, the repository for this program module, "File::Where", is
    "File::".

    In an array context, the *where_repository* subroutine/method returns
    the "$absolute_directory", the directory "$inc_path" in "@INC" for the
    first directory in "@INC" list of directories, and the relative
    directory of the repository where it found the "$repository"; otherwise,
    it returns just the "$absolute_file".\ When *where_repository* cannot
    find a directory containing the "$repository" relative directory,
    *where_repository* pops the last directory off the "$repository"
    relative directory and trys again. If *where_repository* finds that
    "$repository" is empty, it returns emptys.

    for the "$repository"; otherwise, it returns just the
    "$absolute_directory".

    When the "@path" list of directores exists and is not '' or 0, the
    "where_repository" subroutine/method searches the "@path" list of
    directories instead of the "@INC" list of directories.

REQUIREMENTS
DEMONSTRATION
     #########
     # perl Where.d
     ###

    ~~~~~~ Demonstration overview ~~~~~

    The results from executing the Perl Code follow on the next lines as
    comments. For example,

     2 + 2
     # 4

    ~~~~~~ The demonstration follows ~~~~~

         use File::Spec;
         use File::Copy;
         use File::Path;
         use File::Package;
         my $fp = 'File::Package';

         my $uut = 'File::Where';
         my $loaded = '';
         # Use the test file as an example since know its absolute path
         #
         my $test_script_dir = cwd();
         chdir File::Spec->updir();
         chdir File::Spec->updir();
         my $include_dir = cwd();
         chdir $test_script_dir;
         my $OS = $^O;  # need to escape ^
         unless ($OS) {   # on some perls $^O is not defined
             require Config;
            $OS = $Config::Config{'osname'};
         } 
         $include_dir =~ s=/=\\=g if( $OS eq 'MSWin32');
         $test_script_dir =~ s=/=\\=g if( $OS eq 'MSWin32');

         # Put base directory as the first in the @INC path
         #
         my @restore_inc = @INC;

         my $relative_file = File::Spec->catfile('t', 'File', 'Where.pm'); 
         my $relative_dir1 = File::Spec->catdir('t', 'File');
         my $relative_dir2 = File::Spec->catdir('t', 'Jolly_Green_Giant');

         my $absolute_file1 = File::Spec->catfile($include_dir, 't', 'File', 'Where.pm');
         my $absolute_dir1A = File::Spec->catdir($include_dir, 't', 'File');
         my $absolute_dir1B = File::Spec->catdir($include_dir, 't');

         mkpath (File::Spec->catdir($test_script_dir, 't','File'));
         my $absolute_file2 = File::Spec->catfile($test_script_dir, 't', 'File', 'Where.pm');
         my $absolute_dir2A = File::Spec->catdir($include_dir, 't', 'File', 't', 'File');
         my $absolute_dir2B = File::Spec->catdir($include_dir, 't', 'File', 't');

         #####
         # If doing a target site install, blib going to be up front in @INC
         # Locate the include directory with high probability of having the
         # first File::Where in the include path.
         #
         # Really not important that that cheapen test somewhat by doing a quasi
         # where search in that using this to test for a boundary condition where
         # the class, 'File::Where', is the same as the program module 'File::Where
         # that the 'where' subroutine/method is locating.
         #
         my $absolute_dir_where = File::Spec->catdir($include_dir, 'lib');
         foreach (@INC) {
             if ($_ =~ /blib/) {
                 $absolute_dir_where = $_ ;
                 last;
             }
             elsif ($_ =~ /lib/) {
                 $absolute_dir_where = $_ ;
                 last;
             }
         }
         my $absolute_file_where = File::Spec->catfile($absolute_dir_where, 'File', 'Where.pm');

         my @inc2 = ($test_script_dir, @INC);  # another way to do unshift

         copy $absolute_file1,$absolute_file2;
         unshift @INC, $include_dir;    

         my (@actual,$actual); # use for array and scalar context

     ##################
     # Load UUT
     # 

     my $errors = $fp->load_package('File::Where', 'where_pm')
     $errors

     # ''
     #

     ##################
     # pm2require
     # 

     $actual = $uut->pm2require( 'File::Where')

     # 'File\Where.pm'
     #

     ##################
     # program modules('_Drivers_')
     # 

     [my @drivers = sort $uut->program_modules( '_Drivers_' )]

     # [
     #          'Driver',
     #          'Generate',
     #          'IO'
     #        ]
     #

     ##################
     # is_module('dri', Driver Generate IO)
     # 

     $uut->is_module('dri', @drivers )

     # 'Driver'
     #

     ##################
     # repository_pms('t::File::_Drivers_')
     # 

     [@drivers = sort $uut->repository_pms( 't::File::_Drivers_' )]

     # [
     #          'Driver',
     #          'Generate',
     #          'IO'
     #        ]
     #

     ##################
     # dir_pms( '_Drivers_' )
     # 

     [@drivers = sort $uut->dir_pms( '_Drivers_' )]

     # [
     #          'Driver',
     #          'Generate',
     #          'IO'
     #        ]
     #

     ##################
     # where finding a file, array context, path absent
     # 

     [@actual = $uut->where($relative_file)]

     # [
     #          'E:\User\SoftwareDiamonds\installation\t\File\Where.pm',
     #          'E:\User\SoftwareDiamonds\installation',
     #          't\File\Where.pm'
     #        ]
     #

     ##################
     # where finding a file, scalar context, path absent
     # 

     $actual = $uut->where($relative_file)

     # 'E:\User\SoftwareDiamonds\installation\t\File\Where.pm'
     #

     ##################
     # where finding a file, array context, array reference path
     # 

     [@actual = $uut->where($relative_file, [$test_script_dir, $include_dir])]

     # [
     #          'E:\User\SoftwareDiamonds\installation\t\File\t\File\Where.pm',
     #          'E:\User\SoftwareDiamonds\installation\t\File',
     #          't\File\Where.pm'
     #        ]
     #

     ##################
     # where finding a dir, array context, path absent
     # 

     [@actual = $uut->where($relative_dir1, '', 'nofile')]

     # [
     #          'E:\User\SoftwareDiamonds\installation\t\File',
     #          'E:\User\SoftwareDiamonds\installation',
     #          't\File'
     #        ]
     #

     ##################
     # where finding a dir, scalar context, path absent
     # 

     $actual = $uut->where($relative_file, '', 'nofile')

     # 'E:\User\SoftwareDiamonds\installation\t\File'
     #

     ##################
     # where finding a dir, array context, array reference path
     # 

     [@actual = $uut->where($relative_dir2, \@inc2, 'nofile')]

     # [
     #          'E:\User\SoftwareDiamonds\installation\t\File\t',
     #          'E:\User\SoftwareDiamonds\installation\t\File',
     #          't'
     #        ]
     #

     ##################
     # where finding a dir, scalar context, array reference path
     # 

     $actual = $uut->where('t', [$test_script_dir,@INC], 'nofile')

     # 'E:\User\SoftwareDiamonds\installation\t\File\t'
     #

     ##################
     # where_file, array context, path absent
     # 

     [@actual = $uut->where_file($relative_file)]

     # [
     #          'E:\User\SoftwareDiamonds\installation\t\File\Where.pm',
     #          'E:\User\SoftwareDiamonds\installation',
     #          't\File\Where.pm'
     #        ]
     #

     ##################
     # where_file, scalar context, array path
     # 

     $actual = $uut->where_file($relative_file, $test_script_dir, $include_dir)

     # 'E:\User\SoftwareDiamonds\installation\t\File\t\File\Where.pm'
     #

     ##################
     # where_dir, array context, array reference
     # 

     [@actual = $uut->where_dir($relative_dir1, \@inc2)]

     # [
     #          'E:\User\SoftwareDiamonds\installation\t\File\t\File',
     #          'E:\User\SoftwareDiamonds\installation\t\File',
     #          't\File'
     #        ]
     #

     ##################
     # where_dir, array context, array reference
     # 

     [@actual = $uut->where_dir($relative_dir2, $test_script_dir)]

     # [
     #          'E:\User\SoftwareDiamonds\installation\t\File\t',
     #          'E:\User\SoftwareDiamonds\installation\t\File',
     #          't'
     #        ]
     #

     ##################
     # where_dir, scalar context, path absent
     # 

     $actual = $uut->where_dir($relative_file)

     # 'E:\User\SoftwareDiamonds\installation\t\File'
     #

     ##################
     # where_pm, array context, path absent
     # 

     [@actual= $uut->where_pm( 't::File::Where' )]

     # [
     #          'E:\User\SoftwareDiamonds\installation\t\File\Where.pm',
     #          'E:\User\SoftwareDiamonds\installation',
     #          't\File\Where.pm'
     #        ]
     #

     ##################
     # where_pm, scalar context, array path
     # 

     $actual = $uut->where_pm( 't::File::Where', @inc2)

     # 'E:\User\SoftwareDiamonds\installation\t\File\t\File\Where.pm'
     #

     ##################
     # where_pm, File::Where boundary case
     # 

     $actual = $uut->where_pm( 'File::Where')

     # 'E:\User\SoftwareDiamonds\installation\lib\File\Where.pm'
     #

     ##################
     # where_pm subroutine, array context, array reference path
     # 

     [@actual= $uut->where_pm( 't::File::Where', [$test_script_dir])]

     # [
     #          'E:\User\SoftwareDiamonds\installation\t\File\t\File\Where.pm',
     #          'E:\User\SoftwareDiamonds\installation\t\File',
     #          't\File\Where.pm'
     #        ]
     #

     ##################
     # where_repository, array context, path absent
     # 

     [@actual= $uut->where_repository( 't::File' )]

     # [
     #          'E:\User\SoftwareDiamonds\installation\t\File',
     #          'E:\User\SoftwareDiamonds\installation',
     #          't\File'
     #        ]
     #

     ##################
     # where_repository, scalar context, array path
     # 

     $actual = $uut->where_repository( 't::File', @inc2)

     # 'E:\User\SoftwareDiamonds\installation\t\File\t\File'
     #

     ##################
     # where_repository, array context, array reference path
     # 

     [@actual= $uut->where_repository( 't::Jolly_Green_Giant', [$test_script_dir])]

     # [
     #          'E:\User\SoftwareDiamonds\installation\t\File\t',
     #          'E:\User\SoftwareDiamonds\installation\t\File',
     #          't'
     #        ]
     #
        @INC = @restore_inc; #restore @INC;
        rmtree 't';

QUALITY ASSURANCE
    Running the test script "Where.t" verifies the requirements for this
    module.

    The "tmake.pl" cover script for Test::STDmaker automatically generated
    the "Where.t" test script, "Where.d" demo script, and "t::Data::Where"
    program module POD, from the "t::Data::Where" program module contents.
    The "t::Data::Where" program module is in the distribution file
    Data-Where-$VERSION.tar.gz.

NOTES
  Author

    The holder of the copyright and maintainer is

    <support@SoftwareDiamonds.com>

  Copyright Notice

    Copyrighted (c) 2002 Software Diamonds

    All Rights Reserved

  Binding Requirements Notice

    Binding requirements are indexed with the pharse 'shall[dd]' where dd is
    an unique number for each header section. This conforms to standard
    federal government practices, STD490A 3.2.3.6. In accordance with the
    License, Software Diamonds is not liable for any requirement, binding or
    otherwise.

  License

    Software Diamonds permits the redistribution and use in source and
    binary forms, with or without modification, provided that the following
    conditions are met:

    1   Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.

    2   Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.

    SOFTWARE DIAMONDS, http://www.softwarediamonds.com, PROVIDES THIS
    SOFTWARE 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
    NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SOFTWARE
    DIAMONDS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL,EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
    TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,DATA, OR
    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF NEGLIGENCE OR OTHERWISE) ARISING IN
    ANY WAY OUT OF THE POSSIBILITY OF SUCH DAMAGE.

SEE ALSO
    Docs::Site_SVD::Data_Where
    Test::STDmaker
Title Page
     Software Version Description

     for

      File::Where - find the absolute file for a program module; dir for a repository

     Revision: D

     Version: 0.05

     Date: 2004/05/04

     Prepared for: General Public 

     Prepared by:  SoftwareDiamonds.com E<lt> support@SoftwareDiamonds.com E<gt>

     Copyright: copyright � 2003 Software Diamonds

     Classification: NONE

1.0 SCOPE
    This paragraph identifies and provides an overview of the released
    files.

  1.1 Identification

    This release, identified in 3.2, is a collection of Perl modules that
    extend the capabilities of the Perl language.

  1.2 System overview

    The system is the Perl programming language software. As established by
    the Perl referenced documents, program modules, such the "File::Where"
    module, extend the Perl language.

    The subroutines in File::Where program module finds the absolute file or
    dir for a program module, program module repository, relative file,
    relative directory by searching the directories in the @INC array of
    directories or an override array of directories. The File::Where program
    module supercedes the File::PM2File program module.

  1.3 Document overview.

    This document releases File::Where version 0.05 providing a description
    of the inventory, installation instructions and other information
    necessary to utilize and track this release.

3.0 VERSION DESCRIPTION
    All file specifications in this SVD use the Unix operating system file
    specification.

  3.1 Inventory of materials released.

    This document releases the file

     File-Where-0.05.tar.gz

    found at the following repository(s):

      http://www.softwarediamonds/packages/
      http://www.perl.com/CPAN/authors/id/S/SO/SOFTDIA/

    Restrictions regarding duplication and license provisions are as
    follows:

    Copyright.
        copyright � 2003 Software Diamonds

    Copyright holder contact.
         603 882-0846 E<lt>support@SoftwareDiamonds.comE<gt>

    License.
        Software Diamonds permits the redistribution and use in source and
        binary forms, with or without modification, provided that the
        following conditions are met:

        1   Redistributions of source code, modified or unmodified must
            retain the above copyright notice, this list of conditions and
            the following disclaimer.

        2   Redistributions in binary form must reproduce the above
            copyright notice, this list of conditions and the following
            disclaimer in the documentation and/or other materials provided
            with the distribution.

        SOFTWARE DIAMONDS, http://www.SoftwareDiamonds.com, PROVIDES THIS
        SOFTWARE 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
        BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
        FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
        SOFTWARE DIAMONDS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
        SPECIAL,EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
        LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
        USE,DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
        ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING USE OF THIS SOFTWARE, EVEN IF ADVISED OF
        NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE POSSIBILITY
        OF SUCH DAMAGE.

  3.2 Inventory of software contents

    The content of the released, compressed, archieve file, consists of the
    following files:

     file                                                         version date       comment
     ------------------------------------------------------------ ------- ---------- ------------------------
     lib/Docs/Site_SVD/File_Where.pm                              0.05    2004/05/04 revised 0.04
     MANIFEST                                                     0.05    2004/05/04 generated, replaces 0.04
     Makefile.PL                                                  0.05    2004/05/04 generated, replaces 0.04
     README                                                       0.05    2004/05/04 generated, replaces 0.04
     lib/File/Where.pm                                            1.16    2004/05/04 revised 1.15
     t/File/Where.d                                               0.04    2004/05/04 revised 0.03
     t/File/Where.pm                                              0.04    2004/05/04 revised 0.03
     t/File/Where.t                                               0.04    2004/05/04 revised 0.03
     t/File/_Drivers_/Driver.pm                                   0.02    2004/05/04 new
     t/File/_Drivers_/Generate.pm                                 0.02    2004/05/04 new
     t/File/_Drivers_/IO.pm                                       0.02    2004/05/04 new
     t/File/File/Package.pm                                       1.16    2004/05/04 revised 1.15
     t/File/Test/Tech.pm                                          1.22    2004/05/04 revised 1.17
     t/File/Data/Secs2.pm                                         1.19    2004/05/04 revised 1.15
     t/File/Data/SecsPack.pm                                      0.04    2004/05/04 new
     t/File/Data/Startup.pm                                       0.04    2004/05/04 new

  3.3 Changes

    The changes to the previous version are as follows:

    File-Where-0.01
        Originated.

    File-Where-0.02
        Added code to where_pm for the boundary case where

          where_pm('File::Where') # subroutine interface
          'File::Where'->where_pm('File::Where') # class interface

        This bug was discovered because the obsoleted File::PM2File module
        now uses File::Where for backwards compatibility.

    File-Where-0.03
         Subject: FAIL Test-Tech-0.18 i586-linux 2.4.22-4tr 
         From: cpansmoke@alternation.net 
         Date: Thu,  8 Apr 2004 15:09:35 -0300 (ADT) 

         PERL_DL_NONLAZY=1 /usr/bin/perl5.8.0 "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/Test/Tech/Tech.t
         t/Test/Tech/Tech....Can't locate FindBIN.pm

         Summary of my perl5 (revision 5.0 version 8 subversion 0) configuration:
           Platform:
             osname=linux, osvers=2.4.22-4tr, archname=i586-linux

        This is capitalization problem. The program module name is 'FindBin'
        not 'FindBIN' which is part of Perl. Microsoft does not care about
        capitalization differences while linux does. This error is in the
        test script automatically generated by "Test::STDmaker" and was just
        introduced when moved test script libraries from "tlib" to the
        directory of the test script. Repaired "Test::STDmaker" and
        regenerated the distribution.

    File-Where-0.04
        Subject: FAIL File-Where-0.03 ppc-darwin-thread-multi 7.2.0 From:
        nothingmuch@woobling.org Date: Fri, 9 Apr 2004 21:59:10 +0300 (IDT)

        # Test 19 got:
        '/private/var/cpanplus/5.8.3/build/File-Where-0.03/blib/lib/File/Whe
        re.pm' (t/File/where.t at line 277)

        # Expected:
        '/private/var/cpanplus/5.8.3/build/File-Where-0.03/lib/File/Where.pm
        '

        If doing a target site install, the install software going to place
        the "blib" directory up front in @INC Changed the file test to
        locate the include directory with high probability of having the
        first "File::Where" in the include path in determining the expected
        value.

        Really does not cheapen test by doing a quasi where search where
        actual does the same. The object of the test to validate boundary
        condition where the class, 'File::Where', is the same as the program
        module 'File::Where that the 'where' subroutine/method is locating.
        There are plenty of successful test where "where" finds directories
        and files as expected.

    File-Where-0.05
        Rework the POD NOTES and QUALITY ASSURANCE sections.

    File-Where-0.06
        Added the "is_module", "program_modules", "repository_pms" and
        "dir_pms" subroutines.

  3.4 Adaptation data.

    This installation requires that the installation site has the Perl
    programming language installed. There are no other additional
    requirements or tailoring needed of configurations files, adaptation
    data or other software needed for this installation particular to any
    installation site.

  3.5 Related documents.

    There are no related documents needed for the installation and test of
    this release.

  3.6 Installation instructions.

    Instructions for installation, installation tests and installation
    support are as follows:

    Installation Instructions.
        To installed the release file, use the CPAN module pr PPM module in
        the Perl release or the INSTALL.PL script at the following web site:

         http://packages.SoftwareDiamonds.com

        Follow the instructions for the the chosen installation software.

        If all else fails, the file may be manually installed. Enter one of
        the following repositories in a web browser:

          http://www.softwarediamonds/packages/
          http://www.perl.com/CPAN/authors/id/S/SO/SOFTDIA/

        Right click on 'File-Where-0.05.tar.gz' and download to a temporary
        installation directory. Enter the following where $make is 'nmake'
        for microsoft windows; otherwise 'make'.

         gunzip File-Where-0.05.tar.gz
         tar -xf File-Where-0.05.tar
         perl Makefile.PL
         $make test
         $make install

        On Microsoft operating system, nmake, tar, and gunzip must be in the
        exeuction path. If tar and gunzip are not install, download and
        install unxutils from

         http://packages.softwarediamonds.com

    Prerequistes.
         None.

    Security, privacy, or safety precautions.
        None.

    Installation Tests.
        Most Perl installation software will run the following test
        script(s) as part of the installation:

         t/File/Where.t

    Installation support.
        If there are installation problems or questions with the
        installation contact

         603 882-0846 E<lt>support@SoftwareDiamonds.comE<gt>

  3.7 Possible problems and known errors

    There is still much work needed to ensure the quality of this module as
    follows:

    *   State the functional requirements for each method including not only
        the GO paths but also what to expect for the NOGO paths

    *   All the tests are GO path tests. Should add NOGO tests.

4.0 NOTES
    The following are useful acronyms:

    .d  extension for a Perl demo script file

    .pm extension for a Perl Library Module

    .t  extension for a Perl test script file

    POD Plain Old Documentation

2.0 SEE ALSO
    File::Where
    Docs::US_DOD::SVD