1BTOOL_FAQ(1)                        btparse                       BTOOL_FAQ(1)
2
3
4

NAME

6       btool_faq - Frequently-Asked Questions about btparse and Text::BibTeX
7

DESCRIPTION

9       This document attempts to address questions that I have been asked
10       several times, and are easy to answer -- but not by perusing the
11       documentation.  For various reasons, the answers tend to be thinly
12       distributed across several man pages, making it difficult to figure out
13       what's going on.  Hence, this man page will attempt to tie together
14       various strands of thought, providing quick, focused, "How do I do X?"
15       answers as opposed to lengthy descriptions of the capabilities and
16       conventions of the btOOL libraries.
17

PERL LIBRARY

19       This section covers questions that users of "Text::BibTeX", the Perl
20       component of btOOL, have asked.
21
22   Why aren't the BibTeX "month" macros defined?
23       Because they're bibliography-specific, and "Text::BibTeX" by default
24       doesn't impose any assumptions about a particular type of database or
25       data-processing domain on your entries.  The problem arises when you
26       parse entries from a file, say foo.bib that quite sensibly use the
27       month macros ("jan", "feb", etc.) provided by the BibTeX standard style
28       files:
29
30          $bibfile = Text::BibTeX::File->new('foo.bib')    # open file
31             or die "foo.bib: $!\n";
32          $entry = Text::BibTeX::Entry->new($bibfile);     # parse first entry
33
34       Using this code, you might get an "undefined macro" warning for every
35       entry parsed from foo.bib.  Apart from the superficial annoyance of all
36       those warning messages, the undefined macros are expanded as empty
37       strings, meaning you lose any information about them---not good.
38
39       You could always kludge it and forcibly define the month macros
40       yourself.  Prior to release 0.30, this had to be done by parsing a set
41       of fake entries, but now "Text::BibTeX" provides a direct interface to
42       the underlying macro table.  You could just do this before parsing any
43       entries:
44
45          use Text::BibTeX qw(:macrosubs);
46          # ...
47          my %month = (jan => 'January', feb => 'February', ... );
48          add_macro_text ($macro, $value)
49             while (($macro, $value) = each %month);
50
51       But there's a better way that's more in keeping with how things are
52       done under BibTeX (where default macros are defined in the style file):
53       use "Text::BibTeX"'s object-oriented analogue to style files, called
54       structure modules.  "Text::BibTeX" provides a structure module,
55       "Text::BibTeX::Bib", that (partially) emulates the standard style files
56       of BibTeX 0.99, including the definition of month macros.  Structure
57       modules are specified on a per-file basis by using the "set_structure"
58       method on a "Text::BibTeX::File" object.  It's quite simple to tell
59       "Text::BibTeX" that entries from $bibfile are expected to conform to
60       the "Bib" structure (which is implemented by the "Text::BibTeX::Bib"
61       module, but you don't really need to know that):
62
63          $bibfile = Text::BibTeX::File->new('foo.bib')
64             or die "foo.bib: $!\n";
65          $bibfile->set_structure ('Bib');
66
67       You probably shouldn't hardcode the name of a particular structure in
68       your programs, though, as there will eventually be a multitude of
69       structure modules to choose from (just as there are a multitude of
70       BibTeX style files to choose from).  My preferred approach is to make
71       the structure a command-line option which defaults to "Bib" (since
72       that's the only structure actually implemented as of this writing).
73
74   How do I append to a BibTeX file?
75       Just open it in append mode, and write entries to it as usual.
76       Remember, a "Text::BibTeX::File" object is mainly a wrapper around an
77       "IO::File" object, and the "Text::BibTeX::File::open" method (and thus
78       "new" as well) is just a front-end to "IO::File::open".
79       "IO::File::open", in turn, is a front-end either to Perl's builtin
80       "open" (if called with one argument) or "sysopen" (two or three
81       arguments).  To save you the trouble of going off and reading all those
82       man pages, here's the trick: if you pass just a filename to
83       "Text::BibTeX::File"'s "new" method, then it's treated just like a
84       filename passed to Perl's builtin "open":
85
86          my $append_file = Text::BibTeX::File->new(">>$filename")
87             or die "couldn't open $filename for appending: $!\n";
88
89       opens $filename for appending.  If, later on, you have an entry from
90       another file (say $entry), then you can append it to $append_file by
91       just writing it as usual:
92
93          $entry->write ($append_file);
94
95       See "append_entries" in the examples/ subdirectory of the
96       "Text::BibTeX" distribution for a complete example.
97

C LIBRARY

99       This section covers frequently-asked questions about btparse, the C
100       component of btOOL.
101
102   Is there a Python binding for btparse yet?
103       Not that I know of.  I haven't written one.  If you do so, please let
104       me know about it.
105

SEE ALSO

107       btparse, Text::BibTeX
108

AUTHOR

110       Greg Ward <gward@python.net>
111
113       Copyright (c) 1997-2000 by Gregory P. Ward.  All rights reserved.  This
114       file is part of the Text::BibTeX library.  This library is free
115       software; you may redistribute it and/or modify it under the same terms
116       as Perl itself.
117
118
119
120btparse, version 0.88             2021-01-27                      BTOOL_FAQ(1)
Impressum