From e83ddb0c0c40cddccb9e35b6a1f83b3a70fc2b3d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 3 Jun 2024 03:02:26 +0000 Subject: CTAN sync 202406030302 --- macros/latex/required/tools/varioref.dtx | 96 ++++++++++++++++---------------- 1 file changed, 49 insertions(+), 47 deletions(-) (limited to 'macros/latex/required/tools/varioref.dtx') diff --git a/macros/latex/required/tools/varioref.dtx b/macros/latex/required/tools/varioref.dtx index e801c54f81..40b3038074 100644 --- a/macros/latex/required/tools/varioref.dtx +++ b/macros/latex/required/tools/varioref.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1993-2023 +% Copyright (C) 1993-2024 % % The LaTeX Project and any individual authors listed elsewhere % in this file. @@ -33,14 +33,15 @@ %% % %\NeedsTeXFormat{LaTeX2e}[1995/05/16] -%\providecommand\DeclareRelease[3]{} -%\providecommand\DeclareCurrentRelease[2]{} % +% +% For any rollback before 2019 load the 2016 version and hope for the best: +%\DeclareRelease{}{1994-06-01}{varioref-2016-02-16.sty} %\DeclareRelease{}{2016-02-16}{varioref-2016-02-16.sty} %\DeclareCurrentRelease{}{2019-10-01} % %\ProvidesPackage{varioref} -% [2022/01/09 v1.6f package for extended references (FMi)] +% [2024/05/23 v1.6g package for extended references (FMi)] % \fi % %% @@ -144,8 +145,8 @@ %\DescribeMacro\vref The implementation of |\vref| below produces only % a |\ref| when reference and |\label| are on the same page. It will % additionally produce one of the strings `on the facing page', `on -% the preceding page', or `on the following page', if label and -% reference differ by one and it will produce both |\ref| and +% the preceding page', or `on the following page' if label and +% reference differ by one; and it will produce both |\ref| and % |\pageref| when the difference is larger. The word `facing' is used % when label and reference both fall onto a double spread. However, % if a special page numbering scheme is used instead of the usual @@ -169,7 +170,7 @@ % comes out as ``\ldots~see the example which shows~\ldots'', which % could be misleading. % -% A space in front of |\vpageref| it will be ignored if +% A space in front of |\vpageref| will be ignored if % the command doesn't produce any text at all. % % But in fact |\vpageref| allows even more control. It has two @@ -210,7 +211,7 @@ % \DescribeMacro\vrefrange % This command is similar to |\vref| but it % takes two mandatory arguments denoting a range to refer to (e.g., a -% sequences of figures or a sequence of equations, etc.). So if +% sequence of figures or a sequence of equations, etc.). So if % |fig:a| is your first figure in the sequence and |fig:c| your last % you can write %\begin{verbatim} @@ -273,8 +274,8 @@ % \DescribeMacro\vpagerefcompare % \NewIn{2019} % For this kind of application the package also provides -% |\vpagerefcompare| as a command that takes four argument: two labels for -% comparison and a \meta{true} and \meta{false} argument. One of them +% |\vpagerefcompare| as a command that takes four arguments: two labels +% for comparison and a \meta{true} and \meta{false} argument. One of them % is executed depending on whether the two labels are on the same page % or on different pages. With its help the above definition could be % shortened to @@ -293,8 +294,9 @@ % Another command for conditional processing is |\vpagerefnearby|. It % takes three arguments: a label and a \meta{true} and \meta{false} % argument. It compares the page reference to the label with the -% current page number and if both are Arabic number and only differ by -% $\pm1$ the \meta{true} argument is executed otherwise the +% current page number; if each of these is a positive integer +% (expressed in Arabic numerals) and they differ by at most +% $\pm1$, the \meta{true} argument is executed, otherwise the % \meta{false} argument. In other words it tells you if a |\vpageref| % to the label would result in a textual reference to the previous, % current or next page.\footnote{There is also a @@ -320,11 +322,11 @@ % versions of the macros which do not add any space before the % generated text (they do nevertheless remove space at the left). % -% However, that too has problems (one is that \pkg{hyperref} +% However, that too has problems: one is that \pkg{hyperref} % \ChangedIn{2019} -% introduced the star forms as a means to generating references -% without hyperlinks (which is clearly the more important -% application). +% introduced the star forms as a means of generating references +% without hyperlinks, which is clearly the more important +% application. % So these days I recommend to always call the package with the option % \option{nospace} which prevents \pkg{varioref} from messing with the % space in front. Of course you are then responsible to always add it @@ -381,7 +383,7 @@ % label and reference fall onto the same page, but prefer reference to % page numbers otherwise then |\thevpagerefnum| can be used. This macro % hold the current page ``number'' when |\vpageref| and friends are -% executed. Thus, by defining, for example +% executed. Thus, by defining, for example, %\begin{verbatim} %\renewcommand\reftextfaceafter {on page~\thevpagerefnum} %\renewcommand\reftextfacebefore{on page~\thevpagerefnum} @@ -436,7 +438,7 @@ %\DescribeMacro\reftextafter %\DescribeMacro\reftextfaceafter Backward references use % |\reftextbefore| if the label is on the preceding page but invisible -% and |\reftextfacebefore| if it is one the facing page (i.e., if the +% and |\reftextfacebefore| if it is on the facing page (i.e., if the % current page number is odd). Similarly |\reftextafter| is used % when the label comes on the next page but one has to turn the page % and |\reftextfaceafter| if it is on the following but facing page. @@ -447,7 +449,7 @@ %\DescribeMacro\reftextfaraway Finally we have |\reftextfaraway| which % is used whenever label and reference differ by more than one or when % they aren't numeric. This macro is a bit different because it takes -% one argument, the symbolic reference string so that one cane make +% one argument, the symbolic reference string, so that one can make % use of |\pageref| in its replacement text. % % @@ -521,7 +523,7 @@ % and \option{nospace}. While the former is the default to allow % \NewIn{2019} % documents written in the last twenty years to continue to work -% correctly, I nowadays, suggest that you always use the package with +% correctly, I nowadays suggest that you always use the package with % the option \option{nospace}. This will stop \pkg{varioref} from % meddling with the spaces preceding commands and thus make the star % forms |\vref*| and |\vpageref*| unnecessary. @@ -536,7 +538,7 @@ % Defining commands like the ones described above poses some % interesting problems. Suppose, for example, that a generated text % like `on the next page' gets broken across pages. If this happens it -% is very difficult to find an acceptable solution and in fact can +% is very difficult to find an acceptable solution and it can, in fact, % even result in a document that will always change from one state to % another (i.e., inserting one string, finding that this is wrong, % inserting another string on the next run which makes the first @@ -699,7 +701,7 @@ % \begin{macro}{\reftextbefore} % \begin{macro}{\reftextcurrent} % \label{reftextbefore} The options do set the macros that -% generate the textual strings. Note, that they do not start with a +% generate the textual strings. Note that they do not start with a % space, the space is already added in the main macro below. % \changes{v1.2a}{1998/08/22}{Added American defaults for % \cs{reftextpagerange} and \cs{reftextlabelrange}} @@ -838,7 +840,7 @@ % the noun (clause); bertentangan is ``opposite'' in the sense of % ``facing''; berikutnya is ``next'' (in this context - actually % next-to-this, literally); berikutnya also translates as ``following -% this'' sebelumnya is ``preceding''; also ``previous'' ``ini'' translates, +% this''; sebelumnya is ``preceding'', also ``previous''; ``ini'' translates, % literally, as ``this'' but is also used in the sense of current page. % \changes{v1.4o}{2005/12/02}{Bahasa Malaysia defaults added.} % \begin{macrocode} @@ -1036,7 +1038,7 @@ \let\vrefrangeformat\vrefrangedefaultformat }} % \end{macrocode} -% Default string for dutch have been contributed by Frank Poppe +% Default strings for Dutch have been contributed by Frank Poppe % (\verb=POPPE@SWOV.NL=). % This option currently supports one additional string macro % |\refpagename| so that you can easily change to |bladzijde| @@ -1124,9 +1126,9 @@ \let\vrefrangeformat\vrefrangedefaultformat }} % \end{macrocode} -% The finnish strings were suggested by Matti Rintala +% The Finnish strings were suggested by Matti Rintala % (\verb=bitti@cs.tut.fi=) and Hillevi Gavel -% \verb=Hillevi.Gavel@mdh.se=. +% (\verb=Hillevi.Gavel@mdh.se=). % \changes{v1.0m}{1994/09/23}{Added finnish strings} % \changes{v1.4o}{2005/11/07}{Added a few more finnish strings} % \begin{macrocode} @@ -1200,10 +1202,10 @@ }} % \end{macrocode} % There are no good variants for German (I think and still think but -% this is a matter of taste :-). +% this is a matter of taste :-)). % \changes{v1.0b}{1994/01/31}{Replace in incorrect `def by `let} % The following definitions were recently suggested to me but since -% the original are in for a long time i don't want to change them +% the originals have been there for a long time I don't want to change them % now since that could make a lot of documents change their formatting. % If you fancy them, add a redefinition of the corresponding macro(s) % to the preamble of your document. @@ -1935,7 +1937,7 @@ % \end{macrocode} % But if \texttt{nospace} is in force we simply use the same space % value that was used in the source document (unless that was zero -% or non-existent. +% or non-existent). % \begin{macrocode} \ifdim\@tempskipa=\z@ \else \hskip\@tempskipa @@ -1978,7 +1980,7 @@ % \begin{macrocode} \vrefpagenum\thevpagerefnum{#3}% % \end{macrocode} -% Now after the internal label has served its purpose if would be +% Now after the internal label has served its purpose it would be % nice to free the memory it occupies by using something like % \begin{verbatim} % \global\expandafter\let @@ -2008,7 +2010,7 @@ \fi \else % \end{macrocode} -% If |#2| is empty we do nothing otherwise we insert it followed by +% If |#2| is empty we do nothing, otherwise we insert it followed by % a space. % \begin{macrocode} \def\@tempc{#2}% @@ -2017,7 +2019,7 @@ \fi % \end{macrocode} % Now we check if the page number of the referenced object (stored -% in |\thevpagerefnum| is a single positive number. +% in |\thevpagerefnum|) is a single positive number. % \begin{macrocode} \is@pos@number\thevpagerefnum {% @@ -2032,7 +2034,7 @@ }% % \end{macrocode} % If it is not a positive number we assign the largest possible -% number to |\@tempcnta| and thereby pretending that label and +% number to |\@tempcnta|, thereby pretending that label and % reference are miles away from each other. % \begin{macrocode} {\@tempcnta\maxdimen}% @@ -2049,7 +2051,7 @@ % Thus if the object falls onto an odd page then the reference is % on the facing even page (and so we insert |\reftextfaceafter|), % otherwise the object can not be seen from the reference (and we -% in insert |\reftextafter|). Don't be surprised if we are not +% insert |\reftextafter|). Don't be surprised if we are not % using |\thevpagerefnum| in the check. Since |\@tempcnta| has the same % value it is faster to use the register instead of parsing the % macro contents anew. @@ -2061,7 +2063,7 @@ % used. % Since the value of |\if@twoside| is evaluated before reading in % packages we could do better (saving some tokens) by defining -% the current macro in dependence of this boolean. +% the current macro depending on this boolean. % \begin{macrocode} \if@twoside \reftextfaceafter @@ -2075,11 +2077,11 @@ % If the object is not on the page following the reference we check % if it is on the page before the reference. In \LaTeX{} this % situation is not too common, for example with floats it normally -% does not occur, but of course it isn't impossible if you more +% does not occur, but of course it isn't impossible if you have more % than one reference to the same object, or if you have back % references to sections, theorems, etc. To test this we now % subtract two from the current value of |\@tempcnta| (which was -% set to one higher as the reference page number). Note, that +% set to one higher as the reference page number). Note that % subtraction is also possible if the value was |\maxdimen| --- we % still get something that is much larger than any sensible page % number. @@ -2131,7 +2133,7 @@ \reftextfaraway{#3}}% \fi % \end{macrocode} -% Finally we generate the internal label so that it can be check on +% Finally, we generate the internal label so that it can be checked on % the next run. This means that we compare the position after the % string with the position of the referenced object. There is one % thing to note: to conserve space we locally make |\@currentlabel| @@ -2252,8 +2254,8 @@ % The star form is easy (and just a convenient shortcut), just call % |\ref| followed by |\vpageref| and pass the optional argument to % the latter. We don't support the second optional argument of -% |\vpageref|, it that is needed one has to call both commands -% explicitly +% |\vpageref|, if that is needed one has to call both commands +% explicitly. % \changes{v1.6a}{2019/08/25}{Command added to support hyperref better} % \changes{v1.6e}{2020/07/25}{Changed for Japanese (gh/352)} % \begin{macrocode} @@ -2264,7 +2266,7 @@ % % \begin{macro}{\vrefformat,\vrefdefaultformat} % Japanese needs a different word order in \cs{vref@star} so this -% is separated out o that it can be changed on language level. +% is separated out so that it can be changed at the language level. % \changes{v1.6e}{2020/07/25}{Macro added (gh/352)} % \begin{macrocode} \def\vrefdefaultformat#1#2{% @@ -2293,7 +2295,7 @@ \unskip \nobreakspace \fi % \end{macrocode} -% The use of|\nobreakspace| or |~| after the |\unskip| means that +% The use of |\nobreakspace| or |~| after the |\unskip| means that % this command will always produce a normal space while % something like |\nobreak\space| will % react to settings of |\nonfrenchspacing|. @@ -2341,10 +2343,10 @@ % Now we have to check whether or not the whole string was parsed % into that register or some remainder was left over. Since we have % added a |\@nil| token at the very end we can use that to delimit -% the argument of |\is@pos@num@|. Note, that the added space in +% the argument of |\is@pos@num@|. Note that the added space in % |\is@pos@number| \vpageref[above]{isposnumber} gets parsed away % by the counter assignment. If it would be missing, and the full -% string would consist of a number, \TeX{}would try to replace +% string would consist of a number, \TeX{} would try to replace % |\@nil| by its definition to see if it would contain additional % digits and thus we would be in trouble at this point. % \begin{macrocode} @@ -2389,7 +2391,7 @@ % % \begin{macro}{\fullrefformat,\fullrefdefaultformat} % Japanese needs a different word order in \cs{fullref} so this -% is separated out o that it can be changed on language level. +% is separated out so that it can be changed at the language level. % \changes{v1.6e}{2020/07/25}{Macro added (gh/352)} % \begin{macrocode} \def\fullrefdefaultformat#1{% @@ -2523,7 +2525,7 @@ % % \begin{macro}{\vrefrangeformat,\vrefrangedefaultformat} % Japanese needs a different word order in \cs{vrefrange} so this -% is separated out o that it can be changed on language level. +% is separated out so that it can be changed at the language level. % \changes{v1.6d}{2020/07/20}{Macro added (gh/352)} % \begin{macrocode} \def\vrefrangedefaultformat#1#2#3{% @@ -2558,7 +2560,7 @@ % % \begin{macro}{\Vrefformat,\Vrefdefaultformat} % Japanese needs a different word order in \cs{Vref} so this -% is separated out o that it can be changed on language level. +% is separated out so that it can be changed at the language level. % \changes{v1.6e}{2020/07/25}{Macro added (gh/352)} % \begin{macrocode} \def\Vrefdefaultformat#1#2{% -- cgit v1.2.3