Text::BibTeX
                               version 0.31
                       Greg Ward (gward@python.net)
                            28 October, 1999

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

Text::BibTeX is a Perl library for reading, parsing, and processing
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.  Comments/criticism of the documentation
are welcome -- much of it is rather raw braindump, so may need a bit of
massaging.

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).  You can find it at the btOOL home page:

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

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.


BUGS AND LIMITIATIONS
---------------------

See the btparse(3) and Text::BibTeX(3) man pages for details.  Executive
summary:

  * Text::BibTeX is not thread-safe, due to a heavy dependence on
    global variables in the parser and lexical scanner components
    of btparse

  * for the same reason, you can't have multiple files open and
    being parsed at the same time; attempting to do so is an
    invalid use of btparse

  * Text::BibTeX cannot be used with an sfio-based Perl, because
    the Perl I/O API is apparently not yet up to the task of replacing
    stdio in third-party C libraries

  * there are some weird subtle bugs that I have been unable to isolate;
    if you see messages like "Subroutine format redefined at
    /usr/lib/perl5/site_perl/Text/BibTeX/Name.pm ...", please get
    in touch with me -- you're not the first to have this problem.
    However, I have been unable to reproduce the bug, much less
    isolate and fix it -- so if you can reproduce it, I need your help!


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

You can find the latest version of Text::BibTeX, as well as
documentation, information on known bugs, etc. at the btOOL web site:

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

Here you will 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.6 1999/10/28 23:24:50 greg Exp $