1

I have been digging the source code of \autoref for quite a while, but haven't understood the way \autoref determines the types of labels.

I am sort of lost in the relevant code (hyperref.dtx line 13400-13474):

\DeclareRobustCommand*{\autoref}{%
  \leavevmode
  \@ifstar{\HyRef@autoref\@gobbletwo}{\HyRef@autoref\hyper@@link}%
}
\def\HyRef@autoref#1#2{%
  \begingroup
    \Hy@safe@activestrue
    \expandafter\HyRef@autosetref\csname r@#2\endcsname{#2}{#1}%
  \endgroup
}
\def\HyRef@autosetref#1#2#3{% link command, csname, refname
  \HyRef@ShowKeysRef{#2}%
  \ifcase 0\ifx#1\relax 1\fi\ifx#1\Hy@varioref@undefined 1\fi\relax
    \edef\HyRef@thisref{%
      \expandafter\@fourthoffive#1\@empty\@empty\@empty
    }%
    \expandafter\HyRef@testreftype\HyRef@thisref.\\%
    \Hy@safe@activesfalse
    #3{%
      \expandafter\@fifthoffive#1\@empty\@empty\@empty
    }{%
      \expandafter\@fourthoffive#1\@empty\@empty\@empty
    }{%
      \HyRef@currentHtag
      \expandafter\@firstoffive#1\@empty\@empty\@empty
      \null
    }%
  \else
    \protect\G@refundefinedtrue
    \nfss@text{\reset@font\bfseries ??}%
    \@latex@warning{%
      Reference `#2' on page \thepage\space undefined%
    }%
  \fi
}

I believe \HyRef@currentHtag would be the tag name (e.g.chapter, section, etc.), but I don't understand how this block of code works.

What does \csname r@#2\endcsname (expanded to \r@#2) do? Is #2 here the label (e.g. chap:1 defined by \label{chap:1})

3

The story begins with \refstepcounter, then follows \label and .aux file, finally ends with reference commands like \ref or \autoref.

In LaTeX2e format (in a simplified form),

  • \refstepcounter{<counter>} steps <counter> and then stores (or updates) its value in \@currentlabel.
  • \label{<key>} writes \newlabel{<key>}{{<value of \@currentlabel>}{<value of \thepage}} to .aux file, in which a link between label key and reference contents is established.
  • When .aux is input in \begin{document}, \newlabel is expanded and it defines \r@<key> to {<value of \@currentlabel>}{<value of \thepage}.
  • At the end, \ref{<key>} and \pageref{<key>} gets <value of \@currentlabel> and <value of \thepage} linked to <key>, respectively.
\documentclass{article}
\usepackage{amsmath}

\begin{document}
% 3. at second running, .aux file is input and 
%    \r@key is defined to be "{3}{1}"

section \ref{key}
% 4. get 3 from \r@key and output 3

\setcounter{section}{2}
\section{title}
% 1. now \@currentlabel is 3

\label{key} % current page is 1
% 2. now \newlabel{key}{{2}{1}} is written to .aux file
\end{document}

hyperref extends the <key> -> <value>, <page> link to <key> -> <value>, <page>, <name>, <hyper ref>, <file>. Using the above example,

  • now \section{<name>} (which calls \refstepcounter) updates \@currentlabel to 3, \@currentlabelname to <name> (which is "title"), and \@currentHref to <hyper ref> (which is "section.3", in the form of <counter name>.<counter value>). Note that the counter name is contained in`.
  • now \label{key} writes \newlabel{key}{{3}{1}{title}{section.13}{}} to .aux file
  • now input .aux file defines \r@key to {3}{1}{title}{section.13}{}.
  • now \ref and \pageref acts like before, and \nameref{<key>} gets <name> (which is "title" in our example), \autoref{<key>} gets the combination of <autoref name per counter> <value> (which is "section 3").

PS:

  • \nameref is provided by nameref package, which is distributed and auto loaded with hyperref.
  • Suppose #2 is "key", then \csname r@#2\endcsname expands to control sequence \r@key in one step of expansion. You can learn more about \csname ... \endcsname in docs like TeX by Topic.
6
  • Hi there! Muzi you are everywhere answering questions enthusiastically! I am reading your answer.
    – Frank
    May 15 '20 at 1:44
  • 1
    Thank you for such a clear answer! May I ask one more question? Is there a book for LaTeX equivalent to The TeXbook for Knuth TeX?
    – Frank
    May 15 '20 at 1:58
  • @Frank I'm afraid not. TeX engines (like knuth tex, pdftex, xetex, and luatex) and their backends (like dvips and dvipdfm-x) are relatively stable (and centralized), while the development of LaTeX packages and utilities are more active (and decentralized). The LaTeX Companion, 2nd edition is the book matches your requirement when it published in 2004. Today you can still use it to learn the basic concepts in LaTeX2e format and how to config each part of a document, or waiting for its third edition which is still under preparation. May 15 '20 at 3:32
  • @Frank For an intro to LaTeX2e format and the standard document classes, take a look at latexref.xyz. May 15 '20 at 3:34
  • 1
    In my answer to the question How to prevent reference to enumeration inside new environment? I tried to explain the mechanisms that underlie cross-referencing. With hyperref the data-structure of cross-referencing-labels contains one element which delivers the name of the destination for hyperlinking. That name usually is made up from the name and the value of the counter incremented via \refstepcounter as the last one before placing label{...}. \autoref from this element retrieves info about which LaTeX-counter's value is referred to. May 16 '20 at 21:29

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.