The footbib package^{∗}

Eric Domenjoud Eric.Domenjoud@loria.fr

1997/03/28

Contents

1 General overview 1

2 The user interface 2 2.1 Package options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.2 Commands to generate the foot bibliography . . . . . . . . . . . . 4 2.3 customisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 Known and potential problems 6

1 General overview

This package makes bibliographic references appear as footnotes. It defines a command \footcite which is similar to the \cite command of L^{A}TEX but the references cited in this way are inserted at the bottom of the pages. This foot bibliography does not conflict with the standard one and both may exist simultaneously in a document. The command \cite may still be used to produce the standard bibliography.

The foot bibliography uses its own style and bibliographic database which may be specified independently of the standard one. Any standard bibliography style may be used. If the style does not provide explicit labels (e.g. plain), the references are numbered. The default is to number the references in the order in which they appear in the thebibliography environment. This may be overridden through options which allow the user to define a numbering unit. Then the references will be numbered in the order in which they are cited in the unit and the numbering restarts from 1 in each unit. The numbering unit may be a page, a double page, a chapter, a part or the whole document. Chapter and part may be used only if they are defined by the document class.

The user may also define a citation unit which may be a page, a double page, a chapter, a part or the whole document. The text of a reference will be inserted only once in each citation unit, on the page where the first citation occurs in the unit.

∗This file has version number 2.0, last revised 1997/03/28.

The mechanism used to put a reference only once in each citation unit may require several runs of L^{A}TEX before the references find their exact place. If necessary, L^{A}TEX will issue, near the end of the document, a warning saying

 Package footbib Warning: Bibliography not yet stable. Rerun LaTeX.

Using footbib in a document ⟨doc⟩.tex produces a file ⟨doc⟩.fb.aux. One must pass the argument ⟨doc⟩.fb to BibTEX to produce the bibliography which will be put in the file ⟨doc⟩.fb.bbl.

Note: This name might cause some problem on systems which do not allow a double extension in a file name or put a limit on the length of file names. A user command is provided to change it (see section 2.3).

At the beginning of the document, footbib inputs the bibliography from the file ⟨doc⟩.fb.bbl (or the name given by the user). If one wants to include the thebibliography environment in the main document, this may be done with a filecontents environment before the \documentclass command. See the L^{A}TEX 2ε documentation for more details about this environment.

2 The user interface

2.1 Package options

2.1.1 oneside/twoside

oneside The oneside and twoside options affect the behaviour of footbib when either twoside unit (citation or numbering) is the page. In oneside mode, the actual unit is a

single page while in twoside mode, the unit is a double page. These options may be used to override a global oneside or twoside option.

2.1.2 citeonce[*]

citeonce The citeonce option overrides the default citation unit. footbib puts the text citeonce* of a reference only once in each citation unit which may be a (double) page, a

chapter, a part or the whole document. The default citation unit is the page in oneside mode and the double page in twoside mode. The new citation unit (chapter, part or document) is given as an optional argument between paren-

theses (citeonce(chapter), citeonce(part) or citeonce(document)). If no

argument is supplied, document is assumed. The argument chapter (resp. part) may be used only if the document class defines \chapter (resp. \part). The argument page may also be used but has a somehow special meaning. It defines a citation unit which is not overridden by another citeonce option but instead has a cumulative effect. For instance if one says

    \usepackage[twoside,citeonce(page),citeonce(chapter)]{footbib}

then each double page and also each \chapter command starts a new citation unit. This may be useful if one wants a chapter to start a new unit even if it starts on a right page. It is only meaningful in twoside mode in conjunction with another citeonce option. In all other cases, it has no effect.

The citeonce option has a star form citeonce* with the same optional argument. When the star form is used, for each subsequent citation of a reference in the same citation unit but on another (double) page, the text of the reference is not omitted but replaced with a cross reference to the first citation in the same citation unit. The page argument is not available since it would have no effect.

2.1.3 firstcite

firstcite The firstcite option affects the way the references are labelled. When the bibliography style does not provide explicit labels, the references are numbered. The default is to assign to each reference a static label which is its order in the thebibliography environment. The label is then the same for all citations of a given reference. The firstcite option causes the references to be numbered dynamically according to the order of their first citations. firstcite takes an optional argument between parentheses firstcite(⟨unit⟩) which defines the numbering unit. The numbering restarts then from 1 in each numbering unit. The argument ⟨unit⟩ may take the value page, chapter, part or document. If page is used, then the numbering unit is a page in oneside mode and a double page in twoside mode. If no argument is supplied, document is assumed.

The effect of several firstcite options is cumulative in the sense that if one says for instance

    \usepackage[twoside,firstcite(page),firstcite(chapter)]{footbib}

then each double page and each \chapter command starts a new numbering unit. This means that a \chapter command starts a new numbering unit even if it is on a right page.

If the bibliography style provides explicit labels, the firstcite option has no effect.

2.1.4 crossrefs[*] and nocrossrefs

crossrefs When an entry in the bibliographic database contains a CROSSREF field, BibTEX

crossrefs*
nocrossrefs

includes the cross-referenced entry in the bibliography and puts a \cite command in the entry where the CROSSREF field occurs. If no standard bibliography is produced, L^{A}TEX will complain about an undefined reference. One may generally inhibit this behaviour of BibTEX by invoking it with the -min-crossrefs=⟨number⟩ option which tells how many times an entry must be cross-referenced before it is included in the bibliography and replaced with a \cite command. Setting ⟨number⟩ to a large value will generally inhibit the cross-referencing mechanism. However, this option has no effect if the cross-referenced entry is explicitely cited in the document.

The crossrefs option of footbib solves this problem by replacing each \cite command in a foot reference with \footcite (see the description of this command below). The star form crossrefs* replaces the \cite command with a \footcite*, which means that the text of the reference is not inserted. It is then the responsibility of the user to insert the text in the right place with a \footnocite command. Of course, standard citation through \cite is not possible anymore in a foot reference when either form of this option is used.

A nocrossrefs option is also provided to inhibit this behaviour in case it is not wanted but crossrefs occurs in the global options.

2.1.5 split and nosplit

split The nosplit option tells footbib not to split the references across pages. The nosplit split option allows references to be split. split is the default and exists only to

allow the user to override a global nosplit option.

2.2 Commands to generate the foot bibliography

\footbibliography  \footbibliography{⟨file⟩,⟨file⟩,. . . }

Defines the list of bibliographic databases for the foot bibliography. This command has the same syntax as the \bibliography command of L^{A}TEX.

\footbibliographystyle  \footbibliographystyle{⟨style⟩}

Defines the style of the foot bibliography. This command has the same syntax as

the \bibliographystyle command of L^{A}TEX.
\footcite  \footcite{⟨key⟩,⟨key⟩,. . . }

Puts the list of labels in the text and the text of the references at the bottom of the page. The text of each reference is inserted at most once in a citation unit, even if it is cited several times.

\footcite*  \footcite*{⟨key⟩,⟨key⟩,. . . }

Puts the list of labels in the text but does not put the reference at the bottom of the page.

\footnocite  \footnocite{⟨key⟩,⟨key⟩,. . . }

Puts the reference at the bottom of the page but puts nothing in the text.

Note: The main purpose of the commands \footcite* and \footnocite is to solve the problem of a \footcite occuring inside an environment where the reference will be lost (for instance in a minipage or tabular environment, in a \mbox, etc.). In this case, if the reference is not cited otherwise on the same page, it won’t show up at the bottom of the page. It suffices to add a \footnocite command just before or after this environment. The command \footcite{⟨key⟩} is more or less (but not completely) equivalent

     to \footcite*{⟨key⟩}\footnocite{⟨key⟩}.

2.3 customisation

\footbibliographyname The basename of the .aux and .bbl files used for the foot bibliography may be re-

defined by \footbibliographyname{⟨name⟩}. The default value is \jobname.fb^{1}

which causes footbib to read the bibliography from \jobname.fb.bbl and to use \jobname.fb.aux as an auxiliary file. This command may be used only in the preamble. The name supplied to \footbibliographyname must be different from the name of the main document.

\footcitelabel The list of citations in the text may not be typeseted in one step as done by the

\putfootcitelabel
\footcitelistformat

\cite command of L^{A}TEX. The reason is that the command which creates the text of the foot reference must be inserted after each citation. The way (L^{A})TEX handles insertions makes them vanish if they occur in a box. Hence if the command which formats the list of citations puts them in a box, the text is lost and the references do not show up at the bottom of the page. All references could be inserted at once, either before or after the list of citations but if this list gets split across pages, the text of some references could show up on the wrong page. Hence the list is created one piece at a time and the text of the corresponding reference is inserted after each citation. The list of citation is created as follows:

1\jobname is a primitive TEX command which holds the name of the main document.

1) start of list

2) for each citation: a) if it is not the first one, separator of citations

b) label of the reference, to which \footcitelabel is applied c) insertion of the text of the reference

3) end of list

The separator of citations is made of two parts: ⟨sep_{1}⟩ and ⟨sep_{2}⟩. The command \putfootcitelabel is applied to each component of the list, excepted ⟨sep_{2}⟩ which is put as such. Typically, ⟨sep_{2}⟩ is a separator which may disappear at a line break, like a penalty or some spacing. That’s why \putfootcitelabel is not applied to it so that it won’t be put in a box. The effect is as follows:

\putfootcitelabel{⟨start of list⟩}
\putfootcitelabel{\footcitelabel{⟨label 1⟩}}

⟨insertion of the text of reference 1⟩

\putfootcitelabel{⟨sep_{1}⟩}

⟨sep_{2}⟩

\putfootcitelabel{\footcitelabel{label 2}}

⟨insertion of the text of reference 2⟩

\putfootcitelabel{⟨sep_{1}⟩}

⟨sep_{2}⟩

⋮

\putfootcitelabel{\footcitelabel{label n}}

⟨insertion of the text of reference n⟩

\putfootcitelabel{⟨end of list⟩}

Each component of the list may be redefined as follows:

\renewcommand*\footcitelabel[1]{. . . }
\renewcommand*\putfootcitelabel[1]{. . . }

\footcitelistformat⟨start of list⟩⟨sep_{1}⟩⟨sep_{2}⟩⟨end of list⟩

Here are some examples of the variations allowed by this mechanism.

example 1: list of citations a la L^{A}TEX : [label 1, label 2, …]

\renewcommand*\footcitelabel[1]{#1}
\renewcommand*\putfootcitelabel[1]{#1}
\footcitelistformat[,{\penalty1000\␣}]

example 2: ditto but the list may not be cut

⋮

\footcitelistformat[,{\penalty10000\␣}]

example 3: the list is raised and the labels are separated only by commas, without any space: ^{[label 1,label 2,…]}

     \renewcommand*\footcitelabel[1]{#1}
     \renewcommand*\putfootcitelabel[1]{\textsuperscript{\normalfont#1}}
     \footcitelistformat[,{\penalty1000\relax}]

example 4: ditto, but no brackets around the list of labels: ^{label 1,label 2,…} ⋮

     \footcitelistformat{},{\penalty1000\relax}{}

example 5: [label 1], [label 2], …

     \renewcommand*\footcitelabel[1]{[#1]}
     \renewcommand*\putfootcitelabel[1]{#1}
     \footcitelistformat{},{\penalty1000\␣}{}

The default definitions are the ones of example 3 above.

\footbibskip The foot bibliography is separated from the rest of the page by a vertical skip \footbibrule of length \footbibskip in which a horizontal line is drawn by the command

\footbibrule. The length of the skip and the horizontal line may be redefined in the preamble by

     \setlength\footbibskip{. . . }
     \renewcommand\footbibrule{. . . }

CAUTION: \footbibrule must take zero vertical space.

\footreflabel The label of the foot reference is formated by the macro \footreflabel which takes the label as argument. It may be redefined by \renewcommand*\footreflabel[1]{… }.

\footrefstyle The label and the text of the reference at the bottom of the page are typeseted in the style defined by the command \footrefstyle which may be redefined in the preamble by \renewcommad\footrefstyle{… }. The default definition is

\normalfont\footnotesize.

\footxref The options citeonce*(⟨unit⟩) tells footbib to replace the text of each reference but the first in each citation unit with a cross-reference to the last place where the full text of the reference appeared. The text of the cross-reference is generated by the command \footxref which takes two arguments: (1) the label and (2) the page of the last full citation. \footxref may be redefined in the preamble by

\renewcommand*\footxref[2]{. . . }.

3 Known and potential problems

• The foot bibliography is not sorted. The references appear at the bottom of the page in the order in which they are cited on the page.

• If a float is inserted at the bottom of the page, the foot bibliography is put above it, like footnotes.

• The result is not very nice in twocolumn mode. The references should be balanced between the two columns of the page (if there are two) or put in the right column like the package ftnright of Frank Mittelbach does for footnotes.

• footbib does not work with most packages which modify the output routine of

L^{A}TEX: multicol, ftnright, floatflt, wrapfig, etc.

• At present, the convergence is not proved. There is no guarantee that the references eventually find their place. However, footbib was used in large documents (several hundreds pages) and such a problem never occured.

• The references must not contain any verbatim environment. But \verb is allowed since it is sometime used to typeset filenames, url’s, etc.

• The braces must be balanced in the references, excepted the ones that might occur inside the argument of a \verb command. This implies that a reference may not contain say \hbox\bgroup… } which is otherwise correct in (L^{A})TEX.

• When references are numbered, the space between the label and the reference itself may be too large because the longest label is determined from the argument of \begin{thebibliography}{⟨longest label⟩} and its length is used for all references. If all references on a page have small numbers and the bibliography contains many references (say more than 100), this length is not reliable. The longest label should be deduced from the maximal number of foot references on a page, but this may not be known at the beginning of the document, at least at the first run. At the second run, the information could be deduces from what was written into the .aux file, provided the \nofiles command was not used (otherwise, the .aux file was not written). When per page numbering is used (option firstcite(page)), the longest label could also be simply initialised to 99 which is not too large and should be enough.

Index

Numbers written in italic refer to the page where the corresponding entry is described, the ones underlined to the code line of the definition, the rest to the code lines where the entry is used.

C

citation unit . . . . . . 1, 2 citeonce (option) …. 2 citeonce* (option) . 2, 6 crossrefs (option) … 3 crossrefs* (option) . . 3

D

dynamic label . . . . . . . 3

E

environments:

 filecontents . . . . 2
 thebibliography . 2
 verbatim . . . . . . . 6

F

filecontents (environ-

ment) . . . . . . . . 2 firstcite (option) … 2 floatflt (package) … 6

                        \footbibliography . . 3
                        \footbibliographyname

. . . . . . . . . . . . . 4

                        \footbibliographystyle

. . . . . . . . . . . . . 4

                        \footbibrule . . . . . . . 6
                        \footbibskip . . . . . . . 6

\footcite . . . . . . . . . 4

                        \footcite* . . . . . . . . 4
                        \footcitelabel . . . . . 4
                        \footcitelistformat . 4
                        \footnocite . . . . . . . . 4
                        \footreflabel . . . . . . 6
                        \footrefstyle . . . . . . 6

\footxref . . . . . . . . . 6 ftnright (package) … 6

L

label dynamic . . . . . . 3 static . . . . . . . . . 2

M multicol (package) … 6

N

                                                 nocrossrefs (option) . 3

nosplit (option) . . . . . 3 numbering unit …. 1, 3

O oneside (option) . . . . . 2 options:

                                                     citeonce* . . . . . 2, 6
                                                     citeonce . . . . . . . 2
                                                     crossrefs* . . . . . . 3
                                                     crossrefs . . . . . . . 3

firstcite . . . . . . . 2
nocrossrefs . . . . . 3

nosplit . . . . . . . . 3 oneside . . . . . . . . 2 split . . . . . . . . . . 3 twoside . . . . . . . . 2

P

packages:

floatflt . . . . . . . 6
ftnright . . . . . . . 6
multicol . . . . . . . 6

wrapfig . . . . . . . . 6

                       \putfootcitelabel . . 4

S split (option) . . . . . . 3 static label . . . . . . . . . 2

T

                       thebibliography (envi-

ronment) . . . . . 2 twoside (option) . . . . . 2

U

unit citation . . . . . 1, 2 numbering … 1, 3

V \verb . . . . . . . . . . . 6, 7 verbatim (environ-

ment) . . . . . . . . 6

W wrapfig (package) … 6