16

I have sometimes been warned against using cleveref because it makes very fundamental changes of some of the basic LaTeX commands, like \label. Is this concern justified, and what are the issues of loading it? Are there good reasons not to use it?

  • 1
    The cleveref manual does mention some issues and how to get around them; but I would like advice from someone independent, too. – Gaussler Apr 22 '15 at 14:40
  • 4
    I am usually advising for using cleveref, its very useful for large documents. Most advanced packages make changes to basic commands (notably, hyperref) - but they work reasonably well together. And if you do run into issues, there is always tex.stackexchange.com. – Karalga Apr 22 '15 at 16:52
17

How cleveref works

Cleveref augments the \label command so that it writes some additional information into the .aux file. This part is not particularly invasive at all as it keeps the original implementation of \label intact and all standard functions that rely on it will still work (e.g. the normal \ref command). The second command that is augmented is \refstepcounter - again, the original functionality is being preserved and this should cause no issues.

Almost all functionality enhancing packages redefine the standard commands in some way (e.g. modifying lists, sections, equations...). All further functionality (i.e. the \cref command) is being handled in entirely separate functions.

Potential issues

Almost all issues come from the use of the \refstepcounter command - or rather the lack of its usage. All packages that do use it will work with cleveref out of the box. For those that do not, there are two options:

  1. Cleveref has a built-in support for this package, and everything will work fine.
  2. Cleveref does not have support, and using \cref{label} will produce incorrect output (incorrect meaning a missing label and potentially incorrect number). It will cause warnings but will still compile. You've now got two options:
    1. Use the normal \ref command. This will always work.
    2. Send an email to Toby Cubitt, and ask him to add support for the package.

If you want to get a feel for the issues that people have with cleveref, just browse https://tex.stackexchange.com/questions/tagged/cleveref!

Cleveref and breqn packages don't play nice together and Making refcheck work with cleveref are some typical issues that you may encounter.

Lastly, the documentation of cleveref has a section on poor mans cleveref - when you need to send your LaTeX source code to someone else, and they don't have cleveref installed. I think this may have been an issue in the early days of this package, but it has been a standard package for all the major tex distributions for probably 5 years now - so this is unlikely to be an issue.

Why you should use cleveref

Because it is clever and really simplifies your cross-referencing. I would like to point you to Difference between ref, varioref and cleveref. Decision for a thesis, Cross-reference packages: which to use, which conflict? and How to get more complete references.

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.