1Text::BibTeX::Bib(3)  User Contributed Perl Documentation Text::BibTeX::Bib(3)
2
3
4

NAME

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

SYNOPSIS

9          $bibfile = Text::BibTeX::File $filename->new;
10          $bibfile->set_structure ('Bib',
11                                   # Default option values:
12                                   sortby => 'name',
13                                   namestyle => 'full'
14                                   nameorder => 'first',
15                                   atitle => 1,
16                                   labels => 'numeric');
17
18          # Alternate option values:
19          $bibfile->set_option (sortby => 'year');
20          $bibfile->set_option (namestyle => 'nopunct');
21          $bibfile->set_option (namestyle => 'nospace');
22          $bibfile->set_option (nameorder => 'last');
23          $bibfile->set_option (atitle => 0);
24          $bibfile->set_option (labels => 'alpha');   # not implemented yet!
25
26          # parse entry from $bibfile and automatically make it a BibEntry
27          $entry = Text::BibTeX::Entry->new($bibfile);
28
29          # or get an entry from somewhere else which is hard-coded to be
30          # a BibEntry
31          $entry = Text::BibTeX::BibEntry->new(...);
32
33          $sortkey = $entry->sort_key;
34          @blocks = $entry->format;
35

DESCRIPTION

37       (NOTE! Do not believe everything you read in this document.  The
38       classes described here are unfinished and only lightly tested.  The
39       current implementation is a proof-of-principle, to convince myself (and
40       anyone who might be interested) that it really is possible to
41       reimplement BibTeX 0.99 in Perl using the core "Text::BibTeX" classes;
42       this principle is vaguely demonstrated by the current "Bib*" modules,
43       but not really proved.  Many important features needed to reimplement
44       the standard styles of BibTeX 0.99 are missing, even though this
45       document may brashly assert otherwise.  If you are interested in using
46       these classes, you should start by reading and grokking the code, and
47       contributing the missing bits and pieces that you need.)
48
49       "Text::BibTeX::Bib" implements the database structure for
50       bibliographies as defined by the standard styles of BibTeX 0.99.  It
51       does this by providing two classes, "BibStructure" and "BibEntry" (the
52       leading "Text::BibTeX" is implied, and will be omitted for the rest of
53       this document).  These two classes, being specific to bibliographic
54       data, are outside of the core "Text::BibTeX" class hierarchy, but are
55       distributed along with it as they provide a canonical example of a
56       specific database structure using classes derived from the core
57       hierarchy.
58
59       "BibStructure", which derives from the "Structure" class, deals with
60       the structure as a whole: it handles structure options and describes
61       all the types and fields that make up the database structure.  If
62       you're interested in writing your own database structure modules, the
63       standard interface for both of these is described in
64       Text::BibTeX::Structure; if you're just interested in finding out the
65       exact database structure or the options supported by the "Bib"
66       structure, you've come to the right place.  (However, you may have to
67       wade through a bit of excess verbiage due to this module's dual
68       purpose: first, to reimplement the standard styles of BibTeX 0.99, and
69       second, to provide an example for other programmers wishing to
70       implement new or derived database structure modules.)
71
72       "BibEntry" derives from the "StructuredEntry" class and provides
73       methods that operate on individual entries presumed to come from a
74       database conforming to the structure defined by the "BibStructure"
75       class.  (Actually, to be completely accurate, "BibEntry" inherits from
76       two intermediate classes, "BibSort" and "BibFormat".  These two classes
77       just exist to reduce the amount of code in the "Bib" module, and thanks
78       to the magic of inheritance, their existence is usually irrelevant.
79       But you might want to consult those two classes if you're interested in
80       the gory details of sorting and formatting entries from BibTeX
81       0.99-style bibliography databases.)
82

STRUCTURE OPTIONS

84       "BibStructure" handles several user-supplied "structure options" and
85       methods for dealing with them.  The options currently supported by the
86       "Bib" database structure, and the values allowed for them, are:
87
88       "sortby"
89           How to sort entries.  Valid values: "name" (sort on author names,
90           year, and title), "year" (sort on year, author names, and title).
91           Sorting on "author names" is a bit more complicated than just using
92           the "author" field; see Text::BibTeX::BibSort for details.  Default
93           value: "name".
94
95       "namestyle"
96           How to print author (and editor) names: "full" for unabbreviated
97           first names, "abbrev" for first names abbreviated with periods,
98           "nopunct" for first names abbreviated with space but no periods,
99           and "nospace" to abbreviate without space or periods.  Default
100           value: "full".
101
102       "nameorder"
103           The order in which to print names: "first" for "first von last jr"
104           order, and "last" for "von last jr first" order.  Default value:
105           "first".
106
107       "atitle_lower"
108           A boolean option: if true, non-book titles will be changed to
109           "sentence capitalization:" words following colons and sentence-
110           ending punctuation will be capitalized, and everything else at
111           brace-depth zero will be changed to lowercase.  Default value:
112           true.
113
114       "labels"
115           The type of bibliographic labels to generate: "numeric" or "alpha".
116           (Alphabetic labels are not yet implemented, so this option is
117           currently ignored.)  Default value: "numeric".
118
119       Also, several "markup options" are supported.  Markup options are
120       distinct because they don't change how text is extracted from the
121       database entries and subsequently mangled; rather, they supply bits of
122       markup that go around the database-derived text.  Markup options are
123       always two-element lists: the first to "turn on" some feature of the
124       markup language, and the second to turn it off.  For example, if your
125       target language is LaTeX2e and you want journal names emphasized, you
126       would supply a list reference "['\emph{','}']" for the "journal_mkup"
127       option.  If you were instead generating HTML, you might supply
128       "['<emph>','</emph>']".  To keep the structure module general with
129       respect to markup languages, all markup options are empty by default.
130       (Or, rather, they are all references to lists consisting of two empty
131       strings.)
132
133       "name_mkup"
134           Markup to add around the list of author names.
135
136       "atitle_mkup"
137           Markup to add around non-book (article) titles.
138
139       "btitle_mkup"
140           Markup to add around book titles.
141
142       "journal_mkup"
143           Markup to add around journal names.
144
145   Option methods
146       As required by the "Text::BibTeX::Structure" module,
147       "Text::BibTeX::Bib" provides two methods for handling options:
148       "known_option" and "default_option".  (The other two option methods,
149       "set_options" and "get_options", are just inherited from
150       "Text::BibTeX::Structure".)
151
152       known_option (OPTION)
153           Returns true if OPTION is one of the options on the above list.
154
155       default_option (OPTION)
156           Returns the default value of OPTION, or "croak"s if OPTION is not a
157           supported option.
158

DATABASE STRUCTURE

160       The other purpose of a structure class is to provide a method,
161       "describe_entry", that lists the allowed entry types and the known
162       fields for the structure.  Programmers wishing to write their own
163       database structure module should consult Text::BibTeX::Structure for
164       the conventions and requirements of this method; the purpose of the
165       present document is to describe the "Bib" database structure.
166
167       The allowed entry types, and the fields recognized for them, are:
168
169       "article"
170           Required fields: "author", "title", "journal", "year".  Optional
171           fields: "volume", "number", "pages", "month", "note".
172
173       "book"
174           Required fields: "title", "publisher", "year".  Optional fields:
175           "series", "address", "edition", "month", "note".  Constrained
176           fields: exactly one of "author", "editor"; at most one of "volume",
177           "number".
178
179       "booklet"
180           Required fields: "title".  Optional fields: "author",
181           "howpublished", "address", "month", "year", "note".
182
183       "inbook"
184           Required fields: "publisher", "year".  Optional fields: "series",
185           "type", "address", "edition", "month", "note".  Constrained fields:
186           exactly one of "author", "editor"; at least one of "chapter",
187           "pages"; at most one of "volume", "number".
188
189       "incollection"
190           Required fields: "author", "title", "booktitle", "publisher",
191           "year".  Optional fields: "editor", "series", "type", "chapter",
192           "pages", "address", "edition", "month", "note".  Constrained
193           fields: at most one of "volume", "number".
194
195       "inproceedings"
196       "conference"
197           Required fields: "author", "title", "booktitle", "year".  Optional
198           fields: "editor", "series", "pages", "address", "month",
199           "organization", "publisher", "note".  Constrained fields: at most
200           one of "volume", "number".
201
202       "manual"
203           Required fields: "title".  Optional fields: "author",
204           "organization", "address", "edition", "month", "year", "note".
205
206       "mastersthesis"
207           Required fields: "author", "title", "school", "year".  Optional
208           fields: "type", "address", "month", "note".
209
210       "misc"
211           Required fields: none.  Optional fields: "author", "title",
212           "howpublished", "month", "year", "note".
213
214       "phdthesis"
215           Required fields: "author", "title", "school", "year".  Optional
216           fields: "type", "address", "month", "note".
217
218       "proceedings"
219           Required fields: "title", "year".  Optional fields: "editor",
220           "series", "address", "month", "organization", "publisher", "note".
221           Constrained fields: at most one of "volume", "number".
222
223       "techreport"
224           Required fields: "author", "title", "institution", "year".
225           Optional fields: "type", "number", "address", "month", "note".
226
227       "unpublished"
228           Required fields: "author", "title", "note".  Optional fields:
229           "month", "year".
230

STRUCTURED ENTRY CLASS

232       The second class provided by the "Text::BibTeX::Bib" module is
233       "BibEntry" (again, a leading "Text::BibTeX" is implied).  This being a
234       structured entry class, it derives from "StructuredEntry".  The
235       conventions and requirements for such a class are documented in
236       Text::BibTeX::Structure for the benefit of programmers implementing
237       their own structure modules.
238
239       If you wish to write utilities making use of the "Bib" database
240       structure, then you should call one of the "officially supported"
241       methods provided by the "BibEntry" class.  Currently, there are only
242       two of these: "sort_key" and "format".  These are actually implemented
243       in the "BibSort" and "BibFormat" classes, respectively, which are base
244       classes of "BibEntry".  Thus, see Text::BibTeX::BibSort and
245       Text::BibTeX::BibFormat for details on these two methods.
246

SEE ALSO

248       Text::BibTeX::Structure, Text::BibTeX::BibSort,
249       Text::BibTeX::BibFormat.
250

AUTHOR

252       Greg Ward <gward@python.net>
253
255       Copyright (c) 1997-2000 by Gregory P. Ward.  All rights reserved.  This
256       file is part of the Text::BibTeX library.  This library is free
257       software; you may redistribute it and/or modify it under the same terms
258       as Perl itself.
259
260
261
262perl v5.34.0                      2022-01-21              Text::BibTeX::Bib(3)
Impressum