README for PubCrawler + precompiled libraries
---------------------------------------------

The libraries included are:
	MIME-Base64, Version 2.09
       	URI,         Version 1.00 
       	HTML-Parser, Version 2.20 
        libwww-perl, Version 5.36 

PubCrawler is looking for these libraries in certain places when being
executed. Please make sure it can find them by following these steps:

1) Move into the directory, where pubcrawler.pl (PubCrawler's executable Perl-
   script) resides. This should normally be the same directory where you can 
   find this README.


2) Make sure the Perl-script is executable: 

     	chmod +x pubcrawler.pl


3) Try to run PubCrawler with the 'h'-option ('h' for 'help'), by typing the
   following command:

	./pubcrawler.pl -h

   This should print out the PubCrawler help message. If it does, the libraries
   were found and you can continue with step 6 (testing PubCrawler).

   If you see something like 
	"bash: .../pubcrawler.pl: No such file or directory"
   you have to edit the first line of the Perl-script by changing the path to 
   the location of your Perl-executable (find out where it resides by entering
   the following command:  which perl  

   If you get an error message like 
	"Can't locate LWP/Simple.pm in @INC ..."
   then the libraries where not found. Please follow the next steps carefully
   to fix the problem. 

   If none of the following instructions help, send an e-mail with the 
   description of your problen and a copy of any error messages to PubCrawler:
   	'pubcrawlerREMOVECAPShelp@gmail.com'.


4) Type in the following command to find out, in which directories PubCrawler
   will look for modules

	./pubcrawler.pl -lib_test	

   This will print a list of directories. One of them should read

	/your_home_directory/lib

   where 'your_home_directory' could be something like '/usr/users/jsmith/' .
   It means that one of the locations where PubCrawler is looking for libraries
   is the directory 'lib', which is a subdirectory of 'PubCrawler', located
   in your home directory.
   
   When you were unpacking the PubCrawler archive, two new directories where
   created: 'PubCrawler' and 'PubCrawler/lib'. The latter one holds the pre-
   compiled libraries.
   You probably didn't unpack the archive from your home directory, otherwise
   the libraries would have been found.


5) There are two ways to fix the problem:

   a) Extending PubCrawler's search path

	Let's presume that your current position is the directory named 
	'PubCrawler', which has been created when unpacking the archive.

	Run PubCrawler with the option '-add_path' and '-h':

		./pubcrawler.pl -add_path -h

	This will add the path /cwd/lib to the list of directories which
        will be searched for libraries ('cwd' = 'current working directory').
	If you get no error messages but the PubCrawler help-message
	instead, you are sorted and can continue with step 6. Just make
	sure that you are always use the '-add_path' option.

	To avoid that you can also permanently add this path to PubCrawler's
	search directories by following the next instructions:	

	Change to the directory named 'lib' which holds the libraries:

		cd lib

	Print the name of your current working directory:

		pwd

	Copy this path and edit pubcrawler.pl (PubCrawler's Perl-script).
	The name of the path has to be added to a variable called '@INC'.
        You can it at the top of the file in a section called 
		# LOCATION OF MODULES:
	
	At line 20 (approx.) you will find the following:

		unshift(@INC, "$ENV{HOME}/lib", "$ENV{HOME}/lib", 
			      '/path/to/module',);

	These are paths added to the list of directories, in which Pubcrawler
 	will search for modules.

	Add your path to the list, for example after the last comma, or
	replace one of the examplary paths with yours.

	Save the file and start again with step 1 of this readme file.

   b) Moving the libraries into a position known to PubCrawler

	Let's presume that you are currently in the directory named 
	'PubCrawler' which has been created when unpacking the archive.

	Enter the following command to move it to your home directory:

		mv ../PubCrawler ~

	Do a listing of your home directory (ls -l ~) to see if the operation
        worked and start again with step 1 of this readme file.

    
6) Testing PubCrawler:

   Run the program in "check-mode": 

     pubcrawler.pl -check

   The messages appearing in your terminal will tell you if everything is OK, 
   or if there are any problems. In the latter case follow the instructions
   printed to solve them.

7) If you got no errors, run the program again without the -check option but
   in verbose mode: 

     pubcrawler.pl -v

   You should see a lot of text appearing in your terminal, describing commu-
   nications between the program and NCBI. When PubCrawler has finished run-
   ning it will tell you so. This might take a few minutes. 

8) View the output by opening the file "pubcrawler_output.html" with Netscape 
   (File -> Open -> Page in Navigator).  You should see the results of the set
   of searches specified in the file "pubcrawler.config" that is
   distributed with the program. 

9) Visit PubCrawler's Home Page at 

	http://pubcrawler.gen.tcd.ie/

   for instructions on how to configure your own queries.