README
1
2 Text::BibTeX
3---------------------------------------------------------------------------
4
5 Text::BibTeX is a Perl library for reading, parsing, and processing
6 BibTeX files. It is the Perl half of btOOL, a pair of libraries for
7 dealing with BibTeX data.
8
9 Text::BibTeX gives you access to the data at many different levels:
10 you may work with BibTeX entries as simple "field -> string"
11 mappings, or get at the original form of the data as a list of
12 simple values (strings, macros, or numbers) pasted together. You
13 can choose not to impose nany restrictions on the allowed/expected
14 entry types or fields, or you can use the structure defined by
15 BibTeX 0.99's standard style files, or you can invent your own.
16
17 The library is copiously documented. After installing the module,
18 see the Text::BibTeX man page for a comprehensive introduction to
19 the system. If you wish to dive straight in without regards for
20 niceties such as splitting and formatting names, defining or
21 imposing database structures, getting access to unprocessed field
22 values, and other nifty features, then you can probably get away
23 with just reading the Text::BibTeX::Entry man page.
24 Comments/criticism of the documentation are welcome.
25
26
27 In addition to the man pages embedded in each module (and available
28 after installation), Greg Ward has written a technical report
29 describing btOOL, with the btparse and Text::BibTeX documentation
30 included as appendices. The whole report is just over 100 pages,
31 around 45 of which make up the Text::BibTeX documentation (the
32 btparse documentation is a further 30 pages). You can find it at
33 the btOOL home page:
34
35 http://www.gerg.ca/software/btOOL/
36
37
38 INSTALLATION
39---------------------------------------------------------------------------
40
41 To install Text::BibTeX you need a recent Perl, an ANSI-compliant C
42 compiler and a bunch of Perl modules.
43
44 The build system changed with version 0.40, and has been tested in
45 different platforms, ranging from Linux, Mac OS X, Solaris and
46 Windows. Unfortunately on this last just the Strawberry Perl
47 distribution was a success.
48
49 To build the module use the usual set of commands for a
50 Module::Build distribution:
51
52 perl Build.PL
53 ./Build
54 ./Build test
55
56 And then, as super user, install it
57
58 ./Build install
59
60 Note that if your Perl is installed in a non standard path you can
61 end up with libbtparse library in the wrong place. If the tests pass
62 successfully, but after installing you can not issue
63
64 perl -MText::BibTeX
65
66 without an error message, then probably libbtparse is not reachable
67 by the library loader. In this case you can either copy the library
68 to the proper place or add the path to the library in the
69 LD_LIBARY_PATH environment variable.
70
README.OLD
1 Text::BibTeX
2 version 0.34
3 Greg Ward (gward@python.net)
4 22 December, 2000
5
6INTRODUCTION
7------------
8
9Text::BibTeX is a Perl library for reading, parsing, and processing
10BibTeX files. It is the Perl half of btOOL, a pair of libraries for
11dealing with BibTeX data; the C half, btparse, is needed to compile
12Text::BibTeX (see below).
13
14Text::BibTeX gives you access to the data at many different levels: you
15may work with BibTeX entries as simple "field -> string" mappings, or
16get at the original form of the data as a list of simple values
17(strings, macros, or numbers) pasted together. You can choose not to
18impose nany restrictions on the allowed/expected entry types or fields,
19or you can use the structure defined by BibTeX 0.99's standard style
20files, or you can invent your own.
21
22The library is copiously documented. After installing the module, see
23the Text::BibTeX man page for a comprehensive introduction to the
24system. If you wish to dive straight in without regards for niceties
25such as splitting and formatting names, defining or imposing database
26structures, getting access to unprocessed field values, and other nifty
27features, then you can probably get away with just reading the
28Text::BibTeX::Entry man page. Comments/criticism of the documentation
29are welcome.
30
31In addition to the man pages embedded in each module (and available
32after installation), I have written a technical report describing btOOL,
33with the btparse and Text::BibTeX documentation included as appendices.
34The whole report is just over 100 pages, around 45 of which make up the
35Text::BibTeX documentation (the btparse documentation is a further 30
36pages). You can find it at the btOOL home page:
37
38 http://starship.python.net/~gward/btOOL/
39
40I may also make the btparse and Text::BibTeX manuals available as
41separate PostScript files, but they aren't there as of this writing.
42
43
44DEPENDENCIES
45------------
46
47Text::BibTeX requires Perl 5.004 or later and an ANSI-compliant C
48compiler.
49
50You must also have the btparse distribution, the C library underlying
51Text::BibTeX. If you didn't download btparse with Text::BibTeX, don't
52sweat it; the Makefile.PL is smart enough to go out and find it for you
53(using your preferred CPAN mirror if you have set one up,
54http://www.cpan.org/ otherwise). If you did download btparse, just put
55it in the same directory as the Text::BibTeX tarball. Text::BibTeX's
56Makefile.PL will unpack and configure it for you.
57
58
59BUILDING
60--------
61
62Start by generating the Makefile and other preparatory steps (most notably,
63preparing the btparse package for building).
64
65 perl Makefile.PL
66
67This goes to some lengths to ensure that btparse, the companion C library,
68is found and available. It will configure btparse for you, so you
69shouldn't have to do anything in the 'btparse' directory unless things go
70wrong there.
71
72Note that if Perl was built with a non-ANSI C compiler, you will need to
73specify an ANSI compiler when running Makefile.PL. For instance, if you're
74running SunOS and Perl was built with 'cc' (non-ANSI), you will need to
75build Text::BibTeX (and btparse as well, for that matter) with an ANSI
76compiler such as 'gcc' or Sun's 'acc'. This can be done for Text::BibTeX
77as follows:
78
79 perl Makefile.PL CC=gcc # or acc, or whatever works on your system
80
81However, this is fraught with danger and not recommended. The only safe
82thing to do is to build Perl with an ANSI-compliant compiler. This will
83probably save you trouble with other extensions that require an ANSI C
84compiler.
85
86Now, build everything:
87
88 make
89
90This takes care of building btparse as well as the Text::BibTeX modules, so
91again you don't have to go grubbing around in the btparse directory unless
92things go wrong.
93
94Optionally, you can test and install btparse:
95
96 cd btparse
97 make test
98 make install
99 cd ..
100
101(You do not have to install btparse to use Text::BibTeX; that's only needed
102if you plan to do C programming using btparse. See btparse/README for
103details.)
104
105Finally, test and install the Text::BibTeX Perl modules:
106
107 make test
108 make install
109
110Note that you will need to be root on most systems in order to install
111either btparse or Text::BibTeX. Consult the 'perlmodinstall' man page (as
112of Perl 5.005 or later) for more information on building and installing
113Perl module distributions.
114
115Please let me know if anything goes wrong with building either btparse
116or Text::BibTeX.
117
118
119BUGS AND LIMITIATIONS
120---------------------
121
122See the btparse(3) and Text::BibTeX(3) man pages for details. Executive
123summary:
124
125 * Text::BibTeX is not thread-safe, due to a heavy dependence on
126 global variables in the parser and lexical scanner components
127 of btparse
128
129 * for the same reason, you can't have multiple files open and
130 being parsed at the same time; attempting to do so is an
131 invalid use of btparse
132
133 * Text::BibTeX cannot be used with an sfio-based Perl, because
134 the Perl I/O API is apparently not yet up to the task of replacing
135 stdio in third-party C libraries
136
137
138AVAILABILITY
139------------
140
141You can find the latest version of Text::BibTeX, as well as
142documentation, information on known bugs, etc. at the btOOL web site:
143
144 http://starship.python.net/~gward/btOOL/
145
146Here you will find HTML versions of the documentation and technical
147report describing the project, links to download the code, and whatever
148other goodies I can come up with over time.
149
150
151CREDITS
152-------
153
154For spotting bugs and sometimes even providing patches:
155
156 Dirk Vleugels <vleugels@do.isst.fhg.de>
157 Kjetil Kjernsmo <kjetil.kjernsmo@astro.uio.no>
158 Andrew Cassin <acassin@cs.mu.oz.au>
159 Thomas Kamphusmann <thomas@delphi.ping.de>
160 Horst Tellioglu <telliogl@h2hobel.phl.univie.ac.at>
161 Nikolay Pelov <Nikolay.Pelov@cs.kuleuven.ac.be>
162
163...and probably a few others. Please send me email if you feel you
164belong on this list and I forgot to include you.
165
166Also, see the btparse README file for contributors to the C library.
167
168$Id$
169