Download Cleveref latex package and more Thesis Physics in PDF only on Docsity!
The cleveref package
Toby Cubitt
toby-cleveref@dr-qubit.org
Abstract The cleveref package enhances LATEX’s cross-referencing features, allowing the format of cross-references to be determined automatically ac- cording to the “type” of cross-reference (equation, section, etc.) and the context in which the cross-reference is used. The formatting for each cross- reference type can be fully customised in the preamble of your document. In addition, cleveref can typeset cross-references to lists of multiple la- bels, automatically formatting them according to their types, sorting them, and compressing sequences of numerically consecutive labels. Again, the multiple-reference formatting is fully customisable. Normally, the latest version of the cleveref package is available via CTAN. Occasionally, slightly newer “pre-release” versions are available at www.dr-qubit.org/latex.php#cleveref a little before they make their way onto CTAN.
∗This document corresponds to cleveref 0.21.4, dated 2018/03/27.
Contents
- 1 Introduction
- 2 Usage
- 3 Comparison with Other Packages
- 4 Typesetting Cross-References
- 5 Sorting and Compressing
- 6 Overriding the Cross-Reference Type
- 7 Options that Modify the Cross-Reference Format
- 7.1 Capitalising All Cross-Reference Names
- 7.2 Including Names in Hyperlink Targets
- 7.3 Abbreviations in Cross-Reference Names
- 8 Customising the Cross-Reference Formats
- 8.1 Customising the Cross-Reference Components
- 8.1.1 Global Customisation
- 8.1.2 Customising Individual Cross-Reference Types
- 8.1.3 Automatic \newtheorem Definitions
- 8.2 Low-Level Customisation: Taking Full Control
- 8.2.1 Single Cross-References
- 8.2.2 Reference Ranges
- 8.2.3 Multiple Cross-References
- 8.2.4 Label Cross-References
- 9 Advanced Cross-Reference Formating
- 10 Language, babel and polyglossia support
- 11 The cleveref.cfg File
- 12 Poor Man’s cleveref
- 13 Interaction with Other Packages
- 14 Known Bugs, Non-Bugs, and Possible Improvements
- 14.1 Non-Bugs
- 14.2 Known Bugs and Work-Arounds
- 14.3 Possible New Features and Improvements
- 15 Thanks
2 Usage
The cleveref package is loaded in the usual way, by putting the line
\usepackage{cleveref}
in your document’s preamble. However, care must be taken when using cleveref in conjunction with other packages that modify LATEX’s referencing system (see Section 13). Basically, cleveref must be loaded last. If you just want to get going quickly with cleveref, and come back later to read up on all the features it provides in more detail, here’s what you need to do. Wherever you would previously have used \ref, use \cref in- stead. (Except at the beginning of a sentence, where you should use \Cref.) You no longer need to put the name of the thing you’re referencing in front of the \cref command, because cleveref will sort that out for you: i.e. use \cref{eq1} instead of eq.~(\ref{eq1}). If you want to refer to a range of labels, use the \crefrange command: \crefrange{eq1}{eq5} produces eqs.~(1) to~(5). If you want to refer to multiple things at once, you can sim- ply throw them all into one cross-reference and leave cleveref to sort it out: e.g. \cref{eq2,eq1,eq3,eq5,thm2,def1} produces eqs.~(1) to~(3) and~(5), theorem~5, and definition~1. Finally, if you want a page reference, use \cpageref (and don’t write “page” in front), if you want a page range, use \cpagerefrange, and if you want to refer to multiple pages, simply throw them all into a single \cpageref. Just as with \cref (above), cleveref will sort it all out for you automaticaly. Cleveref supports a number of languages other than English, and also sup- ports the babel and polyglossia packages for those languages. Either pass the desired language as an option to cleveref, or pass it as a global option to \documentclass. Note that if you’re writing in a language in which nouns decline, the \cref and \cpageref commands may be less useful, as they always produce the cross-reference name in the nominative case.^2 In such languages, you may instead prefer to use the \labelcref and \labelcpageref commands. Unlike \cref and \cpageref, these don’t produce the name in front of the cross- reference, so you must supply it (in the appropriate case) yourself. But they do still cope with multi-references, so you still gain some benefit from using cleveref.
3 Comparison with Other Packages
Given how useful automated cross-reference typesetting is, there are naturally a number of other LATEX packages with similar goals to cleveref, most notably varioref, fancyref, hyperref’s \autoref command, and (for theorem-like en- vironments) ntheorem with the thref option. (There are many others, but these
(^2) Providing separate variants of the cleveref commands for each noun case quickly becomes more cumbersome than just typing the cross-reference name by hand. Trying to determine the appropriate case automatically would be tantamount to solving the full natural-language processing problem in cleveref. Check back in a century or so for this feature.
come closest to providing similar features to cleveref.) However, all have certain deficiencies which cleveref attempts to overcome. The fancyref package doesn’t automatically determine the type of thing being referred to. Instead, it relies on you adhering to a naming convention for labels. This is usually a good idea in any case, but it can occasionally be inconvenient. For example, if you change a theorem into a lemma, you have to change the label name, and therefore also all cross-references to it. So with fancyref, you will at times be back to searching and replacing label names throughout your document. Not to mention missing out on all the other cleveref features, such as automatic sorting and compressing of consecutive references, ntheorem and amsthm support, precise control over hyperlinks, etc. The enhanced referencing feature provided by the varioref package’s \labelformat command decides how to format cross-references when the label is defined, rather than when it is referenced. Often this isn’t a problem. But it makes it impossible to format cross-references according to the context in which they are referenced, which can sometimes be very useful. For example, you may want cross-references at the beginning of a sentence formatted differently to cross- references in the middle of a sentence. E.g. you may want to use the abbrevi- ation “eq.”, but revert to “Equation” at the beginning of sentences (words at the start of sentences shouldn’t be abbreviated in English). This is not possible with varioref. Perhaps even more significantly, varioref’s \labelformat im- plementation makes it impossible to typeset multiple references automatically; if you want to refer to equations eq1 through eq3, with varioref you are back to typing Eqs.~(\ref{eq1}) to~(\ref{eq3}) by hand. Not to mention missing out on all the other cleveref features. In fact, cleveref fully supports varioref, taking over responsibility for typesetting cross-references, whilst retaining (and even enhancing) all the varioref page-referencing magic. The hyperref package’s \autoref command typesets a name before a cross- reference, determined by the cross-reference type. This is less flexible than cleveref’s fully customisable cross-reference formatting, but, when combined with varioref, the two packages working together come pretty close. But sur- prisingly, even with hyperref, it is impossible to customise precisely which part of the cross-reference is made into a hyperlink in PDF documents; this is simple with cleveref. And it still remains impossible to typeset multiple references, have consecutive references sorted and compressed automatically, etc. The ntheorem package (with the thref option) does the right thing when it comes to how and when the format is defined... except that it only works for theorem-like environments. It is possible to use it for other environments, but only in a bastardized form, by manually supplying an optional argument to every \label command to specify the label type. Cleveref works equally well with any type of cross-reference, as well as fully supporting ntheorem. And again, cleveref provides a number of additional features over ntheorem, such as multi-references, automatic sorting and compressing of consecutive cross-references, control over the placement of hyperlinks, etc.
whether you might later change the section into a chapter, it might be useful to produce just the name “section” associated with the section’s label. If you later change the section into a chapter, the text will then automatically change to “this chapter”. The \namecref and \nameCref do exactly this:
\namecref{sec1}
is typeset as “section” (assuming sec1 labels a section). The \namecrefs and \nameCrefs commands produce the plural forms. The \lcnamecref and \lcnamecrefs commands force the reference name to lowercase, for use when the capitalise option is enabled (see Section 7.1). (When that option is set, \namecref produces an uppercase reference name.) Note that all these commands can only be passed a single reference name; they do not accept multi-references like \cref. (Passing multiple references to these commands would make little sense if the references had different types, and is redundant if they have the same type.) There is a slight pitfall that you should be aware of when using the \namecref commands. They get the reference name from the names defined for the label’s reference type using \crefname or \Crefname (see Section 8.1.2). The default reference formats provide these definitions. However, it is possible to customise reference formats using lower-level commands that do not create \crefname defi- nitions (see Section 8.2). If the \crefname definitions are missing for a particular reference type, \namecref and \nameCref will produce errors for labels of that type. You can fix the error by adding explicit \crefname definitions for these types. \labelcref Conversely, it is occasionally convenient to produce just the label part of a reference, without the cross-reference name. For example, this can be useful when writing in a language in which nouns decline. The \labelcref command does exactly this, and can also cope with multi-references, processing them just as \cref does. However, since it typesets a multi-reference without any name, all labels in a \labelcref multi-reference must be of the same type. The \labelcref command will typeset cross-reference labels using the default label format if no type-specific format is defined using \creflabelformat (see Sections 8.1.1 and 8.1.2). Note that, if you customise reference formats using the low-level commands, you may want to also explicitly define the \labelcref formats to match, using the \labelcrefformat etc. commands (see Section 8.2). \labelcpageref Similarly, \labelcpageref typesets the page numbers alone, without insert- ing “page” in front. Like \cpageref, it also handles multi-references. Like \labelcref, by default \labelcpageref typesets the page numbers using the default label format, customised using \crefdefaultlabelformat. If you want to define a separate format for \labelcpageref, use \creflabelformat to cus- tomise the label format for the “page” cross-reference type. (see Section 8.2).
5 Sorting and Compressing
When cleveref typesets lists of multiple cross-references or page-references, the default behaviour is to automatically sort the list and compress sequences of con- secutive cross-references or page numbers into a reference range. You can change this behaviour by supplying one of the following package options:
sort Sort lists of cross-references, but don’t compress consecutive references.
compress Compress sequences of consecutive references into a reference range, but don’t sort the list of cross-references.
nosort Neither sort lists of cross-references, nor compress consecutive references.
sort&compress Sort lists of cross-references, and compress sequences of consecu- tive references into a reference range (this is the default).
Occasionally, you may want to prevent a particular sequence of consecutive cross-references from being compressed to a reference range, without disabling this feature globally. To achieve this, you can separate the cross-references in the list by one or more empty references, at the point at which you want to prevent compression. For example,
\cref{eq1,eq2,eq3,,eq4}
will be typeset as
eqs. (1) to (3) and (4)
or
\cref{eq1,eq2,,eq3,eq4,eq5,,eq6,eq7,eq8}
will be typeset as
eqs. (1), (2), (3) to (5) and (6) to (8)
You can safely put an empty reference between cross-references that would never be compressed anyway; it will simply be ignored. If lists of cross-references are also being sorted (the default), it can be a little confusing to work out where the empty reference should go in order to prevent compression of a particular consecutive sequence. It’s best to think of the empty reference as being “attached” to the cross-reference preceding it. When the list is sorted, the empty reference will still appear after the same preceding reference, and will prevent it being compressed with any subsequent consecutive cross-references. In other words, an empty reference ensures that the preceding reference will appear explicitly in the final, typeset cross-reference:
\cref{eq3,,eq2,eq1,eq6,eq4,eq5}
will be typeset as
eqs. (1) to (3) and (4) to (6)
\usepackage{aliascnt} \usepackage{cleveref} \newaliascnt{lemma}{theorem} \newtheorem{lemma}[lemma]{Lemma} \aliascntresetthe{lemma} \crefname{lemma}{lemma}{lemmas}
Note that aliascnt must be loaded before cleveref, and any \newaliascnt commands must come after cleveref has been loaded.
7 Options that Modify the Cross-Reference For-
mat
7.1 Capitalising All Cross-Reference Names
capitalise Many authors prefer to always capitalise cross-reference names, regardless of where they appear in the sentence, writing Theorem 1 and Equation 3 (as opposed to theorem 1 and equation 3). If you count yourself among this group, you can pass the capitalise option to the cleveref package (capitalize also works). All the default cross-reference formats will then have the first letter capitalised, as will the automatically generated \cref variants (see Sections 8.1.2 and 8.2). (However, if you explicitly define a \cref variant to not be capitalised, cleveref will still honour your definition. In other words, you’re responsible for defining the capitalisation correctly in your own format definitions.) You should still use the \Cref variants at the beginning of sentences, for one thing, because abbreviations should not be used at the beginning of a sentence,^5 and for another, in case you later change your mind and remove the capitalise option.
7.2 Including Names in Hyperlink Targets
nameinlink When using the hyperref package, cleveref automatically makes all cross- references into hyperlinks to the corresponding reference. By default, only the label itself forms part of the hyperlink target (i.e. the text you can click on to nav- igate to the cross-reference). The cross-reference name is not part of the hyperlink. By contrast, hyperref’s \autoref command does includes the name as part of the hyperlink. If you prefer to include the names in the hyperlinks when using cleveref, you can pass the nameinlink option to the cleveref package. (For even more control over the placement of the hyperlink target, use the commands for customising the cross-reference format. See Section 8.) However, use of this option is discouraged on stylistic grounds. Firstly, when producing PDF output hyperref by default surrounds hyperlinks with red boxes, which looks particularly ugly when the entire cross-reference name is surrounded by a red box (though this unfortunate default can be changed using hyperref (^5) At least in English; I’m not sure about other languages.
package options; see the hyperref documentation for details). Secondly, and more significantly, when using multi-references only the first reference in a group can include the cross-reference name as part of its hyperlink target, for obvious reasons. The hyperlink targets for the other references in the group will necessarily be just the labels. This makes for somewhat non-uniform typesetting of hyperlinks, with the first cross-reference in a multi-reference having a much larger hyperlink target than the others.
7.3 Abbreviations in Cross-Reference Names
noabbrev The default cross-reference names for some languages use common abbreviations for some of the names (e.g. in the default English format, \cref{eq1} will be typeset as eq.~(1)). Some authors may prefer to always use the full name, rather than an abbreviation (equation~(1) instead of eq.~(1)). To disable all use of abbreviations in the default cross-reference names, pass the noabbrev option to the cleveref package. Note that the default names never use abbreviations for the start-of-sentence variants (\Cref etc.) This is because in good written English (and likely other languages too), abbreviations should never be used at the beginning of a sentence. Many of TEX’s default settings (e.g. page margins) are specifically chosen to en- courage good typesetting style. Cleveref tried to follow the same philosophy. If despite this you insist on using abbreviations at the start of sentences, you will need to customise the start-of-sentence formats yourself.
8 Customising the Cross-Reference Formats
The cleveref package allows you to take full control of the typesetting of cross- references, by allowing the formatting to be customised. Defaults appropriate for English documents are provided for the standard label types,^6 and support for a number of languages is provided via package options (see Section 10). But if you don’t like the defaults, or are writing in a language that is not supported yet,^7 or you need to refer to something for which no default format is defined, then you can take charge and define your own formats. If cleveref encounters a cross-reference to a type it does not know, it will produce a “reference type undefined” warning, and typeset the cross-reference as
?? \ref{〈label 〉}
i.e. the label counter preceded by a double question mark. The error message indicates the name of the unknown cross-reference type, which you will then prob- (^6) For any pedantic classics scholars out there: “lemmas” is recognised as a valid plural form of “lemma” in all current versions of the Oxford English Dictionary. “Lemmata” was last heard in a mathematical debate that took place in a pub just around the corner from Hadrian’s wall... a few years before the Romans pulled out of Britain. Cleveref might have “clever” in its name, but even that doesn’t make it pretentious enough to use “lemmata” for the plural of “lemma”. (^7) Any contributions of translations for missing languages are very welcome! See Section 14. for information on how to contribute translations.
It does not have to be an actual conjunction in the linguistic sense, e.g. it is perfectly reasonable to define it to be an endash “--”. \crefrangeconjunction is used directly between the start and end references in a reference range, without any additional space surrounding it, e.g. \crefrange{thm1}{thm2} is typeset as
theorems~\ref{thm1}\crefrangeconjunction\ref{thm2}
so you may or may not want to include surrounding space, depending on the formatting you desire. For example,
\newcommand{\crefrangeconjunction}{ and~}
does require surrounding space, whereas
\newcommand{\crefrangeconjunction}{--}
does not. \crefrangepreconjunction There are two other “conjunction” commands available for customizing the \crefrangepostconjunction formatting for reference ranges. These are \crefrangepreconjunction and \crefrangepostconjunction, which insert text before the first label defining the range, and after the second label, respectively. For example, when these commands are defined, \crefrange{thm1}{thm2} is typeset as
theorems~\crefrangepreconjunction\ref{thm1} Â \crefrangeconjunction\ref{thm2}\crefrangepostconjunction
These commands are not used in the default English format definitions, but they are needed in some languages to correctly express a range. For exam- ple, the Italian format defines \crefrangepreconjunction to be “da”, so that \crefrange{thm1}{thm2} produces
teorema da~\ref{thm1} a~\ref{thm2}
\crefpairconjunction The conjunctions used in lists of multiple cross-references can be customised by \crefmiddleconjunction \creflastconjunction
defining the commands \crefpairconjunction, \crefmiddleconjunction and \creflastconjunction:
\newcommand{\crefpairconjunction}{〈conjunction〉} \newcommand{\crefmiddleconjunction}{〈conjunction〉} \newcommand{\creflastconjunction}{〈conjunction〉}
\crefpairconjunction is used when there are only two cross-references in the list, \creflastconjunction is used between the penultimate and final cross- reference in a list of more than two, and \crefmiddleconjunction is used be- tween all the others. Again, they do not have to be conjunctions in the lin- guistic sense, and the same considerations about surrounding space apply as in the case of \crefrangeconjunction. For example, the default definition of \crefmiddleconjunction is:
\newcommand{\crefmiddleconjunction}{, }
\crefpairgroupconjunction By default, the conjunctions used to separate sub-lists of different cross- \crefmiddlegroupconjunction \creflastgroupconjunction
reference types in a multi-reference are identical to those used to separate cross- references of the same type.^8 You can override this by defining the conjunc- tion commands \crefpairgroupconjunction, \crefmiddlegroupconjunction and \creflastgroupconjunction. For example,
\cref{eq1,eq2,eq3,thm1,thm2,fig1,thm3}
is typeset as
eqs. (1)\crefrangeconjunction(3)\crefmiddlegroupconjunction theorems 1\crefpairconjunction 2 \crefmiddlegroupconjunction fig. 1\creflastgroupconjunction{}theorem 3
8.1.2 Customising Individual Cross-Reference Types
\crefname The cross-reference name for a given cross-reference type is customised using the \Crefname \crefname and \Crefname commands:
\crefname{〈type〉}{〈singular 〉}{〈plural 〉} \Crefname{〈type〉}{〈singular 〉}{〈plural 〉}
used by the \cref and \Cref commands, respectively. You must supply both 〈singular 〉 and 〈plural 〉 forms of the name. If the corresponding \Crefname is un- defined when \crefname is called, it will automatically define \Crefname to be a capitalised version of \crefname, using \MakeUppercase. Conversely, if the corre- sponding \crefname is undefined when \Crefname is called, it will automatically define \crefname to be a lower-case version of \Crefname, using \MakeLowercase. Obviously, this will only work properly if the names begin with a letter. If the first letter is a special character construct, such as an accented character, you will need to surround it by braces. If the first thing in the name is not a letter at all (e.g. if it is a LATEX command), you must define both capitalisation variants explicitly. Otherwise you will get strange and fatal errors when processing the document. The cross-reference 〈type〉 is usually the name of the counter for the environ- ment (equation, chapter, section, etc.). The exceptions are appendices, labels whose type has been overridden explicitly by supplying an optional argument (see Section 6), and theorem-like environments when the ntheorem of amsthm pack- ages are loaded, for which 〈type〉 should instead be the environment name (lemma, corollary, definition, etc.) even when different environments are part of the same numbering sequence. (ntheorem and amsthm provide extra information about the environment when different theorem-like environments share a common counter, which cleveref makes use of to distinguish between them automatically.) In the case of appendices, the 〈type〉 is “appendix” for the top-level sectioning command (^8) More accurately, if you redefine \crefpairconjunction etc. in your preamble, \crefpairgroupconjunction etc. are automatically redefined so that they match. (In some languages, the default definition of \creflastgroupconjunction has an additional comma lacking in \creflastconjunction.)
vironments provides enough information to deduce a reasonable cross-reference name for the new environment. So cleveref automatically defines an appro- priate cross-reference name for new theorem-like environments. This automatic definition is only used if no default definition is provided by cleveref itself, and if no \crefname or \Crefname definition is given explicitly (see Section 8.1.2). The caveat with this automatic definition is that, although \newtheorem es- sentially provides the singular form of the cross-reference name, it doesn’t provide the plural form. And there is no reliable way of constructing the plural form from the singular.^9 Therefore, if the plural form is ever required, cleveref will produce a “reference type undefined” warning, and typeset the cross-reference where the plural form is required as:
?? \ref{〈label 〉}...
In this case, you will have to provide an explicit \crefname or \Crefname definition yourself, to define the plural form as well as the singular form. Note that this has nothing whatsoever to do with automatically determining the type of theorem-like environment in a cross-reference! For that, you need to load either the ntheorem or the amsthm package. See Section 14.1 for more details.
8.2 Low-Level Customisation: Taking Full Control
If you need more precise control over the cross-reference format than is possible by customising the individual components, then you can take full control of the format for any given type, overriding the component-derived format entirely. The formats for single cross-references, reference ranges and multi-references are cus- tomised separately. If you only customise some of these, the other formats will be constructed from components, as usual. Note that when deciding which cross-references should be grouped together for sorting and/or compressing, cleveref does something slightly more complicated than simply checking whether the reference types match. In fact, it checks whether the reference formats match.^10 This will always be the case for cross-references of the same type. But it could also be the case for cross-references that have different types, if the cross-reference formats happen to be identical. The reason for doing this is to allow cross-references to e.g. sections and subsec- tions to be grouped together if they have identical formats. The default formats for the sectioning commands, figures and subfigures, tables and subtables, and enumerated lists are set up in this way. If you change any of them using the low- level customisation commands, but still want them to be grouped together, then you must ensure that the formats are identical. (It is not sufficient for the formats to produce identical typeset text; the format definitions must contain identical LATEX code.)
(^9) If you’re a native English-speaker, you might think that just adding an ‘s’ would work, though a moment’s thought will provide examples of words where this will fail. If you’re a non-English speaker, it probably won’t even occur to you to claim that plurals can reliably be constructed automatically! (^10) To be precise, cleveref checks whether the \crefformat definitions match.
Note that if you use the low-level customisation commands, you might still want to provide \crefname and \Crefname definitions too, so that the \namecref commands will work (see Section 4).
8.2.1 Single Cross-References
\crefformat Cross-reference formats for single cross-references are defined or redefined using \Crefformat the \crefformat and \Crefformat commands, which are used by the \cref and \Cref commands respectively. These take two arguments: the cross-reference type, and the formatting code: \crefformat{〈type〉}{〈format〉} \Crefformat{〈type〉}{〈format〉}
The 〈type〉 is usually the name of the counter, except for labels whose type has been overridden explicitly (see Section 6), theorem-like environments when the ntheorem or amsthm package is loaded, in which case it is the environment name, and appendices. For the latter, the 〈type〉 is “appendix” for the top-level section- ing command (\chapter or \section, depending on the document class), “subap- pendix” for the sectioning command one level below (\section or subsection), “subsubappendix” for the next level of sectioning command, etc. As in the case of the \crefname and \Crefname commands, if the corre- sponding \Crefformat is undefined when \crefformat is called, it will de- fine the \Crefformat to produce a capitalised version of \crefformat, using \MakeUppercase. Conversely, if the corresponding \crefformat is undefined when \Crefformat is called, it will define the \crefformat to produce a lower- case version of \Crefformat, using \MakeLowercase. Obviously, this will only work properly if the format starts with a letter, and letter constructs (such as accented letter constructs) must be surrounded by braces (see Section 8.1.1). The 〈format〉 argument can be any valid LATEX code, though you will need to \protect fragile commands. It should contain three arguments, #1, # and #3. The first argument is the formatted version of the label counter (e.g. \theequation). The other two are used to mark the beginning and end of the part of the cross-reference that forms the hyperlink when the hyperref package is used, and must appear in that order (see Section 13). As an example, \crefformat{equation}{Eq.~(#2#1#3)}
will typeset equation references as Eq. (〈counter 〉)
with the counter (excluding the parentheses) forming the hyperlink. Note that the hyperlink arguments are not letters, so if #2 appears at the beginning of 〈format〉, cleveref will not be able to automatically define the other capitalisation variant automatically using \MakeUppercase or \MakeLowercase. In this case, you will have to define both variants separately. For example, if you wanted the “Eq.” to be part of the hyperlink, you would have to explicitly define:
The 〈type〉 is, as ever, the counter name (except for appendices, explicitly overridden label types, and theorem-like environments when the ntheorem or amsthm packages are loaded). The same considerations apply to the format- ting arguments 〈first〉, 〈second 〉, 〈middle〉 and 〈last〉 as for the 〈format〉 ar- gument of \crefformat or \crefrangeformat, including the meaning of the arguments that should appear in the formatting code (#1, #2 and #3 for \crefmultiformat and \Crefmultiformat, #1–#6 for \crefrangemultiformat and \Crefrangemultiformat). However, when the corresponding other-capitalisation variant is automatically defined, only the first letter of the 〈first〉 argument is upper- or lower-cased; the other arguments are defined to be identical for both variants. Be careful to get the spaces at the beginning and end of the formatting code correct: the 〈first〉 and 〈second 〉, or 〈first〉, 〈middle〉 and 〈last〉, LATEX code snip- pets are typeset one after another in a multi-reference, with no space separating them. You may or may not want spaces at the beginning or end of the format- ting code, depending on the formatting you desire. For example, in the default equation format:
\crefmultiformat{equation}{eqs.~(#2#1#3)}% { and~(#2#1#3)}{, (#2#1#3)}{ and~(#2#1#3)}
the 〈middle〉 argument should not have a space at the beginning, whereas the 〈second 〉 and 〈last〉 arguments should have a space.
8.2.4 Label Cross-References
If you define the format for a particular cross-reference type using the low- level customisation commands, and still want to use the \labelcref command to produce just the label part of the cross-reference, then you must also de- fine the appropriate \labelcref formats for that type. This is done using the \labelcrefformat, \labelcrefrangeformat, \labelcrefmultiformat and \labelcrefrangemultiformat commands. Their syntax is identical to that of the corresponding \crefformat, \crefrangmeformat, \crefmultiformat or \crefrangemultiformat command. Typically, the \labelcref formats should be defined identically to the standard \cref formats, except for the 〈first〉 part, which should leave off the cross-reference name. This is not enforced, however.
9 Advanced Cross-Reference Formating
When you define a custom cross-reference format using \creflabelformat, \creformat et al. (see Section 8), you’re not merely defining a pattern with place- holders to be filled in. You’re really defining the body of a LaTeX macro, with the formatted labels as arguments. This is a very powerful tool. It means that the only limit on how you can process the labels is your ability to code it in TEX.^11 Which potentially allows for very sophisticated cross-reference formatting. (^11) Since TEX is Turing-complete, that means you can do anything you like short of solving the Halting Problem.
One example of this is removing common prefixes from reference ranges. E.g. if you’re numbering equations within sections, and eq1, eq2 and eq3 are all in the section 1.2, then you might want to typeset \cref{eq1,eq2,eq3} as “eqs. (1.2.1– 3)” instead of “eqs. (1.2.1) to (1.2.3)”. Similarly, if eq1a, eq1b and eq1c are amsmath subequations, you might want to typeset \cref{eq1a,eq1b,eq1c} as “eqs. (1a–c)” instead of “eqs. (1a) to (1c)”. Cleveref provides a useful utility macro for this: \crefstripprefix, which takes two strings as arguments, and returns the second one with any common prefix stripped off. (However, the very last run of digits or letters in the string is retained in its entirety, even if it has a part in common.) With the help of this macro, you can produce the desired reference-range formatting with:
\crefrangelabelformat{equation}% {(#3#1#4--#5\crefstripprefix{#1}{#2}#6)} \crefrangelabelformat{subequation}% {(#3#1#4--#5\crefstripprefix{#1}{#2}#6)} Similarly, stripping prefixes from multi-references so that e.g. \cref{fig1a,fig1b,fig1d} is typeset as “figs. 1a, b and d” instead of “figs. 1a, 1b and 1d” can be achieved by passing the prefix from the first component to the others in an auxiliary macro (called \crefstripprefixinfo here):
\crefmultiformat{figure}% {\edef\crefstripprefixinfo{#1}figs.~#2#1#3}% { and~#2\crefstripprefix{\crefstripprefixinfo}{#1}#3}% {, #2\crefstripprefix{\crefstripprefixinfo}{#1}#3}% {, and~#2\crefstripprefix{\crefstripprefixinfo}{#1}#3}
10 Language, babel and polyglossia support
Cleveref supports different languages via package options, in the usual way, though not all languages are supported yet.^12 Basic cleveref language sup- port will work even if babel or polyglossia are not loaded. The only exception currently is Catalan (which requires the \lgem command provided by these pack- ages). The babel package is fully supported if it is loaded, allowing you to change the language used in cross-references using the babel language switching commands, such as \selectlanguage and \foreignlanguage. Similar support is provided for the polyglossia babel replacement package. Note that when using babel, you still need to tell cleveref which language it should use for the default cross-reference formats. It is not sufficient to pass the language option to babel alone. You must also either pass the language options to cleveref package directly when loading it:
\usepackage[〈language〉]{cleveref} (^12) Contributions of translations for missing languages are very welcome! See Section 14.3 for information on how to contribute translations.
