summaryrefslogtreecommitdiff
path: root/macros/latex/required/tools/varioref.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2024-06-03 03:02:26 +0000
committerNorbert Preining <norbert@preining.info>2024-06-03 03:02:26 +0000
commite83ddb0c0c40cddccb9e35b6a1f83b3a70fc2b3d (patch)
treeee8ec365464694362978c23540a534e20c29592c /macros/latex/required/tools/varioref.dtx
parentd751a6e51be81d6c1ba797cd91d4079e7e2e407b (diff)
CTAN sync 202406030302
Diffstat (limited to 'macros/latex/required/tools/varioref.dtx')
-rw-r--r--macros/latex/required/tools/varioref.dtx96
1 files changed, 49 insertions, 47 deletions
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 @@
%%
%
%<package>\NeedsTeXFormat{LaTeX2e}[1995/05/16]
-%<package>\providecommand\DeclareRelease[3]{}
-%<package>\providecommand\DeclareCurrentRelease[2]{}
%<package>
+%
+% For any rollback before 2019 load the 2016 version and hope for the best:
+%<package>\DeclareRelease{}{1994-06-01}{varioref-2016-02-16.sty}
%<package>\DeclareRelease{}{2016-02-16}{varioref-2016-02-16.sty}
%<package>\DeclareCurrentRelease{}{2019-10-01}
%<package>
%<package>\ProvidesPackage{varioref}
-%<package> [2022/01/09 v1.6f package for extended references (FMi)]
+%<package> [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{%