# The problem

I'm writing a document where all of my equations are labeled, not by numbers, but by names, which I provide with amsmath's \tag command. I also use cleveref for ease of cross-referencing. And I just today decided I'd add hyperref. While this didn't break anything old (at least, not after I'd figured out where to put it), it didn't completely work: links to equations jump incorrectly. Why is this? And how can I fix it?

Edit: The extended problem. This isn't just with equations, it's with all mathematical environments. I make use of equation, align, align*, alignat, align*, and gather, and these all need to support appropriate links. And unfortunately, I just realized this, and the due date for this document is bearing down on me, which is my own fault; but the solution is sufficiently important to me that I'm adding a bounty. (The remainder of this question just refers to the shown MWE.tex; however, the problem is more general.)

# An example

In the following document, all three \eqref links jump to the first equation:

\documentclass{book}

\usepackage{amsmath}
\usepackage{hyperref}
\usepackage{cleveref}

\begin{document}

$$\label{eq:first}\tag{first} \text{First equation}$$

$$\label{eq:second}\tag{second} \text{Second equation}$$

$$\label{eq:third}\tag{third} \text{Third equation}$$

\begin{itemize}
\item A reference to~\eqref{eq:first}.
\item A reference to~\eqref{eq:second}.
\item A reference to~\eqref{eq:third}.
\end{itemize}

\newpage

For scrolling purposes.

\end{document}


If I either remove \usepackage{cleveref} or remove the \tags, everything works fine. But with both of them together, everything jumps to the first equation.

# Compilation messages

## With \usepackage{cleveref} and \tags

When I compile this example (in MWE.tex), I get the following warning messages in the log:

[1{/var/lib/texmf/fonts/map/pdftex/updmap/pdftex.map}pdfTeX warning (ext4): des
tination with the same identifier (name{equation.0.0.1}) has been already used,
duplicate ignored

\AtBegShi@Output ...ipout \box \AtBeginShipoutBox
\fi \fi
l.27 \newpage
pdfTeX warning (ext4): destination with the same identifier (name{
equation.0.0.1}) has been already used, duplicate ignored

\AtBegShi@Output ...ipout \box \AtBeginShipoutBox
\fi \fi
l.27 \newpage
] [2] (./MWE.aux) )


And sure enough, if I look at MWE.aux, it contains the following lines:

\newlabel{eq:first}{{{first}}{1}{\relax }{equation.0.0.1}{}}
\newlabel{eq:first@cref}{{[equation][2147483647][]{first}}{1}}
\newlabel{eq:second}{{{second}}{1}{\relax }{equation.0.0.1}{}}
\newlabel{eq:second@cref}{{[equation][2147483647][]{second}}{1}}
\newlabel{eq:third}{{{third}}{1}{\relax }{equation.0.0.1}{}}
\newlabel{eq:third@cref}{{[equation][2147483647][]{third}}{1}}


## With just \tags (no \usepackage{cleveref})

If I compile without cleveref, then I get the same warning:

[1{/var/lib/texmf/fonts/map/pdftex/updmap/pdftex.map}pdfTeX warning (ext4): des
tination with the same identifier (name{equation.0.0.1}) has been already used,
duplicate ignored

\AtBegShi@Output ...ipout \box \AtBeginShipoutBox
\fi \fi
l.27 \newpage
pdfTeX warning (ext4): destination with the same identifier (name{
equation.0.0.1}) has been already used, duplicate ignored

\AtBegShi@Output ...ipout \box \AtBeginShipoutBox
\fi \fi
l.27 \newpage
] [2] (./MWE.aux) )


However, the links work correctly, and the aux file contains

\newlabel{eq:first}{{{first}}{1}{\relax }{AMS.1}{}}
\newlabel{eq:second}{{{second}}{1}{\relax }{AMS.2}{}}
\newlabel{eq:third}{{{third}}{1}{\relax }{AMS.3}{}}


## With just \usepackage{cleveref}s (no \tags)

If I compile without using \tags, then I get no warning, the links work, and my aux file contains

\newlabel{eq:first}{{1}{1}{\relax }{equation.0.0.1}{}}
\newlabel{eq:first@cref}{{[equation][1][0]1}{1}}
\newlabel{eq:second}{{2}{1}{\relax }{equation.0.0.2}{}}
\newlabel{eq:second@cref}{{[equation][2][0]2}{1}}
\newlabel{eq:third}{{3}{1}{\relax }{equation.0.0.3}{}}
\newlabel{eq:third@cref}{{[equation][3][0]3}{1}}


## With nothing (neither \usepackage{cleveref} nor \tags)

If I compile without using either \usepackage{cleveref} or \tags, then I get no warning, the links work, and my aux file contains

\newlabel{eq:first}{{1}{1}{\relax }{equation.0.0.1}{}}
\newlabel{eq:second}{{2}{1}{\relax }{equation.0.0.2}{}}
\newlabel{eq:third}{{3}{1}{\relax }{equation.0.0.3}{}}


## Without \usepackage{hyperref}, but with everything else

If I instead remove just \usepackage{hyperref}, then I get no warning, there are no links, and my aux file contains

\newlabel{eq:first}{{{first}}{1}}
\newlabel{eq:first@cref}{{[equation][2147483647][]{first}}{1}}
\newlabel{eq:second}{{{second}}{1}}
\newlabel{eq:second@cref}{{[equation][2147483647][]{second}}{1}}
\newlabel{eq:third}{{{third}}{1}}
\newlabel{eq:third@cref}{{[equation][2147483647][]{third}}{1}}


## Replacing equation with gather

The hyperref README reports that the equation environment "[isn't] supported too well," and suggests replacing it with the gather environment. Doing that successfully gets rid of the error message, but doesn't fix the behavior of the links; they still jump to the wrong place. The aux file contains

\newlabel{eq:first}{{{first}}{1}{\relax }{Doc-Start}{}}
\newlabel{eq:first@cref}{{[equation][2147483647][]{first}}{1}}
\newlabel{eq:second}{{{second}}{1}{\relax }{Doc-Start}{}}
\newlabel{eq:second@cref}{{[equation][2147483647][]{second}}{1}}
\newlabel{eq:third}{{{third}}{1}{\relax }{Doc-Start}{}}
\newlabel{eq:third@cref}{{[equation][2147483647][]{third}}{1}}


# What's happening?

Admittedly, that's part of my question, but it looks to me like hyperref and \tag don't play well together: if I have both, I get the error message about duplicates. But it doesn't seem to cause any problems in the document unless cleveref is present as well.

I should also add a couple of caveats:

• This is an 85-page document. I really don't want to deal with changing out any of my packages at this point, but if it works….

• I'm compiling this document on a school machine, and so I don't have control over the main TeX install. I have installed some updated versions to my local texmf tree, however. Here are all the package versions in my log file:

• amstext 2000/06/29 v2.01
• amsbsy 1999/11/29 v1.2d
• amsopn 1999/12/14 v2.01
• hyperref 2011/04/09 v6.82f
• ltxcmds 2011/11/09 v1.22
• ifpdf 2011/01/30 v2.3
• pdftexcmds 2011/11/29 v0.20
• infwarerr 2010/04/08 v1.3
• ifluatex 2010/03/01 v1.3
• keyval 1999/03/16 v1.13
• kvsetkeys 2012/04/25 v1.16
• etexcmds 2011/02/16 v1.5
• pdfescape 2011/11/25 v1.13
• ifvtex 2010/03/01 v1.5
• ifxetex 2009/01/23 v0.5
• hycolor 2011/01/30 v1.7
• xcolor-patch 2011/01/30
• hopatch 2011/06/24 v1.1
• letltxmacro 2010/09/02 v1.4
• kvoptions 2011/06/30 v3.11
• intcalc 2007/09/27 v1.1
• url 2006/04/12 ver 3.3
• bitset 2011/01/30 v1.1
• bigintcalc 2012/04/08 v1.3
• atbegshi 2011/10/05 v1.16
• atveryend 2011/06/30 v1.8
• rerunfilecheck 2011/04/15
• uniquecounter 2011/01/30 v1.2
• cleveref 2012/03/07{} v0.18.5{}
• nameref 2010/04/30 v2.40
• refcount 2011/10/16 v3.4
-
I just noticed that the hyperref README suggests replacing equation by gather; that doesn't fix the behavior of the links, but I added information about what happens when I do that. – Antal Spector-Zabusky May 7 '12 at 4:48
I realized that what I was asking for was insufficient, so I've extended the question and added a bounty. – Antal Spector-Zabusky May 18 '12 at 19:41

I have a solution. However this might not be the most elegant way.

You have to define your own numbering scheme for hyperref so that each number is unique:

\listfiles
\documentclass{book}

\usepackage{amsmath}
\usepackage{hyperref}
\usepackage{cleveref}

%%% define a new counter and use it for \theHequation which hyperref uses for the links
\newcounter{Hequation}
\renewcommand{\theHequation}{\thechapter.\arabic{Hequation}}
\makeatletter
\makeatother

\begin{document}
$$\tag{first}\label{eq:first} \text{First equation}$$

$$\tag{second}\label{eq:second} \text{Second equation}$$

$$\label{eq:firstreal} \text{First equation without tag}$$

$$\tag{third}\label{eq:third} \text{Third equation}$$

$$\label{eq:secondreal} \text{Second equation without tag}$$

\begin{itemize}
\item A reference to~\eqref{eq:first}.
\item A reference to~\eqref{eq:second}.
\item A reference to~\eqref{eq:third}.
\item A reference to~\eqref{eq:firstreal}.
\item A reference to~\eqref{eq:secondreal}.
\end{itemize}

\newpage

For scrolling purposes.

\end{document}


As you can see \equation has to be redefined as well. Then equations with and without \tag can be mixed-up without any problems.

Best regards
Martin

-
This seems to work—thanks! A question, though: why are you patching \tag as well as \equation? Intuitively, it seems like you should only need to patch \equation to maintain this new unique \theHequation; and if I comment out the patch to \tag, everything seems to still work at a quick glance. – Antal Spector-Zabusky May 7 '12 at 19:10
Yes, you are right. Patching \equation is enough in this special situation, because \tag is always inside the equation environment. If you want to extend this mechanism to other amsmath environments, you have to patch other macros as well. – Martin May 8 '12 at 7:19
As you noticed, this only works for equation. Unfortunately, I only noticed this now too, which is my own fault but is unfortunate. I've updated the question to reflect my actual needs (I need correct links to most of the possible environments), and I've added a bounty. If you have the solution and/or the time, I'd love to have it... :-) – Antal Spector-Zabusky May 18 '12 at 19:42
I awarded you the bounty because your solution is what gave me the ability to understand what was going on and come up with a half-assed fix; thank you! (I'd still love to see if/how this generalizes to a nicer solution, but my urgent deadline is past, so it's just academic at this point. And/or if I need it in the future.) – Antal Spector-Zabusky May 25 '12 at 4:05

The correct way to use \tag with hyperref and amsmath is to use the starred math environments that are unnumbered. Then, they do not increment the equation counter, which implicitly defines an anchor based on the new counter value, only for \tag to decrement the counter again (there's nothing it can do about the already defined anchor, but one can use the hypertexnames=false option to hyperref to partially alleviate this if necessary).

Even with the above, there are incompatibility problems between hyperref, cleveref and amsmath. As Martin has noted, the problem is that cleveref directly implements amsmath macros and changes them, thus ignoring hyperref's work. One option then is to further patch the macros that amsmath provides to incorporate both hyperref's enhancements and cleverefs addition, which I have done in the following:

\documentclass{article}

\usepackage{amsmath}
\usepackage{hyperref}
\usepackage{cleveref}

\makeatletter

\def\make@df@tag@@#1{%
\gdef\df@tag{%
\maketag@@@{\Hy@make@anchor#1}%
\def\@currentlabel{#1}%
\def\cref@currentlabel{[equation][2147483647][]#1}%
}%
}
\def\make@df@tag@@@#1{%
\gdef\df@tag{%
\tagform@{\Hy@make@anchor#1}%
\toks@\@xp{\p@equation{#1}}%
\edef\@currentlabel{\the\toks@}%
\edef\cref@currentlabel{[equation][2147483647][]\the\toks@}
}%
}
\makeatother

\begin{document}

\begin{equation*}\label{eq:first}\tag{first}
\text{First equation}
\end{equation*}

\begin{equation*}\label{eq:second}\tag{second}
\text{Second equation}
\end{equation*}

\begin{equation*}\label{eq:third}\tag{third}
\text{Third equation}
\end{equation*}

$$\label{eq:fourth} \text{Fourth equation}$$

\begin{itemize}
\item A reference to~\eqref{eq:first}.
\item A reference to~\eqref{eq:second}.
\item A reference to~\eqref{eq:third}.
\item A reference to~\eqref{eq:fourth}.
\end{itemize}

\newpage

For scrolling purposes.

\end{document}

-
Fantastic answer! Could you please explain how you found that? – mafp Mar 12 '13 at 21:43
@mafp: Glad it was of some help. I'm afraid it was a case of examining the various source files for each of the packages involved. Probably the issues with the interactions were never anticipated hence not documented or resolved. – cyberSingularity Mar 12 '13 at 21:56

For reference, this issue seems to have been fixed in recent versions of cleveref (at least since 0.18.10; not yet in CTAN but available from my web site). The redefinitions in the other answers are no longer be necessary. I haven't tracked down precisely which version of cleveref fixed this bug.

-
Awesome! I just checked it out; with hyperref v6.82q, I get the spurious warnings, but things seem to work. Thanks! – Antal Spector-Zabusky Nov 24 '13 at 19:18

Since I had to find a solution to this for the final version of my document, here's the solution I found; it produces a lot of errors in the log file, but they don't appear to correspond to errors in the resulting document. I'm still curious about the Right Way™ to do this, though.

\makeatletter
\newif\if@plaintag
\@plaintagfalse
\let\plaintagform@\tagform@
\newcommand{\plaintag}[1]{\begingroup\let\tagform@\plaintagform@\tag{#1}\endgroup}
\def\tagform@#1{\if@plaintag\else\refstepcounter{equation}\fi%
\maketag@@@{[\textsc{\ignorespaces #1}]}}
\newcommand{\ptag}[1]{\@plaintagtrue\tag{#1}\@plaintagfalse}
\makeatother


Since I was redefining \tagform@ anyway (to render \maketag@@@ around small caps in square brackets), I forced it to include \refstep{equation} (modulo an if statement, for \tagged but unlabled equations). I also placed all \tags before \label`s (I'm not sure if this is necessary, but it didn't hurt). As a result, despite lots of warnings about duplicate labels, everything seemed to work properly; stepping the equation counter made the link destination correct.

-
This works, but is clearly sort of ugly. If there's a better solution, I'm all ears (really!), but this is what ended up in my document. – Antal Spector-Zabusky May 25 '12 at 4:05
I tried to create a solution by redefining hyperref's and cleverref's macros. I think, the problem is, that cleveref directly implements amsmath macros and changes them, thus ignoring hyperref's work. – Martin May 25 '12 at 7:42