.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "btool_faq 3"
.TH btool_faq 3 "2023-01-30" "btparse, version 0.89" "btparse"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
btool_faq \- Frequently\-Asked Questions about btparse and Text::BibTeX
.SH "DESCRIPTION"
.IX Header "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, \*(L"How do I do X?\*(R"
answers as opposed to lengthy descriptions of the capabilities and
conventions of the btOOL libraries.
.SH "PERL LIBRARY"
.IX Header "PERL LIBRARY"
This section covers questions that users of \f(CW\*(C`Text::BibTeX\*(C'\fR, the Perl
component of \fBbtOOL\fR, have asked.
.ie n .SS "Why aren't the BibTeX ""month"" macros defined?"
.el .SS "Why aren't the BibTeX ``month'' macros defined?"
.IX Subsection "Why aren't the BibTeX month macros defined?"
Because they're bibliography-specific, and \f(CW\*(C`Text::BibTeX\*(C'\fR 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 \fIfoo.bib\fR that quite sensibly use the
month macros (\f(CW\*(C`jan\*(C'\fR, \f(CW\*(C`feb\*(C'\fR, etc.) provided by the BibTeX standard
style files:
.PP
.Vb 3
\&   $bibfile = Text::BibTeX::File\->new(\*(Aqfoo.bib\*(Aq)    # open file
\&      or die "foo.bib: $!\en";
\&   $entry = Text::BibTeX::Entry\->new($bibfile);     # parse first entry
.Ve
.PP
Using this code, you might get an \*(L"undefined macro\*(R" warning for every
entry parsed from \fIfoo.bib\fR.  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.
.PP
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 \f(CW\*(C`Text::BibTeX\*(C'\fR provides a direct interface to
the underlying macro table.  You \fIcould\fR just do this before parsing any
entries:
.PP
.Vb 5
\&   use Text::BibTeX qw(:macrosubs);
\&   # ...
\&   my %month = (jan => \*(AqJanuary\*(Aq, feb => \*(AqFebruary\*(Aq, ... );
\&   add_macro_text ($macro, $value) 
\&      while (($macro, $value) = each %month);
.Ve
.PP
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
\&\f(CW\*(C`Text::BibTeX\*(C'\fR's object-oriented analogue to style files, called
structure modules.  \f(CW\*(C`Text::BibTeX\*(C'\fR provides a structure module,
\&\f(CW\*(C`Text::BibTeX::Bib\*(C'\fR, 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 \f(CW\*(C`set_structure\*(C'\fR
method on a \f(CW\*(C`Text::BibTeX::File\*(C'\fR object.  It's quite simple to tell
\&\f(CW\*(C`Text::BibTeX\*(C'\fR that entries from \f(CW$bibfile\fR are expected to conform to
the \f(CW\*(C`Bib\*(C'\fR structure (which is implemented by the \f(CW\*(C`Text::BibTeX::Bib\*(C'\fR
module, but you don't really need to know that):
.PP
.Vb 3
\&   $bibfile = Text::BibTeX::File\->new(\*(Aqfoo.bib\*(Aq)
\&      or die "foo.bib: $!\en";
\&   $bibfile\->set_structure (\*(AqBib\*(Aq);
.Ve
.PP
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 \f(CW\*(C`Bib\*(C'\fR (since
that's the only structure actually implemented as of this writing).
.SS "How do I append to a BibTeX file?"
.IX Subsection "How do I append to a BibTeX file?"
Just open it in append mode, and write entries to it as usual.
Remember, a \f(CW\*(C`Text::BibTeX::File\*(C'\fR object is mainly a wrapper around an
\&\f(CW\*(C`IO::File\*(C'\fR object, and the \f(CW\*(C`Text::BibTeX::File::open\*(C'\fR method (and thus
\&\f(CW\*(C`new\*(C'\fR as well) is just a front-end to \f(CW\*(C`IO::File::open\*(C'\fR.
\&\f(CW\*(C`IO::File::open\*(C'\fR, in turn, is a front-end either to Perl's builtin
\&\f(CW\*(C`open\*(C'\fR (if called with one argument) or \f(CW\*(C`sysopen\*(C'\fR (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
\&\f(CW\*(C`Text::BibTeX::File\*(C'\fR's \f(CW\*(C`new\*(C'\fR method, then it's treated just like a
filename passed to Perl's builtin \f(CW\*(C`open\*(C'\fR:
.PP
.Vb 2
\&   my $append_file = Text::BibTeX::File\->new(">>$filename")
\&      or die "couldn\*(Aqt open $filename for appending: $!\en";
.Ve
.PP
opens \f(CW$filename\fR for appending.  If, later on, you have an entry from
another file (say \f(CW$entry\fR), then you can append it to \f(CW$append_file\fR
by just writing it as usual:
.PP
.Vb 1
\&   $entry\->write ($append_file);
.Ve
.PP
See \f(CW\*(C`append_entries\*(C'\fR in the \fIexamples/\fR subdirectory of the
\&\f(CW\*(C`Text::BibTeX\*(C'\fR distribution for a complete example.
.SH "C LIBRARY"
.IX Header "C LIBRARY"
This section covers frequently-asked questions about \fBbtparse\fR, the C
component of \fBbtOOL\fR.
.SS "Is there a Python binding for \fBbtparse\fP yet?"
.IX Subsection "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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
btparse, Text::BibTeX
.SH "AUTHOR"
.IX Header "AUTHOR"
Greg Ward <gward@python.net>
.SH "COPYRIGHT"
.IX Header "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.