Text::BibTeX
                               version 0.30
                       Greg Ward (gward@python.net)
                              12 March, 1999

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

Text::BibTeX is a Perl library for reading, parsing, and writing BibTeX
files.  It is the Perl half of btOOL, a pair of libraries for dealing
with BibTeX data; the C half, btparse, is needed to compile Text::BibTeX
(see below).

Text::BibTeX gives you access to the data at many different levels: you
may work with BibTeX entries as simple "field -> string" mappings, or
get at the original form of the data as a list of simple values
(strings, macros, or numbers) pasted together.  You can impose no
restrictions on the allowed/expected entry types or fields, or you can
use the structure defined by BibTeX 0.99's standard style files, or you
can invent your own.

The library is copiously documented.  After installing the module, see
the Text::BibTeX man page for a comprehensive introduction to the
system.  If you wish to dive straight in without regards for niceties
such as splitting and formatting names, defining or imposing database
structures, getting access to unprocessed field values, and other nifty
features, then you can probably get away with just reading the
Text::BibTeX::Entry man page.  Much of the documentation is rather raw,
because no one except me has read it, so comments are most welcome --
particularly comments that suggest constructive improvements.

In addition to the man pages embedded in each module (and available
after installation), I have written a technical report describing btOOL,
with the btparse and Text::BibTeX documentation included as appendices.
The whole report is just over 100 pages, around 45 of which make up the
Text::BibTeX documentation (the btparse documentation is a further 30
pages).  It can be downloaded from the same location as the btOOL code:

    http://www.aseonline.net/~gward/

I may also make the btparse and Text::BibTeX manuals available as
separate PostScript files, but they aren't there as of this writing.


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-x.y.tar.gz (where x.y is the
btparse release number -- it should be the same as for Text::BibTeX) in
the same directory where you unpack the Text::BibTeX archive; or you can
put the btparse tar file right into the Text::BibTeX distribution
directory.  If you have already unpacked btparse, the directory that it
unpacked to should be found just fine.


BUILDING
--------

Start by generating the Makefile and other preparatory steps (most
notably, finding and possibly 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

However, this is fraught with danger and not recommended.  The only safe
thing to do is to build Perl with an ANSI-compliant compiler.  This will
probably save you trouble with other extensions that require an ANSI C
compiler.

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 lib
   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

   http://www.aseonline.net/~gward/

Up-to-date information on btOOL is available at the btOOL web site:

   http://starship.python.net/~gward/btOOL/

Here you will (eventually) find HTML versions of the documentation and
technical report describing the project, links to download the code, and
whatever other goodies I can come up with over time.


CREDITS
-------

See the btparse README file.

$Id: README,v 1.5 1999/03/11 04:23:06 greg Exp $