This document starts (and ends) with Section 5, because in reality it is the final section of "BibTeXing'' [4], the general documentation for . But that document was meant for all users, while this one is just for style designers, so the two are physically separate. Still, you should be completely familiar with “BibTeXing'', and all references in this document to sections and section numbers assume that the two documents are one.
This section, along with the standard-style documentation file btxbst.doc, should explain how to modify existing style files and to produce new ones. If you're a serious style hacker you should be familiar with van Leunen [7] for points of style, with Lamport [3] and Knuth [2] for formatting matters, and perhaps with Scribe [6] for compatibility details. And while you're at it, if you don't read the great little book by Strunk and White [5], you should at least look at its entries in the database and the reference list to see how handles multiple names.
To create a new style, it's best to start with an existing style that's close to yours, and then modify that. This is true even if you're simply updating an old style for version 0.99 (I've updated four nonstandard styles, so I say this with some experience). If you want to insert into a new style some function you'd written for an old (version 0.98i) style, keep in mind that the order of the arguments to the assignment (:=) function has been reversed. When you're finished with your style, you may want to try running it on the entire XAMPL.BIB database to make sure it handles all the standard entry types.
If you find any bugs in the standard styles, or if there are things you'd like to do with bibliography-style files but can't, please complain to Oren Patashnik.
You write bibliography styles in a postfix stack language. It's not too hard to figure out how by looking at the standard-style documentation, but this description fills in a few details (it will fill in more details if there's a demand for it).
Basically the style file is a program, written in an unnamed language, that tells how to format the entries that will go in the reference list (henceforth ``the entries'' will be ``the entry list'' or simply ``the list'', context permitting). This programming language has ten commands, described in the next subsection. These commands manipulate the language's objects: constants, variables, functions, the stack, and the entry list. (Warning: The terminology in this documentation, chosen for ease of explanation, is slightly different from 's. For example, this documentation's ``variables'' and ``functions'' are both ``functions'' to . Keep this in mind when interpreting 's error messages.)
There are two types of functions: built-in ones that provides (these are described in Section 5.3), and ones you define using either the MACRO or FUNCTION command.
Your most time-consuming task, as a style designer, will be creating or modifying functions using the FUNCTION command (actually, becoming familiar with the references listed above will be more time consuming, but assume for the moment that that's done).
Let's look at a sample function fragment. Suppose you have a string variable named label and an integer variable named lab.width, and suppose you want to append the character `a' to label and to increment lab.width:
. . . label "a" * 'label := % label := label * "a" lab.width #1 + 'lab.width := % lab.width := lab.width + 1 . . .
In the first line, label pushes that variable's value onto the stack. Next, the "a" pushes the string constant `a' onto the stack. Then the built-in function * pops the top two strings and pushes their concatenation. The 'label pushes that variable's name onto the stack. And finally, the built-in function := pops the variable name and the concatenation and performs the assignment treats the stuff following the % as a comment in the style file. The second line is similar except that it uses #1, with no spaces intervening between the `#' and the `1', to push this integer constant.
The nonnull spacing here is arbitrary: multiple spaces, tabs, or newlines are equivalent to a single one (except that you're probably better off not having blank lines within commands, as explained shortly).
For string constants, absolutely any printing character is legal between two consecutive double quotes, but here (and only here) treats upper- and lower-case equivalents as different. Furthermore, spacing is relevant within a string constant, and you mustn't split a string constant across lines (that is, the beginning and ending double quotes must be on the same line).
Variable and function names may not begin with a numeral and may not contain any of the ten restricted characters on page 143 of the LATEX book, but may otherwise contain any printing characters. Also, considers upper- and lower-case equivalents to be the same.
Integers and strings are the only value types for constants and variables (booleans are implemented simply as 0-or-1 integers). There are three kinds of variables:
These are string-valued, read-only variables that store the information from the database file; their values are set by the READ command. As with entry variables, each has a value for each entry.
There are ten style-file commands: Five (ENTRY, FUNCTION, INTEGERS, MACRO, and STRINGS) declare and define variables and functions; one (READ) reads in the database information; and four (EXECUTE, ITERATE, REVERSE, and SORT) manipulate the entries and produce output. Although the command names appear here in upper case, ignores case differences.
Some restrictions: There must be exactly one ENTRY and one READ command; the ENTRY command, all MACRO commands, and certain FUNCTION commands (see next subsection's description of call.type$) must precede the READ command; and the READ command must precede the four that manipulate the entries and produce output.
Also it's best (but not essential) to leave at least one blank line between commands and to leave no blank lines within a command; this helps recover from any syntax errors you make.
You must enclose each argument of every command in braces. Look at the standard-style documentation for syntactic issues not described in this section. Here are the ten commands:
Declares the fields and entry variables. It has three arguments, each a (possibly empty) list of variable names. The three lists are of: fields, integer entry variables, and string entry variables. There is an additional field that
automatically declares, crossref, used for cross referencing. And there is an additional string entry variable automatically declared, sort.key$, used by the SORT command. Each of these variables has a value for each entry on the list.
Declares global string variables. It has one argument, a list of variable names. You may have any number of these commands, but a variable's declaration must precede its use.
Before we get to the built-in functions, a few words about some other built-in objects. There is one built-in string entry variable, sort.key$, which the style program must set if the style is to do sorting. There is one built-in field, crossref, used for the cross referencing feature described in Section 4. And there are two built-in integer global variables, entry.max$ and global.max$, which are set by default to some internal constants; you should truncate strings to these lengths before you assign to string variables, so as to not generate any warning messages.
There are currently 37 built-in functions. Every built-in function with a letter in its name ends with a `$'. In what follows, ``first'', ``second'', and so on refer to the order popped. A ``literal'' is an element on the stack, and it will be either an integer value, a string value, a variable or function name, or a special value denoting a missing field. If any popped literal has an incorrect type,
complains and pushes the integer 0 or the null string, depending on whether the function was supposed to push an integer or string.
\cite
-command argument
for this entry.Pops the top (string) literal and writes it on the output buffer (which will result in stuff being written onto the bbl file when the buffer fills up).
Note that the built-in functions while$ and if$ require two function literals on the stack. You get them there either by immediately preceding the name of a function by a single quote, or, if you don't feel like defining a new function with the FUNCTION command, by simply giving its definition (that is, giving what would be the second argument to the FUNCTION command, including the surrounding braces). For example the following function fragment appends the character `a' if the string variable named label is nonnull:
. . . label "" = 'skip$ { label "a" * 'label := } if$ . . .
A function whose name you quote needn't be built in like skip$ above--it may, for example, be a field name or a function you've defined earlier.
What's in a name? Section 4 pretty much describes this. Each name consists of four parts: First, von, Last, and Jr; each consists of a list of name-tokens, and any list but Last's may be empty for a nonnull name. This subsection describes the format string you must supply to the built-in function format.name$.
Let's look at an example of a very long name. Suppose a database entry [1] has the field
author = "Charles Louis Xavier Joseph de la Vall{\'e}e Poussin"
and suppose you want this formatted ``last name comma initials''. If you use the format string
"{vv~}{ll}{, jj}{, f}?"
will produce
de~la Vall{\'e}e~Poussin, C.~L. X.~J?
as the formatted string.
Let's look at this example in detail. There are four brace-level 1 pieces to this format string, one for each part of a name. If the corresponding part of a name isn't present (the Jr part for this name), everything in that piece is ignored. Anything at brace-level 0 is output verbatim (the presumed typo `?' for this name is at brace-level 0), but you probably won't use this feature much.
Within each piece a double letter tells to use whole tokens, and a single
letter, to abbreviate them (these letters must be at brace-level 1);
everything else within the piece is used verbatim (well, almost
everything--read on). The tie at the end of the von part (in
{vv~}
) is a discretionary tie-- will output a tie at that point
if it thinks there's a need for one; otherwise it will output a space. If you
really, really, want a tie there, regardless of what thinks, use two of them
(only one will be output); that is, use {vv~~}
. A tie is
discretionary only if it's the last character of the piece; anywhere else
it's treated as an ordinary character.
puts default strings between tokens of a name part: For whole tokens it uses either a space or a tie, depending on which one it thinks is best, and for abbreviated tokens it uses a period followed by either a space or a tie. However it doesn't use this default string after the last token in a list; hence there's no period following the `J' for our example. You should have used
"{vv~}{ll}{, jj}{, f.}" to get to produce the same formatted string but with the question mark replaced by a period. Note that the period should go inside the First-name piece, rather than where the question mark was, in case a name has no First part.
If you want to override 's default between-token strings, you must explicitly specify a string. For example suppose you want a label to contain the first letter from each token in the von and Last parts, with no spaces; you should use the format string
"{v{}}{l{}}"
so that will produce `dlVP' as the formatted string. You must give a string for each piece whose default you want overridden (the example here uses the null string for both pieces), and this string must immediately follow either the single or double letter for the piece. You may not have any other letters at brace-level 1 in the format string.
Mary-Claire van Leunen.
A Handbook for Scholars.
Knopf, 1979.
This document was generated using the LaTeX2HTML translator Version 2002-1 (1.68)
Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer
Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics
Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers
/tmp/lyx_tmpdir16750g899CL/lyx_tmpbuf1/btxhak.tex
The translation was initiated by root on 2002-12-22