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 $