Chapter 7: Using Cross-References

Our documents contain many numbered things, such as pages, sections, list items, figures, and tables. There's even more that we have not listed yet; for instance, if you would like to write mathematical text, you may use number equations, theorems, definitions, and many more.

We number things not just to count them but also to refer to them in other places of our document. For instance, in this chapter, if I wanted to point you towards the third figure, I would say "see Figure 7.3". LaTeX automatically enumerates figures for you. If you insert another figure, LaTeX will automatically adjust the numbering of all figures after it. But what happens with the references? Well, LaTeX can take care of all of our cross-references, which is the subject of this chapter.

In this chapter, we shall learn about the following:

• Setting labels and references
• Using advanced referencing
• Referring to labels in other documents
• Turning...

Technical requirements

You can use a local LaTeX installation, or you can compile the example code online at https://latexguide.org/chapter-07.

The code is also available on GitHub: https://github.com/PacktPublishing/LaTeX-Beginner-s-Guide-2nd-Edition-/tree/main/Chapter_07_-_Using_Cross-References.

In this chapter, we will use the cleveref package and the varioref package.

We will also get to know the fancyref, hyperref, and xr packages.

Setting labels and references

To be able to refer to a certain point, we have to mark it with a label. The name of that label will serve us afterward for referencing.

We will now typeset a list of the most used packages for papers, according to a survey on https://latex.org. Through the \label command, we will mark items that we can later refer to with the \ref command, as shown here:

1. Create a new book document:

   \documentclass{book}
   \begin{document}

2. Start a chapter and a section, and place a label for this section:

   \chapter{Statistics}
   \section{Most used packages by LaTeX.org users}
   \label{sec:packages}

3. Continue with some text, including a footnote:

   The Top Five packages, used by LaTeX.org
   members\footnote{according to the 2021 survey on
   LaTeX.org\label{fn:project}}:

4. Write an enumerated list and put a label on a few items for referring to them:

   \begin{enumerate}
     \item graphicx\label{item:graphicx}
     \item babel
     \item amsmath\label...

Using advanced referencing

LaTeX helps with automating all kinds of references. It's not only limited to numbering. LaTeX can even automate naming and phrasing. We will dig deeper into that here.

Producing intelligent page references

The varioref package offers a command to add on the preceding page, on the following page, or the page number to a reference, depending on the context.

We will use the varioref commands to introduce variable references, \vref, and \vpageref, to achieve enhanced reference texts:

1. Open our current example from the Setting labels and references section. Add the varioref package to your preamble. Use the nospace package option, which ensures that varioref doesn't insert additional undesirable space before or after a reference:

   \usepackage[nospace]{varioref}

2. Edit the content of the second chapter in our example code:

   \emph{amsmath}, on position \vref{item:amsmath}
   of the top list in section~\vref{sec:packages},
   is indispensable to...

Referring to labels in other documents

If you write several related documents that refer to each other, you might want to use references to labels of another document. The package with the name xr (standing for external references) implements this. First, load the xr package:

\usepackage{xr}

If you need to refer to sections or environments in an external document, say, doc.tex, insert this command into your preamble:

\externaldocument{doc}

This enables you to additionally refer to anything that has been given a label in doc.tex. You may do this for several documents. If you need to avoid conflicts when an external document uses the same \label as the main document, declare a prefix using the optional argument of \externaldocument, which you can use to add a prefix. For example, we can use D- as a prefix:

\externaldocument[D-]{doc}

This way, all references from doc.tex would be prefixed by D-, and you could write \ref{D-name} to refer to name in doc.tex. Instead of...

Turning references into hyperlinks

PDF documents offer bookmarks and hyperlink capabilities. How about exploring that? There's an outstanding package that offers hyperlink support – the hyperref package.

Try it by loading hyperref right before cleveref. This order is essential for the references to work because cleveref detects whether hyperref has been loaded and makes the references to hyperlinks. Even without any options or commands, your document will be hyperlinked as much as possible because of the following:

• All references become hyperlinks. Click on any of those numbers to jump to the referred table, list item, section, or page.
• Each footnote marker is a hyperlink to the footnote text. Click it to jump there.
• If you insert \tableofcontents, you will get a bookmark list for the documents, chapters, and sections listed in a navigation bar of your PDF reader.

hyperref can do even more for you – linking index entries to text passages...

Summary

In this chapter, we learned how to reference chapters, sections, footnotes, and environments by their number or by the number of the corresponding page.

Using labels for referencing, we did not need to specify a number by ourselves; LaTeX determines the correct number of a page for us, or of a section, a footnote, or an environment.

We even got to know some clever ways of context-dependent referencing.

In the next chapter, we shall deal with lists, which consist mainly of references: tables of contents, lists of figures and tables, and bibliographies.