ReDIF-perl -- A kit of Perl tools to process and validate ReDIF data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Copyright (c) 1997-2001 Ivan Kurmanov. All rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.


CONTENTS
~~~~~~~~
  WHAT'S IN THIS PACKAGE
  HOW TO INSTALL
  WHAT IS A STAND-ALONE REDIF HOME
  HOW CAN I USE IT IN MY REDIF APPLICATION
  INCOMPATIBILITIES (WITH PREVIOUS VERSIONS OF THIS SOFTWARE)


WHAT'S IN THIS PACKAGE

This package includes software and documentation which you will need
to work with data in the ReDIF format.  That is:

   - the rr.pm perl module as an application interface to the ReDIF 
     parser
   - the ReDIF::init.pm perl module as a shared tool for ReDIF (RePEc) 
     developers
   - rech - ReDIF checking script 
   - rere - ReDIF reading (filtering) script 
   - Makefile.PL - installation tool (makefile generator)
   - Configure - configuration utility (one parameter :-)
   - related documentation: about rr.pm, rech, redif.spec  

The ReDIF (Research Document Information Format) is a text file data
format, created for and used in RePEc (Research Papers in Economics)
project by the NetEc team, with Thomas Krichel as our leader.  The
ReDIF was designed for simple research metadata exchange.  You will
find more information about RePEc and ReDIF at the following URLs:

http://repec.org/

http://netec.mcc.ac.uk/RePEc/

http://netec.mcc.ac.uk/ReDIF/

Generally, you will want to use this package if you have or are going
to have your own RePEc (or RePEc-like) metadata archive.
Alternatively, you may find it useful if you produce or process, or
otherwise work with the ReDIF data or if you developing some software
for the ReDIF/RePEc/UPS protoproto.

Included documentation you will find in the doc/ directory of the
package.  Most of that documentation has not (yet) been updated for
this release.  In the etc/ you will find default configuration file
for rech and in spec/ - the ReDIF specification file
(redif.spec). In the lib/ directory - the Perl modules.


HOW TO INSTALL

To install this package onto your machine use the following standard
commands (I assume you have already unpacked the package onto your
harddisk):

	perl Makefile.PL
	make
	make test
	make install

For the last step (make install) you will most likely need to have
root (superuser) rights.  If your need to make a private installation
use PREFIX=<DIR> option of perl Makefile.PL command or execute
Makefile.PL with your private copy of perl.  (default PREFIX is
usually /usr)

After this procedure the rech and rere scripts shall be installed to a
directory which is already included into your PATH (e.g. /usr/bin) and
so shall be reachable from everywhere on your system.   

By this step the rr.pm and other related libraries shall be installed
into a directory where perl will find them.  The Makefile.PL will also
execute the Configure utility which will help you to set the only one,
but valuable parameter: your ReDIF home directory which is your
archive's directory if you have one, or it may be any other directory,
where you will create a so-called stand-alone ReDIF home (see next
section).  Configure will ask you about the directory name and will
suggest you to create one if it doesn't exists.  (Note, that this
utility's intellegence is not too high: it will just fail if more than
one level of directory structure need to be created.)

If later you need to change your home directory setting - just
reinstall the package.

You may refuse to enter the ReDIF home directory at the installation
stage.  Then you would have to use Guildford protocol rules to let the
software know your main ReDIF directory. (By environment variable
REDIFDIR or by running software from that directory.)  Or by a
command-line parameter '--rdir' (or '--redif.dir').



WHAT IS A STAND-ALONE REDIF HOME

Stand-alone ReDIF home is a new way to install rech and ReDIF parser
(including rr.pm module) on a system.  Instead of creating a
RePEc-archive-like directory structure (as it was necessary before),
now you can do it simplier.

Choose (create) a directory that will be the ReDIF home and copy there
the spec/, etc/ and doc/ directories of this package.  If you didn't
install the package with "make install" command into a generally
accessibly Perl library tree, then you also need to copy the lib/ dir
and rech and rere scripts. Create data/ directory and store your ReDIF
data files in it. 

Don't forget to look at the REDIFHOME/etc/rech.conf.eg file.

That's it! 


HOW CAN I USE IT IN MY REDIF APPLICATION

While building your ReDIF-related application you might find useful
this package in two different ways.  First is if you need to process
ReDIF data (read .RDF files).  In this case you can use rr.pm module,
which is an interface to the ReDIF parser, which parses templates,
reads them into memory and presents it to your program. (It also does
checking and filtering out the unvalid templates.) To use rr.pm
module, you just include the following line into your Perl code:

	use rr;

If you have installed the package onto the system correctly, then perl
will be able to find rr.pm and all other necessary components.  To
find out more about rr.pm see doc/rr_pm.html documentation and/or rr
manpage (currently manpage is just very brief and may be used as a
short reminder) (pod in lib/rr.pm).

If you are writing an application that just needs to work in ReDIF
environment and wants to get the same installation and configuration
info as included software does, you may use perl module
ReDIF::init.pm.  Function initialize() from that package will look for
a configuration information saved in a Perl-reachable module, will
analyze @ARGV array (command-line arguments), environment variables
and the current working directory, if necessary. It can help your
program to identify: the ReDIF home directory, it's type (RePEc -
Guildford protocol complient or stand-alone), will find the
configuration file for your program in the apropriate directory (if it
needs one).

It will report the main configuration values worked out to the user
(unless you make it silent, which is easy) and will save them for you
in the %ReDIF::CONFIG hash variable. It will not import any symbols to
your package's namespace (unless you ask it to). 

For a detailed discussion of this module please see it's manpage
(man ReDIF::init) or pod data in lib/ReDIF/init.pm.


INCOMPATIBILITIES (WITH PREVIOUS VERSIONS OF THIS SOFTWARE)

Yes, this is a new improved version of software, but it is not 100%
backwards compatible with previous version.  In previous versions I
used an unsafe practice of exporting symbols to your current namespace
(in Perl, when 'use'-ing the module). Now no of internal symbols are
exported, unless you ask it to do so. If are not a Perl coder, then
just note, that programmes, designed to work with previous versions of
ReDIF parser may not work with this one (without some kind of
adaptation).

So if earlier you could do smth like:

    use rr;
    ...
    OpenRDF( $RDF_filename );

Then now you have to do either:

    use rr qw( OpenRDF ... );    ### explicitly requesting to export symbols
    ...
    OpenRDF( $RDF_filename );

or:
    use rr;

    rr::OpenRDF( $RDF_filename ); ### explicitly qualify the package name 


AUTHOR

Ivan Kurmanov,
  kurmanov@yahoo.com
  iku@tut.by
  giku@subvet.com







