Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
BTOOL_FAQ(1)			    btparse			  BTOOL_FAQ(1)

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

       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.

       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

	  $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

	  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.

       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.

       btparse,	Text::BibTeX

       Greg Ward <>

       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.

btparse, version 0.88		  2019-04-29			  BTOOL_FAQ(1)


Want to link to this manual page? Use this URL:

home | help