\pageref link target goes to wrong page

[kberry]

Bug description in text.

\documentclass{article}
\usepackage{hyperref}
\begin{document}
\section{First page section}
First page text.

\newpage
Second page text, with label text2.\label{text2}

\newpage
Third page text, with pageref to text2: page \pageref{text2}.
It is correctly printed as 2, but the hyperlink goes to page 1, since
that is where the last section was. This seems like wrong behavior for
*page*ref.

This is with current (10sep21) pdflatex-dev, although I doubt the
particular versions make a difference.

\end{document}

[kberry]

P.S. Thanks to Nicola for explaining this problem to me.

[u-fischer]

Yes that is known. \pageref uses the information that are set by the label, and the label refer to the last destination you set.

While theoretically pageref could jump to a page, this is not really reliable as the data a label can store is a bit restricted and currently doesn't include the name of the page destination or the abspage, also such a link would always jump to the top of the page and not to the place of the label.

So if you set a label somewhere in the middle of some text \label{text2} you should also set an anchor with \phantomsection\label{text2}.

There should be perhaps a \pagelabel command, eg. \newcommand\pagelabel{\phantomsection\label}, but it is not quite clear who should define it.

[kberry]

Sure, I surmised it was a known bug. It is disconcerting that a \pageref link goes to some page other than what is printed. If LaTeX can print the right page number, it seems strange that it cannot link to the right page. Much better to go to the top of the correct page than some other previous location, seems to me. Anyway, I suggest that 1) there be a recommended amelioration (doesn't \phantomsection have other side effects? Not that I know anything about it), and 2) that that be part of the \pageref documentation. Instead of leaving to users to notice/debug. --thanks, karl.

[ggustaf]

Karl is correct. The documentation needs a few extra lines, especially at \phantomsection page 23, reproduced below.

https://mirrors.nic.cz/tex-archive/macros/latex/contrib/hyperref/doc/hyperref-doc.pdf#page=23

\phantomsection
This sets an anchor at this location. It works similar to \hypertarget{}{} with an automatically
chosen anchor name. Often it is used in conjunction with \addcontentsline for sectionlike things
(index, bibliography, preface). \addcontentsline refers to the latest previous location where an
anchor is set. Example:

\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{\indexname}
\printindex
Now the entry in the table of contents (and bookmarks) for the index points to the start of the
index page, not to a location before this page.

My experience one year ago was the same. There is no specific info in the referenced ctan PDF about \ref and \pageref and what happens to the hyperlinks after pdflatex makes the PDF. I would like to see one sentence added that explains briefly what an "anchor" does in a PDF and why \phantomsection\label{...} is sometimes required to produce targets for \hyperref.

Fischer's idea for command \pagelabel is relevant. The suggestion could be in the documentation as a common user-defined macro. In 2020, the same macro fixed my hyperlinks to hundreds of delayed proofs in a textbook of 1300 pages.

[u-fischer]

@ggustaf There is some explanation about destinations in 4.4 Creating targets. Apart from this: The documentation has grown over 30 years, and there are many places where it could be improved. If you want to help, make a pull request with a suggested change.

[sungheeyun]

THANK YOU SO MUCH!