Last modified on 14 June 2014, at 09:43

LaTeX/Labels and Cross-referencing

LaTeX logo.svg

LaTeX

Getting Started
  1. Introduction
  2. Installation
  3. Installing Extra Packages
  4. Basics

Common Elements

  1. Document Structure
  2. Text Formatting
  3. Paragraph Formatting
  4. Colors
  5. Fonts
  6. List Structures
  7. Special Characters
  8. Internationalization
  9. Rotations
  10. Tables
  11. Title creation
  12. Page Layout
  13. Importing Graphics
  14. Floats, Figures and Captions
  15. Footnotes and Margin Notes
  16. Hyperlinks
  17. Labels and Cross-referencing

Mechanics

  1. Errors and Warnings
  2. Lengths
  3. Counters
  4. Boxes
  5. Rules and Struts

Technical Texts

  1. Mathematics
  2. Advanced Mathematics
  3. Theorems
  4. Chemical Graphics
  5. Algorithms
  6. Source Code Listings
  7. Linguistics

Special Pages

  1. Indexing
  2. Glossary
  3. Bibliography Management
  4. More Bibliographies

Special Documents

  1. Letters
  2. Presentations
  3. Teacher's Corner
  4. Curriculum Vitae

Creating Graphics

  1. Introducing Procedural Graphics
  2. MetaPost
  3. Picture
  4. PGF/TikZ
  5. PSTricks
  6. Xy-pic
  7. Creating 3D graphics

Programming

  1. Macros
  2. Plain TeX
  3. Creating Packages
  4. Themes

Miscellaneous

  1. Modular Documents
  2. Collaborative Writing of LaTeX Documents
  3. Export To Other Formats

Help and Recommendations

  1. FAQ
  2. Tips and Tricks

Appendices

  1. Authors
  2. Links
  3. Package Reference
  4. Sample LaTeX documents
  5. Index
  6. Command Glossary

edit this boxedit the TOC

IntroductionEdit

Another good point of LaTeX is that you can easily reference almost anything that is numbered (sections, figures, formulas), and LaTeX will take care of numbering, updating it whenever necessary. The commands to be used do not depend on what you are referencing, and they are:

\label{marker}
you give the object you want to reference a marker, you can see it like a name.
\ref{marker}
you can reference the object you have marked before. This prints the number that was assigned to the object.
\pageref{marker}
It will print the number of the page where the object is.

LaTeX will calculate the right numbering for the objects in the document; the marker you have used to label the object will not be shown anywhere in the document. Then LaTeX will replace the string "\ref{marker}" with the right number that was assigned to the object. If you reference a marker that does not exist, the compilation of the document will be successful but LaTeX will return a warning:

LaTeX Warning: There were undefined references.

and it will replace "\ref{unknown-marker}" with "??" (so it will be easy to find in the document).

As you may have noticed reading how it works, it is a two-step process: first the compiler has to store the labels with the right number to be used for referencing, then it has to replace the \ref with the right number. That is why, when you use references, you have to compile your document twice to see the proper output. If you compile it only once, LaTeX will use the older information it collected in previous compilations (that might be outdated), but the compiler will inform you printing on the screen at the end of the compilation:

LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.

Using the command \pageref{} you can help the reader to find the referenced object by providing also the page number where it can be found. You could write something like:

See figure~\ref{fig:test} on page~\pageref{fig:test}.

Since you can use exactly the same commands to reference almost anything, you might get a bit confused after you have introduced a lot of references. It is common practice among LaTeX users to add a few letters to the label to describe what you are referencing. Some packages, such as fancyref, rely on this meta information. Here is an example:

chap: chapter
sec: section
subsec: subsection
fig: figure
tab: table
eq: equation
lst: code listing
itm: enumerated list item
app: appendix subsection

Following this convention, the label of a figure will look like \label{fig:my_figure}, etc. You are not obligated to use these prefixes. You can use any string as argument of \label{...}, but these prefixes become increasingly useful as your document grows in size.

Another suggestion: try to avoid using numbers within labels. You are better off describing what the object is about. This way, if you change the order of the objects, you will not have to rename all your labels and their references.

If you want to be able to see the markers you are using in the output document as well, you can use the showkeys package; this can be very useful while developing your document. For more information see the Packages section.

ExamplesEdit

Here are some practical examples, but you will notice that they are all the same because they all use the same commands.

SectionsEdit

\section{Greetings}
\label{sec:greetings}
 
Hello!
 
\section{Referencing}
 
I greeted in section~\ref{sec:greetings}.

Latex example referencing section.png

You could place the label anywhere in the section; however, in order to avoid confusion, it is better to place it immediately after the beginning of the section. Note how the marker starts with sec:, as suggested before. The label is then referenced in a different section. The tilde (~) indicates a non-breaking space.

PicturesEdit

You can reference a picture by inserting it in the figure floating environment.

\begin{figure}
  \centering
    \includegraphics[width=0.5\textwidth]{gull}
  \caption{Close-up of a gull}
  \label{fig:gull}
\end{figure}
Figure~\ref{fig:gull} shows a photograph of a gull.
Latex example figure referencing.png

When a label is declared within a float environment, the \ref{...} will return the respective fig/table number, but it must occur after the caption. When declared outside, it will give the section number. To be completely safe, the label for any picture or table can go within the \caption{} command, as in

\caption{Close-up of a gull\label{fig:gull}}

See the Floats, Figures and Captions section for more about the figure and related environments.

Fixing wrong labelsEdit

The command \label must appear after (or inside) \caption. Otherwise, it will pick up the current section or list number instead of what you intended.

\begin{figure}
  \centering
  \includegraphics[width=0.5\textwidth]{gull}
  \caption{Close-up of a gull} \label{fig:gull} 
\end{figure}

Issues with links to tables and figures handled by hyperrefEdit

In case you use the package hyperref to create a PDF, the links to tables or figures will point to the caption of the table or figure, which is always below the table or figure itself[1]. Therefore the table or figure will not be visible, if it is above the pointer and one has to scroll up in order to see it. If you want the link point to the top of the image you can give the option hypcap to the caption package:

\usepackage[hypcap]{caption}

FormulaeEdit

Here is an example showing how to reference formulae:

\begin{equation} \label{eq:solve}
x^2 - 5 x + 6 = 0
\end{equation}
 
\begin{equation}
x_1 = \frac{5 + \sqrt{25 - 4 \times 6}}{2} = 3
\end{equation}
 
\begin{equation}
x_2 = \frac{5 - \sqrt{25 - 4 \times 6}}{2} = 2
\end{equation}
 
and so we have solved equation ~\ref{eq:solve}

Latex example math referencing.png

As you can see, the label is placed soon after the beginning of the math mode. In order to reference a formula, you have to use an environment that adds numbers. Most of the times you will be using the equation environment; that is the best choice for one-line formulae, whether you are using amsmath or not. Note also the eq: prefix in the label.

eqrefEdit

The amsmath package adds a new command for referencing formulae; it is \eqref{}. It works exactly like \ref{}, but it adds parentheses so that, instead of printing a plain number as 5, it will print (5). This can be useful to help the reader distinguish between formulae and other things, without the need to repeat the word "formula" before any reference. Its output can be changed as desired; for more information see the amsmath documentation.

tagEdit

The \tag{eqnno} command is used to manually set equation numbers where eqnno is the arbitrary text string you want to appear in the document. It is normally better to use labels, but sometimes hard-coded equation numbers might offer a useful work-around. This may for instance be useful if you want to repeat an equation that is used before, e.g. \tag{\ref{eqn:before}}.

numberwithinEdit

The amsmath package adds the \numberwithin{countera}{counterb} command which replaces the simple countera by a more sophisticated counterb.countera. For example \numberwithin{equation}{section} in the preamble will prepend the section number to all equation numbers.

casesEdit

The cases package adds the \numcases and the \subnumcases commands, which produce multi-case equations with a separate equation number and a separate equation number plus a letter, respectively, for each case.

The varioref packageEdit

The varioref package introduces a new command called \vref{}. This command is used exactly like the basic \ref, but it has a different output according to the context. If the object to be referenced is in the same page, it works just like \ref; if the object is far away it will print something like "5 on page 25", i.e. it adds the page number automatically. If the object is close, it can use more refined sentences like "on the next page" or "on the facing page" automatically, according to the context and the document class.

This command has to be used very carefully. It outputs more than one word, so it may happen its output falls on two different pages. In this case, the algorithm can get confused and cause a loop. Let's make an example. You label an object on page 23 and the \vref output happens to stay between page 23 and 24. If it were on page 23, it would print like the basic ref, if it were on page 24, it would print "on the previous page", but it is on both, and this may cause some strange errors at compiling time that are very hard to be fixed. You could think that this happens very rarely; unfortunately, if you write a long document it is not uncommon to have hundreds of references, so situations like these are likely to happen. One way to avoid problems during development is to use the standard ref all the time, and convert it to vref when the document is close to its final version, and then making adjustments to fix possible problems.

The hyperref packageEdit

autorefEdit

The hyperref package introduces another useful command; \autoref{}. This command creates a reference with additional text corresponding to the target's type, all of which will be a hyperlink. For example, the command \autoref{sec:intro} would create a hyperlink to the \label{sec:intro} command, wherever it is. Assuming that this label is pointing to a section, the hyperlink would contain the text "section 3.4", or similar (the full list of default names can be found here). Note that, while there's an \autoref* command that produces an unlinked prefix (useful if the label is on the same page as the reference), no alternative \Autoref command is defined to produce capitalized versions (useful, for instance, when starting sentences); but since the capitalization of autoref names was chosen by the package author, you can customize the prefixed text by redefining \typeautorefname to the prefix you want, as in:

\def\sectionautorefname{Section}

This renaming trick can, of course, be used for other purposes as well.

  • If you would like a hyperlink reference, but do not want the predefined text that \autoref{} provides, you can do this with a command such as \hyperref[sec:intro]{Appendix~\ref*{sec:intro}}. Note that you can disable the creation of hyperlinks in hyperref, and just use these commands for automatic text.
  • Keep in mind that the \label must be placed inside an environment with a counter, such as a table or a figure. Otherwise, not only the number will refer to the current section, as mentioned above, but the name will refer to the previous environment with a counter. For example, if you put a label after closing a figure, the label will still say "figure n", on which n is the current section number.

namerefEdit

The hyperref package also automatically includes the nameref package, and a similarly named command. It is similar to \autoref{}, but inserts text corresponding to the section name, for example.

Input:

\section{MyFirstSection} \label{sec:marker}
\section{MySecondSection}
In section~\nameref{sec:marker} we defined...

Output:

In section MyFirstSection we defined...

Anchor manual positioningEdit

When you define a \label outside a figure, a table, or other floating objects, the label points to the current section. In some cases, this behavior is not what you'd like and you'd prefer the generated link to point to the line where the \label is defined. This can be achieved with the command \phantomsection as in this example:

%The link location will be placed on the line below.
\phantomsection
\label{the_label}

The cleveref packageEdit

The cleveref package introduces the new command \cref{} which includes the type of referenced object like \autoref{} does. The alternate \labelcref{} command works more like standard \ref{}. References to pages are handled by the \cpageref{} command.

The \crefrange{}{} and \cpagerefrange{} commands expect a start and end label in either order and provide a natural language (babel enabled) range. If labels are enumerated as a comma-separated list with the usual \cref{} command, it will sort them and group into ranges automatically.

The format can be specified in the preamble.

See alsoEdit

Notes and ReferencesEdit


Previous: Hyperlinks Index Next: Errors and Warnings