                              Text::BibTeX
                              version 0.21
                   Greg Ward (greg@bic.mni.mcgill.ca)
                           6 October, 1997

INTRODUCTION
------------

Text::BibTeX is a Perl module (with a couple of helper modules) for
reading, parsing, and writing BibTeX files.  Currently, the documented
interface provides only the lowest level of support needed to process
BibTeX bibliographies: parsing the entries and turning them into Perl
hashes.  (Or rather, Perl objects queried through methods.  But it's all
done with hashes internally.)  No knowledge of BibTeX conventions or
requirements is present in the module, both in order to make it more
general (i.e. the input files could hold any kind of data that lends
itself to a bit of structure) and because I wanted to make this release
before adding a whole new layer of code.

After installing the module, see the Text::BibTeX man page for a brief
introduction to the system, Text::BibTeX::File for a little more material
that is essentially introductory, and Text::BibTeX::Entry for the real
thing.


DEPENDENCIES
------------

Text::BibTeX requires Perl 5.004 or later and an ANSI-compliant C
compiler.

You must also have the btparse distribution, the C library underlying
Text::BibTeX.  It is enough to put btparse-0.2.tar.gz in the same
directory where you unpack the Text-BibTeX-0.2 archive; or you can put
the btparse tar file right into the Text-BibTeX-0.2 directory.


BUILDING
--------

Start by generating the Makefile and other preparatory steps (most
notably, finding and unpacking the btparse distribution):

   perl Makefile.PL

Note that if Perl was built with a non-ANSI C compiler, you will need to
specify an ANSI compiler when running Makefile.PL.  For instance, if
you're running SunOS and Perl was built with 'cc' (non-ANSI), you will
need to build Text::BibTeX (and btparse as well, for that matter) with
an ANSI compiler such as 'gcc' or Sun's 'acc'.  This can be done for
Text::BibTeX as follows:

   perl Makefile.PL CC=gcc      # or acc, or whatever works on your system

Now, configure btparse (the C library that is the back-end to
Text::BibTeX):

   cd btparse
   ./configure

(Again, you might have to jump through some hoops -- although in a
different way -- to build btparse with an appropriate compiler.  See the
btparse README for more information.  The only requirement is that you
build both btparse and Text::BibTeX with an ANSI-compliant compiler, but
I would recommend that you use the same compiler for both.  If possible
-- i.e., if you haven't already built Perl with a non-ANSI compiler -- I
would also recommend using the same compiler to build Perl itself.)

Next, build and test the C library (still in the 'btparse' directory):

   make
   make test

Return to the main Text::BibTeX distribution directory, and continue as
usual:

   cd ..
   make
   make test
   make install

Note that "make install" only installs the Perl modules; if you wish to
install the C library, see the btparse README file.

Please let me know if anything goes wrong with building either btparse
or Text::BibTeX.


AVAILABILITY
------------

The latest version of Text::BibTeX and btparse should be available from

   ftp://ftp.bic.mni.mcgill.ca/pub/users/greg/
