(eplain.info)Citations

---

Next: Displays Prev: Rules Up: User definitions

---

Enter node , (file) or (file)node

4.3 Citations
=============

Bibliographies are part of almost every technical document.  To handle
them conveniently, 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'.

   On the other hand, if your document's bibliography is very simple,
you may prefer to create the '.bbl' file yourself, by hand, instead of
using BibTeX.  An annotated example of this approach is also given
below.

   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
(Note: Formatting citations).  '\cite' takes one required argument, a
comma-separated list of cross-reference labels (Note:
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.)

   Eplain can create hypertext links for citations pointing to the
relevant bibliography entries (Note: Citation hyperlinks).

   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 above '\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 'texi2dvi' program can help you automate this process (Note:
Invoking Eplain).

   For simple documents you might choose to write the '.bbl' file
yourself, instead of running BibTeX.  For this scenario, the following
commands should suffice:

     $ tex citex     (read citex.bbl, produces undefined citation messages)
     $ 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'.)

Formatting citations

Changing the way citations are printed.

Formatting bibliographies

Changing the way bibliographies are printed.

Commands from LaTeX

LaTeX commands defined by 'btxmac'.