NAME

       Text::BibTeX::Bib - defines the "Bib" database structure

SYNOPSIS

          $bibfile = Text::BibTeX::File $filename->new;
          $bibfile->set_structure ('Bib',
                                   # Default option values:
                                   sortby => 'name',
                                   namestyle => 'full'
                                   nameorder => 'first',
                                   atitle => 1,
                                   labels => 'numeric');

          # Alternate option values:
          $bibfile->set_option (sortby => 'year');
          $bibfile->set_option (namestyle => 'nopunct');
          $bibfile->set_option (namestyle => 'nospace');
          $bibfile->set_option (nameorder => 'last');
          $bibfile->set_option (atitle => 0);
          $bibfile->set_option (labels => 'alpha');   # not implemented yet!

          # parse entry from $bibfile and automatically make it a BibEntry
          $entry = Text::BibTeX::Entry->new($bibfile);

          # or get an entry from somewhere else which is hard-coded to be
          # a BibEntry
          $entry = Text::BibTeX::BibEntry->new(...);

          $sortkey = $entry->sort_key;
          @blocks = $entry->format;

DESCRIPTION

       (NOTE! Do not believe everything you read in this document.  The classes described here
       are unfinished and only lightly tested.  The current implementation is a proof-of-
       principle, to convince myself (and anyone who might be interested) that it really is
       possible to reimplement BibTeX 0.99 in Perl using the core "Text::BibTeX" classes; this
       principle is vaguely demonstrated by the current "Bib*" modules, but not really proved.
       Many important features needed to reimplement the standard styles of BibTeX 0.99 are
       missing, even though this document may brashly assert otherwise.  If you are interested in
       using these classes, you should start by reading and grokking the code, and contributing
       the missing bits and pieces that you need.)

       "Text::BibTeX::Bib" implements the database structure for bibliographies as defined by the
       standard styles of BibTeX 0.99.  It does this by providing two classes, "BibStructure" and
       "BibEntry" (the leading "Text::BibTeX" is implied, and will be omitted for the rest of
       this document).  These two classes, being specific to bibliographic data, are outside of
       the core "Text::BibTeX" class hierarchy, but are distributed along with it as they provide
       a canonical example of a specific database structure using classes derived from the core
       hierarchy.

       "BibStructure", which derives from the "Structure" class, deals with the structure as a
       whole: it handles structure options and describes all the types and fields that make up
       the database structure.  If you're interested in writing your own database structure
       modules, the standard interface for both of these is described in Text::BibTeX::Structure;
       if you're just interested in finding out the exact database structure or the options
       supported by the "Bib" structure, you've come to the right place.  (However, you may have
       to wade through a bit of excess verbiage due to this module's dual purpose: first, to
       reimplement the standard styles of BibTeX 0.99, and second, to provide an example for
       other programmers wishing to implement new or derived database structure modules.)

       "BibEntry" derives from the "StructuredEntry" class and provides methods that operate on
       individual entries presumed to come from a database conforming to the structure defined by
       the "BibStructure" class.  (Actually, to be completely accurate, "BibEntry" inherits from
       two intermediate classes, "BibSort" and "BibFormat".  These two classes just exist to
       reduce the amount of code in the "Bib" module, and thanks to the magic of inheritance,
       their existence is usually irrelevant.  But you might want to consult those two classes if
       you're interested in the gory details of sorting and formatting entries from BibTeX
       0.99-style bibliography databases.)

STRUCTURE OPTIONS

       "BibStructure" handles several user-supplied "structure options" and methods for dealing
       with them.  The options currently supported by the "Bib" database structure, and the
       values allowed for them, are:

       "sortby"
           How to sort entries.  Valid values: "name" (sort on author names, year, and title),
           "year" (sort on year, author names, and title).  Sorting on "author names" is a bit
           more complicated than just using the "author" field; see Text::BibTeX::BibSort for
           details.  Default value: "name".

       "namestyle"
           How to print author (and editor) names: "full" for unabbreviated first names, "abbrev"
           for first names abbreviated with periods, "nopunct" for first names abbreviated with
           space but no periods, and "nospace" to abbreviate without space or periods.  Default
           value: "full".

       "nameorder"
           The order in which to print names: "first" for "first von last jr" order, and "last"
           for "von last jr first" order.  Default value: "first".

       "atitle_lower"
           A boolean option: if true, non-book titles will be changed to "sentence
           capitalization:" words following colons and sentence-ending punctuation will be
           capitalized, and everything else at brace-depth zero will be changed to lowercase.
           Default value: true.

       "labels"
           The type of bibliographic labels to generate: "numeric" or "alpha".  (Alphabetic
           labels are not yet implemented, so this option is currently ignored.)  Default value:
           "numeric".

       Also, several "markup options" are supported.  Markup options are distinct because they
       don't change how text is extracted from the database entries and subsequently mangled;
       rather, they supply bits of markup that go around the database-derived text.  Markup
       options are always two-element lists: the first to "turn on" some feature of the markup
       language, and the second to turn it off.  For example, if your target language is LaTeX2e
       and you want journal names emphasized, you would supply a list reference "['\emph{','}']"
       for the "journal_mkup" option.  If you were instead generating HTML, you might supply
       "['<emph>','</emph>']".  To keep the structure module general with respect to markup
       languages, all markup options are empty by default.  (Or, rather, they are all references
       to lists consisting of two empty strings.)

       "name_mkup"
           Markup to add around the list of author names.

       "atitle_mkup"
           Markup to add around non-book (article) titles.

       "btitle_mkup"
           Markup to add around book titles.

       "journal_mkup"
           Markup to add around journal names.

   Option methods
       As required by the "Text::BibTeX::Structure" module, "Text::BibTeX::Bib" provides two
       methods for handling options: "known_option" and "default_option".  (The other two option
       methods, "set_options" and "get_options", are just inherited from
       "Text::BibTeX::Structure".)

       known_option (OPTION)
           Returns true if OPTION is one of the options on the above list.

       default_option (OPTION)
           Returns the default value of OPTION, or "croak"s if OPTION is not a supported option.

DATABASE STRUCTURE

       The other purpose of a structure class is to provide a method, "describe_entry", that
       lists the allowed entry types and the known fields for the structure.  Programmers wishing
       to write their own database structure module should consult Text::BibTeX::Structure for
       the conventions and requirements of this method; the purpose of the present document is to
       describe the "Bib" database structure.

       The allowed entry types, and the fields recognized for them, are:

       "article"
           Required fields: "author", "title", "journal", "year".  Optional fields: "volume",
           "number", "pages", "month", "note".

       "book"
           Required fields: "title", "publisher", "year".  Optional fields: "series", "address",
           "edition", "month", "note".  Constrained fields: exactly one of "author", "editor"; at
           most one of "volume", "number".

       "booklet"
           Required fields: "title".  Optional fields: "author", "howpublished", "address",
           "month", "year", "note".

       "inbook"
           Required fields: "publisher", "year".  Optional fields: "series", "type", "address",
           "edition", "month", "note".  Constrained fields: exactly one of "author", "editor"; at
           least one of "chapter", "pages"; at most one of "volume", "number".

       "incollection"
           Required fields: "author", "title", "booktitle", "publisher", "year".  Optional
           fields: "editor", "series", "type", "chapter", "pages", "address", "edition", "month",
           "note".  Constrained fields: at most one of "volume", "number".

       "inproceedings"
       "conference"
           Required fields: "author", "title", "booktitle", "year".  Optional fields: "editor",
           "series", "pages", "address", "month", "organization", "publisher", "note".
           Constrained fields: at most one of "volume", "number".

       "manual"
           Required fields: "title".  Optional fields: "author", "organization", "address",
           "edition", "month", "year", "note".

       "mastersthesis"
           Required fields: "author", "title", "school", "year".  Optional fields: "type",
           "address", "month", "note".

       "misc"
           Required fields: none.  Optional fields: "author", "title", "howpublished", "month",
           "year", "note".

       "phdthesis"
           Required fields: "author", "title", "school", "year".  Optional fields: "type",
           "address", "month", "note".

       "proceedings"
           Required fields: "title", "year".  Optional fields: "editor", "series", "address",
           "month", "organization", "publisher", "note".  Constrained fields: at most one of
           "volume", "number".

       "techreport"
           Required fields: "author", "title", "institution", "year".  Optional fields: "type",
           "number", "address", "month", "note".

       "unpublished"
           Required fields: "author", "title", "note".  Optional fields: "month", "year".

STRUCTURED ENTRY CLASS

       The second class provided by the "Text::BibTeX::Bib" module is "BibEntry" (again, a
       leading "Text::BibTeX" is implied).  This being a structured entry class, it derives from
       "StructuredEntry".  The conventions and requirements for such a class are documented in
       Text::BibTeX::Structure for the benefit of programmers implementing their own structure
       modules.

       If you wish to write utilities making use of the "Bib" database structure, then you should
       call one of the "officially supported" methods provided by the "BibEntry" class.
       Currently, there are only two of these: "sort_key" and "format".  These are actually
       implemented in the "BibSort" and "BibFormat" classes, respectively, which are base classes
       of "BibEntry".  Thus, see Text::BibTeX::BibSort and Text::BibTeX::BibFormat for details on
       these two methods.

SEE ALSO

       Text::BibTeX::Structure, Text::BibTeX::BibSort, Text::BibTeX::BibFormat.

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.