NAME

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

DESCRIPTION

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

PERL LIBRARY

       This section covers questions that users of "Text::BibTeX", the Perl component of btOOL,
       have asked.

   Why aren't the BibTeX "month" macros defined?
       Because they're bibliography-specific, and "Text::BibTeX" by default doesn't impose any
       assumptions about a particular type of database or data-processing domain on your entries.
       The problem arises when you parse entries from a file, say foo.bib that quite sensibly use
       the month macros ("jan", "feb", etc.) provided by the BibTeX standard style files:

          $bibfile = Text::BibTeX::File->new('foo.bib')    # open file
             or die "foo.bib: $!\n";
          $entry = Text::BibTeX::Entry->new($bibfile);     # parse first entry

       Using this code, you might get an "undefined macro" warning for every entry parsed from
       foo.bib.  Apart from the superficial annoyance of all those warning messages, the
       undefined macros are expanded as empty strings, meaning you lose any information about
       them---not good.

       You could always kludge it and forcibly define the month macros yourself.  Prior to
       release 0.30, this had to be done by parsing a set of fake entries, but now "Text::BibTeX"
       provides a direct interface to the underlying macro table.  You could just do this before
       parsing any entries:

          use Text::BibTeX qw(:macrosubs);
          # ...
          my %month = (jan => 'January', feb => 'February', ... );
          add_macro_text ($macro, $value)
             while (($macro, $value) = each %month);

       But there's a better way that's more in keeping with how things are done under BibTeX
       (where default macros are defined in the style file): use "Text::BibTeX"'s object-oriented
       analogue to style files, called structure modules.  "Text::BibTeX" provides a structure
       module, "Text::BibTeX::Bib", that (partially) emulates the standard style files of BibTeX
       0.99, including the definition of month macros.  Structure modules are specified on a per-
       file basis by using the "set_structure" method on a "Text::BibTeX::File" object.  It's
       quite simple to tell "Text::BibTeX" that entries from $bibfile are expected to conform to
       the "Bib" structure (which is implemented by the "Text::BibTeX::Bib" module, but you don't
       really need to know that):

          $bibfile = Text::BibTeX::File->new('foo.bib')
             or die "foo.bib: $!\n";
          $bibfile->set_structure ('Bib');

       You probably shouldn't hardcode the name of a particular structure in your programs,
       though, as there will eventually be a multitude of structure modules to choose from (just
       as there are a multitude of BibTeX style files to choose from).  My preferred approach is
       to make the structure a command-line option which defaults to "Bib" (since that's the only
       structure actually implemented as of this writing).

   How do I append to a BibTeX file?
       Just open it in append mode, and write entries to it as usual.  Remember, a
       "Text::BibTeX::File" object is mainly a wrapper around an "IO::File" object, and the
       "Text::BibTeX::File::open" method (and thus "new" as well) is just a front-end to
       "IO::File::open".  "IO::File::open", in turn, is a front-end either to Perl's builtin
       "open" (if called with one argument) or "sysopen" (two or three arguments).  To save you
       the trouble of going off and reading all those man pages, here's the trick: if you pass
       just a filename to "Text::BibTeX::File"'s "new" method, then it's treated just like a
       filename passed to Perl's builtin "open":

          my $append_file = Text::BibTeX::File->new(">>$filename")
             or die "couldn't open $filename for appending: $!\n";

       opens $filename for appending.  If, later on, you have an entry from another file (say
       $entry), then you can append it to $append_file by just writing it as usual:

          $entry->write ($append_file);

       See "append_entries" in the examples/ subdirectory of the "Text::BibTeX" distribution for
       a complete example.

C LIBRARY

       This section covers frequently-asked questions about btparse, the C component of btOOL.

   Is there a Python binding for btparse yet?
       Not that I know of.  I haven't written one.  If you do so, please let me know about it.

SEE ALSO

       btparse, Text::BibTeX

AUTHOR

       Greg Ward <gward@python.net>

COPYRIGHT

       Copyright (c) 1997-2000 by Gregory P. Ward.  All rights reserved.  This file is part of
       the Text::BibTeX library.  This library is free software; you may redistribute it and/or
       modify it under the same terms as Perl itself.