summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/tools/varioref.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-10-04 20:57:14 +0000
committerKarl Berry <karl@freefriends.org>2019-10-04 20:57:14 +0000
commit70aaae3b3c98fb6357c846ad54ce2367e9682f50 (patch)
treef0446e015c31510a11ada780ad4978dce03ad104 /Master/texmf-dist/source/latex/tools/varioref.dtx
parentbe53f9d0af947622afca67b99c89a90d5c08dbd4 (diff)
latex2e (4oct19)
git-svn-id: svn://tug.org/texlive/trunk@52286 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/tools/varioref.dtx')
-rw-r--r--Master/texmf-dist/source/latex/tools/varioref.dtx642
1 files changed, 471 insertions, 171 deletions
diff --git a/Master/texmf-dist/source/latex/tools/varioref.dtx b/Master/texmf-dist/source/latex/tools/varioref.dtx
index 2417e9b1203..049bd0d55ea 100644
--- a/Master/texmf-dist/source/latex/tools/varioref.dtx
+++ b/Master/texmf-dist/source/latex/tools/varioref.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 1993-2016
+% Copyright (C) 1993-2019
%
% The LaTeX3 Project and any individual authors listed elsewhere
% in this file.
@@ -14,7 +14,7 @@
% The latest version of this license is in
% https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
-% version 2005/12/01 or later.
+% version 2008 or later.
%
% The list of all files belonging to the LaTeX `Tools Bundle' is
% given in the file `manifest.txt'.
@@ -22,19 +22,25 @@
% \fi
% \iffalse
%% Package varioref to use with LaTeX2e
-%% Copyright (C) 1992-2016 Frank Mittelbach, all rights reserved.
+%% Copyright (C) 1992-2019 Frank Mittelbach, all rights reserved.
%%
%% For additions or updates to the language options please contact
%% the author at
%%
%% frank.mittelbach@latex-project.org
%%
-%% In case of bugs, please use "latexbug.tex" (category tools) to report them.
+%% or open an issue at https://github.com/latex3/latex2e.
%%
%
%<package>\NeedsTeXFormat{LaTeX2e}[1995/05/16]
+%<package>\providecommand\DeclareRelease[3]{}
+%<package>\providecommand\DeclareCurrentRelease[2]{}
+%<package>
+%<package>\DeclareRelease{}{2016-02-16}{varioref-2016-02-16.sty}
+%<package>\DeclareCurrentRelease{}{2019-10-01}
+%<package>
%<package>\ProvidesPackage{varioref}
-%<package> [2016/02/16 v1.5c package for extended references (FMi)]
+%<package> [2019/09/08 v1.6b package for extended references (FMi)]
% \fi
%
%%
@@ -44,11 +50,32 @@
% \changes{v1.0g}{1994/05/27}{Use \cmd\DeclareRobustCommand}
% \changes{v1.5c}{2016/02/09}{Revamped some of the documentation to better
% explain how varioref could be used in a multi-lingual context}
-
+% \changes{v1.6a}{2019/08/25}{\cs{labelformat} and \cs{Ref} now available in the kernel
+% so removed from this package but only in new kernel}
+%
+%
+% \newcommand\NewIn[1]{\marginpar{\fbox{\fbox{\sffamily\tabular{l}New
+% in\\#1\endtabular}}}}
+% \newcommand\ChangedIn[1]{\marginpar{\fbox{\fbox{\sffamily\tabular{l}Changed
+% in\\#1\endtabular}}}}
+%
+% \providecommand\pkg[1]{\texttt{#1}}
+% \providecommand\option[1]{\texttt{#1}}
+% \providecommand\meta[1]{$\langle§\textit{#1}$\rangle$}
%
-% \newcommand\NewIn[1]{\marginpar{\fbox{\fbox{\sffamily\tabular{l}New in\\#1\endtabular}}}}
%
-% \title{The \texttt{varioref} package\thanks{This file
+% \makeatletter
+% \def\allowtofu{^^A
+%\def\UTFviii@undefined@err##1{^^A
+% \PackageWarning{inputenc}{Unicode character \expandafter
+% \UTFviii@splitcsname\string##1\relax
+% \MessageBreak
+% not set up for use with LaTeX}^^A
+% \raisebox{.8pt}{\fboxsep1pt\kern.1pt\fbox{$\cdot$}\kern.1pt}^^A
+% }}
+% \makeatother
+%
+% \title{The \pkg{varioref} package\thanks{This file
% has version number \fileversion, last
% revised \filedate.}}
% \author{Frank Mittelbach}
@@ -95,6 +122,23 @@
%
%
%
+% \section{Loading the package}
+%
+%
+% The suggested way of loading the package these days is by
+% \emph{always} using
+% the package option \option{nospace},
+% \NewIn{2019}
+% i.e.,
+% \begin{verbatim}
+% \usepackage[nospace]{varioref}
+%\end{verbatim}
+% See below for an explanation of why this is needed. There are some
+% other options that you may want to use additionally; they are
+% explained \vpageref{options}.
+%
+%
+%
% \section{The user interface}
%
%\DescribeMacro\vref The implementation of |\vref| below produces only
@@ -112,9 +156,11 @@
% number and again such a reference should normally be suppressed if
% we are referring to the current page. For this purpose the package
% defines the |\vpageref| command. It will produce the same strings as
-% |\vref| except that it doesn't start with the |\ref| and except that
+% |\vref| except that it doesn't start with the |\ref|. A further
+% difference is that
% it will produce the string that is saved in |\reftextcurrent| if
-% label and reference fall onto the same page. By defining
+% label and reference fall onto the same page (and no optional
+% argument is used). By defining
% |\reftextcurrent| to produce ``on this page'' or something similar,
% we can avoid that
% \begin{verbatim}
@@ -123,7 +169,7 @@
% comes out as ``\ldots~see the example which shows~\ldots'', which
% could be misleading.
%
-% You can put a space in front of |\vpageref| it will be ignored if
+% A space in front of |\vpageref| it will be ignored if
% the command doesn't produce any text at all.
%
% But in fact |\vpageref| allows even more control. If has two
@@ -162,7 +208,6 @@
%
%
% \DescribeMacro\vrefrange
-% \NewIn{1998}
% 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
@@ -203,12 +248,11 @@
% So if you have two (or more) labels you could retrieve their page
% numbers, compare them and then decide what to print. For example,
% the following not very serious definition (also using the
-% \texttt{ifthen} package)
+% \pkg{ifthen} package)
%\begin{verbatim}
-% \newcommand\amusingversion[2]{%
+% \newcommand\amusingversion[2]{the definition%
% \vrefpagenum\firstnum{#1}%
% \vrefpagenum\secondnum{#2}%
-% the definition%
% \ifthenelse{\equal\firstnum\secondnum}%
% {s of \ref{#1} and \ref{#2} \vpageref{#1}}%
% { of \ref{#1} \vpageref{#1} and of \ref{#2} \vpageref{#2}}%
@@ -224,44 +268,82 @@
% \begin{quote}
% \ldots the definition of 3 on the next page and of 4 on page~13
% \end{quote}
-% in case the are on different pages.
+% in case they are on different pages.
+%
+% \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
+% 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
+%\begin{verbatim}
+% \newcommand\amusingversion[2]{the definition%
+% \vpagerefcompare{#1}{#2}%
+% {s of \ref{#1} and \ref{#2} \vpageref{#1}}%
+% { of \ref{#1} \vpageref{#1} and of \ref{#2} \vpageref{#2}}%
+% }
+%\end{verbatim}
+% and you don't have to load the \pkg{ifthen} package any longer to
+% make it work.
+%
+% \DescribeMacro\vpagerefnearby
+% \NewIn{2019}
+% 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
+% \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
+% \cs{vpagerefcomparenearby} but this is only meant for package
+% writers, so it is only documented in the implementation section.}
+
%
%
-% The user commands |\vref|, |\vpageref|, and |\vpagerefrange| all
-% \NewIn{2001}
-% work by first removing any space on their left and then inserting
-% some space of their own (|\vref|, for example, a nonbreakable
-% space). That seemed like a good idea back then, but it has the
-% disadvantage that you can't use these macros in situations where you
-% definitely do not want any space before the generated text. E.g., in
-% situations like |(\vref{foo} ...)| you end up with a space after the
-% open parenthesis.
+% If you don't use the \texttt{nospace} option the user commands
+% |\vref|, |\vpageref|, and |\vpagerefrange| all work by first
+% removing any space on their left and then inserting some space of
+% their own (|\vref|, for example, a nonbreakable space). That seemed
+% like a good idea back then, but it has the disadvantage that you
+% can't use these macros in situations where you definitely do not
+% want any space before the generated text. E.g., in situations like
+% |(\vref{foo} ...)| you end up with a space after the open
+% parenthesis.
%
% \DescribeMacro{\vref*}
% \DescribeMacro{\vpageref*}
% \DescribeMacro{\vpagerefrange*}
-% Since it is too late to change the default behaviour I've added star
+% Since it was too late to change the default in 2001 I added star
% 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}
+% \ChangedIn{2019}
+% introduced the star forms as a means to 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
+% when necessary, but that does make the source more readable so it is
+% a good thing. This also has the advantage that the star forms are
+% now unnecessary again and can be used in the way implemeented by
+% \pkg{hyperref} if both packages are used together.
+%
+% In fact it would be much nicer to make that the
+% default but the package has been used by many people for so many
+% years that changing the default would break way to many older documents.
%
%
% \DescribeMacro\labelformat
-% \NewIn{2002}
% A reference via |\ref| produces by default the data associated with
% the corresponding |\label| command (typically a number); any
-% additional formatting has to be provided by the user. If, for
-% example, references to equations are always to be typeset as
-% ``equation (\textit{number})'', one has to code
-% ``\verb=equation (\ref{=\textit{key}\verb=})=''. With |\labelformat|
-% the \texttt{varioref} package offers a possibility to generate such
-% frills automatically. The command takes two arguments: the first is
-% the name of a counter and the second is its representation when
-% referenced. This means that for a successful usage, one has to know
-% the counter name being used for generating the label, though in
-% practice this should not pose a problem. The current counter number
-% is picked up as an argument.
-% Here are two examples:
+% additional formatting has to be provided by the user. With
+% |\labelformat| it is possible to declare scuch formatting for each
+% ``reference'' counter, e.g.,
%\begin{verbatim}
% \labelformat{section}{section~#1}
% \labelformat{equation}{equation~(#1)}}
@@ -273,25 +355,31 @@
% A side effect of using |\labelformat| is that, depending on the
% defined formatting, it becomes impossible to use |\ref| at the
% beginning of a sentence (if its replacement text starts with a
-% lowercase letter). To overcome this problem \texttt{varioref}
-% introduces the commands |\Ref| and |\Vref| that behave like
-% |\ref| and |\{vref| except that they uppercase the first token
-% of the generated string.
-%
-% To make |\Ref| or |\Vref| work properly the very first token in
-% the second argument of |\labelformat| has to be a simple \textsc{ascii}
-% letter, otherwise the capitalization will fail or worse, you will end
-% up with some error messages. If you actually need something more
-% complicated in this place (e.g., an accented letter)
-% you have to explicitly surround it with braces, to
-% identify the part that needs to be capitalized. For example, for
-% figure references in the Hungarian language you might want to write
-% |\labelformat{figure}{{\'a}bra~\thefigure}|.
-%
-% \DescribeMacro\vpagerefnum
+% lowercase letter).
+% \ChangedIn{2019}
+% For that reason \pkg{varioref} provided the commands |\Ref| and
+% |\Vref|. They behave like |\ref| and |\vref| except that they
+% uppercase the first token of the generated string. These days
+% |\labelformat| and |\Ref| are already provided by the \LaTeX{}
+% kernel; only |\Vref| is still defined within the \pkg{varioref}
+% package.
+%
+% To make |\Ref| or |\Vref| work properly the very first token in the
+% second argument of |\labelformat| has to be a simple \textsc{ascii}
+% or UTF-8 letter, otherwise the capitalization will fail or worse,
+% you will end up with some error messages. If you actually need
+% something more complicated in this place (e.g., an accented letter
+% not written as a UTF-8 character) you have to explicitly surround it
+% with braces, to identify the part that needs to be capitalized. For
+% example, for figure references in the Hungarian language you might
+% want to write |\labelformat{figure}{{\'a}bra~\thefigure}| or use
+% |\labelformat{figure}{ábra~\thefigure}| which avoids the brace
+% problem.
+%
+% \DescribeMacro\thevpagerefnum
% If you like to have |\vref| suppress the page number on pages where
% label and reference fall onto the same page, but prefer reference to
-% page numbers otherwise then |\vpagerefnum| can be used. This macro
+% 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
%\begin{verbatim}
@@ -321,10 +409,10 @@
%\end{verbatim}
% to achieve the same effect.
%
-% If more than one language is specified with \texttt{varioref} then
+% If more than one language is specified with \pkg{varioref} then
% it will start using the last language selected. Switching of
% languages is managed through Babel; nevertheless all languages of
-% interest need to be specified when \texttt{varioref} is loaded so
+% interest need to be specified when \pkg{varioref} is loaded so
% that it can integrate their strings into the Babel system.
%
%
@@ -404,7 +492,7 @@
%
%
%
-% \section{Options}
+% \section{Options} \label{options}
%
% As mentioned above the package supports all standard options offered
% by the Babel system to customize the strings produced, it may also
@@ -414,6 +502,19 @@
% development. The default \texttt{final} produces error message when
% a generated string falls onto a page boundary (see next section).
%
+% Newly introduced in 2019 are the options \option{space} (default)
+% 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
+% 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.
+%
+% This means that the star forms can then be used as defined by
+% \pkg{hyperref} for suppressing a hyperlink when both packages are
+% used together (which is a rather typical scenario these days).
+%
%
% \section{A few warnings}
%
@@ -425,7 +526,7 @@
% another (i.e., inserting one string, finding that this is wrong,
% inserting another string on the next run which makes the first
% string correct again, inserting \ldots). The current implementation
-% of \texttt{varioref} therefore issues an error message whenever the
+% of \pkg{varioref} therefore issues an error message whenever the
% generated text is broken across page boundaries, e.g.,
% \begin{quote}
% table 5 on the current \meta{page break} page
@@ -447,8 +548,10 @@
% At the end final a warning: every use of |\vref| will internally
% generate two macro names to keep track of the string positions
% within the document. As a result you may run out of name space or
-% main memory if you make heavy use of this macro on a small \TeX{}
-% installation.
+% main memory\footnote{Not really that likely these days, but one
+% never knows \ldots. In any case \TeX{} will process your document a
+% tiny bit faster.} if you make heavy use of this macro on a small
+% \TeX{} installation.
%\DescribeMacro\fullref For this reason the primitive command
% |\fullref| is also provided. This command can be used whenever you
% know for sure that label and reference can't fall onto nearby pages.
@@ -461,7 +564,7 @@
% The next bit of code contains the documentation driver file for
% \TeX{}, i.e., the file that will produce the documentation you are
% currently reading. It will be extracted from this file by the
-% \texttt{docstrip} program.
+% \pkg{docstrip} program.
% \begin{macrocode}
%<*driver>
\documentclass{ltxdoc}
@@ -622,6 +725,27 @@
\def\reftextlabelrange#1#2{\ref{#1} to~\ref{#2}}%
}}
% \end{macrocode}
+% Arabic option text was contributed by Ihab Samir Mattar
+% (\texttt{dr\_kremlin@hotmail.com}). As our standard documentation
+% workflow uses pdf\TeX{} the Arabic letters can't be displayed
+% easily, so you will see missing glyphs below. To see the real
+% letters you have to look at the source or package file.
+% \changes{v1.6b}{2019/09/8}{Option arabic added}
+% \begin{allowtofu}
+% \begin{macrocode}
+\DeclareOption{arabic}
+ {\vref@addto\extrasarabic{%
+ \def\reftextfaceafter {بالصفحة \reftextvario{المقابلة}{اللاحقة}}%
+ \def\reftextfacebefore{بالصفحة \reftextvario{المقابلة}{المُنْصَرِمَةٌ}}%
+ \def\reftextafter {بالصفحة \reftextvario{اللاحقة}{التالية}}%
+ \def\reftextbefore {بالصفحة \reftextvario{السابقة}{المُنْصَرِمَةٌ}}%
+ \def\reftextcurrent {ب\reftextvario{الصفحة الحالية}{هذه الصفحة}}%
+ \def\reftextfaraway#1{بالصفحة رقم~\pageref{#1}}%
+ \def\reftextpagerange#1#2{بالصفحات~\pageref{#1}--\pageref{#2}}%
+ \def\reftextlabelrange#1#2{\ref{#1} حتى~\ref{#2}}%
+ }}
+% \end{macrocode}
+% \end{allowtofu}
% \changes{v1.2a}{1998/11/27}{Added austrian defaults (identical to german)}
% The austrian defaults are the same as the german ones.
% \begin{macrocode}
@@ -1437,14 +1561,30 @@
\DeclareOption{final}{\AtEndOfPackage\vrefshowerrors} % the default
% \end{macrocode}
%
+%
+% Whether or not \pkg{varioref} uses its own white space and
+% removes the one in the source document is handeled by the
+% following two options. For historical reasons the default is to
+% handle the space, but the recommendation these days is to use
+% \texttt{nospace}.
+% \changes{v1.6a}{2019/08/25}{Provide options \texttt{space} and \texttt{nospace}}
+% \begin{macrocode}
+\newif\if@vrefhandlespace
+\DeclareOption{space} {\@vrefhandlespacetrue}
+\DeclareOption{nospace}{\@vrefhandlespacefalse}
+% \end{macrocode}
+%
+%
+%
+%
% After all options are declared we execute the default option
% \texttt{english} to set up the defaults and then call
% |\ProcessOptions*| to handle any option passed to the package.
% The star form is used since we want to execute the options in the
% order they are given (in case this isn't used together with the
-% \texttt{babel} package).
+% \pkg{babel} package).
% \begin{macrocode}
-\ExecuteOptions{english,final}
+\ExecuteOptions{english,final,space}
\ProcessOptions*
% \end{macrocode}
%
@@ -1470,12 +1610,23 @@
% internal and the user label. This command should be robust since
% the user might put it anywhere.
%
-% We now start by scanning for a star which means: do not add a
-% space in front of the generated text---ever.
+% We now start by scanning for a star and then call either
+% |\vp@gerefstar| or |\vp@geref|.
+% The space handling logic is a bit twisted these days: if the
+% option \texttt{space} is
+% in force then preceding spaces in the document are removed and
+% the star means that the command should not add its own
+% space. However, with option \texttt{nospace} any space already in the
+% source will be left alone and the command doesn't add its own
+% space either. Thus in this case the star form doesn't
+% have any effect and below |\vp@gerefstar| is let to
+% |\vp@geref|. This allows a package like \pkg{hyperef} to redefine
+% it and useit for its own tasks (like denoting that no link should
+% be produced).
% \begin{macrocode}
\DeclareRobustCommand\vpageref{\@ifstar
- {\let\vref@space\relax\vp@geref}%
- {\let\vref@space\space\vp@geref}}
+ {\let\vref@maybe@space\@empty\vp@gerefstar}%
+ {\let\vref@maybe@space\space \vp@geref}}
% \end{macrocode}
%
% \begin{macrocode}
@@ -1493,7 +1644,7 @@
% \begin{macro}{\vref@space}
% \changes{v1.4a}{2002/03/06}{Default added}
% A default for |\vref@space|. This isn't really needed except in
-% the case that somebody has hooked into the \texttt{varioref}
+% the case that somebody has hooked into the \pkg{varioref}
% interfaces at a lower level (which isn't really supported,
% but\ldots). So giving a default will prevent an error message in
% that case (and should hopefully produce the same behavior as before).
@@ -1507,13 +1658,12 @@
% \begin{macrocode}
\def\@vpageref[#1]{\@ifnextchar[%
% \end{macrocode}
-% The default for the second optional argument is a space which is
-% prefixed by |\unskip| to get rid of any leading space inserted
-% already.
+% By default the second optional argument is empty.
% \changes{v1.0h}{1994/06/11}{Pass first argument in both cases}
% \changes{v1.0i}{1994/06/20}{Do it correctly}
+% \changes{v1.6a}{2019/08/25}{Default for optional argumet changed}
% \begin{macrocode}
- {\@@vpageref{#1}}{\@@vpageref{#1}[\unskip\vref@space]}}
+ {\@@vpageref{#1}}{\@@vpageref{#1}[]}}
% \end{macrocode}
% \end{macro}
%
@@ -1525,10 +1675,14 @@
% \begin{macrocode}
\def\@@vpageref#1[#2]#3{%
% \end{macrocode}
-% First it switches to horizontal mode if necessary and also
-% removes any leading space.
+% First it switches to horizontal mode if necessary. If there was a
+% preceding space we remember its size in |\@tempskipa| and then remove it for
+% reinsertion later.
+% \changes{v1.6a}{2019/08/25}{Don't drop a preceding space completely
+% but reinsert it later after setting a label}
% \begin{macrocode}
- \leavevmode\unskip
+ \leavevmode
+ \@tempskipa\lastskip \unskip
% \end{macrocode}
% Then it advances the counter |\c@vrcnt| by one which is used to
% generate internal label names.
@@ -1561,15 +1715,37 @@
% special combination of packages.
%
% These days we actually use |\vref@label| instead of |\label| as
-% this avoids problems with Babel or \texttt{amsmath} redefining
+% this avoids problems with Babel or \pkg{amsmath} redefining
% the latter command.
% \changes{v1.4e}{2003/01/08}{Use \cs{vref@label} instead of
% \cs{label} (pr/3489)}
% \begin{macrocode}
\vref@label{\the\c@vrcnt @xvr}%
% \end{macrocode}
+% Since we have removed
+% any leading space above we now insert a space here after the
+% label. It is done here so that it is still visible from following
+% code---the space before the label would be hidden.
+% What kind of space depends on the options to the
+% package. If \texttt{space} was specified, we insert our own
+% space, namely |\vref@maybe@space|. This will typeset a space
+% unless the star form of the current command was used.
+% \begin{macrocode}
+ \if@vrefhandlespace
+ \vref@maybe@space
+ \else
+% \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.
+% \begin{macrocode}
+ \ifdim\@tempskipa=\z@ \else
+ \hskip\@tempskipa
+ \fi
+ \fi
+% \end{macrocode}
% \changes{v1.1g}{1998/05/10}{Test if inside AMS display (pr2175)}
-% Inside displays of the \texttt{amsmath} package the |\label| command
+% Inside displays of the \pkg{amsmath} package the |\label| command
% is redefined which makes the test for loops incorrect if a |\vref|
% is used in, say, |\intertext|. So we test this condition first and
% only do the test if |\label| doesn't have a special meaning.
@@ -1612,19 +1788,17 @@
%\end{verbatim}
% But this is not possible because it would result in getting
% `Labels may have changed\ldots' warnings for every run. Now we
-% are ready to produce the textual strings. Since we have removed
-% any leading space we now insert a space (unless this was the star
-% form of the command) and then compare the two
-% page references.
+% are ready to produce the textual strings.
% \begin{macrocode}
- \vref@space
\ifx\@tempa\thevpagerefnum
% \end{macrocode}
% If they are the same we insert the first argument into the input
% stream. Otherwise we insert the second argument. Recall that
% those are the two optional arguments of |...|. However, if the
% user explicitly requested an empty text string using the optional
-% argument we cancel any preceding space.
+% argument we cancel any preceding space since in this case we are
+% otherwise likely to end up with spaces one before and one after
+% |\vpageref|.
% \changes{v1.2f}{2000/07/07}{Don't output space if optional argument
% empty (pr/3230)}
% \begin{macrocode}
@@ -1635,7 +1809,14 @@
#1%
\fi
\else
- #2%
+% \end{macrocode}
+% If |#2| is empty we do nothing otherwise we insert it followed by
+% a space.
+% \begin{macrocode}
+ \def\@tempc{#2}%
+ \ifx\@tempc\@empty \else
+ #2\vref@space
+ \fi
% \end{macrocode}
% Now we check if the page number of the referenced object (stored
% in |\thevpagerefnum| is a single positive number.
@@ -1761,7 +1942,7 @@
% \changes{v1.0l}{1994/07/07}{Explicitly expand \cs{label} argument for babel}
%
% These days we actually use |\vref@label| instead of |\label| as
-% this avoids problems with Babel or \texttt{amsmath} redefining
+% this avoids problems with Babel or \pkg{amsmath} redefining
% the latter command.
% \changes{v1.4e}{2003/01/08}{Use \cs{vref@label} instead of
% \cs{label} (pr/3489)}
@@ -1778,12 +1959,38 @@
% \end{macro}
%
%
+% \begin{macro}{\vp@gerefstar}
+% The default code for the star form is identical to the previous
+% macro |\vp@geref|. It only produces a different result because
+% before calling it we set |\vref@maybe@space| to do nothing.
+%
+% The \pkg{hyperref} package can then change the meaning of this
+% command to suppress a hyperlink.
+%
+% It is is also a good way to check if we are running with a new
+% \pkg{varioref} by testing
+%\begin{verbatim}
+% \ifdefined\vp@gerefstar
+% ... code fore noew varioref
+% \else
+% ... code for old varioref
+% \fi
+%\end{verbatim}
+%
+% \changes{v1.6a}{2019/08/25}{Command added to support hyperref better}
+% \begin{macrocode}
+\let\vp@gerefstar\vp@geref
+% \end{macrocode}
+% \end{macro}
+%
+%
+
% \begin{macro}{\vref@label}
% \changes{v1.4e}{2003/01/08}{Macro added (pr/3489)}
% This macro is like |\label| in the kernel but without passing on
% |\@currentlabel|, ie useful if all we are interested in is the
% page number. It also has the effect that it is unaffected by
-% \texttt{amsmath} or Babel redefining the |\label| command.
+% \pkg{amsmath} or Babel redefining the |\label| command.
% \begin{macrocode}
\def\vref@label#1{\@bsphack
\protected@write\@auxout{}%
@@ -1830,19 +2037,48 @@
%
%
% \begin{macro}{\vref}
+% We start by scanning for a star form and then continue in a
+% different macro depending on the result.
% \changes{v1.3a}{2001/04/12}{Scan for star form}
-% We start by scanning for a star form in which case we do not put
-% any space before the generated text (only remove some).
-% \begin{macro}{\vr@f}
+% \changes{v1.6a}{2019/08/25}{Adjusted for new spacing regime}
% \begin{macrocode}
\DeclareRobustCommand\vref{\@ifstar
- {\let\vref@space\relax\vr@f}%
- {\let\vref@space\nobreakspace\vr@f}}
+ {\vref@star}{\vr@f}}
% \end{macrocode}
-% And now we do the real work\ldots
+% \end{macro}
+
+
+
+% \begin{macro}{\vref@star}
+%
+% 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
+% \changes{v1.6a}{2019/08/25}{Command added to support hyperref better}
+% \begin{macrocode}
+\newcommand\vref@star[2][]{%
+ \ref{#2}
+ \vpageref[#1]{#2}}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\vr@f}
+% The normal case is a little bit more elaborated \ldots
% \changes{v1.3c}{2001/09/04}{Correct typo in name}
+% \changes{v1.6a}{2019/08/25}{Adjusted for new spacing regime}
% \begin{macrocode}
-\def\vr@f#1{%
+\def\vr@f{%
+ \leavevmode
+% \end{macrocode}
+% If option \texttt{space} is used then we remove a preceding space
+% and add our own unbreakable space instead. Otherwise we don't do
+% any space-handling.
+% \begin{macrocode}
+ \if@vrefhandlespace
+ \unskip \nobreakspace
+ \fi
% \end{macrocode}
% The use of|\nobreakspace| or |~| after the |\unskip| means that
% this command will always produce a normal space while
@@ -1856,24 +2092,15 @@
% \changes{v1.2a}{1998/11/27}{Use \cs{nobreakspace} (pr/2909)}
% \changes{v1.2a}{1998/11/27}{Add \cs{leavevmode}}
%
-% Above comments all refer to the earlier versions where there was
-% no possibility to suppress the space at all. By now we have
-% |\vref*| and |\vpageref*| to suppress the in internally generated
-% space by redefining |\vref@space| appropriately.
-% \begin{macrocode}
- \leavevmode\unskip\vref@space
- \ref{#1}%
-% \end{macrocode}
-% That means we have have to use |\vpageref| and not the internal
-% |\@vpageref| --- otherwise we would pick up the
-% ``current'' definition for |\vref@space| instead of setting it
-% back to |\space|.
-% \changes{v1.4c}{2002/06/18}{Use \cs{vpageref} not \cs{@vpageref} (pr/3403)}
+% After having handled (or not handled) the spacing we call
+% |\vref@star| to scan the optional arguments and do the rest.
+% If that command has been altered by \pkg{hyperref} then the
+% current one needs altering too and does the argument scanning explicitly.
% \begin{macrocode}
- \vpageref[\unskip]{#1}}
+ \vref@star % in hyperref this needs to be explicit
+}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
% \begin{macro}{\is@pos@number}
@@ -2061,81 +2288,154 @@
% \end{macro}
%
%
-% \subsection{An extension of counter referencing}
-%
-% \begin{macro}{\refstepcounter}
-% \changes{v1.4a}{2002/02/24}{Macro redefined}
-%
-% At the moment a reference to a counter |foo| will generate the
-% equivalent of |\p@foo\thefoo| although not quite in this form. For
-% some applications it would be nice of one could have |\thefoo| being
-% an argument to |\p@foo| to be able to put material before and after
-% the number generated by |\thefoo|. This can be easily achieved with
-% a small change to one of the kernel commands as follows:
-% \begin{macrocode}
-\def\refstepcounter#1{\stepcounter{#1}%
- \protected@edef\@currentlabel
- {\csname p@#1\expandafter\endcsname\csname the#1\endcsname}%
-}
-% \end{macrocode}
-% The trick is to ensure that |\csname the#1\endcsname| is turned into
-% a single token before |\p@...| is expanded further. This way, if the
-% |\p@...| command is a macro with one argument it will receive
-% |\the...|. With the kernel code (i.e., without the |\expandafter|)
-% it will instead pick up |\csname| which would be disastrous.
-%
-% Using |\expandafter| instead of braces delimiting the argument is
-% better because, assuming that the |\p@...| command is not defined as
-% a macro with one argument, the braces will stay and prohibit kerning
-% that might otherwise happen between the glyphs generated by
-% |\the...| and surrounding glyphs.
-% \end{macro}
%
-% \begin{macro}{\labelformat}
+% \begin{macro}{\Vref}
% \changes{v1.4a}{2002/02/24}{Macro added}
-% A shortcut to set the |\p@...| macro for a counter. It will pick
-% up the counter representation as an argument so that it can be
-% specially formatted.
+% |\Vref| is the counterpart to |\vref| with |\ref| replaced by
+% |\Ref| in its definition.
+% \changes{v1.6a}{2019/08/25}{Adjusted for new spacing regime}
% \begin{macrocode}
-\def\labelformat#1{\expandafter\def\csname p@#1\endcsname##1}
+\DeclareRobustCommand\Vref{\@ifstar
+ {\Vref@star}%
+ {\Vr@f}}
% \end{macrocode}
% \end{macro}
-%
-% \begin{macro}{\Ref}
-% \changes{v1.4a}{2002/02/24}{Macro added}
-% This macro expands the result of |\ref| and then uppercases the
-% first token. Only useful if the label was generated via
-% |\labelformat| and contains some lower case letter at its start. If
-% the label starts with a complicated construct (e.g., an accented
-% letter) one has to surround everything that needs uppercasing in
-% a brace group in the definition of |\labelformat|.\footnote{There
-% is one problem with this approach: the braces are kept in a
-% normal \texttt{\textbackslash ref} which might spoil kerning.
-% Perhaps one day this needs redoing.}
-% \begin{macrocode}
-\DeclareRobustCommand\Ref[1]{\protected@edef\@tempa{\ref{#1}}%
- \expandafter\MakeUppercase\@tempa}
+%
+% \begin{macro}{\Vref@star}
+% \changes{v1.6a}{2019/08/25}{Command added to support hyperref better}
+% \begin{macrocode}
+\newcommand\Vref@star[2][]{%
+ \Ref{#2}
+ \vpageref[#1]{#2}}
% \end{macrocode}
% \end{macro}
-%
-% \begin{macro}{\Vref}
-% \changes{v1.4a}{2002/02/24}{Macro added}
+%
% \begin{macro}{\Vr@f}
% \changes{v1.4a}{2002/02/24}{Macro added}
% \changes{v1.4x}{2010/08/04}{Correct spacing -- same mistake as in \cs{vref}
% (pr/4123)}
-% |\Vref| is the counterpart to |\vref| with |\ref| replaced by
-% |\Ref| in its definition.
+% \changes{v1.6a}{2019/08/25}{Adjusted for new spacing regime}
% \begin{macrocode}
-\DeclareRobustCommand\Vref{\@ifstar
- {\let\vref@space\relax\Vr@f}%
- {\let\vref@space\nobreakspace\Vr@f}}
-\def\Vr@f#1{%
- \leavevmode\unskip\vref@space
- \Ref{#1}%
- \vpageref[\unskip]{#1}}
+\def\Vr@f{%
+ \if@vrefhandlespace
+ \unskip \vref@space
+ \fi
+ \Vref@star % in hyperref this needs to be explicit
+}
% \end{macrocode}
% \end{macro}
+
+
+% \begin{macro}{\vpagerefcompare}
+%
+% \changes{v1.6a}{2019/08/25}{Macro added}
+% \begin{macrocode}
+\DeclareRobustCommand\vpagerefcompare[2]{% label1, label2, TRUE, FALSE
+ \vrefpagenum\@tempa{#1}%
+ \vrefpagenum\@tempb{#2}%
+ \ifx\@tempa\@tempb
+ \expandafter\@firstoftwo
+ \else
+ \expandafter\@secondoftwo
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\vpagerefnearby}
+% \changes{v1.6a}{2019/08/25}{Macro added}
+% Test if |\vpageref| is going to be at most $\pm1$ off from
+% current page.
+% \begin{macrocode}
+\DeclareRobustCommand\vpagerefnearby[1]{% label, TRUE, FALSE
+ \leavevmode
+ \@tempskipa\lastskip \unskip
+ \global\advance\c@vrcnt\tw@ % keep oddness to not disturb \vrefvario
+ \vref@label{\the\c@vrcnt @vn}%
+ \ifdim\@tempskipa=\z@ \else
+ \hskip\@tempskipa
+ \fi
+ \vref@pagenum\@tempa{\the\c@vrcnt @vn}%
+ \is@pos@number\@tempa
+ {%
+ \vrefpagenum\@tempb{#1}%
+ \is@pos@number\@tempb
+ {%
+ \ifcase\numexpr \@tempa -\@tempb+1\relax
+ \or \or \else \expandafter \@thirdofthree \fi
+ \@firstoftwo
+ }%
+ {\@secondoftwo}%
+ }%
+ {\@secondoftwo}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+
+% \begin{macro}{\vpagerefcomparenearby}
+% \changes{v1.6a}{2019/08/25}{Macro added}
+% True if the two pages have arabic page numbers are at most off by
+% one so that |\vpageref| would produce a special string.
+%
+% This is n some sense a general version of |\vpagerefnearby| for
+% use in more complex situations. I.e., if you try to determine if
+% a larger set of references would be close to the current page and
+% you use each time |\vpagerefnearby| then you generate a lot of
+% internal labels for the current point. Thus by setting the label
+% yourself you can save processing time and space. On the other
+% hand you have to be careful to place the label into the right
+% place which can be a bit complicated if you look at the
+% definition of |\vpagerefnearby| that does all this automatically
+% for you. This is why the current macro is not discussed in the
+% user interface section as it is really just for package
+% developers.
+% \begin{macrocode}
+\DeclareRobustCommand\vpagerefcomparenearby[2]{% label1, label2, TRUE, FALSE
+ \vrefpagenum\@tempa{#1}%
+ \is@pos@number\@tempa
+ {%
+ \vrefpagenum\@tempb{#2}%
+ \is@pos@number\@tempb
+ {%
+ \ifcase\numexpr \@tempa -\@tempb+1\relax
+ \or \or \else \expandafter \@thirdofthree \fi
+ \@firstoftwo
+ }%
+ {\@secondoftwo}%
+ }%
+ {\@secondoftwo}%
+}
+% \end{macrocode}
+% \end{macro}
+
+%
+%
+% \subsubsection{Compatibility with older \LaTeX{} formats}
+%
+%
+% \begin{macro}{\labelformat}
+% \begin{macro}{\Ref}
+% \begin{macro}{\refstepcounter}
+% We don't need to define \cs{labelformat} and \cs{Ref} or change the
+% definition of \cs{refstepcounter} any longer because this is now
+% done in the \LaTeX{} kernel. However, if this package is used
+% together with an older kernel, this is not true, so for this
+% special case we keep the definitions.
+% \begin{macrocode}
+\ifx\labelformat\@undefined % assume we are in an older kernel
+ \def\labelformat#1{\expandafter\def\csname p@#1\endcsname##1}
+ \DeclareRobustCommand\Ref[1]{\protected@edef\@tempa{\ref{#1}}%
+ \expandafter\MakeUppercase\@tempa}
+ \def\refstepcounter#1{\stepcounter{#1}%
+ \protected@edef\@currentlabel
+ {\csname p@#1\expandafter\endcsname\csname the#1\endcsname}}
+\fi
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
% \end{macro}
%
% \begin{macrocode}