Managing Hyperref Incompatibilities: A 2024 Update

Identifying Package Conflicts

The hyperref package allows adding hyperlinks and other interactive features to LaTeX documents. However, it often conflicts with other packages due to its extensive redefinitions and hooks into LaTeX internals. Some common symptoms of hyperref incompatibilities include incorrect or missing links, odd warnings, changed output, and compile errors.

There are a few key ways to identify potential issues:

• Review warning and error messages - Conflicts usually generate warnings about overwritten commands, failed redefinitions etc.
• Check link highlighting - Missing or incorrect links indicate problems with anchor placement hooks.
• Compare output versions - Changed output with and without hyperref loaded points to deeper conflicts.
• Review package documentation - The documentation often lists known incompatibilities.

Isolating the culprit by selectively disabling packages can help zero in on the source of conflicts. Maintaining outdated package versions can also introduce issues as both hyperref and other packages evolve, so keeping packages updated is advised.

Resolving Clashing Options

Many conflicts between hyperref and other LaTeX packages come down to clashing options that enable similar functionality in incompatible ways. For example, multiple packages trying to manage document bookmarks independently can cause issues. The key is identifying overlapping options and selectively disabling them.

Common overlapping options include:

• Bookmark and outline management settings
• Link color and style settings
• Index and table of contents adjustments
• Equation label configurations
• Citation and bibliography tweaks
• Figure/table caption and reference changes

Carefully compare options across all loaded packages and disable settings uniformly to prevent inconsistencies. For example:

\usepackage[bookmarks=false]{hyperref}
\usepackage


Table of Contents
Toggle

{otherpackage}

This avoids both packages fighting for control of the document outline and bookmarks.

Handling Incompatible Commands

Some LaTeX packages define commands and environments that directly clash with hyperref adjustments. Attempting to load both results in compile errors or fatal conflicts. There are a few approaches to address this:

1. Select only one conflicting package
2. Redefine commands with unique names
3. Load packages in strategic order
4. Patch incompatible code sections

For example, the nopagenumbers environment in the fancytooltips package clashes with hyperref. Solution options include:

1. \usepackage{fancytooltips} % Drop hyperref
2. \newenvironment{fnopageenums}{...}{...} % Rename
3. \usepackage[..]{hyperref} \usepackage{fancytooltips} % Ordering
4. \makeatletter \g@addto@macro\@endtooltip{...} \makeatother % Patching

Identifying and working around every incompatible command takes trial and error. Thankfully, common conflicts are well documented.

Example Code Showing Conflicts

Consider the following LaTeX sample exhibiting hyperref conflicts:

\documentclass{article}
\usepackage[utf8]{inputenc}

\usepackage{cleveref}
\usepackage[colorlinks]{hyperref}

\title{Conflict Demo}  
\author{Anonymous}

\begin{document}

\maketitle

\section{Introduction}
See Section \cref{sec:conclusion}

\section{Details}
More details here...

\section{Conclusion}\label{sec:conclusion}
In conclusion...

\end{document}

This generates warnings about multiple definition of commands like \cref. Also, the cross-reference link is missing. Reason - both cleveref and hyperref try to manage references their own way. Disabling one package is needed, or settings must be aligned like:

\usepackage[capitalise,nameinlink]{cleveref} 
\usepackage[hypertexnames=false]{hyperref}

Similar small examples help uncover typically opaque conflicts incrementally during development. Testing packages together in basic templates helps identify issues early.

Prioritizing Package Loading Order

LaTeX packages interact closely within a complex cascading set of definitions, replacements and extensions. The order they are loaded changes this equation and can resolve or introduce conflicts.

As a rule of thumb for hyperref compatibility:

1. Load hyperref last of all packages
2. Load hyperref before packages that modify references
3. Load packages modifying same feature together

For example:

\usepackage[options]{cleveref}
\usepackage[options]{nameref}
...
\usepackage[options]{hyperref}

This way all modifications by cleveref and nameref are available to hyperref when it makes its adjustments. Getting order right can sometimes avoid the need to actively modify or disable commands.

Using \RequirePackage over \usepackage

The \RequirePackage command allows more fine-grained loading of packages only when specific commands, objects or environments are actually used. This helps avoid conflicts for unused package features. It works as follows:

\\ Declare requirement, load only when \foo used
\RequirePackage{conflictpackageA} 

\\ Use command to trigger loading 
\newcommand{\foo}{..}  

\\ Package loaded here, contained impact
\foo

LaTeX's documenting mechanism can automate this further:

\PackageInfo{conflictpackageB}{Loaded when \bar used}
\DeclareRobustCommand{\bar}{
  \PackageInfo{conflictpackageB}{Triggered loading}  
  \RequirePackage{conflictpackageB}
  \barImpl%
}
\newcommand{\barImpl}{..}

Using \RequirePackage strategically reduces the need for complicated compatibility fixes and options management when only selective features are needed.

Patching Incompatible Commands

When all else fails, patching and redefining incompatible commands is needed. This requires understanding where and why conflicts occur through:\

• Reviewing clash error messages
• Studying package code and documentation
• Reading packages .sty files
• Testing minimal example documents

Common approaches include:

• Saving and restoring clashing definitions
• Reimplementing features with new custom commands
• Nullifying and disabling problematic hooks
• Adjusting internal macros and targets
• Reordering dependency declarations

This is nontrivial and requires expertise, but may be unavoidable. Targeted small patches help manage very stubborn conflicts between equally important packages.

Recommended Practices for 2024

Based on the current state of LaTeX packages, here are some best practices for managing hyperref compatibility issues in 2024 documents:

1. Use LaTeX distributions or editors that automatically resolve many common clashes.
2. Enable only essential non-core packages to minimize conflicts.
3. Prefer reference packages compatible with hyperref like cleveref and cref.
4. Use \RequirePackage over \usepackage where possible.
5. Update all packages frequently to benefit from latest compatibility fixes.
6. Report stubborn conflicts to package authors to improve future versions.
7. Construct documents modularly to isolate conflicts at subsection level.

Following these guidelines helps craft robust documents that can enable advanced interactivity through hyperref while avoiding difficult debugging. What challenges remain require narrow troubleshooting using the specialized techniques discussed here as needed on a case-by-case basis. With some care and planning, even complex cross-references, links, bookmarks and multimedia can be added successfully to diverse LaTeX papers and books without compatibility woes, making the most of available techniques in 2024.