Reference for \newlabel

Question

In this question it is mentioned that hyperref overwrites \newlabel and therefore if one loads the package it requires six (rather than two) arguments. I was trying to learn the syntax of \newlabel, with and without hyperref, but in the documentation PDF here I found nothing. Can someone point to a reference where I can read and learn how these commands work?

Answer 1

The statement that \newlabel requires six arguments under hyperref compared to the default two is not correct. hyperref still only uses a two-argument \newlabel, but rather puts five arguments inside the second; the default is to pack only two elements in the second argument...

To see this in better detail, consider the difference in how \label is defined, since it ultimately writes a \newlabel to the .aux file; here's a view of the traditional \label (from latex.ltx):

def\label#1{%
  \@bsphack
  \protected@write\@auxout{}%
    {\string\newlabel{#1}{%
      {\@currentlabel}%
      {\thepage}%
    }}%
  \@esphack}

A call to \label{<label>} will write \newlabel{<label>}{{\@currentlabel}{\thepage}} in the .aux (resolving for \@currentlabel and \thepage to whatever the current label and it's page representation should be). As a consequence, \ref{<label>} will return the stored \@currentlabel (via a \@firstoftwo call) while \pageref{<label>} will return the stored \thepage (via a \@secondoftwo call).

Now let's look at \label when loading hyperref (inside nameref.dtx):

\def\label#1{%
  \@bsphack
  \begingroup
    \def\label@name{#1}%
    \label@hook
    \protected@write\@auxout{}{%
      \string\newlabel{#1}{%
        {\@currentlabel}%
        {\thepage}%
        {\@currentlabelname}%
        {\@currentHref}{}%
      }%
    }%
  \endgroup
  \@esphack
}%

Now a call to \label{<label>} will write \newlabel{<label>}{{\@currentlabel}{\thepage}{\@currentlabelname}{\@currentHref}{}} to the .aux. Note that the first two elements are similar to the traditional \label. It's the addition of three more elements (the last of which is purposefully left empty {}) that makes the difference. The latter discussion is briefly mentioned in the nameref documentation (section 3 Implementation).

Since hyperref now has to deal with extraction of the elements from a 5-set, if defines \@firstoffive, \@secondoffive, ..., \@fifthoffive.

Ultimately, \newlabel in the traditional and hyperref sense only work with two arguments. It's just that the second argument is comprised of more elements when using hyperref.