diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/cleveref')
| -rw-r--r-- | Master/texmf-dist/source/latex/cleveref/cleveref.dtx | 1297 |
1 files changed, 653 insertions, 644 deletions
diff --git a/Master/texmf-dist/source/latex/cleveref/cleveref.dtx b/Master/texmf-dist/source/latex/cleveref/cleveref.dtx index 6cad24c2f7a..28e8004b3e5 100644 --- a/Master/texmf-dist/source/latex/cleveref/cleveref.dtx +++ b/Master/texmf-dist/source/latex/cleveref/cleveref.dtx @@ -12,16 +12,16 @@ %% %% http://www.latex-project.org/lppl.txt %% -%% and version 1.2 or later is part of all distributions of LaTeX +%% and version 1.2 or later is part of all distributions of LaTeX %% version 1999/12/01 or later. -% +% % Please send bugreports and suggestions to toby-cleveref@dr-qubit.org % \fi % % \iffalse %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01] %<package>\ProvidesPackage{cleveref} -%<package> [2007/21/11 v0.11 Automatic cross-reference formatting] +%<package> [2009/11/02 v0.12 Automatic cross-reference formatting] % %<*driver> \documentclass{ltxdoc} @@ -46,7 +46,7 @@ }} \def\endpackeddescr{\end{list}} %% Commands for referring to code lines -\def\codelabel#1{\@bsphack +\def\codelabel#1{\@bsphack \protected@write\@auxout{}{\string\newlabel{#1}{{\number\the \c@CodelineNo}{\thepage}}}\@esphack} \newcounter{tmpcount} @@ -60,7 +60,7 @@ %</driver> % \fi % -% \CheckSum{3387} +% \CheckSum{3407} %% \CharacterTable %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z @@ -83,7 +83,8 @@ % \changes{v0.4}{2007/26/05}{Renamed "cleveref" -- first public release} % \changes{v0.5}{2007/31/05}{Added poorman option} % \changes{v0.6}{2007/11/06}{Poorman no longer writes extra .tmp file} -% \changes{v0.7}{2007/21/06}{Allow prevention of reference range collapsing} +% \changes{v0.7}{2007/21/06}{Allow prevention of reference range +% collapsing} % \changes{v0.8}{2007/10/07}% % {Made referencing commands robust, improved default formats, made % starred versions of referencing commands for hyperref, allowed @@ -102,12 +103,14 @@ % amsmath is enabled automatically if those packages are loaded.} % \changes{v0.11}{2007/21/11}{Made referencing aware of appendices.} % \changes{v0.11.1}{2007/29/11}{Bug fixes.} +% \changes{v0.12}{2009/11/02}{Restore working \\ref* when hyperref is +% loaded -- first release mirrored on www.dr-qubit.org} % % % \GetFileInfo{cleveref.sty} -% -% \def\fileversion{0.11} -% \def\filedate{21/11/2007} +% +% \def\fileversion{0.12} +% \def\filedate{11/02/2009} % % \title{The \package{cleveref} package\thanks{This document % corresponds to \textsf{cleveref}~\fileversion, dated @@ -118,125 +121,120 @@ % \maketitle % % \begin{abstract} -% The \package{cleveref} package enhances \LaTeX{}'s -% cross-referencing features, allowing the format of references to -% be determined automatically according to the type of reference -% (equation, section, etc.) and the context in which the reference -% is used. The formatting for each reference type can be fully -% customised in the preamble of your document. In addition, -% \package{cleveref} can typeset references to lists of multiple -% labels, automatically formatting them according to their type, and -% collapsing sequences of numerically consecutive labels to a -% reference range. Again, the multiple-reference formatting is fully -% customisable. +% The \package{cleveref} package enhances \LaTeX{}'s cross-referencing +% features, allowing the format of references to be determined +% automatically according to the type of reference (equation, section, +% etc.) and the context in which the reference is used. The formatting +% for each reference type can be fully customised in the preamble of +% your document. In addition, \package{cleveref} can typeset references +% to lists of multiple labels, automatically formatting them according +% to their type, and collapsing sequences of numerically consecutive +% labels to a reference range. Again, the multiple-reference formatting +% is fully customisable. % \end{abstract} % % % % \section{Introduction} -% When ``clever'' is used in the name of a computer program, it -% usually signifies that the programmer is overly smug about his -% achievements! On the other hand, at the heart of the \LaTeX{} -% philosophy is the idea that it is clever to delegate as much of the -% typesetting as possible to the computer, in order to achieve a -% beautiful, but above all consistent, visual appearance. -% +% When ``clever'' is used in the name of a computer program, it usually +% signifies that the programmer is overly smug about his achievements! On +% the other hand, at the heart of the \LaTeX{} philosophy is the idea +% that it is clever to delegate as much of the typesetting as possible to +% the computer, in order to achieve a beautiful, but above all +% consistent, visual appearance. +% % Both these points of view are probably valid when it comes to the % \package{cleveref} package. It's goals are two-fold: to use the -% information that \LaTeX{} inherently has about labels as -% intelligently as possible in order to type-set references to them -% (clever processing); and to enable you to produce an attractive, -% consistent formatting of references throughout your document, with -% the minimum of effort (you'd be clever to use it!). +% information that \LaTeX{} inherently has about labels as intelligently +% as possible in order to type-set references to them (clever +% processing); and to enable you to produce an attractive, consistent +% formatting of references throughout your document, with the minimum of +% effort (you'd be clever to use it!). % % The \package{cleveref} package enhances \LaTeX{}'s cross-referencing % facilities by allowing references to be formatted automatically % according to the type of object they refer to (chapter, section, % equation, theorem, etc.) and the context in which the reference is -% used. It can also automatically format references to multiple -% labels, automatically collapsing references to consecutive labels -% into a reference range, and all kinds of other clever wizardry. -% -% In standard \LaTeX{}, you have almost certainly found yourself -% writing things like |Eq.~(\ref{eq1})| and -% |Theorems~\ref{thm1} to~\ref{thm2}| over and over again. Tedium -% isn't the only downside to this. What happens if you later decide -% you want equation references to be typeset as |Equation~\ref{eq1}| -% instead? What happens if you decide to change the theorem labelled -% |thm1| into a lemma? You have to search through the entire \LaTeX{} -% source of your document, modifying all references to equations, or -% changing all references to |thm1|. +% used. It can also automatically format references to multiple labels, +% automatically collapsing references to consecutive labels into a +% reference range, and all kinds of other clever wizardry. +% +% In standard \LaTeX{}, you have almost certainly found yourself writing +% things like |Eq.~(\ref{eq1})| and |Theorems~\ref{thm1} to~\ref{thm2}| +% over and over again. Tedium isn't the only downside to this. What +% happens if you later decide you want equation references to be typeset +% as |Equation~\ref{eq1}| instead? What happens if you decide to change +% the theorem labelled |thm1| into a lemma? You have to search through +% the entire \LaTeX{} source of your document, modifying all references +% to equations, or changing all references to |thm1|. % % The \package{cleveref} package allows you to define the format for % references once-and-for-all in the preamble of your document. If you -% later decide to change the format of equation references, you only -% have to change one preamble definition. If you xchange a theorem -% into a lemma, you don't need to change any references at all, -% because \package{cleveref} will automatically typeset references to -% it using the appropriate formatting. This makes it far easier to -% typeset references uniformly across your whole document, as well as -% avoiding repetitively typing the same text for each and every -% reference. -% -% There are a number of other packages with similar goals, most -% notably \package{varioref}, \package{fancyref}, \package{hyperref}'s -% |\autoref| command, and (for theorem-like environments) -% \package{ntheorem} (with the \option{thref} option). (There are many -% others, but these come closest to providing similar features to -% \package{cleveref}.) However, all have certain deficiencies which -% \package{cleveref} attempts to overcome. -% -% The \package{fancyref} package doesn't automatically determine the -% type of object 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 be inconvenient. For example, if you change a -% theorem into a lemma, you have to change the label name, and -% therefore also all references to it. So you are back to searching -% and replacing through the entire document. +% later decide to change the format of equation references, you only have +% to change one preamble definition. If you xchange a theorem into a +% lemma, you don't need to change any references at all, because +% \package{cleveref} will automatically typeset references to it using +% the appropriate formatting. This makes it far easier to typeset +% references uniformly across your whole document, as well as avoiding +% repetitively typing the same text for each and every reference. +% +% There are a number of other packages with similar goals, most notably +% \package{varioref}, \package{fancyref}, \package{hyperref}'s |\autoref| +% command, and (for theorem-like environments) \package{ntheorem} (with +% the \option{thref} option). (There are many others, but these come +% closest to providing similar features to \package{cleveref}.) However, +% all have certain deficiencies which \package{cleveref} attempts to +% overcome. +% +% The \package{fancyref} package doesn't automatically determine the type +% of object 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 be inconvenient. For example, if you change a theorem into a +% lemma, you have to change the label name, and therefore also all +% references to it. So you are back to searching and replacing through +% the entire document. % % The enhanced referencing feature provided by the \package{varioref} % package decides how to format references when the label is % \emph{defined}, rather than when it is \emph{referenced}. Often this % isn't a problem. But it makes it impossible to format references -% differently according the context in which they are referenced, -% which can sometimes be very useful. For example, if you want -% references at the beginning of a sentence formatted any other way -% than by capitalising the first letter of the reference text, it is -% impossible using \package{varioref}. Perhaps even more -% significantly, it makes it impossible to typeset multiple references -% automatically; you are back typesetting -% |Eqs.~(\ref{eq1}) and~(\ref{eq2})| or -% |Eqs.~(\ref{eq1})--(\ref{eq3})| by hand. Not to mention missing out -% on automatic collapsing of consecutive references, -% \package{ntheorem} support, etc. +% differently according the context in which they are referenced, which +% can sometimes be very useful. For example, if you want references at +% the beginning of a sentence formatted any other way than by +% capitalising the first letter of the reference text, it is impossible +% using \package{varioref}. Perhaps even more significantly, it makes it +% impossible to typeset multiple references automatically; you are back +% typesetting |Eqs.~(\ref{eq1}) and~(\ref{eq2})| or +% |Eqs.~(\ref{eq1})--(\ref{eq3})| by hand. Not to mention missing out on +% automatic collapsing of consecutive references, \package{ntheorem} +% support, etc. % % The \package{hyperref} package's |\autoref| command typesets a name % before a reference, determined by the reference type. This is less % flexible than \package{cleveref}'s fully customisable reference -% formatting but, when combined with \package{varioref}, the two -% packages working together come close. However, even with -% \package{hyperref}, it is impossible to customise precisely which -% part of the reference is made into a hyper-link in PDF documents; -% this is very easy with \package{cleveref}. And it still remains -% impossible to typeset multiple references, have consecutive -% references collapsed automatically, etc. +% formatting but, when combined with \package{varioref}, the two packages +% working together come close. However, even with \package{hyperref}, it +% is impossible to customise precisely which part of the reference is +% made into a hyper-link in PDF documents; this is very easy with +% \package{cleveref}. And it still remains impossible to typeset multiple +% references, have consecutive references collapsed automatically, etc. % % The \package{ntheorem} package (with the \option{thref} option) does % things right\ldots 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 |\label| commands that specifies the label -% type. \package{cleveref} works equally well when referencing any -% type of object, as well as fully supporting \package{ntheorem}. And -% again, \package{cleveref} provides a number additional features, -% such as multiple references, automatic collapsing of reference -% ranges, control over the placement of hyper-links, etc. +% environments. It is possible to use it for other environments, but only +% in a bastardized form, by manually supplying an optional argument to +% |\label| commands that specifies the label type. \package{cleveref} +% works equally well when referencing any type of object, as well as +% fully supporting \package{ntheorem}. And again, \package{cleveref} +% provides a number additional features, such as multiple references, +% automatic collapsing of reference ranges, control over the placement of +% hyper-links, etc. % % % % \section{Usage} -% The \package{cleveref} package is loaded in the usual way, by -% putting the line +% The \package{cleveref} package is loaded in the usual way, by putting +% the line % \begin{quote} % |\usepackage{cleveref}| % \end{quote} @@ -246,18 +244,18 @@ % \cref{sec:other_packages}). Basically, \package{cleveref} must be % loaded \emph{last}. % -% If you just want to get going quickly with \package{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| instead. (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 \package{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 |\crefrange|: |\crefrange{eq1}{eq5}| -% gives |eqs.~(1)--(5)|. Finally, if you want to refer to multiple -% things at once, you can now combine them all into one reference and -% leave \package{cleveref} to sort it out: e.g.\ +% If you just want to get going quickly with \package{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| instead. (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 +% \package{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 |\crefrange|: |\crefrange{eq1}{eq5}| gives +% |eqs.~(1)--(5)|. Finally, if you want to refer to multiple things at +% once, you can now combine them all into one reference and leave +% \package{cleveref} to sort it out: e.g.\ % |\cref{eq1,eq2,eq3,eq5,thm2,def1}| produces % |eqs.~(1)--(3) and~(5), theorem~5, and definition~1|. % @@ -266,35 +264,33 @@ % \label{sec:typesetting} % \DescribeMacro\cref % To automatically typeset a cross-reference according to the type of -% object referred to, simply refer to it using -% |\cref{|\meta{label}|}|. \package{cleveref} imposes just one extra -% restriction on the names of labels: they are no longer allowed to -% contain commas ``,''. These are instead used to typeset multiple -% references (see below). +% object referred to, simply refer to it using |\cref{|\meta{label}|}|. +% \package{cleveref} imposes just one extra restriction on the names of +% labels: they are no longer allowed to contain commas ``,''. These are +% instead used to typeset multiple references (see below). % % \DescribeMacro\Cref % As it is very difficult\footnote{Actually, very likely impossible!} % for \LaTeX{} to determine whether a cross-reference appears at the % beginning of a sentence or not, a capitalised version exists: -% |\Cref{|\meta{label}|}|. By default, this typesets the reference -% with the first letter capitalised. (Though the formatting of the -% |\cref| and |\Cref| forms can be fully and independently customised, -% see \cref{sec:customising}.) +% |\Cref{|\meta{label}|}|. By default, this typesets the reference with +% the first letter capitalised. (Though the formatting of the |\cref| and +% |\Cref| forms can be fully and independently customised, see +% \cref{sec:customising}.) % % \DescribeMacro\ref % \package{cleveref} does \emph{not} modify the standard |\ref| % command\footnote{This is not quite true. The original \cmd{\ref} % command no longer works when \package{cleveref} is loaded, so -% \package{cleveref} redefines it to recover the original -% behaviour.}, so you can still use it to typeset the formatted -% label counter alone, without any additional text or formatting. +% \package{cleveref} redefines it to recover the original behaviour.}, +% so you can still use it to typeset the formatted label counter alone, +% without any additional text or formatting. % % \DescribeMacro\crefrange % \DescribeMacro\Crefrange % To typeset a reference range, e.g. |Eqs.~(1.1)--(1.5)|, use % |\crefrange| or |\Crefrange| (depending on the capitalisation you -% require), which take the beginning and end of the range as -% arguments: +% require), which take the beginning and end of the range as arguments: % \begin{quote} % |\crefrange{|\meta{label1}|}{|\meta{label2}|}| % \end{quote} @@ -307,13 +303,12 @@ % \begin{quote} % |\cref{|\meta{label1}|,|\meta{label2}|,|\meta{label3}|,...}| % \end{quote} -% The references will be typeset in the order in which they appear in -% the list, and sequences of consecutive references will be collapsed -% to a reference range. It is up to you to put the labels in the order -% you require. This is especially significant if the labels refer to -% different types of object, or to consecutive sequences of -% labels. For example, if |eq*| are equation labels, and |thm*| are -% theorem labels, +% The references will be typeset in the order in which they appear in the +% list, and sequences of consecutive references will be collapsed to a +% reference range. It is up to you to put the labels in the order you +% require. This is especially significant if the labels refer to +% different types of object, or to consecutive sequences of labels. For +% example, if |eq*| are equation labels, and |thm*| are theorem labels, % \begin{quote} % |\cref{eq1,eq2,eq3,thm1,thm2}| % \end{quote} @@ -331,10 +326,10 @@ % \end{quote} % (assuming you haven't customised the reference formats). % -% To prevent a sequence of consecutive references from being collapsed -% to a reference range, you can separate the references in the list by -% one or more empty references, at the point at which you want to -% prevent collapsing. For example, +% To prevent a sequence of consecutive references from being collapsed to +% a reference range, you can separate the references in the list by one +% or more empty references, at the point at which you want to prevent +% collapsing. For example, % \begin{quote} % |\cref{eq1,eq2,eq3,,eq4}| % \end{quote} @@ -361,26 +356,26 @@ % package (see \cref{sec:customising,sec:other_packages}), additional % starred variants of all the referencing commands are available. The % standard referencing commands will make references into hyper-links; -% the starred variants prevent this, producing the same typeset text -% but without creating hyper-links. +% the starred variants prevent this, producing the same typeset text but +% without creating hyper-links. % % % \section{Customising the Reference Format} % \label{sec:customising} -% The \package{cleveref} package allows you to take full control of -% the typesetting of references. Defaults appropriate for English -% documents are provided for the standard label types\footnote{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\dots a few years before the Romans -% pulled out of Britain. \package{cleveref} might have ``clever'' in -% its name, but even that doesn't make it pretentious enough to use +% The \package{cleveref} package allows you to take full control of the +% typesetting of references. Defaults appropriate for English documents +% are provided for the standard label types\footnote{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\dots a few years before the Romans pulled out of +% Britain. \package{cleveref} might have ``clever'' in its name, but +% even that doesn't make it pretentious enough to use % ``lemmata''.}. But if you don't like them, or are writing in a -% different language, or you need to cross-reference something for -% which no default format is defined, then you can take charge and -% define your own formats. +% different language, or you need to cross-reference something for which +% no default format is defined, then you can take charge and define your +% own formats. % % If \package{cleveref} encounters a reference to a type it does not % know, it will produce a ``reference type undefined'' warning, and @@ -388,8 +383,8 @@ % \begin{quote} % {\bf ??}~|\ref{|\meta{label}|}| % \end{quote} -% i.e.\ it will typeset the reference as the label counter preceded by -% a double question mark. The error message indicates the name of the +% i.e.\ it will typeset the reference as the label counter preceded by a +% double question mark. The error message indicates the name of the % unknown reference type, which you will then probably want to % define. (References to undefined labels still produce a ``reference % undefined'' warning and are typeset as a double question mark, as @@ -398,32 +393,35 @@ % The reference formats are usually constructed out of components: the % reference name (different for each type of reference), the label % formats, and the conjunctions used in reference ranges and lists of -% multiple references. There are three levels of customisation: you -% can customise the components globally, individually for each -% reference type, or you can take full control and ignore the -% components entirely. +% multiple references. There are three levels of customisation: you can +% customise the components globally, individually for each reference +% type, or you can take full control and ignore the components entirely. % % % \subsection{Global Customisation} % \label{sec:global_customisation} +% The global customisation commands can only be used in the preamble, and +% \emph{must} come before any lower-level customisation commands if they +% are to have any effect. +% % \DescribeMacro\crefdefaultlabelformat % The format for the label counter itself can be customised globally % using % \begin{quote} % |\crefdefaultlabelformat{|\meta{format}|}| % \end{quote} -% The \meta{format} argument can be any valid \LaTeX{} code, though -% you will need to |\protect| fragile commands. It can (and almost -% certainly should!) contain three arguments, |#1|, |#2| 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 reference that should form the hyper-link -% when the \package{hyperref} package is used (see -% \cref{sec:other_packages}). The hyper-link arguments |#2| and |#3| -% \emph{must} appear in that order. (Leaving them out completely will -% not cause an error, but in that case no hyper-link will be created -% when \package{hyperref} is used, and there are better ways to -% achieve this. See \cref{sec:typesetting,sec:other_packages}.) +% The \meta{format} argument can be any valid \LaTeX{} code, though you +% will need to |\protect| fragile commands. It can (and almost certainly +% should!) contain three arguments, |#1|, |#2| 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 reference that should form the hyper-link when the +% \package{hyperref} package is used (see \cref{sec:other_packages}). The +% hyper-link arguments |#2| and |#3| \emph{must} appear in that +% order. (Leaving them out completely will not cause an error, but in +% that case no hyper-link will be created when \package{hyperref} is +% used, and there are better ways to achieve this. See +% \cref{sec:typesetting,sec:other_packages}.) % % \DescribeMacro\crefrangeconjunction % The conjunction used in a reference range can be customised by @@ -431,17 +429,17 @@ % \begin{quote} % |\renewcommand{\crefrangeconjunction}{|\meta{conjunction}|}| % \end{quote} -% 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 emdash +% 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 emdash % ``|--|''. |\crefrangeconjunction| is used directly between the start -% and end references in a reference range, without any additional -% space surrounding it, e.g.\ |\crefrange{eq1}{eq2}| is typeset as +% and end references in a reference range, without any additional space +% surrounding it, e.g.\ |\crefrange{thm1}{thm2}| is typeset as % \begin{quote} -% |eqs.~(\ref{eq1})\crefrangeconjunction(\ref{eq2})| +% |theorems~\ref{thm1}\crefrangeconjunction\ref{thm2}| % \end{quote} -% (assuming the default equation format hasn't been customised). So -% you may or may not want to include surrounding space, depending on -% the formatting you desire. For example, +% (assuming the default theorem format hasn't been customised). So you +% may or may not want to include surrounding space, depending on the +% formatting you desire. For example, % \begin{quote} % |\renewcommand{\crefrangeconjunction}{ and~}| % \end{quote} @@ -451,6 +449,12 @@ % \end{quote} % does not. % +% Note that customizing |\crefrangeconjunction| will \emph{not} work for +% equations and figures because of the way the default formats for these +% are defined. See |\crefrangeformat| in +% \cref{sec:individual_customisation} for a way to change the conjunction +% for these reference types. +% % \DescribeMacro\crefpairconjunction % \DescribeMacro\crefmiddleconjunction % \DescribeMacro\creflastconjunction @@ -465,8 +469,8 @@ % |\crefpairconjunction| is used when there are only two references in % the list, |\creflastconjunction| is used between the penultimate and % final reference in a list of more than two, and -% |\crefmiddleconjunction| is used between all the others. Again, they -% do not have to be conjunctions in the linguistic sense, and the same +% |\crefmiddleconjunction| is used between all the others. Again, they do +% not have to be conjunctions in the linguistic sense, and the same % comments about surrounding space apply as in the case of % |\crefrangeconjunction|. For example, the default definition of % |\crefmiddleconjunction| is: @@ -482,10 +486,10 @@ % separate references of the same type\footnote{More accurately, % redefining $\backslash$crefpairconjunction etc.\ automatically % redefines $\backslash$crefpairgroupconjunction etc.\ so that they -% match. If you \emph{don't} redefine anything, the default -% definition of $\backslash$creflastgroupconjunction has an -% additional comma lacking in $\backslash$creflastconjunction.}. You -% can override this by redefining |\crefpairgroupconjunction|, +% match. If you \emph{don't} redefine anything, the default definition +% of $\backslash$creflastgroupconjunction has an additional comma +% lacking in $\backslash$creflastconjunction.}. You can override this +% by redefining |\crefpairgroupconjunction|, % |\crefmiddlegroupconjunction| and |\creflastgroupconjunction|. % % For example, if |eq*|, |thm*| and |fig*| are respectively equation, @@ -502,60 +506,60 @@ % % % \subsection{Customising Individual Reference Types} +% \label{sec:individual_customisation} % \DescribeMacro\crefname % \DescribeMacro\Crefname -% The reference name for a given reference type is customised using -% the |\crefname| and |\Crefname| commands: +% The reference name for a given reference type is customised using the +% |\crefname| and |\Crefname| commands: % \begin{quote} % |\crefname{|\meta{type}|}{|\meta{singular}|}{|\meta{plural}|}|\\ % |\Crefname{|\meta{type}|}{|\meta{singular}|}{|\meta{plural}|}| % \end{quote} -% used by the |\cref| and |\Cref| commands, respectively. You must -% supply both \meta{singular} and \meta{plural} forms of the name. If -% the corresponding |\Crefname| is undefined when |\crefname| is -% called, it will define |\Crefname| to be a capitalised version of -% |\crefname|, using |\MakeUppercase|. Conversely, if the -% corresponding |\crefname| is undefined when |\Crefname| is called, -% it will 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 -% \emph{not} a letter at all (e.g.\ if it is a \LaTeX{} command), you -% \emph{must} define both capitalisation variants +% used by the |\cref| and |\Cref| commands, respectively. You must supply +% both \meta{singular} and \meta{plural} forms of the name. If the +% corresponding |\Crefname| is undefined when |\crefname| is called, it +% will define |\Crefname| to be a capitalised version of |\crefname|, +% using |\MakeUppercase|. Conversely, if the corresponding |\crefname| is +% undefined when |\Crefname| is called, it will 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 \emph{not} a letter at all (e.g.\ if it is a \LaTeX{} +% command), you \emph{must} define both capitalisation variants % explicitly. Otherwise you will get strange and fatal errors when % processing the document. % % The reference \meta{type} is usually the name of the counter for the % environment (equation, chapter, section, etc.). Currently, the only -% exceptions are appendices, for which \meta{type} should be -% ``appendix'' (instead of chapter or section), and theorem-like -% environments when the \package{ntheorem} package is loaded, for -% which \meta{type} should instead be the environment name (lemma, -% corollary, definition, etc.). \package{ntheorem} provides extra -% information about the environment when different theorem-like -% environments use a common counter, which \package{cleveref} makes -% use of to distinguish between them automatically. +% exceptions are appendices, for which \meta{type} should be ``appendix'' +% (instead of chapter or section), and theorem-like environments when the +% \package{ntheorem} package is loaded, for which \meta{type} should +% instead be the environment name (lemma, corollary, definition, +% etc.). \package{ntheorem} provides extra information about the +% environment when different theorem-like environments use a common +% counter, which \package{cleveref} makes use of to distinguish between +% them automatically. % % \DescribeMacro\creflabelformat -% You may want the label format for a particular reference type to -% differ from the global format set by |\crefdefaultlabelformat| (see +% You may want the label format for a particular reference type to differ +% from the global format set by |\crefdefaultlabelformat| (see % \ref{sec:global_customisation}. You can do this using % \begin{quote} % |\creflabelformat{|\meta{type}|}{|\meta{format}|}| % \end{quote} % The \meta{type} argument is the reference type to customise, and the -% \meta{format} argument defines the label format for references of -% that type. As in the case of\linebreak[4] |\crefdefaultlabelformat|, -% the latter should contain the three arguments |#1|, |#2| and |#3|, -% the first being the formatted version of the label counter, the -% others determining the beginning and end of the portion that becomes -% a hyper-link when the \package{hyperref} package is loaded (see +% \meta{format} argument defines the label format for references of that +% type. As in the case of\linebreak[4] |\crefdefaultlabelformat|, the +% latter should contain the three arguments |#1|, |#2| and |#3|, the +% first being the formatted version of the label counter, the others +% determining the beginning and end of the portion that becomes a +% hyper-link when the \package{hyperref} package is loaded (see % \cref{sec:other_packages}). |#2| and |#3| must appear in that order. % -% \DescribeMacro\crefrangelabelformat -% Normally, the start and end references in a reference range are -% typeset using using the usual label format (as defined by +% \DescribeMacro\crefrangelabelformat +% Normally, the start and end references in a reference range are typeset +% using using the usual label format (as defined by % |\crefdefaultlabelformat| or |\creflabelformat|) separated by % |\crefrangeconjunction| (\cref{sec:global_customisation}). You can % override this for a given reference type using @@ -563,65 +567,69 @@ % |\crefrangelabelformat{|\meta{type}|}{|\meta{format}|}| % \end{quote} % The \meta{format} argument should contain six arguments: |#1|, |#2|, -% |#3|, |#4|, |#5|, |#6|. The first two (|#1| and |#2|) are the -% formatted versions of the two label counters defining the reference -% range. The next two (|#3| and |#4|) denote the beginning and end of -% the hyper-link for the first reference, the final two (|#5| and -% |#6|) the hyper-link for the second reference. The hyper-link -% arguments must appear in order. For example, the default format for -% equations is defined as: +% |#3|, |#4|, |#5|, |#6|. The first two (|#1| and |#2|) are the formatted +% versions of the two label counters defining the reference range. The +% next two (|#3| and |#4|) denote the beginning and end of the hyper-link +% for the first reference, the final two (|#5| and |#6|) the hyper-link +% for the second reference. The hyper-link arguments must appear in +% order. For example, the default format for equations is defined as: % \begin{quote} % |\crefrangelabelformat{equation}{(#3#1#4)--(#5#2#6)}| % \end{quote} -% +% +% Note that the above default reference range format for equations (and +% similarly for figures) already overrides the normal +% |\crefrangelabelformat|, so customizing |\crefrangeconjunction| will +% not affect these particular default formats. If you want to change the +% conjunction used in equation and figure reference ranges, you have to +% use |\crefrangelabelformat|. % % % \subsection{Taking Full Control} +% \label{sec:full-control_customisation} % If you need more precise control over the 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 -% references, reference ranges and multi-references are customised -% separately. If you only customise some of these, the other formats -% will still be constructed from components, as usual. +% component-derived format entirely. The formats for single references, +% reference ranges and multi-references are customised separately. If you +% only customise some of these, the other formats will still be +% constructed from components, as usual. % % \subsubsection{Single References} % \label{sec:ref_format} % \DescribeMacro\crefformat % \DescribeMacro\Crefformat -% Reference formats for \emph{single} references are defined or -% redefined using the\linebreak[4] |\crefformat| and |\Crefformat| -% commands, which are used by the |\cref| and |\Cref| commands -% respectively. These take two arguments: the reference type, and the -% formatting code: +% Reference formats for \emph{single} references are defined or redefined +% using the\linebreak[4] |\crefformat| and |\Crefformat| commands, which +% are used by the |\cref| and |\Cref| commands respectively. These take +% two arguments: the reference type, and the formatting code: % \begin{quote} % |\crefformat{|\meta{type}|}{|\meta{format}|}|\\ % |\Crefformat{|\meta{type}|}{|\meta{format}|}| % \end{quote} % The \meta{type} is usually the name of the counter, except for -% theorem-like environments when \package{ntheorem} is loaded, in -% which case it is the environment name,and appendices, when it is +% theorem-like environments when \package{ntheorem} is loaded, in which +% case it is the environment name,and appendices, when it is % ``appendix''. % % As in the case of the |\crefname| and |\Crefname| commands, if the -% corresponding |\Crefformat| is undefined when |\crefformat| is -% called, it will define the |\Crefformat| to produce a capitalised -% version of |\crefformat|, using |\MakeUppercase|. Conversely, if the -% corresponding |\crefformat| is undefined whe |\Crefformat| is -% called, if will define the |\Crefformat| to produce a lower-case -% version of |\Crefformat|, using |\MakeLowercase|. Obviosly, 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 \cref{sec:global_customisation}). -% -% The \meta{format} argument can be any valid \LaTeX{} code, though -% you will need to |\protect| fragile commands. It should contain -% three arguments, |#1|, |#2| 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 -% reference that forms the hyper-link when the \package{hyperref} -% package is used, and must appear in that order (see -% \cref{sec:other_packages}). +% corresponding |\Crefformat| is undefined when |\crefformat| is called, +% it will define the |\Crefformat| to produce a capitalised version of +% |\crefformat|, using |\MakeUppercase|. Conversely, if the corresponding +% |\crefformat| is undefined whe |\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 +% \cref{sec:global_customisation}). +% +% The \meta{format} argument can be any valid \LaTeX{} code, though you +% will need to |\protect| fragile commands. It should contain three +% arguments, |#1|, |#2| 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 reference that +% forms the hyper-link when the \package{hyperref} package is used, and +% must appear in that order (see \cref{sec:other_packages}). % % As an example, % \begin{quote} @@ -633,13 +641,13 @@ % \end{quote} % with the counter (excluding the brackets) forming the hyper-link. % -% Note that the hyper-link arguments are \emph{not} letters, so if -% |#2| appears at the beginning of \meta{format}, \package{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 to the ``Eq.'' to be part of the hyper-link, -% you would have to define: +% Note that the hyper-link arguments are \emph{not} letters, so if |#2| +% appears at the beginning of \meta{format}, \package{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 to the ``Eq.'' to be part of the hyper-link, you would have to +% define: % \begin{quote} % |\crefformat{equation}{#2eq.~(#1)#3}|\\ % |\Crefformat{equation}{#2Eq.~(#1)#3}| @@ -652,26 +660,25 @@ % \DescribeMacro\Crefrangeformat % The format for reference ranges is defined by |\crefrangeformat| % and\linebreak[4] |\Crefrangeformat|. Like |\creformat| and -% |\Crefformat|, the commands take two arguments: the reference type, -% and the formatting code. +% |\Crefformat|, the commands take two arguments: the reference type, and +% the formatting code. % \begin{quote} % |\crefrangeformat{|\meta{type}|}{|\meta{format}|}|\\ % |\Crefrangeformat{|\meta{type}|}{|\meta{format}|}| % \end{quote} % The same comments apply as in the case of single references: the -% \meta{type} is usually the name of the counter, except for -% theorem-like environments when \package{ntheorem} is loaded, and if -% the other-capitalisation variant is not already defined, it will be -% defined automatically. -% -% The \meta{format} argument can again be any valid \LaTeX{} code, -% with fragile commands |\protect|ed. However, this time it should -% contain \emph{six} arguments, |#1|--|#6|. The first two (|#1| and -% |#2|) are the formatted versions of the label counters, the next two -% (|#3| and |#4|) are used to mark the beginning and end of the -% hyper-link for the first reference (|#1|), and the final two (|#5| -% and |#6|) mark the beginning and end of the second reference's -% hyper-link. +% \meta{type} is usually the name of the counter, except for theorem-like +% environments when \package{ntheorem} is loaded, and if the +% other-capitalisation variant is not already defined, it will be defined +% automatically. +% +% The \meta{format} argument can again be any valid \LaTeX{} code, with +% fragile commands |\protect|ed. However, this time it should contain +% \emph{six} arguments, |#1|--|#6|. The first two (|#1| and |#2|) are the +% formatted versions of the label counters, the next two (|#3| and |#4|) +% are used to mark the beginning and end of the hyper-link for the first +% reference (|#1|), and the final two (|#5| and |#6|) mark the beginning +% and end of the second reference's hyper-link. % % As an example, the default % \begin{quote} @@ -693,17 +700,17 @@ % The format for multiple references is defined by |\crefmultiformat| % and\linebreak[4] |\Crefmultiformat|, and that of reference ranges % within multiple references by |\crefrangemultiformat| and -% |\Crefrangemultiformat|. Multi-references also require \emph{all} -% the other reference formats to be defined (see +% |\Crefrangemultiformat|. Multi-references also require \emph{all} the +% other reference formats to be defined (see % \cref{sec:ref_format,sec:ref_range_format}), including the single % reference range formats, even if you never use the |\crefrange| and % |\Crefrange| commands. % % The commands all take five arguments: the reference type, the format -% for the first reference in a list, the format for the second -% reference in a list of two, the format for the middle references in -% a list of more than two, and the format for the last reference in a -% list of more than two. +% for the first reference in a list, the format for the second reference +% in a list of two, the format for the middle references in a list of +% more than two, and the format for the last reference in a list of more +% than two. % \begin{quote} % |\crefmultiformat{|\meta{type}|}{|\meta{first}|}{|\meta{second}|}{|\meta{middle}|}{|\meta{last}|}|\\ % |\Crefmultiformat{|\meta{type}|}{|\meta{first}|}{|\meta{second}|}{|\meta{middle}|}{|\meta{last}|}|\\ @@ -711,26 +718,26 @@ % |\Crefrangemultiformat{|\meta{type}|}{|\meta{first}|}{|\meta{second}|}{|\meta{middle}|}{|\meta{last}|}| % \end{quote} % -% The \meta{type} is, as ever, the counter name, or environment name -% in the case of \package{ntheorem} theorem-like environments. The -% same considerations apply to the formatting arguments \meta{first}, -% \meta{second}, \meta{middle} and \meta{last} as for the -% \meta{format} argument 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 |\crefmultiformat| and -% |\Crefmultiformat|). However, when the corresponding -% other-capitalisation variant is automatically defined, only the -% first letter of the \meta{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 \meta{first} and {|\meta{second}|}, or -% \meta{first}, \meta{middle} and \meta{last}, \LaTeX{} code is -% typeset one after another in a multi-reference, with no space -% separating them. You may or may not want spaces at the beginning and -% end of the formatting code, depending on the formatting you -% desire. For example, in the default equation format +% The \meta{type} is, as ever, the counter name, or environment name in +% the case of \package{ntheorem} theorem-like environments. The same +% considerations apply to the formatting arguments \meta{first}, +% \meta{second}, \meta{middle} and \meta{last} as for the \meta{format} +% argument 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 +% |\crefmultiformat| and |\Crefmultiformat|). However, when the +% corresponding other-capitalisation variant is automatically defined, +% only the first letter of the \meta{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 \meta{first} and {|\meta{second}|}, or \meta{first}, +% \meta{middle} and \meta{last}, \LaTeX{} code is typeset one after +% another in a multi-reference, with no space separating them. You may or +% may not want spaces at the beginning and end of the formatting code, +% depending on the formatting you desire. For example, in the default +% equation format % \begin{quote} % |\crefmultiformat{equation}%|\\ % |{eqs.~(#2#1#3)}{ and~(#2#1#3)}{, (#2#1#3)}{ and~(#2#1#3)}| @@ -742,24 +749,24 @@ % % % \section{Overriding the Reference Type} -% As described previously, a label's reference type is usually -% determined by its counter, or in the case of \package{ntheorem} -% theorem-like environments by the environment name. Occasionally, you -% may want to override the reference type for a particular label. You -% can do this by supplying the desired type as an optional argument to -% the |\label| command: +% As described previously, a label's reference type is usually determined +% by its counter, or in the case of \package{ntheorem} theorem-like +% environments by the environment name. Occasionally, you may want to +% override the reference type for a particular label. You can do this by +% supplying the desired type as an optional argument to the |\label| +% command: % \begin{quote} % |\label[|\meta{type}|]{|\meta{label}|}| % \end{quote} % % One circumstance in which is useful is when you want to define a % special reference format for certain labels of a given type. By -% specifying a type that doesn't already exist in the |\label|'s -% optional argument, you can then define the reference format for that -% new type in whatever way you like, without affecting other -% references of the same type. For example, if a particular equation -% contains multiple expressions and you want it to always be referred -% to in the plural, you could use: +% specifying a type that doesn't already exist in the |\label|'s optional +% argument, you can then define the reference format for that new type in +% whatever way you like, without affecting other references of the same +% type. For example, if a particular equation contains multiple +% expressions and you want it to always be referred to in the plural, you +% could use: % \begin{quote} % |\crefname{pluralequation}{eqs.}{eqs.}|\\ % \dots\\ @@ -767,10 +774,10 @@ % \end{quote} % You can of course reuse this format for other plural equations, too. % -% If you need to do this frequently, it can become tedious specifying -% the label explicitly each time. An alternative is to use the -% \package{aliascnt} package. This lets you define one counter to be -% an alias for another, so that effectively the same counter has two +% If you need to do this frequently, it can become tedious specifying the +% label explicitly each time. An alternative is to use the +% \package{aliascnt} package. This lets you define one counter to be an +% alias for another, so that effectively the same counter has two % names. Since \package{cleveref} determines the label type from the % counter name, the two counter aliases can have different reference % formats whilst really being the same counter. You have to somehow @@ -780,12 +787,11 @@ % convenience of not having to remember to pass an explicit optional % argument to a large number of labels. % -% You can use this trick to get different reference formats for -% different theorem-like environments, \emph{without} using the -% \package{ntheorem} package\footnote{This trick seems to belong to -% \LaTeX{} mythology, and certainly isn't my own idea! I haven't -% been able to definitively track down who originally came up with -% it.}. For example, +% You can use this trick to get different reference formats for different +% theorem-like environments, \emph{without} using the \package{ntheorem} +% package\footnote{This trick seems to belong to \LaTeX{} mythology, and +% certainly isn't my own idea! I haven't been able to definitively +% track down who originally came up with it.}. For example, % \begin{quote} % |\usepackage{aliascnt}|\\ % |\usepackage{cleveref}|\\ @@ -799,32 +805,31 @@ % % \section{Poor Man's \package{cleveref}} % Sometimes you may need to send your \LaTeX{} source to someone who -% can't install the \package{cleveref} package themselves. For -% example, many academic journals accept papers in \LaTeX{} format, -% but only support a small subset of the packages available on -% CTAN. The \option{poorman} option was designed specifically to help -% in this situation. +% can't install the \package{cleveref} package themselves. For example, +% many academic journals accept papers in \LaTeX{} format, but only +% support a small subset of the packages available on CTAN. The +% \option{poorman} option was designed specifically to help in this +% situation. % % When the \option{poorman} option is supplied, your document will be % processed as normal. But in addition, a {\tt sed} script will % automatically be written, containing rules for replacing all the % \cmd{\cref} commands with the \LaTeX{} code that they would produce, % and using the standard \cmd{\ref} command to produce the -% cross-references themselves. I.e.\ the script rewrites your document -% as you would have done if you had had to do it manually! +% cross-references themselves. I.e.\ the script rewrites your document as +% you would have done if you had had to do it manually! % % The advantage, of course, is that you \emph{don't} have to do it -% manually. Instead, you can use all the features of -% \package{cleveref}, and once you've created a version of your -% document that you want to send elsewere, you can process it through -% the {\tt sed} script to completely remove the \package{cleveref} -% dependency. The recipient won't even realise you used -% \package{cleveref}! +% manually. Instead, you can use all the features of \package{cleveref}, +% and once you've created a version of your document that you want to +% send elsewere, you can process it through the {\tt sed} script to +% completely remove the \package{cleveref} dependency. The recipient +% won't even realise you used \package{cleveref}! % % The {\tt sed} script is written to the same directory as the (main) -% \LaTeX{} source file, and given the same name as that source file -% but with the extension \file{.sed}. To process your document through -% the script, all you need to do is run the following from your shell: +% \LaTeX{} source file, and given the same name as that source file but +% with the extension \file{.sed}. To process your document through the +% script, all you need to do is run the following from your shell: % \begin{quote} % sed -f \meta{name}\file{.sed} \ % \meta{name}\file{.tex} \textgreater \meta{newname}\file{.tex} @@ -832,91 +837,92 @@ % where \meta{name} is the name of the file containing your \LaTeX{} % source file minus the \file{.tex} extension, and \meta{newname} is % whatever you want to call the new version. \emph{Do not} make -% \meta{newname} the same as \meta{name}. (It's in any case wise to -% keep the original \LaTeX{} source file containing the -% \package{cleveref} commands, in case you need to produce an updated -% version of your document in the future. Think of the -% \meta{newname}\file{.tex} file as being rather like a \file{DVI} -% file: something you can always reproduce from the original source.) -% If your document is composed of a number of separate \LaTeX{} source -% files, combined with |\include| commands, only one {\tt sed} script -% will be generated, but you will need to run \emph {each} source file -% through that \emph{same} script (and probably modify the |\include| -% commands to match the new file names). +% \meta{newname} the same as \meta{name}. (It's in any case wise to keep +% the original \LaTeX{} source file containing the \package{cleveref} +% commands, in case you need to produce an updated version of your +% document in the future. Think of the \meta{newname}\file{.tex} file as +% being rather like a \file{DVI} file: something you can always reproduce +% from the original source.) If your document is composed of a number of +% separate \LaTeX{} source files, combined with |\include| commands, only +% one {\tt sed} script will be generated, but you will need to run \emph +% {each} source file through that \emph{same} script (and probably modify +% the |\include| commands to match the new file names). % % % % \section{Interaction with Other Packages} % \label{sec:other_packages} -% The \package{cleveref} package \emph{must} be loaded \emph{after} -% all other packages that don't specifically support it\footnote{At -% the time of writing, I'm not aware of any that do.}, i.e.\ the +% The \package{cleveref} package \emph{must} be loaded \emph{after} all +% other packages that don't specifically support it\footnote{At the time +% of writing, I'm not aware of any that do.}, i.e.\ the % \begin{quote} % |\usepackage{cleveref}| % \end{quote} -% line should always be the last |\usepackage| command in your -% document's preamble. +% line should always be the last |\usepackage| command in your document's +% preamble. % -% Since \package{cleveref} redefines many internal commands involved -% in \LaTeX{}'s referencing system, it can interact badly with other +% Since \package{cleveref} redefines many internal commands involved in +% \LaTeX{}'s referencing system, it can interact badly with other % packages that do the same. \package{varioref}'s enhanced referencing -% features (the ones you make use of by via the |\labelformat| -% command), the \package{fancyref} package, and \package{ntheorem}'s -% \option{thref} option are incompatible with -% \package{cleveref}. However, since \package{cleveref} implements an -% enhanced version of these packages' features, this is not really a -% problem. For example, if you have a pre-existing document that uses -% \package{ntheorem}'s |\thref| command, you can simply redefine it to -% call |\cref| instead: +% features (the ones you make use of by via the |\labelformat| command), +% the \package{fancyref} package, and \package{ntheorem}'s \option{thref} +% option are incompatible with \package{cleveref}. However, since +% \package{cleveref} implements an enhanced version of these packages' +% features, this is not really a problem. For example, if you have a +% pre-existing document that uses \package{ntheorem}'s |\thref| command, +% you can simply redefine it to call |\cref| instead: % \begin{quote} % |\renewcommand{\thref}{\cref}| % \end{quote} % In fact, \package{cleveref} does this for you automatically if -% \package{ntheorem} was loaded with the \option{thref} option. Note -% that you can still use the other features of \package{varioref} and +% \package{ntheorem} was loaded with the \option{thref} option. Note that +% you can still use the other features of \package{varioref} and % \package{ntheorem} whilst using \package{cleveref}, as long as % \package{cleveref} is loaded \emph{last}. % -% Other packages which alter the \LaTeX{} referencing system are -% unlikely to work properly with \package{cleveref}. +% Other packages which alter the \LaTeX{} referencing system are unlikely +% to work properly with \package{cleveref}. % % % -% \section{Known Bugs} +% \section{Known Bugs and Word-Arounds} % In no particular order. % \begin{itemize} % \item \package{cleveref} will not work properly with the standard -% \LaTeX{} |eqnarray| environment. The |eqnarray| environment is -% poorly implemented, making it somewhat difficult to get it to work -% properly with \package{cleveref}. You're better off using the +% \LaTeX{} |eqnarray| environment. The |eqnarray| environment is poorly +% implemented, making it somewhat difficult to get it to work properly +% with \package{cleveref}. You're better off using the % \package{amsmath} replacements in any case, such as |gather|, % |align|, |multine| and |split|, which \emph{do} work properly with % \package{cleveref}. (See % \url{http://www.tug.org/pracjourn/2006-4/madsen/}). +% \item When both the \package{amsmath} \emph{and} \package{hyperref} +% packages are loaded at the same time, the \package{cleveref} +% cross-referencing commands will not work in section titles. If anyone +% can figure out why, let me know! +% \item \package{cleveref} provides no \package{babel} support. (This +% should be fixed in a future version.) +% \item \package{cleveref} breaks \package{hyperref}'s \option{backref} +% option, and probably also the \package{backref} package when used by +% itself. (This should be fixed in a future version.) +% \item \package{cleveref} assumes that counters are only ever reset by +% the standard sectioning commands (chapter, section, etc.). If this is +% not the case, the automatic collapsing of consecutive references into +% a reference range may be incorrect. % \item The \option{poorman} sed script always uses |\ref| rather than % |\ref*|, even if the command it's replacing is a starred variant % |\cref*|, |\crefrange*| etc. (This should be fixed in a future % version.) -% \item \package{cleveref} provides no \package{babel} support. (This -% should be fixed in a future version.) -% \item \package{cleveref} breaks \package{hyperref}'s -% \option{backref} option, and probably also the \package{backref} -% package when used by itself. (This should be fixed in a future -% version.) -% \item \package{cleveref} assumes that counters are only ever reset -% by the standard sectioning commands (chapter, section, etc.). If -% this is not the case, the automatic collapsing of consecutive -% references into a reference range may be incorrect. % \item The \option{poorman} sed script uses |\ref| when replacing % \package{cleveref} cross-references, but this loses any custom -% \package{cleveref} hyper-link formatting you might have -% defined. The philosophy behind the \option{poorman} option is to -% replace \package{cleveref}'s enhanced cross-referencing with -% standard \LaTeX{} cross-reference commands that are guaranteed to -% work with any standard \LaTeX{} installation. Although it would be -% simple to fix this ``bug'', it's not obvious how to do it without -% compromising this underlying philosophy, i.e.\ without using -% \LaTeX{} code that is unlikely to be supported by journals. +% \package{cleveref} hyper-link formatting you might have defined. The +% philosophy behind the \option{poorman} option is to replace +% \package{cleveref}'s enhanced cross-referencing with standard +% \LaTeX{} cross-reference commands that are guaranteed to work with +% any standard \LaTeX{} installation. Although it would be simple to +% fix this ``bug'', it's not obvious how to do it without compromising +% this underlying philosophy, i.e.\ without using \LaTeX{} code that is +% unlikely to be supported by journals. % \end{itemize} % % @@ -928,8 +934,8 @@ % package option % \item Add an option to automatically sort references in a % multi-reference before typesetting them. -% \item Enhance the \option{poorman} option to allow a choice of -% script language rather than just sed (e.g.\ awk, perl, \dots?). +% \item Enhance the \option{poorman} option to allow a choice of script +% language rather than just sed (e.g.\ awk, perl, \dots?). % \end{itemize} % % @@ -946,28 +952,27 @@ % % The least invasive implementation seems to be that used by the % \package{varioref} package. Namely, to redefine the -% \cmd{\refstepcounter} command so that the \cmd{\@currentlabel} -% macro, which usually just cotains the typeset version of the -% counter, now contains the additional type information. (In fact, we -% write three extra pieces of information: the type, the counter value -% itself, and the formatted version of the counter that causes the -% label's counter to be reset, which we call the ``prefix'' from now -% on.) \cmd{\@currentlabel} eventually gets written to the aux file as -% an argument to \cmd{\newlabel} by the usual \LaTeX{} -% mechanisms. This involves less hacking to get everything else -% working again, since very few macros other than \cmd{\ref} use this -% particular \cmd{\newlabel} argument (nor are other packages likely -% to, given that \package{varioref} is a \texttt{required} \LaTeX{} -% package). +% \cmd{\refstepcounter} command so that the \cmd{\@currentlabel} macro, +% which usually just cotains the typeset version of the counter, now +% contains the additional type information. (In fact, we write three +% extra pieces of information: the type, the counter value itself, and +% the formatted version of the counter that causes the label's counter to +% be reset, which we call the ``prefix'' from now on.) +% \cmd{\@currentlabel} eventually gets written to the aux file as an +% argument to \cmd{\newlabel} by the usual \LaTeX{} mechanisms. This +% involves less hacking to get everything else working again, since very +% few macros other than \cmd{\ref} use this particular \cmd{\newlabel} +% argument (nor are other packages likely to, given that +% \package{varioref} is a \texttt{required} \LaTeX{} package). % % % \subsection{Redefinitions of \LaTeX{} kernel macros} % We store the original \cmd{\refstepcounter} in % \cmd{\cref@old@refstepcounter}, then redefine \cmd{\refstepcounter} so -% that it first calls the old version and then adds the extra -% information to \cmd{\@currentlabel}. The new \cmd{\@refstepcounter} -% can take an optional argument, which overrides using the counter -% name as the ``type'' and instead uses whatever is supplied. +% that it first calls the old version and then adds the extra information +% to \cmd{\@currentlabel}. The new \cmd{\@refstepcounter} can take an +% optional argument, which overrides using the counter name as the +% ``type'' and instead uses whatever is supplied. % \begin{macrocode} \let\cref@old@refstepcounter\refstepcounter \def\refstepcounter{% @@ -988,7 +993,7 @@ \protected@edef\@currentlabel{% [#1][\arabic{#2}][\@result]\@currentlabel}} % \end{macrocode} -% +% % We redefine the \cmd{\label} command to allow it to take an optional % argument that overrides the default reference type in % \cmd{\@currentlabel}. We have to postpone this redefinition of @@ -1004,24 +1009,24 @@ \expandafter\cref@override@label@type\@currentlabel\@nil{#1}}% \cref@old@label}% % \end{macrocode} -% -% The \package{amsmath} package redefines the \cmd{\label} command -% within equation environments, so if it is loaded we have to extend -% the behaviour to support the optional argument. With -% \package{amsmath}, the original \cmd{\label} command in stored in -% \cmd{ltx@label}, and \cmd{\label@in@display} replaces \cmd{label} -% inside equations. \cmd{\label@in@display} just saves the label for -% later, and defining it is left until the end of the equation, when +% +% The \package{amsmath} package redefines the \cmd{\label} command within +% equation environments, so if it is loaded we have to extend the +% behaviour to support the optional argument. With \package{amsmath}, the +% original \cmd{\label} command in stored in \cmd{ltx@label}, and +% \cmd{\label@in@display} replaces \cmd{label} inside +% equations. \cmd{\label@in@display} just saves the label for later, and +% defining it is left until the end of the equation, when % \cmd{\ltx@label} is finally called. % -% To allow \cmd{label} within equations to support an optional -% argument, we first store the original \cmd{\label@in@display} and -% the new \cmd{\label} macro we defined above (since \cmd{\label} will -% be clobbered inside equations). Then we redefine -% \cmd{label@in@display} so that it wraps all its arguments, including -% any optional argument, in an extra set of braces \{\}. These are -% stripped away again by \cmd{\ltx@label} before calling the -% \cmd{\label} macro we defined above (saved in \cmd{\cref@label}). +% To allow \cmd{label} within equations to support an optional argument, +% we first store the original \cmd{\label@in@display} and the new +% \cmd{\label} macro we defined above (since \cmd{\label} will be +% clobbered inside equations). Then we redefine \cmd{label@in@display} so +% that it wraps all its arguments, including any optional argument, in an +% extra set of braces \{\}. These are stripped away again by +% \cmd{\ltx@label} before calling the \cmd{\label} macro we defined above +% (saved in \cmd{\cref@label}). % \begin{macrocode} \@ifpackageloaded{amsmath}{% \let\cref@label\label% @@ -1042,31 +1047,31 @@ % want. Therefore, we redefine \cmd{\cref} to recover the original % behaviour. We have to defer redefinition of \cmd{\ref} till the % beginning of the document, in case other packages (such as -% \package{ntheorem}) modify it after \package{cleveref} is -% loaded. For some reason, \cmd{\DeclareRobustCommand} doesn't work -% here, so we make it robust manually. +% \package{ntheorem}) modify it after \package{cleveref} is loaded. We +% add a level of redirection to make it easier in case we need to +% redefine it for \package{hyperref} later. % \begin{macrocode} \def\cref@reflabel#1#2{\@result} \AtBeginDocument{% - \expandafter\def\csname ref \endcsname#1{% - \expandafter\ifx\csname r@#1\endcsname\relax% - \let\@result\relax% - \else% - \cref@getlabel{#1}{\@result}% - \fi% - \expandafter\@setref\csname r@#1\endcsname{\cref@reflabel}{#1}}% - \def\ref{\expandafter\protect\csname ref \endcsname}% + \DeclareRobustCommand{\ref}{\cref@ref} + \def\cref@ref#1{% + \expandafter\ifx\csname r@#1\endcsname\relax% + \let\@result\relax% + \else% + \cref@getlabel{#1}{\@result}% + \fi% + \expandafter\@setref\csname r@#1\endcsname{\cref@reflabel}{#1}}% } % \end{macrocode} % % The \cmd{\appendix} command causes the top-level sectioning commands -% (\cmd{\chapter} or \cmd{\section}, depending on the document class) -% to produce appendices instead. Since we want to be able to format -% references to appendices separately from references to normal -% top-level sections, we add to the tasks that \cmd{\appendix} does: -% it redefines \cmd{\refstepcounter@noarg} to exceptionally override -% the label type for chapters or sections, as appropriate, setting it -% to ``appendix'' instead. +% (\cmd{\chapter} or \cmd{\section}, depending on the document class) to +% produce appendices instead. Since we want to be able to format +% references to appendices separately from references to normal top-level +% sections, we add to the tasks that \cmd{\appendix} does: it redefines +% \cmd{\refstepcounter@noarg} to exceptionally override the label type +% for chapters or sections, as appropriate, setting it to ``appendix'' +% instead. % \begin{macrocode} \let\cref@old@appendix\appendix \renewcommand\appendix{% @@ -1082,7 +1087,7 @@ \ifx\@tmpa\@tmpb% \protected@edef\@currentlabel{% [appendix][\arabic{##1}][\@result]\@currentlabel}% - \else + \else \protected@edef\@currentlabel{% [##1][\arabic{##1}][\@result]\@currentlabel} \fi} @@ -1097,7 +1102,7 @@ \ifx\@tmpa\@tmpb% \protected@edef\@currentlabel{% [appendix][\arabic{##1}][\@result]\@currentlabel}% - \else + \else \protected@edef\@currentlabel{% [##1][\arabic{##1}][\@result]\@currentlabel} \fi}% @@ -1109,17 +1114,17 @@ % \subsection{Utility Macros} % Define some utility macros for extracting label, type, and counter % information from the contents of \cmd{\@currentlabel}, as written to -% the aux file and stored in \cmd{\r@\meta{label}} when this is -% re-read on the next pass. Some other packages commandeer the -% referencing system to write label information to the aux file for -% other purposes, and probably use \cmd{\ref} to recover it later. We -% still want them to work, so our utility macros must cope with the -% type information being absent. However, since we need them to be -% fully expandable in various places, and \cmd{\@ifnextchar} is -% definitely \emph{not} fully expandable, we use the work-around of -% having the macros store their result in another macro, whose name is -% passed as the second argument. This other macro \emph{will} then be -% fully expandable, and can be used e.g.\ inside an \cmd{\edef} or +% the aux file and stored in \cmd{\r@\meta{label}} when this is re-read +% on the next pass. Some other packages commandeer the referencing system +% to write label information to the aux file for other purposes, and +% probably use \cmd{\ref} to recover it later. We still want them to +% work, so our utility macros must cope with the type information being +% absent. However, since we need them to be fully expandable in various +% places, and \cmd{\@ifnextchar} is definitely \emph{not} fully +% expandable, we use the work-around of having the macros store their +% result in another macro, whose name is passed as the second +% argument. This other macro \emph{will} then be fully expandable, and +% can be used e.g.\ inside an \cmd{\edef} or % \cmd{\csname}\ldots\cmd{\endcsname}. % \begin{macrocode} \def\cref@getlabel#1#2{% @@ -1185,19 +1190,17 @@ \ifx#1\@tmpa\@cref@stackfullfalse% \else\@cref@stackfulltrue\fi} % \end{macrocode} -% -% We need to be able to determine which counter is used to reset a -% given counter. Usually, resets are done by sectioning counters, and -% we assume that to be the case here. \cmd{\isinresetlist} searches -% through one counter's reset list, stored in -% \cmd{\cl@\meta{counter}}, to determine whether another counter -% appears there, and sets the new conditional +% +% We need to be able to determine which counter is used to reset a given +% counter. Usually, resets are done by sectioning counters, and we assume +% that to be the case here. \cmd{\isinresetlist} searches through one +% counter's reset list, stored in \cmd{\cl@\meta{counter}}, to determine +% whether another counter appears there, and sets the new conditional % appropriately. \cmd{\reset@by} searches through all the sectioning % counters' reset lists, from lowest-level (subsubsection) to highest -% (part), checking whether the given counter is in the list, and -% returns the first sectioning counter whose list it appears (value is -% returned by defining its second argument, which should be a macro -% name). +% (part), checking whether the given counter is in the list, and returns +% the first sectioning counter whose list it appears (value is returned +% by defining its second argument, which should be a macro name). % \begin{macrocode} \newif\if@cref@inresetlist \def\cref@isinresetlist#1#2{% @@ -1271,18 +1274,18 @@ \DeclareRobustCommand{\Crefrange}[2]{\@setcrefrange{#1}{#2}{Cref}{}} % \end{macrocode} % To save duplicating code, the referencing macros pass an argument -% determining the variant to an auxilliary macro \cmd{\@cref}, which -% does the real work. The \cmd{\@cref} macro is the behemoth at the -% heart of all the smart referencing features. It deals with grouping -% references by type, typesetting the conjunctions between groups, -% choosing the right formatting macro to use for each reference, -% and collapsing consecutive references into ranges. +% determining the variant to an auxilliary macro \cmd{\@cref}, which does +% the real work. The \cmd{\@cref} macro is the behemoth at the heart of +% all the smart referencing features. It deals with grouping references +% by type, typesetting the conjunctions between groups, choosing the +% right formatting macro to use for each reference, and collapsing +% consecutive references into ranges. % \begin{macrocode} \def\@cref#1#2{% \begingroup% % \end{macrocode} -% Initialise some things, and put all the references into a stack -% called \cmd{\@refstack}. +% Initialise some things, and put all the references into a stack called +% \cmd{\@refstack}. % \begin{macrocode} \countdef\count@consecutive=0% \def\@empty{}% @@ -1307,9 +1310,9 @@ \fi% \let\@nexttype\@currenttype% % \end{macrocode} -% Move references from \cmd{\@refstack} into a different stack -% called \cmd{\@refsubstack}, until we encounter a reference that -% has a different type to those that came before. +% Move references from \cmd{\@refstack} into a different stack called +% \cmd{\@refsubstack}, until we encounter a reference that has a +% different type to those that came before. % \begin{macrocode} \@whilesw\ifx\@nexttype\@currenttype\fi{% \expandafter\cref@stack@pull\expandafter% @@ -1375,10 +1378,10 @@ \@cref@refconsecutivefalse% \else% % \end{macrocode} -% If next reference in substack is empty, it indicates that no -% further collapsing should take place. Having served its -% purpose, the empty reference and any consecutive empty -% references are removed from the substack. +% If next reference in substack is empty, it indicates that no further +% collapsing should take place. Having served its purpose, the empty +% reference and any consecutive empty references are removed from the +% substack. % \begin{macrocode} \ifx\@nextref\@empty% \@cref@refconsecutivefalse% @@ -1613,11 +1616,11 @@ }% end loop over main reference stack \endgroup} % \end{macrocode} -% % -% The internal \cmd{\@setcref} macro deals with actually typesetting -% the reference, by calling the appropriate type-dependent formatting -% macro defined by \cmd{\crefformat} etc. +% +% The internal \cmd{\@setcref} macro deals with actually typesetting the +% reference, by calling the appropriate type-dependent formatting macro +% defined by \cmd{\crefformat} etc. % \begin{macrocode} \def\@setcref#1#2#3{% \expandafter\ifx\csname r@#1\endcsname\relax% @@ -1639,20 +1642,20 @@ \fi} % \end{macrocode} % -% We separate out the very final typesetting step into a separate -% macro, in order to make it easier to redefine things later to make -% them work with the \package{hyperref} package. +% We separate out the very final typesetting step into a separate macro, +% in order to make it easier to redefine things later to make them work +% with the \package{hyperref} package. % \begin{macrocode} \def\@@setcref#1#2{\cref@getlabel{#2}{\@templabel}#1{\@templabel}{}{}} % \end{macrocode} % -% Define a new conditional to test whether two references are -% consecutive (needed when typesetting reference ranges). This uses -% the counter and prefix (i.e. formatted version of the counter that -% resets the label's counter) information provided by -% \cmd{\r@\meta{label}} (via the aux file) to check if the prefices are -% identical (i.e. the references come from the same chapter, section -% or whatever), and that the label counters differ by 1. +% Define a new conditional to test whether two references are consecutive +% (needed when typesetting reference ranges). This uses the counter and +% prefix (i.e. formatted version of the counter that resets the label's +% counter) information provided by \cmd{\r@\meta{label}} (via the aux +% file) to check if the prefices are identical (i.e. the references come +% from the same chapter, section or whatever), and that the label +% counters differ by 1. % \begin{macrocode} \newif\if@cref@refconsecutive% \def\cref@isrefconsecutive#1#2{% @@ -1677,12 +1680,11 @@ % % The internal \cmd{\@setcrefrange} macro deals with typesetting % reference ranges, just as \cmd{\@setcref} does for normal -% references. The actual typesetting is no more complicated in the -% range case; it's the error checking that makes the code so much -% longer. We now have to check whether \emph{two} references are -% undefined, whether \emph{two} reference formats are undefined, -% whether the reference types are consistent, and also combinations of -% these various errors. +% references. The actual typesetting is no more complicated in the range +% case; it's the error checking that makes the code so much longer. We +% now have to check whether \emph{two} references are undefined, whether +% \emph{two} reference formats are undefined, whether the reference types +% are consistent, and also combinations of these various errors. % \begin{macrocode} \def\@setcrefrange#1#2#3#4{% \begingroup% @@ -1730,8 +1732,8 @@ % \end{macrocode} % If reference types are identical, typeset reference range, % otherwise display warning.\\ -% (Note: there's no need to check if reference format for second -% type is defined, since if it isn't it will be caught here as a +% (Note: there's no need to check if reference format for second type +% is defined, since if it isn't it will be caught here as a % non-identical type.) % \begin{macrocode} \ifx\formata\formatb% @@ -1748,9 +1750,9 @@ \endgroup} % \end{macrocode} % -% We again separate out the very final typesetting step into a -% separate macro, in order to make it easier to redefine things later -% to make them work with the \package{hyperref} package. +% We again separate out the very final typesetting step into a separate +% macro, in order to make it easier to redefine things later to make them +% work with the \package{hyperref} package. % \begin{macrocode} \def\@@setcrefrange#1#2#3{% \cref@getlabel{#2}{\@labela}% @@ -1772,16 +1774,15 @@ % \subsection{Reference Format Customisation Commands} % % \subsubsection{Format Component Commands} -% The reference formats are usually constructed out of components -% defined by the user-level \cmd{\crefname}, \cmd{\Crefname}, -% \cmd{\creflabel} and \cmd{\crefrangelabel} commands. They simply use -% the supplied arguments to define appropriately named macros -% containing the formatting components. If the corresponding -% \cmd{\Crefname} or \cmd{\crefname} variant is not already defined, -% \cmd{\crefname} and \cmd{\Crefname} define it to be a version with -% the first letter capitalised or lower-cased, respectively. -% \cmd{\@crefdefineallformats} is then called to define all the -% formats from the new components. +% The reference formats are usually constructed out of components defined +% by the user-level \cmd{\crefname}, \cmd{\Crefname}, \cmd{\creflabel} +% and \cmd{\crefrangelabel} commands. They simply use the supplied +% arguments to define appropriately named macros containing the +% formatting components. If the corresponding \cmd{\Crefname} or +% \cmd{\crefname} variant is not already defined, \cmd{\crefname} and +% \cmd{\Crefname} define it to be a version with the first letter +% capitalised or lower-cased, respectively. \cmd{\@crefdefineallformats} +% is then called to define all the formats from the new components. % \begin{macrocode} \newcommand{\crefdefaultlabelformat}[1]{% \def\cref@default@label##1##2##3{#1}} @@ -1805,21 +1806,20 @@ % \end{macrocode} % % The \cmd{\@crefname} utility macro does the real work of defining -% format names, by defining an appropriately named command to contain -% the format component, and using the first argument (``cref'' of -% ``Cref'') to determine how to define the corresponding command with -% the other capitalisation. +% format names, by defining an appropriately named command to contain the +% format component, and using the first argument (``cref'' of ``Cref'') +% to determine how to define the corresponding command with the other +% capitalisation. % \begin{macrocode} \def\@crefname#1#2#3#4{% \begingroup% \expandafter\gdef\csname #1@#2@name\endcsname{#3}% \expandafter\gdef\csname #1@#2@name@plural\endcsname{#4}% % \end{macrocode} -% The following \cmd{\@tmpa} macro makes use of the fact that the -% first character of \#1 is ``c'' for lower-case and ``C'' for -% upper-case, in order to wrap the capitalisation-dependent parts in -% macros so that the rest of the code can be capitalisation-variant -% agnostic. +% The following \cmd{\@tmpa} macro makes use of the fact that the first +% character of \#1 is ``c'' for lower-case and ``C'' for upper-case, in +% order to wrap the capitalisation-dependent parts in macros so that the +% rest of the code can be capitalisation-variant agnostic. % \begin{macrocode} \def\@tmpa##1##2\@nil{% \if##1c% @@ -1835,10 +1835,10 @@ % \begin{macrocode} \@ifundefined{\@other @#2@name}{% % \end{macrocode} -% Define \cmd{\@tmpa} and \cmd{@tmpb} to be partial expansions -% (expanded just once) of the macros for the capitalisation variant -% we've just defined above. The \cmd{\@toska} token register just -% makes the code less verbose. +% Define \cmd{\@tmpa} and \cmd{@tmpb} to be partial expansions (expanded +% just once) of the macros for the capitalisation variant we've just +% defined above. The \cmd{\@toska} token register just makes the code +% less verbose. % \begin{macrocode} \expandafter\expandafter\expandafter\def% \expandafter\expandafter\expandafter\@tmpa% @@ -1876,12 +1876,11 @@ % \end{macrocode} % % -% \cmd{\@crefconstructcomponents} utility macro puts the reference -% format components for the specified reference type into temporary -% macros, for use by later macros. The ridiculous number of ``\#'' -% characters ensure that enough are left when they come to be used -% later (pairs ``\#\#'' are collapsed to a single ``\#'' each time the -% code is expanded). +% \cmd{\@crefconstructcomponents} utility macro puts the reference format +% components for the specified reference type into temporary macros, for +% use by later macros. The ridiculous number of ``\#'' characters ensure +% that enough are left when they come to be used later (pairs ``\#\#'' +% are collapsed to a single ``\#'' each time the code is expanded). % \begin{macrocode} \def\@crefconstructcomponents#1{% \@ifundefined{cref@#1@label}{% @@ -1934,10 +1933,9 @@ % \end{macrocode} % % The \cmd{\@crefdefineformat} et al.\ macros construct calls to -% \cmd{\crefformat} et al.\ for the supplied reference type that -% define the corresponding formats in terms of the format -% components. This is mostly just an arduous exercise in controlling -% macro expansion order. +% \cmd{\crefformat} et al.\ for the supplied reference type that define +% the corresponding formats in terms of the format components. This is +% mostly just an arduous exercise in controlling macro expansion order. % \begin{macrocode} \def\@crefdefineformat#1{% \begingroup% @@ -1946,8 +1944,8 @@ % \begin{macrocode} \@crefconstructcomponents{#1}% % \end{macrocode} -% Assemble the arguments for \cmd{\crefformat} and \cmd{\Crefformat} -% from the components. +% Assemble the arguments for \cmd{\crefformat} and \cmd{\Crefformat} from +% the components. % \begin{macrocode} \expandafter\expandafter\expandafter\def% \expandafter\expandafter\expandafter\@tmpfirst% @@ -2026,8 +2024,8 @@ \expandafter\expandafter\expandafter{% \expandafter\creflastconjunction\@tmplabel}% % \end{macrocode} -% Bundle all four arguments for \cmd{\crefmultiformat} in token -% register \cmd{\@toksb}, then call it. +% Bundle all four arguments for \cmd{\crefmultiformat} in token register +% \cmd{\@toksb}, then call it. % \begin{macrocode} \toksdef\@toksa=0% \toksdef\@toksb=1% @@ -2043,8 +2041,8 @@ \@toksa={\crefmultiformat{#1}}% \expandafter\the\expandafter\@toksa\the\@toksb% % \end{macrocode} -% Bundle all four arguments for \cmd{\Crefmultiformat} in token -% register \cmd{\@toksb}, then call it. +% Bundle all four arguments for \cmd{\Crefmultiformat} in token register +% \cmd{\@toksb}, then call it. % \begin{macrocode} \@toksb={}% \expandafter\cref@append@toks\expandafter\@toksb\expandafter{% @@ -2141,10 +2139,10 @@ % complete control over the format of different reference types. They % override the component-based formats, simply using the supplied % arguments to define appropriately named formatting macros, which are -% called by \cmd{\@setcref}. The only moderately interesting part is -% that if the corresponding \cmd{\Crefformat} or \cmd{\crefformat} -% variant is not already defined, they define it to be a version with -% the first letter capitalised or lower-cased. +% called by \cmd{\@setcref}. The only moderately interesting part is that +% if the corresponding \cmd{\Crefformat} or \cmd{\crefformat} variant is +% not already defined, they define it to be a version with the first +% letter capitalised or lower-cased. % \begin{macrocode} \newcommand{\crefformat}[2]{\@crefformat{cref}{#1}{#2}} \newcommand{\Crefformat}[2]{\@crefformat{Cref}{#1}{#2}} @@ -2161,19 +2159,17 @@ % \end{macrocode} % % The utility macros do the real work, by using the first argument -% (``cref'' or ``Cref'', and ``crefrange'' or ``Crefrange'') to -% determine how to define the corresponding command with the other -% capitalisation. +% (``cref'' or ``Cref'', and ``crefrange'' or ``Crefrange'') to determine +% how to define the corresponding command with the other capitalisation. % \begin{macrocode} \def\@crefformat#1#2#3{% \begingroup% \expandafter\gdef\csname #1@#2@format\endcsname##1##2##3{#3}% % \end{macrocode} -% The following \cmd{\@tmpa} macro makes use of the fact that the -% first character of \#1 is ``c'' for lower-case and ``C'' for -% upper-case, in order to wrap the capitalisation-dependent parts in -% macros so that the rest of the code can be capitalisation-variant -% agnostic. +% The following \cmd{\@tmpa} macro makes use of the fact that the first +% character of \#1 is ``c'' for lower-case and ``C'' for upper-case, in +% order to wrap the capitalisation-dependent parts in macros so that the +% rest of the code can be capitalisation-variant agnostic. % \begin{macrocode} \def\@tmpa##1##2\@nil{% \if##1c% @@ -2189,9 +2185,9 @@ % \begin{macrocode} \@ifundefined{\@other @#2@format}{% % \end{macrocode} -% Define \cmd{\@tmpa} to be a partial expansion (expanded just once) -% of the capitalisation variant we've just defined above. The -% \cmd{\@toska} token register just makes the code less verbose. +% Define \cmd{\@tmpa} to be a partial expansion (expanded just once) of +% the capitalisation variant we've just defined above. The \cmd{\@toska} +% token register just makes the code less verbose. % \begin{macrocode} \toksdef\@toksa=0% \@toksa={\def\@tmpa##1##2##3}% @@ -2223,11 +2219,10 @@ \expandafter\gdef\csname #1@#2@format\endcsname% ##1##2##3##4##5##6{#3}% % \end{macrocode} -% The following \cmd{\@tmpa} macro makes use of the fact that the -% first character of \#1 is ``c'' for lower-case and ``C'' for -% upper-case, in order to wrap the capitalisation-dependent parts in -% macros so that the rest of the code can be capitalisation-variant -% agnostic. +% The following \cmd{\@tmpa} macro makes use of the fact that the first +% character of \#1 is ``c'' for lower-case and ``C'' for upper-case, in +% order to wrap the capitalisation-dependent parts in macros so that the +% rest of the code can be capitalisation-variant agnostic. % \begin{macrocode} \def\@tmpa##1##2\@nil{% \if##1c% @@ -2243,9 +2238,9 @@ % \begin{macrocode} \@ifundefined{\@other @#2@format}{% % \end{macrocode} -% Define \cmd{\@tmpa} to be a partial expansion (expanded just once) -% of the capitalisation variant we've just defined above. The -% \cmd{\@toska} token register just makes the code less verbose. +% Define \cmd{\@tmpa} to be a partial expansion (expanded just once) of +% the capitalisation variant we've just defined above. The \cmd{\@toska} +% token register just makes the code less verbose. % \begin{macrocode} \toksdef\@toksa=0% \@toksa={\def\@tmpa##1##2##3##4##5##6}% @@ -2279,11 +2274,10 @@ \expandafter\gdef\csname #1@#2@format@middle\endcsname##1##2##3{#5}% \expandafter\gdef\csname #1@#2@format@last\endcsname##1##2##3{#6}% % \end{macrocode} -% The following \cmd{\@tmpa} macro makes use of the fact that the -% first character of \#1 is ``c'' for lower-case and ``C'' for -% upper-case, in order to wrap the capitalisation-dependent parts in -% macros so that the rest of the code can be capitalisation-variant -% agnostic. +% The following \cmd{\@tmpa} macro makes use of the fact that the first +% character of \#1 is ``c'' for lower-case and ``C'' for upper-case, in +% order to wrap the capitalisation-dependent parts in macros so that the +% rest of the code can be capitalisation-variant agnostic. % \begin{macrocode} \def\@tmpa##1##2\@nil{% \if##1c% @@ -2300,9 +2294,9 @@ % \begin{macrocode} \@ifundefined{\@other @#2@format@first}{% % \end{macrocode} -% Define \cmd{\@tmpa} to be a partial expansion (expanded just once) -% of the capitalisation variant we've just defined above. The -% \cmd{\@toska} token register just makes the code less verbose. +% Define \cmd{\@tmpa} to be a partial expansion (expanded just once) of +% the capitalisation variant we've just defined above. The \cmd{\@toska} +% token register just makes the code less verbose. % \begin{macrocode} \toksdef\@toksa=0% \@toksa={\def\@tmpa##1##2##3}% @@ -2366,11 +2360,10 @@ \expandafter\gdef\csname #1@#2@format@last\endcsname% ##1##2##3##4##5##6{#6}% % \end{macrocode} -% The following \cmd{\@tmpa} macro makes use of the fact that the -% first character of \#1 is ``c'' for lower-case and ``C'' for -% upper-case, in order to wrap the capitalisation-dependent parts in -% macros so that the rest of the code can be capitalisation-variant -% agnostic. +% The following \cmd{\@tmpa} macro makes use of the fact that the first +% character of \#1 is ``c'' for lower-case and ``C'' for upper-case, in +% order to wrap the capitalisation-dependent parts in macros so that the +% rest of the code can be capitalisation-variant agnostic. % \begin{macrocode} \def\@tmpa##1##2\@nil{% \if##1c% @@ -2387,9 +2380,9 @@ % \begin{macrocode} \@ifundefined{\@other @#2@format@first}{% % \end{macrocode} -% Define \cmd{\@tmpa} to be a partial expansion (expanded just once) -% of the capitalisation variant we've just defined above. The -% \cmd{\@toska} token register just makes the code less verbose. +% Define \cmd{\@tmpa} to be a partial expansion (expanded just once) of +% the capitalisation variant we've just defined above. The \cmd{\@toska} +% token register just makes the code less verbose. % \begin{macrocode} \toksdef\@toksa=0% \@toksa={\def\@tmpa##1##2##3##4##5##6}% @@ -2480,10 +2473,10 @@ % \end{macrocode} % If the last reference conjunction hasn't been modified from its % default, define the last group conjunction to include an extra -% comma. However, if the user has modified the last reference -% conjunction but hasn't defined the last group conjunction, they will -% expect the last group conjunction to be identical to their last -% reference conjunction definition, so do that. +% comma. However, if the user has modified the last reference conjunction +% but hasn't defined the last group conjunction, they will expect the +% last group conjunction to be identical to their last reference +% conjunction definition, so do that. % \begin{macrocode} \@ifundefined{creflastgroupconjunction}{% \def\@tmpa{ and~}% @@ -2494,10 +2487,9 @@ \fi}{}% % \end{macrocode} % Define default names (and in the case of equations, also the label -% format). We define the lowercase and capitalised versions -% separately, rather than relying on the automatic definitions, -% because the code produced by the poor man's sed script is then -% slightly tidier. +% format). We define the lowercase and capitalised versions separately, +% rather than relying on the automatic definitions, because the code +% produced by the poor man's sed script is then slightly tidier. % \begin{macrocode} \@ifundefined{cref@equation@name}{% \@crefname{cref}{equation}{eq.}{eqs.}% @@ -2679,11 +2671,11 @@ % % % \subsection{\package{hyperref} Support} -% If the \package{hyperref} package is loaded, we add hyper-link -% support to \package{cleveref}. Since \package{hyperref} messes -% around with some of the same \LaTeX{} internals as -% \package{cleveref}, we also have to override some of its -% redefinitions so that they work with \package{cleveref}. +% If the \package{hyperref} package is loaded, we add hyper-link support +% to \package{cleveref}. Since \package{hyperref} messes around with some +% of the same \LaTeX{} internals as \package{cleveref}, we also have to +% override some of its redefinitions so that they work with +% \package{cleveref}. % \begin{macrocode} \@ifpackageloaded{hyperref}{% \PackageInfo{cleveref}{`hyperref' support loaded} @@ -2717,8 +2709,8 @@ % \end{macrocode} % % The \package{hyperref} package stores the original -% \cmd{\refstepcounter} definition as \cmd{\H@refstepcounter}, which -% we therefore need to modify so that it adds the extra information to +% \cmd{\refstepcounter} definition as \cmd{\H@refstepcounter}, which we +% therefore need to modify so that it adds the extra information to % \cmd{\@currentlabel}. % \begin{macrocode} \def\H@refstepcounter#1{% @@ -2734,8 +2726,8 @@ % The original \cmd{\refstepcounter}, as stored earlier in % \cmd{\cref@old@refstepcounter}, already calls \H@refstepcounter if % \package{hyperref} is loaded, and we just redefined it to store the -% type information. So we only need to change \cmd{\@currentlabel} in -% our \cmd{\refstepcounter} if an optional argument was supplied. +% type information. So we only need to change \cmd{\@currentlabel} in our +% \cmd{\refstepcounter} if an optional argument was supplied. % \begin{macrocode} \def\refstepcounter@noarg#1{\cref@old@refstepcounter{#1}% } @@ -2751,8 +2743,8 @@ % % We again make \cmd{\appendix} redefine things so that the label type % for chapters or sections is exceptionally overridden and set to -% ``appendix'' instead. But this time, it is \cmd{\H@refstepcounter} -% that needs to be redefined. +% ``appendix'' instead. But this time, it is \cmd{\H@refstepcounter} that +% needs to be redefined. % \begin{macrocode} \renewcommand\appendix{% \cref@old@appendix% @@ -2795,9 +2787,8 @@ % \end{macrocode} % % Redefine \cmd{\cref} and all the others to allow starred variants, -% which don't create hyper-links. The starred variants simply set a -% flag, which is tested in \cmd{\@@setcref} and \cmd{\@@setrangeref} -% (below). +% which don't create hyper-links. The starred variants simply set a flag, +% which is tested in \cmd{\@@setcref} and \cmd{\@@setrangeref} (below). % \begin{macrocode} \newif\if@crefstarred \DeclareRobustCommand{\cref}{% @@ -2817,8 +2808,8 @@ % \end{macrocode} % % Redefine \cmd{\@@setcref} and \cmd{\@@setrangeref} to create -% hyper-links (unless the starred flag is set), using the extra -% arguments supplied in \cmd{\r@\meta{label}} (via the aux file) by +% hyper-links (unless the starred flag is set), using the extra arguments +% supplied in \cmd{\r@\meta{label}} (via the aux file) by % \package{hyperref}. % \begin{macrocode} \def\@@setcref#1#2{% @@ -2844,6 +2835,24 @@ }{} % \end{macrocode} % +% Redefine \cmd{\ref} command to provide a starred variant with the same +% behaviour as \package{hyperref}'s \cmd{\ref*}. As before, we defer the +% redefinition until the beginning of the document, to ensure it +% `takes'. \package{hyperref} stores the original \cmd{\@setref} in +% \cmd{real@setref}. +% \begin{macrocode} +\AtBeginDocument{% + \DeclareRobustCommand{\ref}{\@ifstar\cref@refstar\cref@ref} + \def\cref@refstar#1{% + \expandafter\ifx\csname r@#1\endcsname\relax% + \let\@result\relax% + \else% + \cref@getlabel{#1}{\@result}% + \fi% + \expandafter\real@setref\csname r@#1\endcsname{\cref@reflabel}{#1}}% +} +% \end{macrocode} +% % % \subsection{\package{ntheorem} Support} % If \package{ntheorem} is loaded, we need to modify its theorem @@ -2858,9 +2867,9 @@ % \end{macrocode} % % Newer versions of \package{ntheorem} require a call to -% \cmd{\theorem@prework} when typesetting theorems. If an older -% version of \package{ntheorem} is being used, we just \cmd{\let} it -% to \cmd{\relax} to make sure it's defined. +% \cmd{\theorem@prework} when typesetting theorems. If an older version +% of \package{ntheorem} is being used, we just \cmd{\let} it to +% \cmd{\relax} to make sure it's defined. % \begin{macrocode} \@ifundefined{theorem@prework}{\let\theorem@prework\relax}{} % \end{macrocode} @@ -2957,9 +2966,9 @@ % \end{macrocode} % % -% Define global macro \cmd{\cref@text} to store the text produced by -% the \cmd{\cref} commands, and open an output stream for writing the -% script before starting to process to document body. +% Define global macro \cmd{\cref@text} to store the text produced by the +% \cmd{\cref} commands, and open an output stream for writing the script +% before starting to process to document body. % \begin{macrocode} \edef\cref@text{} \AtBeginDocument{% @@ -2967,35 +2976,35 @@ \immediate\openout\@crefscript=\jobname.sed% } % \end{macrocode} -% % -% After processing the document body, we re-read in the temporary -% script file, and write it out again to the final sed script file, -% escaping regexp special characters in the process. The escaping is -% carried out by turning the regexp special characters into active -% characters, and defining them to expand to their escaped form. This -% involves a lot of juggling of catcodes and lccodes! +% +% After processing the document body, we re-read in the temporary script +% file, and write it out again to the final sed script file, escaping +% regexp special characters in the process. The escaping is carried out +% by turning the regexp special characters into active characters, and +% defining them to expand to their escaped form. This involves a lot of +% juggling of catcodes and lccodes! % % Both \cmd{\DeclareOption} and \cmd{\AtEndDocument} store their % arguments in token lists, so all the following \TeX code is already % tokenised long before it is expanded and evaluated. Thus there is no % (easy) way to change the catcodes of the characters appearing here -% before they are tokenised. In one way this is convenient: the -% catcode changes we make don't ``take'' until evaluated, so we can -% continue to use the standard \TeX characters ($\backslash$, \{, \} -% etc.) even after the lines containing the catcode commands. But in -% another, more significant, way, it is very inconvenient: it makes it -% difficult to define the regexp special characters as active -% characters, since it's impossible to directly create tokens with the -% correct char- and catcodes. +% before they are tokenised. In one way this is convenient: the catcode +% changes we make don't ``take'' until evaluated, so we can continue to +% use the standard \TeX characters ($\backslash$, \{, \} etc.) even after +% the lines containing the catcode commands. But in another, more +% significant, way, it is very inconvenient: it makes it difficult to +% define the regexp special characters as active characters, since it's +% impossible to directly create tokens with the correct char- and +% catcodes. % % We get around this by creating the unusual charcode/catcode -% combinations using the \cmd{\lowercase} trick (\cmd{\lowercase} -% changes the charcodes of all characters in its argument to their -% lccodes, but \emph{leaves} their catcodes alone). That way, the -% argument of \cmd{\AtEndDocument} is tokenised correctly, and when it -% comes to be expanded and evaluated, the \cmd{\lowercase} commands -% create tokens with the correct char- and catcodes. +% combinations using the \cmd{\lowercase} trick (\cmd{\lowercase} changes +% the charcodes of all characters in its argument to their lccodes, but +% \emph{leaves} their catcodes alone). That way, the argument of +% \cmd{\AtEndDocument} is tokenised correctly, and when it comes to be +% expanded and evaluated, the \cmd{\lowercase} commands create tokens +% with the correct char- and catcodes. % \begin{macrocode} \AtEndDocument{% \immediate\closeout\@crefscript% @@ -3022,8 +3031,8 @@ \lccode`~=36\lowercase{\def~{\string/\string$}}% $ \lccode`~=0 \lccode`/=0 \catcode`~=12 % \end{macrocode} -% Read lines from the temporary script file, expand them to escape -% regexp special characters, and store them in \cmd{\cref@text}. +% Read lines from the temporary script file, expand them to escape regexp +% special characters, and store them in \cmd{\cref@text}. % \begin{macrocode} \def\cref@text{}% \immediate\read\@crefscript to \@tmpa% @@ -3048,8 +3057,8 @@ % \end{macrocode} % Add some rules to remove likely \package{cleveref} preamble % commands. We use the \cmd{\lowercase} trick again for writing the -% $\backslash$, \{ and \} characters. (This could be done in other -% ways, but since we're in \cmd{\lowercase} mood, why not go with it!) +% $\backslash$, \{ and \} characters. (This could be done in other ways, +% but since we're in \cmd{\lowercase} mood, why not go with it!) % \begin{macrocode} \begingroup% \lccode`|=92 \lccode`<=123 \lccode`>=125 \lccode`C=67 @@ -3161,7 +3170,7 @@ } % \end{macrocode} % -% +% % The \cmd{\cref@writescript} utility macro does the actual writing of % the substitution rule to the script. % \begin{macrocode} @@ -3220,7 +3229,7 @@ %% %% End of file `cleveref.dtx'. -%%% Local Variables: +%%% Local Variables: %%% mode: doctex %%% TeX-master: t -%%% End: +%%% End: |