Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

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
  • varioref somehow works together with hyperref makes sometimes trouble with pagebreaks
  • cleveref is still in beta(?) and does the same like varioref

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

share|improve this question
5  
Related: tex.stackexchange.com/questions/36295/… –  Torbjørn T. Nov 16 '12 at 22:54
5  
Also, cleveref doesn't do the same as varioref. The former will try to figure what you're referencing, so \cref{fig:figure} can print e.g. Figure 1. varioref doesn't do this, but \vref{fig:figure} reference can print e.g. 1 on this page, or 1 on the preceding page. Only if the reference is more than two pages away, will the page number be printed, 1 on page 12. The two can be used together though, see the cleveref manual. –  Torbjørn T. Nov 16 '12 at 23:02
    
OK i thought the packages would compete each other –  Jonas Stein Nov 16 '12 at 23:12
1  
The cleveref package has been around for a number of years and can't be considered to be "in beta" at this point. –  Mico Nov 20 '12 at 20:23
1  
Someone should correct the Wikipedia article then where it is called "beta". –  Jonas Stein Nov 21 '12 at 1:24

1 Answer 1

up vote 38 down vote accepted

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.

share|improve this answer
    
The 3rd item reads Use Figure 1 on the preceding I guess cref and vref should switch in the example, right? –  Jonas Stein Nov 17 '12 at 14:07
    
I suggest to change the head to \crefname{table}{table}{tables} \Crefname{table}{Table}{Tables} \crefname{figure}{figure}{figures} \Crefname{figure}{Figure}{Figures} –  Jonas Stein Nov 17 '12 at 14:13
1  
@JonasStein that is a matter of personal preference, and precisely one of the reasons to use the cleveref :) however, since it's your question, I'll leave your edit :) –  cmhughes Nov 17 '12 at 16:22
1  
According to the hyperref README, the varioref package is not supported by the hyperref package due to various reasons. Doesn’t this apply any more? –  mhp Nov 17 '12 at 20:06
5  
@mhp - Loading the cleveref package (in addition to varioref and hyperref, of course) happens to eliminate the pesky little incompatibilities between varioref and hyperref. See tex.stackexchange.com/a/51640/5001 for more information on this. –  Mico Nov 20 '12 at 20:22

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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