Different mechanics of \hyperlink vs. \hyperref

Question

I am fiddling around with the hyperref package to build a hypertext structure into my pdf. At first glance, hyperref provides two similar macros to put links between parts of my document: \hyperlink{target}{text} and \hyperref[target]{text}. You might notice their slightly different syntax.

What really interests me is their different working mechanics. I will illustrate this by the following example:

\documentclass{article}

\usepackage{pdfpages}
\usepackage[]{hyperref}
\usepackage{mwe}

\begin{document}

\section{Section Heading}
\label{sectionheading}

\includepdf[link=true, linkname=pdfpage]{example-image}


Link to section works with \hyperref[sectionheading]{hyperref}
and with \hyperlink{sectionheading}{hyperlink}
(but with slightly different targets on the page).

Link to pdf works with \hyperlink{pdfpage.1}{hyperlink}
but not with \hyperref[pdfpage.1]{hyperref}
(and not this way, either: \hyperref[pdfpage]{hyperref}).

\end{document}

To link to the labeled section heading, I may use both commands. While \hyperref directs my pdf viewer directly to the linked section, \hyperlink directs me somewhere slightly different, so I can see more context.

To link to the \includepdf of pdfpages however, I may only use \hyperlink. \hyperref does not work at all.

I suspect this is because of a subtle difference in their working mechanisms. While checking the aux file, I found a line \newlabel{sectionheading}{{1}{1}{Section Heading}{section.1}{}} which \hyperref seems to use as a target. However, I did not find any similar target for the included pdf.

My question: I suspect, I understand the workings of \label and \ref very well. \hyperref seems to work quite similarly with the added clickability. Could you please explain to me how \hyperlink does work differently and how it is implemented? E.g. what mechanics explain the difference when clicked on the link and where and how are the link targets stored in the first place?

Answer 1

Links go to destinations. Destinations are objects in the pdf created (in pdflatex, for the other engines they are similar commands) with the primitive \pdfdest command. The destination object contains a coordinate and a page object reference number. In a different part of the pdf there is a reference from the name of the destination to this object.

<<
/D [6 0 R /XYZ 133.768 667.198 null]
>>

hyperref creates a number of such destinations automatically.

For example a \section command creates a destination called section.1 , section.2 etc.

You can also add more destinations with the \hypertarget command.

To create a link to such a destination you can either use the name of the destination directly (if you know it) with \hyperlink and a brace argument:

\hyperlink{section.1}{some text}

Or you can add a label to the structure where hyperref adds internally destinations and then use \hyperref and the bracket notation, then hyperref will find the destination name by going through the label information:

\section{section}\label{sectionheading}
\hyperref[sectionheading]{some text}

Your third variant does not work:

\hyperlink{sectionheading}{some text}

It gives a warning in the log:

pdfTeX warning (dest): name{sectionheading} has been referenced but does not 
exist, replaced by a fixed one

That means that you get a link, but not to the right place as the destination sectionheading doesn't exist (the "fixed one" used as replacement is normally the first page.)

\includepdf creates a number of destinations for the pages called (in your example) pdfpage.1, pdfpage.2 etc. So to link to this destinations you have to use the brace notation:

 \hyperlink{pdfpage.1}{hyperlink}

(To make life difficult, \hyperref accepts also four braced arguments to link to an url, and I at least gets constantly confused by this).

Answer 2

In your question you say

...\hyperlink{target}{text} and \hyperref[target]{text}...

but it should probably be

...\hyperlink{⟨named destination⟩}{⟨text⟩} and
\hyperref[⟨cross-referencing-label⟩]{⟨text⟩}...

Don't confuse names of LaTeX's cross-referencing-labels with the names of so called "named destinations"="targets"="anchors" which get placed into the .pdf-file for hyperlinking:

Basically a cross-referencing-label is a record of data maintained via the .aux-files during the LaTeX-run and providing pieces of data holding information that is needed for cross-referencing. A cross-referencing-label exists during a LaTeX-run/exists while the LaTeX-compiler is running and creating the .pdf-file/output-file.

It does not exist when the .pdf-file/output-file that was produced during the LaTeX-run is displayed by a pdf-viewing-application.

The name of the cross-referencing-label is the name of the record. Usually such a record consists of several elements like a page-number and the printed value of some LaTeX-sectioning-counter and - in case hyperref is loaded - the heading of the corresponding section and the name of a "named destination" placed into the .pdf-file for hyperlinking that section/for "navigating" to that section while viewing the .pdf-file. Different referencing-commands can retrieve different elements of such a record.

E.g., with \ref the printed value of the LaTeX-counter is retrieved. In case the hyperref-package is loaded, the name of the "named destination" which due to some sectioning-command (\section, \subsection, ... \caption etc) automatically got placed at the beginning of the corresponding item of sectioning is retrieved also for turning the printed value into a hyperlink leading to the corresponding item of sectioning.

I tried to explain the concepts related to LaTeX 2ε's cross-referencing-mechanism in my answer to the question "How to prevent reference to enumeration inside new environment?".

A named destination=a target=an anchor -- as already explained by Ulrike Fischer -- is an object which gets placed into the .pdf-file itself and which is used by the .pdf-viewing-application for "navigating" to a specific "place" of the document when viewing the .pdf-file.

A named destination/a target/an anchor does exist when the .pdf-file/output-file is displayed by a pdf-viewing-application.

When loading the hypperref-package, then LaTeX does automatically place such objects/named destinations into the .pdf-file when processing sectioning-commands like \section, \subsection, ..., \caption. Due to the \label-command (which triggers writing to the .aux-file the record of data which you wish to use for cross-referencing) LaTeX beneath other components also stores as a component of the cross-referencing-label the name of the named destination which was placed automatically by LaTeX as the last one before encountering the \label-command in question. Referencing-commands like \ref or \pageref can extract this piece of data for turning things into hyperlinks.

Besides hyperref's automatic placing of named destinations you can use \hypertarget for placing a named destination into a .pdf-file "by hand".

The difference between \hyperref[sectionheading]{some text} and \hyperlink{section.1}{some text} is:

The optional argument of \hyperref[sectionheading]{some text} denotes a cross-referencing-label and the \hyperref-command will wrap the phrase "some text" into a hyperlink by obtaining the name of the corresponding named destination from that cross-referencing-label which basically is a record of data whereof one component denotes the name of a named destination that got placed into the .pdf-file.

The first non-optional argument of \hyperlink{section.1}{some text} directly denotes the name of a named destination that got placed into the .pdf-file. The name of the named destination is given directly and is not to be obtained as a component from a record of data handled as cross-referencing-label.

If you like it cumbersome you can use the refcount-package for obtaining single components of these records of data that are called cross-referencing-labels and do something like this:

\documentclass{article}

\usepackage{pdfpages}
\usepackage{hyperref}
\usepackage{refcount}
...
\section{section}\label{sectionheading}
... 
\IfRefUndefinedBabel{sectionheading}{%
  \refused{sectionheading}%
}{%
  \hyperlink{\getrefbykeydefault{sectionheading}{anchor}{UndefinedDestination}}%
            {some text}%
}
...

With this construct during the first LaTeX-run, i.e., while cross-referencing-labels aren't recorded to the .aux-files yet and thus still are undefined, \refused{...} will be carried out and you get questionmarks into the .pdf-file and warnings into the .log-file and on the console.
In consecutive LaTeX-runs the name of the named destination belonging to the cross-referencing-label sectionheading will be extracted from the data-record formed by the cross-referencing-label sectionheading and delivered to the \hyperlink-command by the \getrefbykeydefault-command.

But you don't really need this. \hyperref[sectionheading]{some text} is shorter and does the same. ;-)