The BibTeX Format

At first glance, the BibTeX file format seems very clear and simple; however, there are a number of peculiarities which warrant some explanation. The best place to start reading is probably at your closest ctan server where the original bibtex from 1988 still lives. Additionally, Xavier Decoret has written a great summary of the format; another invaluable source of information is Nicolas Markey's website. Unfortunately, even after consulting these documents, a number of issues remain. Therefore, it is the purpose of this section to deliver the rationale that went into some of the design decision in BibTeX-Ruby.

A BibTeX bibliography is typically stored in a file with the file extension '.bib'. This file may contain any number of BibTeX objects; everything that is not a BibTeX object is assumed to be a comment and ignored.

The individual objects are discussed in further detail below. First, however, a number of general remarks:

• BibTeX-Ruby begins in comment-mode, treating all text it encounters as comments. Normally these comments are ignored; however, if you wish the parser to include them, you can do so by adding the symbol :meta_comments to the :include array in the parser's options.
• Note that string literals in BibTeX are either contained in quotes or braces; nested quotes in a quoted literal are not escaped with a usual backslash but must be placed inside braces. Nested braces must be balanced in literals, regardless of whether they are surrounded by quotes or braces.
• Quoted strings and string constants (which are defined by @string objects) can be concatted by the '#' symbol. String literals in braces can not be concatted in this way.
• The '@' symbol may only occur in quoted string literals (not in braced out literals) in the original BibTeX; note, however, that this is not true for BibTeX-Ruby (i.e., it will parse any string containing an '@').

@comment

The purpose of the @comment object is not entirely clear, because everything outside of an object is treated as a comment anyway. Nicolas Markay argues that a @comment makes it possible to quickly comment out a number of consecutive objects; however, as Xavier Decoret points out that this does not work with the original `bibtex' program (following a @comment, it simply ignores everything until the end of the line). Indeed, on page 13 of the original documentation, Oren Patashnik explains that @comment objects are not really necessary; they exist only for Scribe system compatibility.

Because they would be useless otherwise, BibTeX-Ruby treats @comment objects as Nicolas Markay describes them: thus, everything inside a @comment is treated as a comment and is ignored -- everything, that is, until the object is closed. For this reason, BibTeX-Ruby assumes that braces inside a @comment are balanced! Obviously, BibTeX-Ruby differs from bibtex in that respect; though, the gain is, that it is now possible to comment out a sequence of entries, without removing their respective '@' symbols.

@string

The @string object defines a single string constant (for multiple constant assignments, it is necessary to define separate @string objects). These constants can be used within string assignments in other @string or @preamble objects, as well as in regular BibTeX entries. For example, this is a valid constant definition and usage:

@string{ generator = "BibTeX-Ruby"}
@preamble{ "This bibliography was generated by " # generator }

@preamble

Typically, the purpose of @preamble objects is to define LaTeX statements, which will be put into the '.bbl' file by bibtex. A @preamble object may contain a single string literal, a single string constant (defined by a @string object), or a concatenation of literals and constants.

Entries

Entries represent proper BibTeX objects (e.g., @book, @collection, etc.).