texlive[63874] Master/texmf-dist: zref-vario (11jul22)
commits+karl at tug.org
commits+karl at tug.org
Mon Jul 11 22:31:00 CEST 2022
Revision: 63874
http://tug.org/svn/texlive?view=revision&revision=63874
Author: karl
Date: 2022-07-11 22:31:00 +0200 (Mon, 11 Jul 2022)
Log Message:
-----------
zref-vario (11jul22)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/latex/zref-vario/CHANGELOG.md
trunk/Master/texmf-dist/doc/latex/zref-vario/zref-vario-code.pdf
trunk/Master/texmf-dist/doc/latex/zref-vario/zref-vario.pdf
trunk/Master/texmf-dist/doc/latex/zref-vario/zref-vario.tex
trunk/Master/texmf-dist/source/latex/zref-vario/zref-vario.dtx
trunk/Master/texmf-dist/tex/latex/zref-vario/zref-vario.sty
Modified: trunk/Master/texmf-dist/doc/latex/zref-vario/CHANGELOG.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/zref-vario/CHANGELOG.md 2022-07-11 20:30:44 UTC (rev 63873)
+++ trunk/Master/texmf-dist/doc/latex/zref-vario/CHANGELOG.md 2022-07-11 20:31:00 UTC (rev 63874)
@@ -1,7 +1,16 @@
# Changelog
-## [Unreleased](https://github.com/gusbrs/zref-vario/compare/v0.1.4...HEAD)
+## [Unreleased](https://github.com/gusbrs/zref-vario/compare/v0.1.5...HEAD)
+## [v0.1.5](https://github.com/gusbrs/zref-vario/compare/v0.1.4...v0.1.5) (2022-07-08)
+
+### Added
+- `\zvsetup` for package options settings.
+- `pageprop` option to set the reference property used for page comparisons.
+ This option lifts `varioref`'s restriction of depending on the arabic page
+ numbering to distinguish between nearby and far away references. See the
+ user manual for details.
+
## [v0.1.4](https://github.com/gusbrs/zref-vario/compare/v0.1.3-alpha...v0.1.4) (2022-04-24)
### Changed
Modified: trunk/Master/texmf-dist/doc/latex/zref-vario/zref-vario-code.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/latex/zref-vario/zref-vario.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/latex/zref-vario/zref-vario.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/zref-vario/zref-vario.tex 2022-07-11 20:30:44 UTC (rev 63873)
+++ trunk/Master/texmf-dist/doc/latex/zref-vario/zref-vario.tex 2022-07-11 20:31:00 UTC (rev 63874)
@@ -61,6 +61,14 @@
\NewDocumentCommand\opt{m}{\texttt{#1}}
+% Temporary workaround for 'l3doc' bug.
+% https://github.com/latex3/latex3/issues/1111
+% FIXME Remove when fixed upstream.
+\NewDocElement[
+ macrolike = false ,
+ printtype = \textit{opt.} ,
+]{Option}{optiondesc}
+
\lstdefinestyle{code}{
language=[LaTeX]TeX,
% moretexcs={
@@ -142,8 +150,45 @@
to ensure its load order requirements are met.
-\section{User interface}
+\section{Package options}
+Package options can be set by means of \cs{zvsetup}.
+
+\begin{function}{\zvsetup}
+ \begin{syntax}
+ \cs{zvsetpup}\marg{options}
+ \end{syntax}
+\end{function}
+
+Available options are:
+
+\bigskip{}
+
+\DescribeOption{pageprop} %
+\pkg{varioref} uses the \texttt{page} field of the standard label to check
+whether a reference and its label are on the same page, nearby, or far away.
+And has no real alternative data to use for the purpose. Possibly for this
+reason, the basic mechanism of page comparison in \pkg{varioref} is restricted
+to arabic numbered pages. Any other page numbering scheme results in
+\pkg{varioref} making no distinction between one or many pages off. But with
+\pkg{zref} it is trivial to detach the printed representation of the reference
+and the data used to make page comparisons. And that's what the
+\opt{pageprop} option allows to control. It receives a \pkg{zref} property as
+value to be used by \pkg{zref-vario} to make page comparisons, and defaults to
+the \texttt{page} property, which corresponds to the usual \pkg{varioref}
+behavior. The property must be defined and be included in \pkg{zref}'s main
+list at the time the setting is performed. The natural intended use case of
+this option is the \texttt{abspage} property provided by the
+\pkg{zref-abspage} module, which already handles these two requirements.
+Thus, loading this module and setting \opt{pageprop} to \texttt{abspage} gives
+us page comparisons independent of the page numbering scheme, which works in
+the front matter with roman numbering, across front and main matter
+boundaries, etc. In sum, regardless of whether the page numbering is arabic
+or anything else.
+
+
+\section{Reference commands}
+
\begin{function}{\zvref}
\begin{syntax}
\cs{zvref}\meta{*}\oarg{options}\marg{label}
@@ -203,14 +248,17 @@
but does not eliminate the limitations which arise from the underlying
problem.}
-Besides these options, two other are provided corresponding to
-\pkg{varioref}'s commands' optional arguments: \opt{vcurrent} (the first
-optional argument) and \opt{vother} (the second optional argument). Of
-course, these are only available when the underlying \pkg{varioref} command
-supports them.
+\DescribeOption{vcurrent} %
+\DescribeOption{vother} %
+Besides \cs{zcref}'s options, mentioned above, two other ones are provided for
+\pkg{zref-vario}'s reference commands, corresponding to \pkg{varioref}'s
+commands optional arguments: \opt{vcurrent} (the first optional argument) and
+\opt{vother} (the second optional argument). Of course, these are only
+available when the underlying \pkg{varioref} command supports them.
-\section{Customization}
+\section{Reference format}
+
\begin{function}{\zvLanguageSetup}
\begin{syntax}
\cs{zvLanguageSetup}\marg{language}\marg{options}
Modified: trunk/Master/texmf-dist/source/latex/zref-vario/zref-vario.dtx
===================================================================
--- trunk/Master/texmf-dist/source/latex/zref-vario/zref-vario.dtx 2022-07-11 20:30:44 UTC (rev 63873)
+++ trunk/Master/texmf-dist/source/latex/zref-vario/zref-vario.dtx 2022-07-11 20:31:00 UTC (rev 63874)
@@ -128,7 +128,7 @@
%
% Identify the package.
% \begin{macrocode}
-\ProvidesExplPackage {zref-vario} {2022-04-24} {0.1.4}
+\ProvidesExplPackage {zref-vario} {2022-07-08} {0.1.5}
{Extended LaTeX page cross-references with varioref and zref-clever}
% \end{macrocode}
%
@@ -146,8 +146,70 @@
% \end{macrocode}
%
%
-% \section{Customization}
+% \section{Options}
%
+% \subsection*{\cs{zvsetup}}
+%
+%
+% \begin{macro}[int]{\zvsetup}
+% Provide \cs{zvsetup}.
+% \begin{syntax}
+% \cs{zvsetup}\marg{options}
+% \end{syntax}
+% \begin{macrocode}
+\NewDocumentCommand \zvsetup { m }
+ { \keys_set:nn { zref-vario/setup } {#1} }
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection*{\opt{pageprop}}
+%
+% \begin{macrocode}
+\tl_new:N \l_@@_pageprop_tl
+\keys_define:nn { zref-vario/setup }
+ {
+ pageprop .code:n =
+ {
+ \zref at ifpropundefined {#1}
+ { \msg_warning:nnn { zref-vario } { pageprop-not-declared } {#1} }
+ {
+ \zref at iflistcontainsprop { \ZREF at mainlist } {#1}
+ { \tl_set:Nn \l_@@_pageprop_tl {#1} }
+ { \msg_warning:nnn { zref-vario } { pageprop-not-in-main } {#1} }
+ }
+ } ,
+ pageprop .value_required:n = true ,
+ pageprop .initial:n = { page } ,
+ }
+\AddToHook { begindocument }
+ {
+ \keys_define:nn { zref-vario/setup }
+ {
+ pageprop .code:n =
+ {
+ \msg_warning:nnn { zref-vario }
+ { option-preamble-only } { pageprop }
+ }
+ }
+ }
+\msg_new:nnn { zref-vario } { option-preamble-only }
+ { Option~'#1'~only~available~in~the~preamble~\msg_line_context:. }
+\msg_new:nnn { zref-vario } { pageprop-not-declared }
+ {
+ Property~'#1'~not~declared~\msg_line_context:.~
+ Using~default~'page'~property.
+ }
+\msg_new:nnn { zref-vario } { pageprop-not-in-main }
+ {
+ Property~'#1'~not~in~main~list~\msg_line_context:.~
+ Using~default~'page'~property.
+ }
+% \end{macrocode}
+%
+%
+% \section{Reference format}
+%
% Provide some functions to define options names in a standard form.
%
% \begin{macro}[EXP]{\@@_ref_opt_default_cs:nn}
@@ -616,7 +678,7 @@
\cs_new_protected:Npn \@@_vref_pagenum:Nn #1#2
{
\exp_args:NNNo \exp_args:NNo \cs_set_nopar:Npn #1
- { \zref at extractdefault {#2} { page } { ?? } }
+ { \zref at extractdefault {#2} { \l_@@_pageprop_tl } { ?? } }
}
\cs_new_protected:Npn \@@_vrefpagenum:Nn #1#2
{
@@ -624,7 +686,7 @@
\@@_vref_pagenum:Nn #1 {#2}
}
\cs_new_protected:Npn \@@_vref_label:n #1
- { \zref at labelbyprops {#1} { page } }
+ { \zref at labelbyprops {#1} { \l_@@_pageprop_tl } }
% \end{macrocode}
% \end{macro}
%
Modified: trunk/Master/texmf-dist/tex/latex/zref-vario/zref-vario.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/zref-vario/zref-vario.sty 2022-07-11 20:30:44 UTC (rev 63873)
+++ trunk/Master/texmf-dist/tex/latex/zref-vario/zref-vario.sty 2022-07-11 20:31:00 UTC (rev 63874)
@@ -42,11 +42,52 @@
%%
%% -----------------------------------------------------------------------
%%
-\ProvidesExplPackage {zref-vario} {2022-04-24} {0.1.4}
+\ProvidesExplPackage {zref-vario} {2022-07-08} {0.1.5}
{Extended LaTeX page cross-references with varioref and zref-clever}
\RequirePackage { zref-clever } [ 2022-01-28 ] % v0.2.0-alpha
\AddToHook { begindocument/before }
{ \RequirePackage { varioref } }
+\NewDocumentCommand \zvsetup { m }
+ { \keys_set:nn { zref-vario/setup } {#1} }
+\tl_new:N \l__zrefvario_pageprop_tl
+\keys_define:nn { zref-vario/setup }
+ {
+ pageprop .code:n =
+ {
+ \zref at ifpropundefined {#1}
+ { \msg_warning:nnn { zref-vario } { pageprop-not-declared } {#1} }
+ {
+ \zref at iflistcontainsprop { \ZREF at mainlist } {#1}
+ { \tl_set:Nn \l__zrefvario_pageprop_tl {#1} }
+ { \msg_warning:nnn { zref-vario } { pageprop-not-in-main } {#1} }
+ }
+ } ,
+ pageprop .value_required:n = true ,
+ pageprop .initial:n = { page } ,
+ }
+\AddToHook { begindocument }
+ {
+ \keys_define:nn { zref-vario/setup }
+ {
+ pageprop .code:n =
+ {
+ \msg_warning:nnn { zref-vario }
+ { option-preamble-only } { pageprop }
+ }
+ }
+ }
+\msg_new:nnn { zref-vario } { option-preamble-only }
+ { Option~'#1'~only~available~in~the~preamble~\msg_line_context:. }
+\msg_new:nnn { zref-vario } { pageprop-not-declared }
+ {
+ Property~'#1'~not~declared~\msg_line_context:.~
+ Using~default~'page'~property.
+ }
+\msg_new:nnn { zref-vario } { pageprop-not-in-main }
+ {
+ Property~'#1'~not~in~main~list~\msg_line_context:.~
+ Using~default~'page'~property.
+ }
\cs_new:Npn \__zrefvario_ref_opt_default_cs:nn #1#2
{ __zrefvario_ref_opt_default_ #1 : #2 }
\cs_new:Npn \__zrefvario_base_lang:n #1
@@ -384,7 +425,7 @@
\cs_new_protected:Npn \__zrefvario_vref_pagenum:Nn #1#2
{
\exp_args:NNNo \exp_args:NNo \cs_set_nopar:Npn #1
- { \zref at extractdefault {#2} { page } { ?? } }
+ { \zref at extractdefault {#2} { \l__zrefvario_pageprop_tl } { ?? } }
}
\cs_new_protected:Npn \__zrefvario_vrefpagenum:Nn #1#2
{
@@ -392,7 +433,7 @@
\__zrefvario_vref_pagenum:Nn #1 {#2}
}
\cs_new_protected:Npn \__zrefvario_vref_label:n #1
- { \zref at labelbyprops {#1} { page } }
+ { \zref at labelbyprops {#1} { \l__zrefvario_pageprop_tl } }
\bool_new:N \l__zrefvario_varioref_setup_bool
\cs_new_protected:Npn \__zrefvario_varioref_setup:
{
More information about the tex-live-commits
mailing list.