Text::BibTeX version 0.33 Greg Ward (gward@python.net) 22 March, 2000 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 choose not to impose nany 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. 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. If you didn't download btparse with Text::BibTeX, don't sweat it; the Makefile.PL is smart enough to go out and find it for you (using your preferred CPAN mirror if you have set one up, http://www.cpan.org/ otherwise). If you did download btparse, just put it in the same directory as the Text::BibTeX tarball. Text::BibTeX's Makefile.PL will unpack and configure it for you. BUILDING -------- Start by generating the Makefile and other preparatory steps (most notably, preparing the btparse package for building). perl Makefile.PL This goes to some lengths to ensure that btparse, the companion C library, is found and available. It will configure btparse for you, so you shouldn't have to do anything in the 'btparse' directory unless things go wrong there. 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, build everything: make This takes care of building btparse as well as the Text::BibTeX modules, so again you don't have to go grubbing around in the btparse directory unless things go wrong. Optionally, you can test and install btparse: cd btparse make test make install cd .. (You do not have to install btparse to use Text::BibTeX; that's only needed if you plan to do C programming using btparse. See btparse/README for details.) Finally, test and install the Text::BibTeX Perl modules: make test make install Note that you will need to be root on most systems in order to install either btparse or Text::BibTeX. Consult the 'perlmodinstall' man page (as of Perl 5.005 or later) for more information on building and installing Perl module distributions. 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 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 ------- For spotting bugs and sometimes even providing patches: Dirk Vleugels Kjetil Kjernsmo Andrew Cassin Thomas Kamphusmann Horst Tellioglu Nikolay Pelov ...and probably a few others. Please send me email if you feel you belong on this list and I forgot to include you. Also, see the btparse README file for contributors to the C library. $Id: README,v 1.9 2000/03/23 02:00:15 greg Exp $