[latex3-commits] [git/LaTeX3-latex3-latex2e] varioref: more documentation [ci skip] (e65388ed)
Frank Mittelbach
frank.mittelbach at latex-project.org
Sun Sep 1 13:43:45 CEST 2019
Repository : https://github.com/latex3/latex2e
On branch : varioref
Link : https://github.com/latex3/latex2e/commit/e65388edceca501d4a6e7356b3b0ebcf709cdc84
>---------------------------------------------------------------
commit e65388edceca501d4a6e7356b3b0ebcf709cdc84
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Sun Sep 1 13:43:45 2019 +0200
more documentation [ci skip]
>---------------------------------------------------------------
e65388edceca501d4a6e7356b3b0ebcf709cdc84
required/tools/changes.txt | 8 +---
required/tools/varioref.dtx | 104 ++++++++++++++++++++++++++++----------------
2 files changed, 69 insertions(+), 43 deletions(-)
diff --git a/required/tools/changes.txt b/required/tools/changes.txt
index 7f6126d8..b2fc4e09 100644
--- a/required/tools/changes.txt
+++ b/required/tools/changes.txt
@@ -1,7 +1,3 @@
-2019-08-27 Frank Mittelbach <Frank.Mittelbach at latex-project.org>
-
- * varioref.dtx
-
=======================================================================
This file lists changes to the LaTeX2e files in reverse chronological order.
It is provided for convenience only. It therefore makes no claims to
@@ -12,7 +8,7 @@ are not part of the distribution.
2019-08-25 Frank Mittelbach <Frank.Mittelbach at latex-project.org>
* varioref.dtx: \labelformat and \Ref now available in the kernel
- so removed from this package
+ so removed from this package but only if running on new kernel
(subsection{Options}):
Provide options space and nospace
@@ -24,7 +20,7 @@ are not part of the distribution.
hyperref better
(subsubsection{Supporting ranges}):
- Added \vpagerefcompare
+ Added \vpagerefcompare, \vpagrefnearby and \vpagerefcomparenearby
2019-03-01 Frank Mittelbach <Frank.Mittelbach at latex-project.org>
diff --git a/required/tools/varioref.dtx b/required/tools/varioref.dtx
index 47a2cc69..b32d5eba 100644
--- a/required/tools/varioref.dtx
+++ b/required/tools/varioref.dtx
@@ -51,7 +51,7 @@
% \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}
+% so removed from this package but only in new kernel}
%
%
% \newcommand\NewIn[1]{\marginpar{\fbox{\fbox{\sffamily\tabular{l}New
@@ -197,7 +197,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
@@ -261,6 +260,7 @@
% 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
@@ -274,23 +274,38 @@
% { 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.
+% 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 was 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).
%
@@ -2280,18 +2295,26 @@
}
% \end{macrocode}
% \end{macro}
-
-
-
-% \begin{macro}{\vpagerefcomparenearby}
-% True if the two pages have arabic page numbers are at most off by
-% one so that |\vpageref| would produce a special string.
+%
+%
+%
+% \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\vpagerefcomparenearby[2]{% label1, label2, TRUE, FALSE
- \vrefpagenum\@tempa{#1}%
+\DeclareRobustCommand\vpagerefnearby[1]{% label, TRUE, FALSE
+ \leavevmode
+ \@tempskipa\lastskip \unskip
+ \global\advance\c at vrcnt\tw@ % keep oddness to not disturb \vrefvario
+ \vref at label{\the\c at vrcnt @vn}%
+ \ifdim\@tempskipa=\z@ \else
+ \hskip\@tempskipa
+ \fi
+ \vref at pagenum\@tempa{\the\c at vrcnt @vn}%
\is at pos@number\@tempa
{%
- \vrefpagenum\@tempb{#2}%
+ \vrefpagenum\@tempb{#1}%
\is at pos@number\@tempb
{%
\ifcase\numexpr \@tempa -\@tempb+1\relax
@@ -2304,24 +2327,31 @@
}
% \end{macrocode}
% \end{macro}
+%
-
-% \begin{macro}{\vpagerefnearby}
-% Test if |\vpageref| is going to be at most $\pm1$ off from
-% current page.
+% \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\vpagerefnearby[1]{% label, TRUE, FALSE
- \leavevmode
- \@tempskipa\lastskip \unskip
- \global\advance\c at vrcnt\tw@ % keep oddness to not disturb \vrefvario
- \vref at label{\the\c at vrcnt @vn}%
- \ifdim\@tempskipa=\z@ \else
- \hskip\@tempskipa
- \fi
- \vref at pagenum\@tempa{\the\c at vrcnt @vn}%
+\DeclareRobustCommand\vpagerefcomparenearby[2]{% label1, label2, TRUE, FALSE
+ \vrefpagenum\@tempa{#1}%
\is at pos@number\@tempa
{%
- \vrefpagenum\@tempb{#1}%
+ \vrefpagenum\@tempb{#2}%
\is at pos@number\@tempb
{%
\ifcase\numexpr \@tempa -\@tempb+1\relax
@@ -2334,7 +2364,7 @@
}
% \end{macrocode}
% \end{macro}
-%
+
%
%
% \subsubsection{Compatibility with older \LaTeX{} formats}
More information about the latex3-commits
mailing list