Difference between ref, varioref and cleveref. Decision for a thesis

Question

How can one make a quick decision what the best "ref" for a thesis in pdflatex with hyperref is?

After a few hours reading I do not know more than

• ref is used by everyone who does not know about the other ~ref and works stable
• \vref varioref somehow works together with hyperref makes sometimes trouble with pagebreaks
• \cref in cleveref is still in beta(?) (edit: not in beta any more) and does the same like varioref

What are the essential questions that I have to ask myself to find out which method fits best?

Answer 1

You can certainly load both the varioref and the cleveref with hyperref provided that you load them in the following order

\usepackage{varioref}
\usepackage{hyperref}
\usepackage{cleveref}

They all play very nicely together.

The varioref and cleveref weren't around when I did my thesis, but I'm working on a multi-chapter document at the moment in which I'm using both. Here is what I have found to be a good workflow:

• at a minimum, use \cref and friends (from cleveref) in favour of \ref. This means that, for example, you never have to worry about if you have to capitalize Figure or figure when referencing a figure; instead of saying Figure \ref{fig:myfig} you just use \cref{fig:myfig}. Maybe you'll change your mind and end up using fig.; in which case you can make the change globally using \crefname and \Crefname
• use \vref and friends (from varioref) to refer to objects 'far away' from the current position in the text; my rule for the moment is to use \vref when referring to something in a different section. Some might say that this isn't very robust, but if the object you are referring to moves closer, \vref will still work fine. If you load cleveref then \vref becomes clever too, so you simply write \vref{fig:myfig}, not Figure \vref{fig:myfig}

The problems you describe with varioref occur if you allow hyperlinks to break, and the reference happens to break across a page that changes the reference from something like 'this page' to 'the next page'. In such a case, you'll have to tweak things manually- if you're using the work flow I've described above and only using \vref for 'far away' references and \cref for everything else, then this won't be an issue.

Here's a MWE to illustrate some of the features:

\documentclass{report}
\usepackage{varioref}       
\usepackage{hyperref}      
\usepackage{cleveref}     

% each of the following has two versions
%   \crefname{environmentname}{singular}{plural}, to be used mid-sentence
%   \Crefname{environmentname}{singular}{plural}, to be used at the beginning of a sentence
\crefname{table}{table}{tables}
\Crefname{table}{Table}{Tables}
\crefname{figure}{figure}{figures}
\Crefname{figure}{Figure}{Figures}
\begin{document}

\begin{figure}[!htb]
  \centering
  \rule{20pt}{20pt}
  \caption{My figure}
  \label{fig:myfig}
\end{figure}

\clearpage
\begin{itemize}
  \item Use \cref{fig:myfig} mid sentence.
  \item \Cref{fig:myfig} is appropriate for the beginning of a sentence.
  \item Use \vref{fig:myfig} mid sentence, note that it has become `clever'.
  \item \Vref{fig:myfig} is appropriate for the beginning of a sentence.
\end{itemize}
\end{document}

EDIT following comments

Quoting the hyperref README,

There are too many problems with varioref. Nobody has time to sort them out. Therefore this package is now unsupported.

In fact, as noted by @Mico in Lost labels using intertext with varioref and hyperref, loading the cleveref package in addition to varioref and hyperref seems to eliminate a lot of the problems, as cleveref redefines \vref and friends to make them clever.