MacResearch

This is meant to be a companion to something I just posted elsewhere. More details (and future updates) can be found there.

I just learned about the LaTeX package cleveref, which was in version 0.6 in June of 2007. When it reaches version 1.0, I think it will be a good replacement for the wonderful \autoref command included with the hyperref package. Below, I introduce the package and give some macros that make it a little nicer.

If you're not familiar with \autoref, it works like \ref, but it detects the type of the reference and then appends a name corresponding to that type. For example, \autoref{eq:one} will expand to "Equation 1". Additionally, the entire "Equation 1" gets hyperlinked to the equation. Similarly, \ref{eq:one} expands to "1" as usual but it also gets linked to the equation. If you don't want the links, you can add stars to both of those macros. That is, \ref*{eq:one} works just like the original unlinked \ref and \autoref*{eq:one} expands to "Equation 1" without the link.

Unfortunately, there is no \Autoref for references at the beginning of sentences. For example, you might want \autoref{eq:one} to expand to "Eq. 1" and \Autoref{eq:one} to expand to "Equation 1" (you don't want to put an abbreviation at the start of a sentence). Additionally, there is no direct way to get round brackets around equation (and item) numbers. Instead, you have to use varioref's \labelformat command (e.g., \labelformat{equation}{\textup{#1}}). Also, there is no support for plural references. Most importantly, there is no way to configure what gets linked. That is, you might want \autoref{eq:one} to expand to "Equation (1)", but you only want the "1" to be expanded.

The solution is to load hyperref and then load cleveref with the hyperref option turned on (e.g., \usepackage[hyperref]{cleveref}). cleveref gives you \cref, \crefrange, \Cref, and \Crefrange. You can also configure these in your preamble using macros like \crefformat and \Crefformat.

For example, by default, \cref{eq:one} expands to "Eq. (1)" where the "(1)" is hyperlinked. In fact, you can configure exactly what gets hyperlinked. You could make just the "1" hyperlinked or maybe just the "q" or the "E" (i.e., you define the position of the start of hyperlinking and the position of the end of hyperlinking).

This is pretty nice. However, there is no \cref* or anything similar. Therefore, I defined these:

\makeatletter

% \cref and \cref*
\let\origcref\cref
\newcommand{\crefstar}[1]
    {\begin{NoHyper}\origcref{#1}\end{NoHyper}}
\renewcommand{\cref}{\@ifstar{\crefstar}{\origcref}}

% \crefrange and \crefrange*
\let\origcrefrange\crefrange
\newcommand{\crefrangestar}[2]
    {\begin{NoHyper}\origcrefrange{#1}{#2}\end{NoHyper}}
\renewcommand{\crefrange}
    {\@ifstar{\crefrangestar}{\origcrefrange}}

% \Cref and \Cref*
\let\origCref\Cref
\newcommand{\Crefstar}[1]
    {\begin{NoHyper}\origCref{#1}\end{NoHyper}}
\renewcommand{\Cref}
    {\@ifstar{\Crefstar}{\origCref}}

% \Crefrange and \Crefrange*
\let\origCrefrange\Crefrange
\newcommand{\Crefrangestar}[2]
    {\begin{NoHyper}\origCrefrange{#1}{#2}\end{NoHyper}}
\renewcommand{\Crefrange}
    {\@ifstar{\Crefrangestar}{\origCrefrange}}

\makeatother

This temporarily turns off linking.

The only major downsides I see with cleveref is that it breaks some Springer journal document classes (e.g., svjour3 and svjour2 at least) and it has some silly default formats (e.g., it doesn't surround parentheses with \textup and it starts sentences with abbreviations). There's also a chance that it won't always work with item (e.g., from enumerate) references.

So it's something you should check out. It should speed up your typesetting and add some consistency to your documents.