| 1 |
% Copyright (C) 1988, 2010 Oren Patashnik. |
| 2 |
% Unlimited copying and redistribution of this file are permitted if it |
| 3 |
% is unmodified. Modifications (and their redistribution) are also |
| 4 |
% permitted, as long as the resulting file is renamed. |
| 5 |
|
| 6 |
\def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em |
| 7 |
T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}} |
| 8 |
|
| 9 |
\title{Designing B\kern-.05em{\large I}\kern-.025em{\large B}\kern-.08em\TeX\ |
| 10 |
Styles} |
| 11 |
\author{Oren Patashnik} |
| 12 |
\date{February 8, 1988} |
| 13 |
|
| 14 |
\documentstyle{article} |
| 15 |
\begin{document} |
| 16 |
|
| 17 |
\maketitle |
| 18 |
|
| 19 |
\setcounter{section}{4} |
| 20 |
\section{Bibliography-style hacking} |
| 21 |
\label{style} |
| 22 |
|
| 23 |
This document starts (and ends) with Section~\ref{style}, |
| 24 |
because in reality it is the final section of ``\BibTeX ing''~\cite{btxdoc}, |
| 25 |
the general documentation for \BibTeX. |
| 26 |
But that document was meant for all \BibTeX\ users, |
| 27 |
while this one is just for style designers, |
| 28 |
so the two are physically separate. |
| 29 |
Still, you should be completely familiar with ``\BibTeX ing''$\!$, |
| 30 |
and all references in this document |
| 31 |
to sections and section numbers |
| 32 |
assume that the two documents are one. |
| 33 |
|
| 34 |
This section, |
| 35 |
along with the standard-style documentation file \hbox{\tt btxbst.doc}, |
| 36 |
should explain how to modify |
| 37 |
existing style files and to produce new ones. |
| 38 |
If you're a serious style hacker you should be familiar |
| 39 |
with van~Leunen~\cite{van-leunen} for points of style, |
| 40 |
with Lamport~\cite{latex} and Knuth~\cite{texbook} for formatting matters, |
| 41 |
and perhaps with {\em Scribe\/}~\cite{scribe} for compatibility details. |
| 42 |
And while you're at it, if you don't read the great little book by Strunk and |
| 43 |
White~\cite{strunk-and-white}, you should at least look at its |
| 44 |
entries in the database and the reference list |
| 45 |
to see how \BibTeX\ handles multiple names. |
| 46 |
|
| 47 |
To create a new style, |
| 48 |
it's best to start with an existing style that's close to yours, |
| 49 |
and then modify that. |
| 50 |
This is true even if you're simply updating an old style |
| 51 |
for \BibTeX\ version 0.99 |
| 52 |
(I've updated four nonstandard styles, |
| 53 |
so I say this with some experience). |
| 54 |
If you want to insert into a new style |
| 55 |
some function you'd written for an old (version 0.98i) style, |
| 56 |
keep in mind that the order of the arguments to |
| 57 |
the assignment ({\tt :=}) function has been reversed. |
| 58 |
When you're finished with your style, |
| 59 |
you may want to try running it on the entire \hbox{\tt XAMPL.BIB} database |
| 60 |
to make sure it handles all the standard entry types. |
| 61 |
|
| 62 |
If you find any bugs in the standard styles, |
| 63 |
or if there are things you'd like to do |
| 64 |
with bibliography-style files but can't, |
| 65 |
please complain to Oren Patashnik. |
| 66 |
|
| 67 |
|
| 68 |
\subsection{General description} |
| 69 |
|
| 70 |
You write bibliography styles in a postfix stack language. It's |
| 71 |
not too hard to figure out how by looking at the standard-style documentation, |
| 72 |
but this description fills in a few details (it will fill in more |
| 73 |
details if there's a demand for it). |
| 74 |
|
| 75 |
Basically the style file is a program, written in an unnamed language, that |
| 76 |
tells \BibTeX\ how to format the entries that will go in the reference list |
| 77 |
(henceforth ``the entries'' will be ``the entry list'' |
| 78 |
or simply ``the list''$\!$, context permitting). |
| 79 |
This programming language has ten commands, described in the next subsection. |
| 80 |
These commands manipulate the language's objects: |
| 81 |
constants, variables, functions, the stack, and the entry list. |
| 82 |
(Warning: The terminology in this documentation, |
| 83 |
chosen for ease of explanation, is slightly different from \BibTeX's. |
| 84 |
For example, this documentation's ``variables'' and ``functions'' |
| 85 |
are both ``functions'' to \BibTeX. |
| 86 |
Keep this in mind when interpreting \BibTeX's error messages.) |
| 87 |
|
| 88 |
There are two types of functions: {\it built-in\/} ones that \BibTeX\ provides |
| 89 |
(these are described in Section~\ref{built-in-fns}), and ones you define |
| 90 |
using either the \hbox{\tt MACRO} or \hbox{\tt FUNCTION} command. |
| 91 |
|
| 92 |
Your most time-consuming task, as a style designer, |
| 93 |
will be creating or modifying functions |
| 94 |
using the \hbox{\tt FUNCTION} command |
| 95 |
(actually, becoming familiar with the references listed above will be |
| 96 |
more time consuming, but assume for the moment that that's done). |
| 97 |
|
| 98 |
Let's look at a sample function fragment. |
| 99 |
Suppose you have a string variable named \hbox{\tt label} |
| 100 |
and an integer variable named \hbox{\tt lab.width}, |
| 101 |
and suppose you want to append the character `{\tt a}' to \hbox{\tt label} |
| 102 |
and to increment \hbox{\tt lab.width}: |
| 103 |
\begin{verbatim} |
| 104 |
. . . |
| 105 |
label "a" * 'label := % label := label * "a" |
| 106 |
lab.width #1 + 'lab.width := % lab.width := lab.width + 1 |
| 107 |
. . . |
| 108 |
\end{verbatim} |
| 109 |
In the first line, |
| 110 |
\hbox{\tt label} pushes that variable's value onto the stack. |
| 111 |
Next, the {\tt "a"} pushes the string constant `{\tt a}' onto the stack. |
| 112 |
Then the built-in function {\tt *} pops the top two strings and |
| 113 |
pushes their concatenation. |
| 114 |
The \hbox{\tt 'label} pushes that variable's name onto the stack. |
| 115 |
And finally, the built-in function {\tt :=} pops |
| 116 |
the variable name and the concatenation and performs the assignment. |
| 117 |
\BibTeX\ treats the stuff following the {\tt \%} as a comment |
| 118 |
in the style file. |
| 119 |
The second line is similar except that it uses {\tt \#1}, |
| 120 |
with no spaces intervening between the `{\tt \#}' and the `{\tt 1}'$\!$, |
| 121 |
to push this integer constant. |
| 122 |
|
| 123 |
The nonnull spacing here is arbitrary: multiple spaces, tabs, or newlines |
| 124 |
are equivalent to a single one (except that you're probably better off |
| 125 |
not having blank lines within commands, as explained shortly). |
| 126 |
|
| 127 |
For string constants, absolutely any printing character |
| 128 |
is legal between two consecutive double quotes, but \BibTeX\ here |
| 129 |
(and only here) treats upper- and lower-case equivalents as different. |
| 130 |
Furthermore, spacing {\em is\/} relevant within a string constant, |
| 131 |
and you mustn't split a string constant across lines |
| 132 |
(that is, the beginning and ending double quotes must be on the same line). |
| 133 |
|
| 134 |
Variable and function names may not begin with a numeral and |
| 135 |
may not contain any of the ten restricted characters |
| 136 |
on page~143 of the \LaTeX\ book, |
| 137 |
but may otherwise contain any printing characters. |
| 138 |
Also, \BibTeX\ considers upper- and lower-case equivalents to be the same. |
| 139 |
|
| 140 |
Integers and strings are the only value types for constants and variables |
| 141 |
(booleans are implemented simply as 0-or-1 integers). |
| 142 |
There are three kinds of variables: |
| 143 |
\begin{description} |
| 144 |
|
| 145 |
\item[global variables\hfill] These are either integer- or string-valued, |
| 146 |
declared using an \hbox{\tt INTEGERS} or \hbox{\tt STRINGS} command. |
| 147 |
|
| 148 |
\item[entry variables\hfill] These are either integer- or string-valued, |
| 149 |
declared using the \hbox{\tt ENTRY} command. |
| 150 |
Each has a value for each entry on the list |
| 151 |
(example: a variable \hbox{\tt label} might store |
| 152 |
the label string you'll use for the entry). |
| 153 |
|
| 154 |
\item[fields\hfill] These are string-valued, read-only variables |
| 155 |
that store the information from the database file; |
| 156 |
their values are set by the \hbox{\tt READ} command. |
| 157 |
As with entry variables, each has a value for each entry. |
| 158 |
\end{description} |
| 159 |
|
| 160 |
|
| 161 |
\subsection{Commands} |
| 162 |
|
| 163 |
There are ten style-file commands: |
| 164 |
Five (\hbox{\tt ENTRY}, \hbox{\tt FUNCTION}, \hbox{\tt INTEGERS}, |
| 165 |
\hbox{\tt MACRO}, and \hbox{\tt STRINGS}) |
| 166 |
declare and define variables and functions; |
| 167 |
one (\hbox{\tt READ}) reads in the database information; |
| 168 |
and four (\hbox{\tt EXECUTE}, \hbox{\tt ITERATE}, \hbox{\tt REVERSE}, |
| 169 |
and \hbox{\tt SORT}) manipulate the entries and produce output. |
| 170 |
Although the command names appear here in upper case, |
| 171 |
\BibTeX\ ignores case differences. |
| 172 |
|
| 173 |
Some restrictions: |
| 174 |
There must be exactly one \hbox{\tt ENTRY} and one \hbox{\tt READ} command; |
| 175 |
the \hbox{\tt ENTRY} command, all \hbox{\tt MACRO} commands, |
| 176 |
and certain \hbox{\tt FUNCTION} commands |
| 177 |
(see next subsection's description of \hbox{\tt call.type\$}) |
| 178 |
must precede the \hbox{\tt READ} command; |
| 179 |
and the \hbox{\tt READ} command must precede the four that |
| 180 |
manipulate the entries and produce output. |
| 181 |
|
| 182 |
Also it's best (but not essential) to leave at least one blank line |
| 183 |
between commands and to leave no blank lines within a command; |
| 184 |
this helps \BibTeX\ recover from any syntax errors you make. |
| 185 |
|
| 186 |
You must enclose each argument of every command in braces. |
| 187 |
Look at the standard-style documentation |
| 188 |
for syntactic issues not described in this section. |
| 189 |
Here are the ten commands: |
| 190 |
\begin{description} |
| 191 |
|
| 192 |
\item[\hbox{\tt ENTRY}\hfill] |
| 193 |
Declares the fields and entry variables. |
| 194 |
It has three arguments, each a (possibly empty) list of variable names. |
| 195 |
The three lists are of: |
| 196 |
fields, integer entry variables, and string entry variables. |
| 197 |
There is an additional field that \BibTeX\ automatically |
| 198 |
declares, \hbox{\tt crossref}, used for cross referencing. |
| 199 |
And there is an additional string entry variable automatically declared, |
| 200 |
\hbox{\tt sort.key\$}, used by the \hbox{\tt SORT} command. |
| 201 |
Each of these variables has a value for each entry on the list. |
| 202 |
|
| 203 |
\item[\hbox{\tt EXECUTE}\hfill] |
| 204 |
Executes a single function. |
| 205 |
It has one argument, the function name. |
| 206 |
|
| 207 |
\item[\hbox{\tt FUNCTION}\hfill] |
| 208 |
Defines a new function. |
| 209 |
It has two arguments; the first is the function's name and the |
| 210 |
second is its definition. |
| 211 |
You must define a function before using it; |
| 212 |
recursive functions are thus illegal. |
| 213 |
|
| 214 |
\item[\hbox{\tt INTEGERS}\hfill] |
| 215 |
Declares global integer variables. |
| 216 |
It has one argument, a list of variable names. |
| 217 |
There are two such automatically-declared variables, |
| 218 |
\hbox{\tt entry.max\$} and \hbox{\tt global.max\$}, |
| 219 |
used for limiting the lengths of string variables. |
| 220 |
You may have any number of these commands, but a variable's declaration |
| 221 |
must precede its use. |
| 222 |
|
| 223 |
\item[\hbox{\tt ITERATE}\hfill] |
| 224 |
Executes a single function, once |
| 225 |
for each entry in the list, in the list's current order |
| 226 |
(initially the list is in citation order, but the \hbox{\tt SORT} |
| 227 |
command may change this). |
| 228 |
It has one argument, the function name. |
| 229 |
|
| 230 |
\item[\hbox{\tt MACRO}\hfill] |
| 231 |
Defines a string macro. |
| 232 |
It has two arguments; the first is the macro's name, which is treated like |
| 233 |
any other variable or function name, |
| 234 |
and the second is its definition, which must be double-quote-delimited. |
| 235 |
You must have one for each three-letter month abbreviation; |
| 236 |
in addition, you should have one for common journal names. |
| 237 |
The user's database may override any definition you define using this command. |
| 238 |
If you want to define a string the user can't touch, |
| 239 |
use the \hbox{\tt FUNCTION} command, which has a compatible syntax. |
| 240 |
|
| 241 |
\item[\hbox{\tt READ}\hfill] |
| 242 |
Dredges up from the database file |
| 243 |
the field values for each entry in the list. |
| 244 |
It has no arguments. |
| 245 |
If a database entry doesn't have a value for a field |
| 246 |
(and probably no database entry will have a value for every field), |
| 247 |
that field variable is marked as missing for the entry. |
| 248 |
|
| 249 |
\item[\hbox{\tt REVERSE}\hfill] |
| 250 |
Exactly the same as the |
| 251 |
\hbox{\tt ITERATE} command except that it executes the function |
| 252 |
on the entry list in reverse order. |
| 253 |
|
| 254 |
\item[\hbox{\tt SORT}\hfill] |
| 255 |
Sorts the entry list using |
| 256 |
the values of the string entry variable \hbox{\tt sort.key\$}. |
| 257 |
It has no arguments. |
| 258 |
|
| 259 |
\item[\hbox{\tt STRINGS}\hfill] |
| 260 |
Declares global string variables. |
| 261 |
It has one argument, a list of variable names. |
| 262 |
You may have any number of these commands, but a variable's declaration |
| 263 |
must precede its use. |
| 264 |
\end{description} |
| 265 |
|
| 266 |
|
| 267 |
\subsection{The built-in functions} |
| 268 |
\label{built-in-fns} |
| 269 |
|
| 270 |
Before we get to the built-in functions, |
| 271 |
a few words about some other built-in objects. |
| 272 |
There is one built-in string entry variable, \hbox{\tt sort.key\$}, |
| 273 |
which the style program must set if the style is to do sorting. |
| 274 |
There is one built-in field, \hbox{\tt crossref}, |
| 275 |
used for the cross referencing feature |
| 276 |
described in Section~4. |
| 277 |
And there are two built-in integer global variables, |
| 278 |
\hbox{\tt entry.max\$} and \hbox{\tt global.max\$}, |
| 279 |
which are set by default to some internal \BibTeX\ constants; |
| 280 |
you should truncate strings to these lengths before |
| 281 |
you assign to string variables, |
| 282 |
so as to not generate any \BibTeX\ warning messages. |
| 283 |
|
| 284 |
There are currently 37 built-in functions. |
| 285 |
Every built-in function with a letter in its name ends with a `{\tt \$}'$\!$. |
| 286 |
In what follows, ``first''$\!$, ``second''$\!$, |
| 287 |
and so on refer to the order popped. |
| 288 |
A ``literal'' is an element on the stack, and it will be either |
| 289 |
an integer value, a string value, a variable or function name, |
| 290 |
or a special value denoting a missing field. |
| 291 |
If any popped literal has an incorrect type, \BibTeX\ complains and pushes |
| 292 |
the integer 0 or the null string, depending on whether the function |
| 293 |
was supposed to push an integer or string. |
| 294 |
\begin{description} |
| 295 |
|
| 296 |
\item[\hbox{\tt >}\hfill] |
| 297 |
Pops the top two (integer) literals, |
| 298 |
compares them, and pushes the integer 1 if the second is greater than |
| 299 |
the first, 0 otherwise. |
| 300 |
|
| 301 |
\item[\hbox{\tt <}\hfill] |
| 302 |
Analogous. |
| 303 |
|
| 304 |
\item[\hbox{\tt =}\hfill] |
| 305 |
Pops the top two (both integer or both string) literals, |
| 306 |
compares them, |
| 307 |
and pushes the integer 1 if they're equal, 0 otherwise. |
| 308 |
|
| 309 |
\item[\hbox{\tt +}\hfill] |
| 310 |
Pops the top two (integer) literals and pushes their sum. |
| 311 |
|
| 312 |
\item[\hbox{\tt -}\hfill] |
| 313 |
Pops the top two (integer) literals and pushes their difference |
| 314 |
(the first subtracted from the second). |
| 315 |
|
| 316 |
\item[\hbox{\tt *}\hfill] |
| 317 |
Pops the top two (string) literals, |
| 318 |
concatenates them (in reverse order, that is, the order in which |
| 319 |
pushed), and pushes the resulting string. |
| 320 |
|
| 321 |
\item[\hbox{\tt :=}\hfill] |
| 322 |
Pops the top two literals and assigns |
| 323 |
to the first (which must be a global or entry variable) |
| 324 |
the value of the second. |
| 325 |
|
| 326 |
\item[\hbox{\tt add.period\$}\hfill] |
| 327 |
Pops the top (string) literal, |
| 328 |
adds a `{\tt .}' to it if the last non`{\tt \}}' character |
| 329 |
isn't a `{\tt .}'$\!$, `{\tt ?}', or `{\tt !}'$\!$, |
| 330 |
and pushes this resulting string. |
| 331 |
|
| 332 |
\item[\hbox{\tt call.type\$}\hfill] |
| 333 |
Executes the function whose name is the entry type of an entry. |
| 334 |
For example if an entry is of type {\tt book}, this function executes |
| 335 |
the {\tt book} function. |
| 336 |
When given as an argument to the \hbox{\tt ITERATE} command, |
| 337 |
\hbox{\tt call.type\$} actually produces the output for the entries. |
| 338 |
For an entry with an unknown type, |
| 339 |
it executes the function \hbox{\tt default.type}. |
| 340 |
Thus you should define (before the \hbox{\tt READ} command) one function |
| 341 |
for each standard entry type as well as a \hbox{\tt default.type} function. |
| 342 |
|
| 343 |
\item[\hbox{\tt change.case\$}\hfill] |
| 344 |
Pops the top two (string) literals; |
| 345 |
it changes the case of the second according to the |
| 346 |
specifications of the first, as follows. (Note: The word `letters' in |
| 347 |
the next sentence refers only to those at brace-level~0, the top-most |
| 348 |
brace level; no other characters are changed, except perhaps for |
| 349 |
``special characters''$\!$, described in Section~4.) |
| 350 |
If the first literal is the |
| 351 |
string~`{\tt t}'$\!$, it converts to lower case all letters except the very |
| 352 |
first character in the string, which it leaves alone, and except the |
| 353 |
first character following any colon and then nonnull white space, |
| 354 |
which it also leaves alone; if it's the string~`{\tt l}'$\!$, it converts all |
| 355 |
letters to lower case; and if it's the string~`{\tt u}'$\!$, it converts all |
| 356 |
letters to upper case. |
| 357 |
It then pushes this resulting string. If either |
| 358 |
type is incorrect, it complains and pushes the null string; however, |
| 359 |
if both types are correct but the specification string (i.e., the |
| 360 |
first string) isn't one of the legal ones, it merely pushes the second |
| 361 |
back onto the stack, after complaining. (Another note: It ignores |
| 362 |
case differences in the specification string; for example, the strings |
| 363 |
{\tt t} and {\tt T} are equivalent for the purposes of this built-in |
| 364 |
function.) |
| 365 |
|
| 366 |
\item[\hbox{\tt chr.to.int\$}\hfill] |
| 367 |
Pops the top (string) literal, |
| 368 |
makes sure it's a single character, converts it to the |
| 369 |
corresponding ASCII integer, and pushes this integer. |
| 370 |
|
| 371 |
\item[\hbox{\tt cite\$}\hfill] |
| 372 |
Pushes the string that was the |
| 373 |
\hbox{\verb|\cite|}-command argument for this entry. |
| 374 |
|
| 375 |
\item[\hbox{\tt duplicate\$}\hfill] |
| 376 |
Pops the top literal from the stack and pushes two copies of it. |
| 377 |
|
| 378 |
\item[\hbox{\tt empty\$}\hfill] |
| 379 |
Pops the top literal and pushes |
| 380 |
the integer 1 if it's a missing field or a string having no |
| 381 |
non-white-space characters, 0 otherwise. |
| 382 |
|
| 383 |
\item[\hbox{\tt format.name\$}\hfill] |
| 384 |
Pops the top three literals |
| 385 |
(they are a string, an integer, and a string literal). |
| 386 |
The last string literal represents a name list (each name |
| 387 |
corresponding to a person), the integer literal specifies which name |
| 388 |
to pick from this list, and the first string literal specifies how to |
| 389 |
format this name, as explained in the next subsection. |
| 390 |
Finally, this function pushes the formatted name. |
| 391 |
|
| 392 |
\item[\hbox{\tt if\$}\hfill] |
| 393 |
Pops the top three literals (they |
| 394 |
are two function literals and an integer literal, in that order); |
| 395 |
if the integer is greater than 0, it executes the second literal, |
| 396 |
else it executes the first. |
| 397 |
|
| 398 |
\item[\hbox{\tt int.to.chr\$}\hfill] |
| 399 |
Pops the top (integer) literal, |
| 400 |
interpreted as the ASCII integer value of a single character, |
| 401 |
converts it to the corresponding single-character string, and pushes |
| 402 |
this string. |
| 403 |
|
| 404 |
\item[\hbox{\tt int.to.str\$}\hfill] |
| 405 |
Pops the top (integer) literal, |
| 406 |
converts it to its (unique) string equivalent, and pushes this string. |
| 407 |
|
| 408 |
\item[\hbox{\tt missing\$}\hfill] |
| 409 |
Pops the top literal and |
| 410 |
pushes the integer 1 if it's a missing field, 0~otherwise. |
| 411 |
|
| 412 |
\item[\hbox{\tt newline\$}\hfill] |
| 413 |
Writes onto the {\tt bbl} file |
| 414 |
what's accumulated in the output buffer. |
| 415 |
It writes a blank line if and only if the output buffer is empty. |
| 416 |
Since \hbox{\tt write\$} does reasonable line breaking, you should use |
| 417 |
this function only when you want a blank line or an explicit line break. |
| 418 |
|
| 419 |
\item[\hbox{\tt num.names\$}\hfill] |
| 420 |
Pops the top (string) literal |
| 421 |
and pushes the number of names the string represents---one plus |
| 422 |
the number of occurrences of the substring ``and'' (ignoring case differences) |
| 423 |
surrounded by nonnull white-space at the top brace level. |
| 424 |
|
| 425 |
\item[\hbox{\tt pop\$}\hfill] |
| 426 |
Pops the top of the stack but |
| 427 |
doesn't print it; this gets rid of an unwanted stack literal. |
| 428 |
|
| 429 |
\item[\hbox{\tt preamble\$}\hfill] |
| 430 |
Pushes onto the stack the concatenation of all the |
| 431 |
\hbox{\tt @PREAMBLE} strings read from the database files. |
| 432 |
|
| 433 |
\item[\hbox{\tt purify\$}\hfill] |
| 434 |
Pops the top (string) literal, |
| 435 |
removes nonalphanumeric characters except for white-space characters and |
| 436 |
hyphens and ties (these all get converted to a space), removes |
| 437 |
certain alphabetic characters contained in the control sequences |
| 438 |
associated with a ``special character''$\!$, and pushes the resulting string. |
| 439 |
|
| 440 |
\item[\hbox{\tt quote\$}\hfill] |
| 441 |
Pushes the string consisting of the double-quote character. |
| 442 |
|
| 443 |
\item[\hbox{\tt skip\$}\hfill] |
| 444 |
Is a no-op. |
| 445 |
|
| 446 |
\item[\hbox{\tt stack\$}\hfill] |
| 447 |
Pops and prints the whole stack; |
| 448 |
it's meant to be used for style designers while debugging. |
| 449 |
|
| 450 |
\item[\hbox{\tt substring\$}\hfill] |
| 451 |
Pops the top three literals |
| 452 |
(they are the two integers literals {\it len\/} and {\it start}, and a |
| 453 |
string literal, in that order). |
| 454 |
It pushes the substring of the (at most) {\it len\/} consecutive characters |
| 455 |
starting at the {\it start\/}th character (assuming 1-based indexing) |
| 456 |
if {\it start\/} is positive, and ending at the $-${\it start\/}th character |
| 457 |
from the end if {\it start\/} is negative |
| 458 |
(where the first character from the end is the last character). |
| 459 |
|
| 460 |
\item[\hbox{\tt swap\$}\hfill] |
| 461 |
Swaps the top two literals on the stack. |
| 462 |
|
| 463 |
\item[\hbox{\tt text.length\$}\hfill] |
| 464 |
Pops the top (string) literal, |
| 465 |
and pushes the number of text characters it contains, where an |
| 466 |
accented character (more precisely, a ``special character''$\!$, |
| 467 |
defined in Section~4) |
| 468 |
counts as a single text character, even if it's missing |
| 469 |
its matching right brace, and where braces don't count as |
| 470 |
text characters. |
| 471 |
|
| 472 |
\item[\hbox{\tt text.prefix\$}\hfill] |
| 473 |
Pops the top two literals |
| 474 |
(the integer literal {\it len\/} and a string literal, in that order). |
| 475 |
It pushes the substring of the (at most) {\it len\/} consecutive text |
| 476 |
characters starting from the beginning of the string. This function |
| 477 |
is similar to \hbox{\tt substring\$}, but this one considers |
| 478 |
a ``special character''$\!$, even if |
| 479 |
it's missing its matching right brace, to be a single text character |
| 480 |
(rather than however many ASCII characters it actually comprises), |
| 481 |
and this function doesn't consider braces to be text characters; |
| 482 |
furthermore, this function appends any needed matching right braces. |
| 483 |
|
| 484 |
\item[\hbox{\tt top\$}\hfill] |
| 485 |
Pops and prints the top of the stack on the terminal and log file. |
| 486 |
It's useful for debugging. |
| 487 |
|
| 488 |
\item[\hbox{\tt type\$}\hfill] |
| 489 |
Pushes the current entry's type (book, article, etc.), |
| 490 |
but pushes the null string |
| 491 |
if the type is either unknown or undefined. |
| 492 |
|
| 493 |
\item[\hbox{\tt warning\$}\hfill] |
| 494 |
Pops the top (string) literal |
| 495 |
and prints it following a warning message. |
| 496 |
This also increments a count of the number of warning messages issued. |
| 497 |
|
| 498 |
\item[\hbox{\tt while\$}\hfill] |
| 499 |
Pops the top two (function) literals, |
| 500 |
and keeps executing the second as long as the (integer) |
| 501 |
literal left on the stack by executing the first is greater than 0. |
| 502 |
|
| 503 |
\item[\hbox{\tt width\$}\hfill] |
| 504 |
Pops the top (string) literal |
| 505 |
and pushes the integer that represents its width in some relative units |
| 506 |
(currently, hundredths of a point, as specified by the June 1987 version |
| 507 |
of the $cmr10$ font; the only white-space character with nonzero width |
| 508 |
is the space). |
| 509 |
This function takes the literal literally; |
| 510 |
that is, it assumes each character in the string is to be printed as |
| 511 |
is, regardless of whether the character has a special meaning to \TeX, |
| 512 |
except that ``special characters'' (even without their right braces) are |
| 513 |
handled specially. |
| 514 |
This is meant to be used for comparing widths of label strings. |
| 515 |
|
| 516 |
\item[\hbox{\tt write\$}\hfill] |
| 517 |
Pops the top (string) literal |
| 518 |
and writes it on the output buffer (which will result in |
| 519 |
stuff being written onto the {\tt bbl} file when the buffer fills up). |
| 520 |
|
| 521 |
\end{description} |
| 522 |
|
| 523 |
Note that the built-in functions \hbox{\tt while\$} and \hbox{\tt if\$} |
| 524 |
require two function literals on the stack. |
| 525 |
You get them there either by immediately preceding the name of a function |
| 526 |
by a single quote, or, if you don't feel like defining a new function with |
| 527 |
the \hbox{\tt FUNCTION} command, |
| 528 |
by simply giving its definition (that is, giving what would be the second |
| 529 |
argument to the \hbox{\tt FUNCTION} command, including the surrounding braces). |
| 530 |
For example the following function fragment appends the character `{\tt a}' |
| 531 |
if the string variable named \hbox{\tt label} is nonnull: |
| 532 |
\begin{verbatim} |
| 533 |
. . . |
| 534 |
label "" = |
| 535 |
'skip$ |
| 536 |
{ label "a" * 'label := } |
| 537 |
if$ |
| 538 |
. . . |
| 539 |
\end{verbatim} |
| 540 |
A function whose name you quote needn't be built in |
| 541 |
like \hbox{\tt skip\$} above---it may, for example, |
| 542 |
be a field name or a function you've defined earlier. |
| 543 |
|
| 544 |
|
| 545 |
\subsection{Name formatting} |
| 546 |
|
| 547 |
What's in a name? |
| 548 |
Section~4 pretty much describes this. |
| 549 |
Each name consists of four parts: First, von, Last, and Jr; |
| 550 |
each consists of a list of name-tokens, |
| 551 |
and any list but Last's may be empty for a nonnull name. |
| 552 |
This subsection describes the format string you must supply to |
| 553 |
the built-in function \hbox{\tt format.name\$}. |
| 554 |
|
| 555 |
Let's look at an example of a very long name. |
| 556 |
Suppose a database entry~\cite{prime-number-theorem} has the field |
| 557 |
\begin{verbatim} |
| 558 |
author = "Charles Louis Xavier Joseph de la Vall{\'e}e Poussin" |
| 559 |
\end{verbatim} |
| 560 |
and suppose you want this formatted ``last name comma initials''$\!$. |
| 561 |
If you use the format string |
| 562 |
\begin{verbatim} |
| 563 |
"{vv~}{ll}{, jj}{, f}?" |
| 564 |
\end{verbatim} |
| 565 |
\BibTeX\ will produce |
| 566 |
\begin{verbatim} |
| 567 |
de~la Vall{\'e}e~Poussin, C.~L. X.~J? |
| 568 |
\end{verbatim} |
| 569 |
as the formatted string. |
| 570 |
|
| 571 |
Let's look at this example in detail. |
| 572 |
There are four brace-level~1 {\em pieces\/} to this format string, |
| 573 |
one for each part of a name. |
| 574 |
If the corresponding part of a name isn't present (the Jr part for this name), |
| 575 |
everything in that piece is ignored. |
| 576 |
Anything at brace-level~0 is output verbatim |
| 577 |
(the presumed typo `{\tt ?}' for this name is at brace-level~0), |
| 578 |
but you probably won't use this feature much. |
| 579 |
|
| 580 |
Within each piece a double letter tells \BibTeX\ to use whole tokens, and |
| 581 |
a single letter, to abbreviate them (these letters must be at brace-level~1); |
| 582 |
everything else within the piece is used verbatim |
| 583 |
(well, almost everything---read on). |
| 584 |
The tie at the end of the von part (in \hbox{\verb|{vv~}|}) |
| 585 |
is a discretionary tie---\BibTeX\ will output a tie at that point |
| 586 |
if it thinks there's a need for one; |
| 587 |
otherwise it will output a space. |
| 588 |
If you really, really, want a tie there, |
| 589 |
regardless of what \BibTeX\ thinks, use two of them |
| 590 |
(only one will be output); that is, use \hbox{\verb|{vv~~}|}. |
| 591 |
A tie is discretionary only if it's the last character of the piece; |
| 592 |
anywhere else it's treated as an ordinary character. |
| 593 |
|
| 594 |
\BibTeX\ puts default strings {\em between\/} tokens of a name part: |
| 595 |
For whole tokens it uses either a space or a tie, |
| 596 |
depending on which one it thinks is best, |
| 597 |
and for abbreviated tokens it uses a period followed by |
| 598 |
either a space or a tie. |
| 599 |
However it doesn't use this default string after the last token in a list; |
| 600 |
hence there's no period following the `J' for our example. |
| 601 |
You should have used |
| 602 |
\begin{verbatim} |
| 603 |
"{vv~}{ll}{, jj}{, f.}" |
| 604 |
\end{verbatim} |
| 605 |
to get \BibTeX\ to produce the same formatted string but with the question |
| 606 |
mark replaced by a period. |
| 607 |
Note that the period should go inside the First-name piece, |
| 608 |
rather than where the question mark was, in case a name has no First part. |
| 609 |
|
| 610 |
If you want to override \BibTeX's default between-token strings, you |
| 611 |
must explicitly specify a string. |
| 612 |
For example suppose you want a label to contain the first letter from each |
| 613 |
token in the von and Last parts, with no spaces; |
| 614 |
you should use the format string |
| 615 |
\begin{verbatim} |
| 616 |
"{v{}}{l{}}" |
| 617 |
\end{verbatim} |
| 618 |
so that \BibTeX\ will produce `{\tt dlVP}' as the formatted string. |
| 619 |
You must give a string for each piece whose default you want overridden |
| 620 |
(the example here uses the null string for both pieces), and this string |
| 621 |
must immediately follow either the single or double letter for the piece. |
| 622 |
You may not have any other letters at brace-level~1 in the format string. |
| 623 |
|
| 624 |
\bibliography{btxdoc} |
| 625 |
\bibliographystyle{plain} |
| 626 |
\end{document} |