Imported Upstream version 0.38

1 files changed, 121 insertions, 0 deletions

diff --git a/btool_faq.pod b/btool_faq.pod
new file mode 100644
index 0000000..bf22ebd
--- /dev/null
+++ b/btool_faq.pod
@@ -0,0 +1,121 @@
+=head1 NAME
+
+btool_faq - Frequently-Asked Questions about btparse and Text::BibTeX
+
+=head1 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.
+
+=head1 PERL LIBRARY
+
+This section covers questions that users of C<Text::BibTeX>, the Perl
+component of B<btOOL>, have asked.
+
+=head2 Why aren't the BibTeX "month" macros defined?
+
+Because they're bibliography-specific, and C<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 F<foo.bib> that quite sensibly use the
+month macros (C<jan>, C<feb>, etc.) provided by the BibTeX standard
+style files:
+
+   $bibfile = new Text::BibTeX::File 'foo.bib'    # open file
+      or die "foo.bib: $!\n";
+   $entry = new Text::BibTeX::Entry $bibfile;     # parse first entry
+
+Using this code, you might get an "undefined macro" warning for every
+entry parsed from F<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 C<Text::BibTeX> provides a direct interface to
+the underlying macro table.  You I<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
+C<Text::BibTeX>'s object-oriented analogue to style files, called
+structure modules.  C<Text::BibTeX> provides a structure module,
+C<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 C<set_structure>
+method on a C<Text::BibTeX::File> object.  It's quite simple to tell
+C<Text::BibTeX> that entries from C<$bibfile> are expected to conform to
+the C<Bib> structure (which is implemented by the C<Text::BibTeX::Bib>
+module, but you don't really need to know that):
+
+   $bibfile = new Text::BibTeX::File '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 C<Bib> (since
+that's the only structure actually implemented as of this writing).
+
+=head2 How do I append to a BibTeX file?
+
+Just open it in append mode, and write entries to it as usual.
+Remember, a C<Text::BibTeX::File> object is mainly a wrapper around an
+C<IO::File> object, and the C<Text::BibTeX::File::open> method (and thus
+C<new> as well) is just a front-end to C<IO::File::open>.
+C<IO::File::open>, in turn, is a front-end either to Perl's builtin
+C<open> (if called with one argument) or C<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
+C<Text::BibTeX::File>'s C<new> method, then it's treated just like a
+filename passed to Perl's builtin C<open>:
+
+   my $append_file = new Text::BibTeX::File ">>$filename"
+      or die "couldn't open $filename for appending: $!\n";
+
+opens C<$filename> for appending.  If, later on, you have an entry from
+another file (say C<$entry>), then you can append it to C<$append_file>
+by just writing it as usual:
+
+   $entry->write ($append_file);
+
+See C<append_entries> in the F<examples/> subdirectory of the
+C<Text::BibTeX> distribution for a complete example.
+
+=head1 C LIBRARY
+
+This section covers frequently-asked questions about B<btparse>, the C
+component of B<btOOL>.
+
+=head2 Is there a Python binding for B<btparse> yet?
+
+Not that I know of.  I haven't written one.  If you do so, please let me
+know about it.
+
+=head1 SEE ALSO
+
+L<btparse>, L<Text::BibTeX>
+
+=head1 AUTHOR
+
+Greg Ward <gward@python.net>
+
+=head1 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.