Extending Latex’S Cross-Referencing Capabilities With Hyperref And Zref

The Core Issue: Fragile LaTeX Labeling and Referencing

How LaTeX’s labeling and referencing system works

LaTeX provides a built-in system for labeling elements such as sections, figures, tables, and equations in a document using the \label{key} command and then cross-referencing them elsewhere using the \ref{key} command which prints the number of the labeled element. However, this system relies on LaTeX internally maintaining a proper ordering of labels and references during compilation which can easily get thrown off by common document edits leading to inaccurate or broken references.

Drawbacks: fragile links, inaccurate page references

Some major drawbacks of LaTeX's built-in cross-referencing system:

  • Fragile links - Adding, deleting, or moving portions of a LaTeX document can cause label references to shift or break across compilations
  • Inaccurate page references - Page numbers printed from \pageref{key} may shift incorrectly when the document is edited
  • Limited functionality - Features like hyperlinks, back-references, and sorting/compression of multiple references at once are missing

Powerful Packages for Robust References

Introducing hyperref: robust hyperlinks and bookmarks

The hyperref package extends LaTeX's cross-referencing system by transforming simple label references into clickable hyperlinks in the final PDF document. It also provides additional functionality:

  • PDF bookmarks - Interactive table of contents for navigation
  • Internal/external links - Link to URLs and other files
  • Stability - Stores reference data externally during compilation
  • Customization - Fine control over link appearance and behavior

Introducing zref: precise label locations

While hyperref makes links more robust, the zref package focuses on improving the precision of label locations and referenced values in a LaTeX document:

  • Independent tracking - Separate underlying label system from LaTeX's built-in references
  • Location modules - Reference page, coordinates, or custom locations
  • Unaffected by edits - Label locations remain fixed during document editing

Together hyperref and zref can take LaTeX's usually fragile cross-referencing system and transform it into a much more capable and extensible framework.

Creating Persistent Label Locations with zref

The zref-user package for declaring labels

The best practice for employing zref is to load the zref-user module which provides new labelling commands separate from LaTeX's \label{}

  \usepackage{zref-user} 

This allows older \label{} links to remain compatible while new elements can be labeled via zref:

  \zlabel{key} % Label the current location
  \zpageref{key} % Reference the page number
  \zref[linker]{key}{File} % Link label to external file

Tracking locations independently from LaTeX

A key difference between zref labels and standard LaTeX labels is that location data is tracked completely independently. For example:

  \zlabel{eq1} % Label equation
  \begin{equation}
  a^2 + b^2 = c^2 \label{eq1}  
  \end{equation}

Here \zlabel{} will record the physical location of the label while \label{} associates logical equation number that may change.

Sample label declarations

Some other examples of declaring zref labels:

  % Section
  \zlabel{sec:intro}  

  % Figure
  \zlabel{fig:diagram}
  \begin{figure}
  \caption{...}
  \end{figure}

  % Custom list item
  \zlabel{item:first} 
  \item My first item

These fixed labels can then be referenced reliably despite document edits shifting content around.

Enhanced PDF Navigation with hyperref

Bookmarks for document sections

Hyperref can transform headings in a LaTeX document into a clickable table of contents in the rendered PDF using the bookmarks option:

  \usepackage[bookmarks]{hyperref}

It will automatically create nested bookmarks to match \section{}, \subsection{}, etc. Very useful for navigation!

Internal and external document links

Regular links:

  See Figure \ref{fig:diagram} on page \pageref{fig:diagram}.

  \href{http://example.com}{External site} 

Are turned into internal clickable links and external website links respectively.

Customizing bookmark text and behavior

The bookmark texts and link targets can be customized as well via:

  \hypertarget{target}{}
  \hyperlink{target}{Text}

And many other hyperref customization options.

Integrating zref and hyperref

Using zref data for hyperref links

Hyperref and zref can be integrated to utilize the robust label locations from zref:

  \usepackage{zref-user,hyperref}
  \zexternalref{extlabel}{http://example.com}

  Link: \href{\zref{extlabel}}{Website}  

Now clicking the rendered link will use the fixed label location instead of LaTeX's usual reference.

Accurate page references with zpageref

The zpageref command can be used to return the correct page number of a zref label:

  See Figure 1 on page \zpageref{fig1}.

Avoiding incorrect page numbers after editing.

Link stability with zref information

Lastly, zref data can be provided to hyperref to improve link stability:

  \hypersetup{zref={fig1,pageref}}

Which uses figure 1's label location instead of only LaTeX's logical reference to place links.

Additional Cross-Referencing Features

backref: Back-references after each bibitem

The backref package prints the page number after each bibliography entry listing locations the entry was referenced from.

amsrefs: Numbered text references

The amsrefs package replaces symbolic references with numeric-style such as [1], [2] for readability.

cleveref: Sorting and compressing references

The cleveref package can automatically sort multiple references and compress consecutive ones to simplify expressions like:

  
  figures 1 to 5 -> figures 1-5

As well as printing "Figure" or "Figure" depending on reference context.

Recommendations and Conclusion

In summary, by leveraging robust packages like hyperref and zref, many of the fragile limitations around LaTeX's built-in cross-referencing system can be overcome.

The combination of persistent label locations from zref and rich linking functionality from hyperref greatly extends LaTeX's capabilities for complex documents requiring robust navigation and references. Additional packages like cleveref, backref, and amsrefs build on top of this foundation to provide even more powerful cross-referencing tools.

For maintainable large documents, the author recommends always employing zref labels for critical structural elements, using hyperref bookmarks for convenient PDF navigation, and integrating the two systems to construct a flexible and extensible cross-referencing framework.

Leave a Reply

Your email address will not be published. Required fields are marked *