Understanding how references and labels work

There are a number of things to take into account when considering using the \label-\ref system. For many, this comes naturally, but once you understand it, it should help out with most of your problems.

1. Placement of \label

Yes, this is important. Why? Well, \label is defined in the LaTeX kernel as

\def\label#1{\@bsphack
  \protected@write\@auxout{}%
         {\string\newlabel{#1}{{\@currentlabel}{\thepage}}}%
  \@esphack}

Note that (despite all the other things going on), it writes to the .aux file something that looks like this:

\newlabel{<label>}{{<currentlabel>}{<page>}}

where <label> is what supply in the form \label{<label>} and <currentlabel> is the current value of \@currentlabel - a macro that is usually updated whenever you call \refstepcounter{<cntr>}. So, if \@currentlabel is not up-to-date according to the reference you're after, then you'll obtain an incorrect reference. Most notably this happens when you place a \label before \caption, since \caption increases some counter (figure or table counter, say). <page> is the page on which the reference occurs within the document and has the value of \thepage at that time - this could be anything set out in the definition of \thepage, just for clarity.

Bottom line: Since \label uses \@currentlabel, make sure your placement of \label is after an update of it. In some cases you can get away with it, since the counter update happens at the beginning of an environment (like in theorems, usually), or the environment is written in such a way to capture and properly allocate a \label to a counter through multiple passes, or just a regular collection process.

Some people try and avoid this confusion of \label placement by placing \label inside a float \caption (say). This is perfectly okay since the counter associated with printing the caption is updated before the caption (and the included \label) is set.

Related reference: Why does an environment's label have to appear after the caption?

2. How many times do I have to compile?

In general, the \label-\ref system works as a two-phase process, and therefore requires at least two compiles (during a first iteration, possibly fewer in subsequent compiles). During the first \label phase, a label is written to the .aux file in the form (assuming you don't load any cross-referencing package like hyperref):

\newlabel{<label>}{{<reference>}{<page>}

Here's a practical example and the output after a single compile:

enter image description here

\documentclass{article}
\begin{document}
\section{A section}\label{sec:section}
See Section~\ref{sec:section}.
\end{document}

In particular, the above MWE produces the following .aux:

\relax 
\@writefile{toc}{\contentsline {section}{\numberline {1}A section}{1}}
\newlabel{sec:section}{{1}{1}}

that, in addition to possible ToC-related content, contains the appropriate \newlabel. The reference itself still shows up as ??, since it was not known what the reference was at the time of writing that content. To understand this a little better, you should know that the .aux file is actually read just before \begin{document}. So, during the first compile, at the time TeX reads \ref{<label>}, the .aux file did not contain any reference information, and therefore \ref leads to ?? as output.

Now, during a subsequent compile, the .aux is read at \begin{document} and therefore associates a reference (and the appropriate page number) with a specific label. As such, when \ref{<label>} is encountered (during the second phase), it can produce the correct reference.

Sure, you don't always need two compiles to obtain the correct reference. This is because no change in a label's location on a specific page would not yield any different output and therefore not require any additional "pair-wise" compilations.

3. So what happens in the .aux file?

As already explained, whenever you write \label{<label>}, the .aux gets written with

\newlabel{<label>}{{<reference>}{<page>}}

at page shipout. However, this information is read and executed at \begin{document} during subsequent compiles. And, from a technical perspective (if you investigate the role of \newlabel and friends in the LaTeX kernel) \label{<label>} creates a macro by the name of \r@<label> that expands to {<reference>}{<page>}. And depending on whether you use \ref{<label>} or \pageref{<label>}, you'll either be receiving <reference> (technically, \@firstoftwo) or <page> (technically, \@secondoftwo).

4. What's with the page reference?

Whenever you use \label, writing of this information to the .aux is actually delayed until page shipout. The reason for this is because the system is set up that way so that a single <label> can be used to reference the <label> "title" (usually in the form of a number) as well as the location (page) within the document. Since TeX asynchronously collects and optimizes page content, it could be that an already-read \label has to wait for a subsequent page to be written. Therefore, not waiting until page shipout may imply an incorrect page number to be associated with the reference.

This is usually also a reason why there is such confusion between having to compile twice, or three times, or perhaps more. The truth behind this is that you have to compile as many times as possible until the references settle (that is, no change in page number or label for a reference change). The magic number is usually two, but it could be more.

For an example of pushing the envelope, see Document requiring infinitely many compiler passes?.

5. Packages that influence the regular \label-\ref system

There are many packages that influence the way \label and \ref work. Most notably is hyperref, since it allows for integration with the default \label-\ref interface, yet adds some additional information beyond the default reference and page number. In fact, when using hyperref with the above MWE

enter image description here

\documentclass{article}
\usepackage{hyperref}% http://ctan.org/pkg/hyperref
\begin{document}
\section{A section}\label{sec:section}
See Section~\ref{sec:section}.
\end{document}

the .aux resembles

\relax 
% ... some hyperref stuff
\@writefile{toc}{\contentsline {section}{\numberline {1}A section}{1}{section.1}}
\newlabel{sec:section}{{1}{1}{A section}{section.1}{}}

Note how \newlabel still has the same two-argument format. However, the second argument now contains 5 groups {..} compared to the original non-hyperref two. The first two are inherited from the original system, while the last three are new. The third contains the title associated with the specific reference (in this case, a section, so the section title). The fourth is a counter-specific reference, used in the hyper-linking process, while the fifth is always empty (perhaps meant for later expansion of the package itself, and therefore just safe-keeping).

6. Packages that extend the regular \label-\ref system

Here are some packages that extend LaTeX's cross-referencing capabilities:

  • hyperref

It allows you to include the named title of the reference (mainly as a result of including nameref). Additionally it provides the option of "auto referencing" an label - using \autoref - which inserts a prefix that is typically added manually (therefore turning see \autoref{<label>} into see Figure~\ref{<label>}, say).

  • zref

All regular \labels store only two values: the current label and the page number where that label exists (see \newlabel above). zref extends this in a natural way to allow for any number of such stored properties through what it calls a "property list". This property list is akin to a key-value interface, but using macros and has the form

    \z@newlabel{<label>}{\propA{<propA>}\propB{<propB>}...}

Note the \z@-prefix, making it obviously different from the traditional \newlabel. In fact, you can still use \label-\ref when using zref, or use the zref-specific \zlabel-\zref. Of course, more complex labelling/referencing exist; see the zref documentation for more details.

Specific to your case:

  • You have \label before \caption - a very common problem. As such, \@currentlabel does not contain the up-to-date information you require, and would return an incorrect reference. See 1 above in terms of the \label placement.

  • As a first run, you need to compile at least twice in order for the references to settle. See 2 above in terms of the number of compilations.

  • You can reference an equation (or anything) before it actually occurs within the text. That's the beauty of TeX's \label-\ref system; that it uses an external file (.aux) as the go-between for writing content about the reference, as well as the location of loading the external file. So, you can most certainly do the following

      %...
  ... see equation~\ref{eqn:myeqn} below:
  \begin{equation}
    f(x) = ax^2 + bx + c \label{eqn:myeqn}
  \end{equation}
  %...

...just as long as you compile at least twice in the first go. See 2 in terms of the number of compilations.


The label for an object must be after that object is defined. So if you are labeling a caption (which you are in your example) the \label command must follow the caption or be part of it. So instead of 

\label{fig:area_Treasuries}
\caption{Treasuries as a portion of total financial flows.}

You should use:

\caption{Treasuries as a portion of total financial flows.}   
\label{fig:area_Treasuries}

or

 \caption{Treasuries as a portion of total financial flows.\label{fig:area_Treasuries}}

Tags:

Cross Referencing

Recent Posts