                                  btparse
                    (a C library to parse BibTeX files)

                                version 0.1
                               7 March, 1997
                   Greg Ward (greg@bic.mni.mcgill.ca)

Copyright (c) 1997 by Gregory P. Ward.  All rights reserved.  This is
free software; you can redistribute it and/or modify it under the terms
of the GNU General Public License, version 2.0.


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

btparse is a C library for parsing BibTeX files.  The current release is
meant for use with my Text::BibTeX Perl module, and isn't a general release
for C programmers.  (If you're really interested though, the API is
well-defined and fairly stable.  See btparse.h for the barebones, and
init.c, input.c, and traversal.c for most of the functions that you'll need
to call; they're all pretty well documented.  Also, be sure to email if
you'd like to see a properly documented and supported C API; currently, my
only plans are for this library to be a backend to Perl and possibly other
high-level languages.  If I hear from people wanting to use it in C,
though, I could be persuaded otherwise.  I also have an example C program
that I could email to you if you're interested.)

You can find the latest version of btparse (as well as its companion
Perl module, Text::BibTeX) at

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

as well as on any CPAN (Comprehensive Perl Archive Network) site, in
modules/by-authors/Greg_Ward/.


BUILDING
--------

To build the library (which you will have to do in any case, even if you
just want to use it through my Perl module), do the following:

   1) Edit Makefile; if you have to change anything at all, it will
      probably only be CC and OPT.  If your default C compiler is ANSI
      compliant and produces correct code with -O2, you shouldn't have to
      change anything.  If you don't have an ANSI C compiler, you will need
      to get one; I recommend gcc.

   2) Type `make'.

If you're just doing this in order to build Text::BibTeX, that should be
all -- go back to the Text::BibTeX README for further instructions.

Incidentally, btparse uses PCCTS (Purdue Compiler Construction Tool Set)
to build the lexer and parser.  You don't need to have PCCTS yourself to
just build the library, but if you want to fiddle with the grammar
(bibtex.g) you'll need it.  You can get PCCTS 1.33 (the version I use)
from

    ftp://ftp.parr-research.com/pccts

A number of source files from PCCTS are included in the `pccts'
directory of the btparse distribution.  This is just to make your life
easier -- with these files included in the package, you don't need to
have PCCTS installed on your system.  You don't even need to have ever
heard of PCCTS; it just works transparently.  You should be aware that
the copyright on these files is different; they are in fact in the
public domain, and their authors reserve NO legal right to those files.
(However, you should of course respect their wishes; please see the
comments at the top of any file in this subdirectory for details.)  This
does NOT hold for the rest of the files in the package; as stated above,
they are covered by the GNU General Public License.


BUGS AND LIMITATIONS
--------------------

There's a memory leak in somewhere the library; this being an alpha
release, you have to expect these sort of things.  ;-)  btparse seems to
consume about 6-7 MB of memory for every 1 MB of .bib file, so don't try
to process anything really huge right away.  Should be fixed in the next
release.

Doesn't yet handle @preamble entries; I know exactly what needs to be
done to the grammar for this to work, too, so it should also be in the
next release.
