Bibliographies are part of almost every technical document. To handle them easily, you need two things: a program to do the tedious formatting, and a way to cite references by labels, rather than by numbers. The BibTeX program, written by Oren Patashnik, takes care of the first item; the citation commands in LaTeX, written to be used with BibTeX, take care of the second. Therefore, Eplain adopts the use of BibTeX, and virtually the same interface as LaTeX.
The general idea is that you put citation commands in the text of your document, and commands saying where the bibliography data is. When you run TeX, these commands produce output on the file with the same root name as your document (by default) and the extension `.aux'. BibTeX reads this file. You should put the bibliography data in a file or files with the extension `.bib'. BibTeX writes out a file with the same root name as your document and extension `.bbl'. Eplain reads this file the next time you run your document through TeX. (It takes multiple passes to get everything straight, because usually after seeing your bibliography typeset, you want to make changes in the `.bib' file, which means you have to run BibTeX again, which means you have to run TeX again...) An annotated example of the whole process is given below.
If your document has more than one bibliography--for example, if it
is a collection of papers--you can tell Eplain to use a different root
name for the `.bbl' file by defining the control sequence
\bblfilebasename.
The default definition is simply \jobname.
See the document BibTeXing (whose text is in the file `btxdoc.tex', which should be in the Eplain distribution you got) for information on how to write your .bib files. Both the BibTeX and the Eplain distributions contain several examples, also.
The \cite
command produces a citation in the text of your document. The exact
printed form the citation will take is under your control;
see section Formatting citations. \cite takes one
required argument, a comma-separated list of cross-reference labels
(see section Cross-references, for exactly what characters are allowed in
such labels). Warning: spaces in this list are taken as part of the
following label name, which is probably not what you expect.
The \cite command also produces a command
in the .aux file that tells BibTeX to retrieve the given reference(s)
from the .bib file. \cite also takes one optional argument,
which you specify within square brackets, as in LaTeX. This text is
simply typeset after the citations. (See the example below.)
Another command, \nocite,
puts the given reference(s) into the bibliography, but produces nothing
in the text.
The \bibliography
command is next. It serves two purposes: producing the typeset
bibliography, and telling BibTeX the root names of the .bib
files. Therefore, the argument to \bibliography is a comma
separated list of the .bib files (without the `.bib'). Again,
spaces in this list are significant.
You tell BibTeX the particular style in which you want your
bibliography typeset with one more command:
\bibliographystyle.
The argument to this is a single filename style, which tells
BibTeX to look for a file style.bst.
See the document Designing BibTeX styles (whose text is in the
`btxhak.tex') for information on how to write your own styles.
Eplain automatically reads the citations from the .aux file when your job starts.
If you don't want to see the messages about undefined citations, you
can say \xrefwarningfalse before making any citations.
Eplain automatically does this if the .aux file does not exist.
You can restore the default by saying \xrefwarningtrue.
Here is a TeX input file that illustrates the various commands.
\input eplain % Reads the .aux file.
Two citations to Knuthian works:
\cite[note]{surreal,concrete-math}.
\beginsection{References.}\par % Title for the bibliography.
\bibliography{knuth} % Use knuth.bib for the labels.
\bibliographystyle{plain} % Number the references.
\end % End of the document.
If we suppose that this file was named `citex.tex' and that the
bibliography data is in `knuth.bib' (as the \bibliography
command says), the following commands do what's required. (`$ '
represents the shell prompt.)
$ tex citex (produces undefined citation messages) $ bibtex citex (read knuth.bib and citex.aux, write citex.bbl) $ tex citex (read citex.bbl, still have undefined citations) $ tex citex (one more time, to resolve the references)
The output looks something like (because we used the plain bibliography style):
Two citations to Knuthian works: [2,1 note].
References
[1] Ronald L. Graham, Donald E. Knuth, and Oren Patashnik. Concrete Mathematics. Addison-Wesley, Reading, Massachusetts, 1989.
[2] Donald E. Knuth. Surreal Numbers. Addison-Wesley, Reading, Massachusetts, 1974.
See the BibTeX documentation for information on how to write the
bibliography databases, and the bibliography styles that are available.
(If you want your references printed with names, as in [Knu74], instead
of numbered, the bibliography style is alpha.)