Cross references in L^{A}TEX

Richard Kaye School of Mathematics and Statistics The University of Birmingham Birmingham B15 2TT U.K. 12th October 2000

Contents

1 Introduction 2 2 More cross references 2 3 The table of contents 3 4 The label, ref, and pageref commands 3 5 Writing a bibliography 4 6 L^{A}TEX’s warning messages 5 7 The nofiles command 5 8 The include and includeonly commands 5 9 Tips on cross-referencing 6 10 You need to run L^{A}TEX several times 6

List of Tables

1 A test table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

List of Figures

1 A figure by Lamport . . . . . . . . . . . . . . . . . . . . . . . . . 2 Figure 1: A figure by Lamport

[figure: cm; 1; 2; 3; 4; 5; car]

Table 1: A test table

Surname First name Age  Sex  Recommended treatment
Regan  Ronald  99  male  Deport to Nicaragua
Major  John  ? indeterminate Send to Coventry
Thatcher Margaret  134  female  Banish to Los Malvinas

1 Introduction

This document is intended to be used as a model for L^{A}TEX documents that use cross-referencing. It should be studied in conjunction with its source the file, crossref.tex, which was used to produce it. Only the most basic kinds of L^{A}TEX cross-referencing commands are mentioned here. In particular, I will not mention indexing nor creating a glossary or index of notation. Perhaps the most important omission here is BibTEX, for bibliographies. All these tools are discussed and used in other example documents, [3, 2] available on the web.

Note that the parts labelled ‘challenge’ (such as Challenge 10.1 on page 6 below) are intended for experts only. They are not easy.

2 More cross references

To show how sections can be labelled and referred to, note that this is section 2.

This section also contains a more complicated example, a figure created with the L^{A}TEX ‘picture’ environment (Figure 1).

The precise code that created this figure is more advanced, and you can skip it for now. But note that L^{A}TEX gives you very little control of where the figure is actually positioned on the page. (In the jargon, it is a ‘floating object’.)

Challenge 2.1 Explain the commands used in Figure 1 (these occur in Lamport’s book [4], page 197).

We can define tables in similar sort of way, such as Table 1.

3 The table of contents

The command \tableofcontents is used to create a table of contents. It is usually placed just after the \maketitle command but before the first \section, \chapter or \part. The command does two things. Firstly, it instructs L^{A}TEX to create a .toc file (with the same same as the main file), and as L^{A}TEX processes your file, it stores all the data concerning what parts, chapters and sections your document contains and on what pages they appear. Secondly, it reads any .toc file that is already present and uses the data there to create a table of contents. Thus the data for the table of contents is always created in the previous run of L^{A}TEX, not the current one. It follows that you must run L^{A}TEX twice if for any reason you suspect that the data in the .toc file is out of date. (The same applies to the other cross-referencing commands, but for a file called the .aux file instead of the .toc file.)

4 The label, ref, and pageref commands

The \label, \ref, and \pageref commands are by far the most important ones. The command \label sets up a label for the most ‘important’ piece of data according to L^{A}TEX at the given moment. (It may be a section number, or a theorem number, or an equation number.) This data, and its page reference is written to the .aux file. On the second pass, the command \ref will be replaced by the appropriate text or number, and the command \pageref gives the appropriate page number.

Some things to note:

1. The .aux file might be out of date; it’s worth running L^{A}TEX two (or sometimes three) times to check.

2. Normal references only take two passes. Page references may take three.

3. Words like ‘equation’ or ‘theorem’ are not provided by the \ref command. You have to type these yourself.

4. Most letters or punctuation symbols are OK in labels.

As an example of what’s needed when making a cross-reference (see item 3 above), consider the cross-reference to page 3, referring to Challenge 2.1 on page 2.

The ‘tie’ symbol ~, by the way, behaves like a normal space character ‘ ’, except that it is never broken across a line, so if you type

     Table~\ref{sampletable}

you will not have the unfortunate effect of splitting ‘Table’ from the table number. See the example of ‘item 3’ in the last paragraph.

Here is the same paragraph with these tie signs instead of spaces.

As an example of what’s needed when making a cross-reference (see item 3 above), consider the cross-reference on page 3, referring to Challenge 2.1 on page 2.

Challenge 4.1 I spent ages modifying my text so that ‘item 3’ accidently went across a line-break. How could I have used L^{A}TEX’s more advanced commands to achieve this effect effortlessly?

Theorem 4.2 This text is littered with examples of \label and \ref.

Theorem 4.2 is true, and to prove the point even more stongly, here are some more examples.

First, an equation

e^{iπ} = −1  (1)

It seems that every mathematician comments at some point in their life that Equation 1 on page 4 is one of the most beautiful in mathematics; I would hate to be an exception to the rule.

1 = 1  (2)
1 + 2 = 3  (3)
1 + 2 + 3 = 6
1 + 2 + 3 + 4 = 10  (4)

Here’s a silly question that doesn’t deserve an answer: What should the number of the equation between 3 and 4 be?

5 Writing a bibliography

Put very simply, you make a bibliography with the thebibliography environment. For example, the bibliography for this document starts

\begin{thebibliography}{XXX}
\bibitem{jones} A. N. Jones, {\it Made up paper ...
...
\end{thebibliography}

The XXX should be the length of the longest printable key, which is usually a number, and not the same as the ‘L^{A}TEX key’ you use to refer to it in your document. (So for bibliographies with between 10 and 99 entries, any two digit number for XXX is fine.) Each item in the bibliography is introduced with bibitem{latexkey}. L^{A}TEX automatically assigns each item a number, which is the printed key. To make a reference to an item you type \cite{latexkey}. This creates a number in square brackets [4].

Some dos and don’ts on citations.

1. L^{A}TEX has provision for you to provide your own printable keys. I strongly recommend you do not use them. Keys other than numbers look ugly and are no more helpful (sometimes less helpful).

2. Decide whether you want your references to be in citation-order or in alphabetical order. L^{A}TEX won’t do this for you.

3. The point of the numbered system is that you can give references without interrupting, breaking, or changing your text [5]. So write as if the numbers in square brackets are not there. Your English should still be grammatical and understandable if they are removed. Don’t indulge in the horrible habit of writing something like ‘Jones in [1] said that this is true.’ Instead, write ‘Jones [1] said that this is true.’

4. Publishers are very fussy (with good reason) about the format of the bibliography entries, especially punctuation and typeface. Be careful!

If you don’t like this system, BibTEX provides a useful improvement, but at some extra cost of implementing it. See my sequel to this paper [2]. In particular, BibTEX will sort the items into alphabetical order for you [2, 5].

Bibliographic data is written to the .aux file, and so cross-references will not be completed until the second run through L^{A}TEX.

6 L^{A}TEX’s warning messages

L^{A}TEX will warn you if it thinks you need to rerun the program to get crossreferences right. It tends to be over-cautious (in particular it checks all references and labels, even ones you don’t refer to by both page and number) but it’s wise not to ignore these messages.

7 The nofiles command

In you really want to stop L^{A}TEX producing all those extra files, you put the command \nofiles in the preamble. You should do this if the auxillary files have been created, you’re sure they are right and you don’t want to destroy them.

8 The include and includeonly commands

These allow a long document to be split into several small parts. This saves time when running L^{A}TEX, since you don’t have to print out the whole document each time you make a change, and yet L^{A}TEX will get the page numbers and crossreferencing right. This example document is too short to demonstrate this feature, but you will certainly want to use it when you are writing a book, a longish report, or a thesis.

Roughly, you put each chapter in a separate file (e.g., chap1.tex, and you read this file in from the main document with the \include command, e.g., you type \include{chap1}. The document is then L^{A}TEXed normally. But if at a later stage you make a change to chapter 2, and only want that chapter printed off, you put \includeonly{chap2} in the main document, somewhere before the ‘\begin{document}’. Then the auxillary files chap1.aux etc., will be read to determine on what page chapter 2 starts, and to get all cross references right, but only the required chapter will go into the .dvi file.

See Lamport’s book [4] for details.

9 Tips on cross-referencing

I find it helpful to indicate in the label what is being referred to , for example, this section is labelled with \label{sec:tips} to remind me that it is a section. This avoids the possible pitfall of erroneously referring to Theorem 10.1 when it is actually a ‘challenge’.

10 You need to run L^{A}TEX several times

To get the cross-referencing information correct, you need to run L^{A}TEX several times. Usually two or three runs suffice, but things can vary. Some published examples are terrible, and I can think of one where the table of contents is incorrect because the final run of L^{A}TEX was omitted [6]. Don’t make your documents look like this!

Challenge 10.1 Write a L^{A}TEX document so that the data in the .toc or the .aux file always changes every time you run L^{A}TEX. In other words, fool L^{A}TEX so that its cross-referencing system is always wrong. Try and make your document as short as possible.

Although it is possible to fool L^{A}TEX, it is very difficult to do so and almost impossible unless you deliberately try to do so.

References

[1] A. N. Jones, Made up paper for the purposes of giving an example. Journal of imaginary statements and transitory phenomena, pp. 99–98.

[2] Richard Kaye, Other cross-referencing tools for L^{A}TEX. Available on the web

   at http://www.mat.bham.ac.uk/R.W.Kaye/latex/extraref.tex.

[3] Richard Kaye, Making an index of notation. Available on the web at

   http://www.mat.bham.ac.uk/R.W.Kaye/latex/indexntn.tex.

[4] Leslie Lamport, L^{A}TEX, a document preparation system.

[5] O. Patasnik, BibTEXing. Supplied with BibTEX.

[6] R. M. Smullyan, Recursion Theory for Metamathematics. Oxford University Press, 1993.