diff options
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-vario/CHANGELOG.md | 11 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-vario/zref-vario-code.pdf | bin | 570457 -> 618882 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-vario/zref-vario.pdf | bin | 143334 -> 146033 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-vario/zref-vario.tex | 62 | ||||
-rw-r--r-- | Master/texmf-dist/source/latex/zref-vario/zref-vario.dtx | 70 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/zref-vario/zref-vario.sty | 47 |
6 files changed, 175 insertions, 15 deletions
diff --git a/Master/texmf-dist/doc/latex/zref-vario/CHANGELOG.md b/Master/texmf-dist/doc/latex/zref-vario/CHANGELOG.md index c539ec3cb14..18e60b2c09c 100644 --- a/Master/texmf-dist/doc/latex/zref-vario/CHANGELOG.md +++ b/Master/texmf-dist/doc/latex/zref-vario/CHANGELOG.md @@ -1,6 +1,15 @@ # 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) diff --git a/Master/texmf-dist/doc/latex/zref-vario/zref-vario-code.pdf b/Master/texmf-dist/doc/latex/zref-vario/zref-vario-code.pdf Binary files differindex 15511b87051..7c9387cdcfb 100644 --- a/Master/texmf-dist/doc/latex/zref-vario/zref-vario-code.pdf +++ b/Master/texmf-dist/doc/latex/zref-vario/zref-vario-code.pdf diff --git a/Master/texmf-dist/doc/latex/zref-vario/zref-vario.pdf b/Master/texmf-dist/doc/latex/zref-vario/zref-vario.pdf Binary files differindex 6e726620724..e53bd0d300a 100644 --- a/Master/texmf-dist/doc/latex/zref-vario/zref-vario.pdf +++ b/Master/texmf-dist/doc/latex/zref-vario/zref-vario.pdf diff --git a/Master/texmf-dist/doc/latex/zref-vario/zref-vario.tex b/Master/texmf-dist/doc/latex/zref-vario/zref-vario.tex index 08da926111a..572ff4fe6f6 100644 --- a/Master/texmf-dist/doc/latex/zref-vario/zref-vario.tex +++ b/Master/texmf-dist/doc/latex/zref-vario/zref-vario.tex @@ -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,7 +150,44 @@ packages, prominently with \pkg{hyperref}, you may wish to load it explicitly 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} @@ -203,13 +248,16 @@ does what it says: passes the options along to the underlying call(s) to 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} diff --git a/Master/texmf-dist/source/latex/zref-vario/zref-vario.dtx b/Master/texmf-dist/source/latex/zref-vario/zref-vario.dtx index c9db0a0f8a2..81d9dec5d18 100644 --- a/Master/texmf-dist/source/latex/zref-vario/zref-vario.dtx +++ b/Master/texmf-dist/source/latex/zref-vario/zref-vario.dtx @@ -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,7 +146,69 @@ % \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@ifpropundefined {#1} + { \msg_warning:nnn { zref-vario } { pageprop-not-declared } {#1} } + { + \zref@iflistcontainsprop { \ZREF@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. % @@ -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@extractdefault {#2} { page } { ?? } } + { \zref@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@labelbyprops {#1} { page } } + { \zref@labelbyprops {#1} { \l_@@_pageprop_tl } } % \end{macrocode} % \end{macro} % diff --git a/Master/texmf-dist/tex/latex/zref-vario/zref-vario.sty b/Master/texmf-dist/tex/latex/zref-vario/zref-vario.sty index 3100822f7e6..9ccbc2133d3 100644 --- a/Master/texmf-dist/tex/latex/zref-vario/zref-vario.sty +++ b/Master/texmf-dist/tex/latex/zref-vario/zref-vario.sty @@ -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@ifpropundefined {#1} + { \msg_warning:nnn { zref-vario } { pageprop-not-declared } {#1} } + { + \zref@iflistcontainsprop { \ZREF@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@extractdefault {#2} { page } { ?? } } + { \zref@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@labelbyprops {#1} { page } } + { \zref@labelbyprops {#1} { \l__zrefvario_pageprop_tl } } \bool_new:N \l__zrefvario_varioref_setup_bool \cs_new_protected:Npn \__zrefvario_varioref_setup: { |