From 9eb6f85105699320d8cbdbb33bcdc88c41ea709a Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Thu, 15 Jun 2023 03:03:06 +0000 Subject: CTAN sync 202306150303 --- macros/latex/contrib/zref-vario/CHANGELOG.md | 8 +- .../latex/contrib/zref-vario/zref-vario-code.pdf | Bin 648126 -> 649972 bytes .../latex/contrib/zref-vario/zref-vario-code.tex | 2 +- macros/latex/contrib/zref-vario/zref-vario-doc.pdf | Bin 0 -> 149965 bytes macros/latex/contrib/zref-vario/zref-vario-doc.tex | 376 +++++++++++++++++++++ macros/latex/contrib/zref-vario/zref-vario.dtx | 9 +- macros/latex/contrib/zref-vario/zref-vario.ins | 4 +- macros/latex/contrib/zref-vario/zref-vario.pdf | Bin 149549 -> 0 bytes macros/latex/contrib/zref-vario/zref-vario.tex | 374 -------------------- 9 files changed, 393 insertions(+), 380 deletions(-) create mode 100644 macros/latex/contrib/zref-vario/zref-vario-doc.pdf create mode 100644 macros/latex/contrib/zref-vario/zref-vario-doc.tex delete mode 100644 macros/latex/contrib/zref-vario/zref-vario.pdf delete mode 100644 macros/latex/contrib/zref-vario/zref-vario.tex (limited to 'macros/latex/contrib/zref-vario') diff --git a/macros/latex/contrib/zref-vario/CHANGELOG.md b/macros/latex/contrib/zref-vario/CHANGELOG.md index 2f0b419280..876440be3e 100644 --- a/macros/latex/contrib/zref-vario/CHANGELOG.md +++ b/macros/latex/contrib/zref-vario/CHANGELOG.md @@ -1,6 +1,12 @@ # Changelog -## [Unreleased](https://github.com/gusbrs/zref-vario/compare/v0.1.7...HEAD) +## [Unreleased](https://github.com/gusbrs/zref-vario/compare/v0.1.8...HEAD) + +## [v0.1.8](https://github.com/gusbrs/zref-vario/compare/v0.1.7...v0.1.8) (2023-06-14) + +### Changed +- Improvements to User manual. +- Simplify and improve regression tests. ## [v0.1.7](https://github.com/gusbrs/zref-vario/compare/v0.1.6...v0.1.7) (2023-01-03) diff --git a/macros/latex/contrib/zref-vario/zref-vario-code.pdf b/macros/latex/contrib/zref-vario/zref-vario-code.pdf index e5aa9feaa1..b035eabb67 100644 Binary files a/macros/latex/contrib/zref-vario/zref-vario-code.pdf and b/macros/latex/contrib/zref-vario/zref-vario-code.pdf differ diff --git a/macros/latex/contrib/zref-vario/zref-vario-code.tex b/macros/latex/contrib/zref-vario/zref-vario-code.tex index 914208b02e..d1774f8f21 100644 --- a/macros/latex/contrib/zref-vario/zref-vario-code.tex +++ b/macros/latex/contrib/zref-vario/zref-vario-code.tex @@ -22,7 +22,7 @@ % % This work consists of the files zref-vario.dtx, % zref-vario.ins, -% zref-vario.tex, +% zref-vario-doc.tex, % zref-vario-code.tex, % and the files generated from them. % diff --git a/macros/latex/contrib/zref-vario/zref-vario-doc.pdf b/macros/latex/contrib/zref-vario/zref-vario-doc.pdf new file mode 100644 index 0000000000..0119708112 Binary files /dev/null and b/macros/latex/contrib/zref-vario/zref-vario-doc.pdf differ diff --git a/macros/latex/contrib/zref-vario/zref-vario-doc.tex b/macros/latex/contrib/zref-vario/zref-vario-doc.tex new file mode 100644 index 0000000000..0923b299ae --- /dev/null +++ b/macros/latex/contrib/zref-vario/zref-vario-doc.tex @@ -0,0 +1,376 @@ +% \iffalse meta-comment +% +% File: zref-vario.tex +% +% This file is part of the LaTeX package "zref-vario". +% +% Copyright (C) 2022-2023 Gustavo Barros +% +% It may be distributed and/or modified under the conditions of the +% LaTeX Project Public License (LPPL), either version 1.3c of this +% license or (at your option) any later version. The latest version +% of this license is in the file: +% +% https://www.latex-project.org/lppl.txt +% +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% +% This work is "maintained" (as per LPPL maintenance status) by +% Gustavo Barros. +% +% This work consists of the files zref-vario.dtx, +% zref-vario.ins, +% zref-vario-doc.tex, +% zref-vario-code.tex, +% and the files generated from them. +% +% The released version of this package is available from CTAN. +% +% ----------------------------------------------------------------------- +% +% The development version of the package can be found at +% +% https://github.com/gusbrs/zref-vario +% +% for those people who are interested. +% +% ----------------------------------------------------------------------- +% +% \fi + +\documentclass{l3doc} + +% The package itself *must* be loaded so that \GetFileInfo can pick up date +% and version data. +\usepackage{zref-vario} + +\usepackage[T1]{fontenc} + +\usepackage[sc]{mathpazo} +\linespread{1.05} +\usepackage[scale=.88]{tgheros} % sans +\usepackage[varqu,scaled=1.03]{inconsolata} % tt + +\usepackage{listings} + +\usepackage{microtype} + +\hypersetup{hidelinks} + +\NewDocumentCommand\opt{m}{\texttt{#1}} + +\NewDocumentCommand\username{m}{`\texttt{#1}'} + +\setlength{\marginparsep}{2\labelsep} + +\lstdefinestyle{code}{ + language=[LaTeX]TeX, + % moretexcs={ + % } +} +\lstdefinestyle{zrefvario}{ + style=code, + % moretexcs={ + % } +} +\lstset{ + style=zrefvario, + basicstyle=\ttfamily\small, + columns=fullflexible, + keepspaces, + xleftmargin=\leftmargin, + xrightmargin=.5\leftmargin, +} +\lstnewenvironment{zvexample}[1][]{% + \renewcommand{\lstlistingname}{Example}% + \lstset{#1}% +}{} + +\begin{document} + +\GetFileInfo{zref-vario.sty} + +\title{% + The \pkg{zref-vario} package% + \thanks{This file describes \fileversion, released \filedate.}% + \texorpdfstring{\\{}\medskip{}}{ - }% + User manual% + \texorpdfstring{\medskip{}}{}% +} + +\author{% + Gustavo Barros% + \thanks{\url{https://github.com/gusbrs/zref-vario}}% +} + +\date{\filedate} + +\maketitle + +\begin{center} + {\bfseries \abstractname\vspace{-.5em}\vspace{0pt}} +\end{center} + +\begin{quotation} + \pkg{zref-vario} offers a compatibility layer for \pkg{varioref} to be used + alongside \pkg{zref-clever}. It provides + ``\texttt{\textbackslash{}z}\dots{}'' counterparts to \pkg{varioref}'s main + reference commands, each of which essentially does some (scoped) setup for + \pkg{varioref}, then calls the original one. +\end{quotation} + +\bigskip{} + +\begin{center} + \textbf{EXPERIMENTAL} +\end{center} + +\tableofcontents + +\clearpage{} + +\section{Loading the package} + +As usual: + +\begin{zvexample} +\usepackage{zref-vario} +\end{zvexample} + +\pkg{zref-vario} loads \pkg{zref-clever}, and will load \pkg{varioref} at +\texttt{begindocument/before}, if it hasn't already been loaded. However, +considering \pkg{varioref} has known load order interaction with other +packages, prominently with \pkg{hyperref}, you may wish to load it explicitly +to ensure its load order requirements are met. + + +\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} + \end{syntax} +\end{function} + +\begin{function}{\zvpageref} + \begin{syntax} + \cs{zvpageref}\meta{*}\oarg{options}\marg{label} + \end{syntax} +\end{function} + +\begin{function}{\zvrefrange} + \begin{syntax} + \cs{zvrefrange}\meta{*}\oarg{options}\marg{label}\marg{label} + \end{syntax} +\end{function} + +\begin{function}{\zvpagerefrange} + \begin{syntax} + \cs{zvpagerefrange}\meta{*}\oarg{options}\marg{label}\marg{label} + \end{syntax} +\end{function} + +\begin{function}{\zfullref} + \begin{syntax} + \cs{zfullref}\meta{*}\oarg{options}\marg{label} + \end{syntax} +\end{function} + +These user commands work pretty much as their \pkg{varioref} +counterparts.\footnote{If you are not acquainted with them, see + \pkg{varioref}'s documentation.} Indeed, they are just wrappers around +them. As such, differently from \pkg{zref-clever}'s commands, these can +receive single labels as arguments, not lists of them. In all of them the +starred version inhibits hyperlinking, and they (locally) set \pkg{varioref}'s +\opt{nospace} option, so that the this syntax can be used unambiguously. + +All of them have a single optional argument, which can receive any of +\cs{zcref}'s options, and those are set for calls to \cs{zcref} or +\cs{zpageref} which are part of the building blocks of the reference formats +and strings set for \pkg{varioref}. However, there is indeed some potential +friction and caveats stemming from the use of these options, which were +designed to work for single calls of \cs{zcref}, to apply to \emph{pairs} of +them. Hence, whether each and every of these options is meaningful, useful, +or potentially harmful in this context depends on the case, and it is up to +the user to make proper use of them. Of course, one can always split the pair +using \cs{zcref} and then \cs{zvpageref}, \cs{zvpagerefrange}, or +\cs{zcpageref}, and have more control over each part. Anyway, the package +does what it says: passes the options along to the underlying call(s) to +\cs{zcref}.\footnote{Note that the options given to each call of these user + macros are set \emph{before} the call to the original \pkg{varioref} + counterpart. This means that options given to \cs{zcref} or \cs{zpageref} + in the strings and formats in \cs{zvLanguageSetup} will have precedence over + the former. Which is useful, so that we can distinguish to some degree the + first from the second call of \cs{zcref}/\cs{zpageref} done in the formats, + but does not eliminate the limitations which arise from the underlying + problem.} + +\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{Reference format} + +\begin{function}{\zvLanguageSetup} + \begin{syntax} + \cs{zvLanguageSetup}\marg{language}\marg{options} + \end{syntax} +\end{function} + +User interface for customization of ``strings'' and ``formats'' for +\meta{language}. \meta{language} must be known to \pkg{zref-clever}. The +\meta{options} are familiar to users of \pkg{varioref}: +\opt{reftextfaceafter}, \opt{reftextfacebefore}, \opt{reftextafter}, +\opt{reftextbefore}, \opt{reftextcurrent}, \opt{reftextfaraway}, +\opt{reftextpagerange}, \opt{reftextlabelrange}, \opt{vrefformat}, +\opt{vrefrangeformat}, and \opt{fullrefformat}.\footnote{For details, see + \pkg{varioref}'s documentation.} Their meaning is the same as the ones they +have in \pkg{varioref} and, indeed, they work by setting those \pkg{varioref} +macros to the values given to the corresponding options in +\cs{zvLanguageSetup}. If you are setting up a language which has no built-in +support, you should set at least the whole set of ``\texttt{reftext}\dots{}'' +options. Language independent default values are provided for the +``\dots{}\texttt{format}'' options (equivalent to the ones from +\pkg{varioref}, which are adequate for most use cases), so you may omit them. +But, if you need to adjust them, the default values can be overridden by +setting the corresponding options in \cs{zvLanguageSetup}. +\cs{zvLanguageSetup} is preamble only. + +\begin{function}{\zvhyperlink} + \begin{syntax} + \cs{zvhyperlink}\marg{text} + \end{syntax} +\end{function} + +Inside the options of \cs{zvLanguageSetup}, and also inside the \opt{vcurrent} +and \opt{vother} options of \pkg{zref-vario}'s reference commands, +\cs{zvhyperlink} can be used to produce a hyperlink to the label of the +reference. For example, one could set \texttt{reftextafter=\{on the + \cs{zvhyperlink}\{next page\}\}} to get ``next page'' hyperlinked. +\cs{zvhyperlink} can be used regardless of \opt{hyperref} being enabled for +\pkg{zref-clever}, it will just pass on the \meta{text} argument if it is not. +On range reference commands, \cs{zvhyperlink} only produces a link when both +labels fall on the same page, in which case it hyperlinks to the first label. + +\bigskip{} + +As far as \pkg{zref-vario} is concerned, \pkg{varioref}'s options are (mostly) +not taken into account: the language options are disregarded (settings made +with \cs{zvLanguageSetup} are used instead), the \opt{nospace} option is +hard-coded (locally) for the ``\texttt{\textbackslash{}z}\dots{}'' commands, +and \opt{draft} and \opt{final} are typically given to \cs{documentclass}, +though they do affect \pkg{zref-vario}'s commands, just as they do with +\pkg{varioref}'s. + + +\section{Integration with \pkg{zref-check}} + +When package \pkg{zref-check} is loaded, \pkg{zref-vario} provides one further +option to its user commands: \opt{vcheck}. The purpose of this option is to +check the relative position of label and reference within the same page. It +can receive two values: \texttt{above} and \texttt{below}, being those the +names of the \pkg{zref-check}'s checks which are meaningful for the use case +at hand. Of course, these could also be performed with \cs{zcref}'s +\opt{check} option, which is available for \pkg{zref-vario}'s commands as +well. The difference here is that the check specified in \opt{vcheck} is only +performed when the referenced label -- or labels, in the case of a range -- +fall on the same page as the reference itself.\footnote{There's another + technical difference between them. \pkg{zref-check}'s checks, and hence + those of the \opt{check} option, make sure the whole reference passes each + check by setting labels both at the start and the end of the reference, and + verifying if each one of them passes the checks. But, since \pkg{varioref} + already has it's own mechanism to handle references which cross page + boundaries, \opt{vcheck}'s checks set only one label, at the end of the + reference, the same position \pkg{varioref} uses to check whether label and + reference are on the same page.} In other words, when \opt{vcurrent} would +be used (if provided). For this reason, only the commands which support +\opt{vcurrent} offer \pkg{vcheck}. Also, \opt{vcheck} cannot receive +\pkg{zref-check}'s options, as \opt{check} is able to, but the latter can be +used for the purpose of locally controlling the behavior of the checks +performed by \opt{vcheck}. Consult \pkg{zref-check}'s documentation for +details and limitations of these checks and envisaged workflows for their +reliable use. + + +\section{Acknowledgments} + +A number of people have contributed to \pkg{zref-vario}. Suggestions, +ideas, solutions to problems, bug reports or even encouragement were +generously provided by (in chronological order): + Matteo Ferrigato, % 'matteo339' + % 2023-01-02: https://github.com/gusbrs/zref-vario/issues/1 + Ulrike Fischer, + % 2023-01-02: https://tex.stackexchange.com/q/670399 (comments) + David Carlisle, + % 2023-01-02: https://chat.stackexchange.com/transcript/message/62684358#62684358 + % and following discussion. + % 2023-02-10: https://tex.stackexchange.com/a/674846 + and Joseph Wright. + % 2023-01-02: https://chat.stackexchange.com/transcript/message/62684358#62684358 + % and following discussion. + +The package's language settings have been provided or improved thanks to: + Matteo Ferrigato (Italian). % 'matteo339' + % 2023-01-02: https://github.com/gusbrs/zref-vario/issues/1 + +If I have inadvertently left anyone off the list I apologize, and please let +me know, so that I can correct the oversight. + +Thank you all very much! + + +\section{Change history} + +A change log with relevant changes for each version, eventual upgrade +instructions, and upcoming changes, is maintained in the package's repository, +at \url{https://github.com/gusbrs/zref-vario/blob/main/CHANGELOG.md}. The +change log is also distributed with the package's documentation through CTAN +upon release so, most likely, \texttt{texdoc zref-vario/changelog} should +provide easy local access to it. An archive of historical versions of the +package is also kept at \url{https://github.com/gusbrs/zref-vario/releases}. + +\end{document} diff --git a/macros/latex/contrib/zref-vario/zref-vario.dtx b/macros/latex/contrib/zref-vario/zref-vario.dtx index 1e07c94694..e029af643c 100644 --- a/macros/latex/contrib/zref-vario/zref-vario.dtx +++ b/macros/latex/contrib/zref-vario/zref-vario.dtx @@ -22,7 +22,7 @@ % % This work consists of the files zref-vario.dtx, % zref-vario.ins, -% zref-vario.tex, +% zref-vario-doc.tex, % zref-vario-code.tex, % and the files generated from them. % @@ -126,9 +126,14 @@ % \end{macrocode} % % +% \begin{macrocode} +\NeedsTeXFormat{LaTeX2e} +% \end{macrocode} +% +% % Identify the package. % \begin{macrocode} -\ProvidesExplPackage {zref-vario} {2023-01-03} {0.1.7} +\ProvidesExplPackage {zref-vario} {2023-06-14} {0.1.8} {Extended LaTeX page cross-references with varioref and zref-clever} % \end{macrocode} % diff --git a/macros/latex/contrib/zref-vario/zref-vario.ins b/macros/latex/contrib/zref-vario/zref-vario.ins index bdc92fffdb..211c1ff0b2 100644 --- a/macros/latex/contrib/zref-vario/zref-vario.ins +++ b/macros/latex/contrib/zref-vario/zref-vario.ins @@ -22,7 +22,7 @@ % % This work consists of the files zref-vario.dtx, % zref-vario.ins, -% zref-vario.tex, +% zref-vario-doc.tex, % zref-vario-code.tex, % and the files generated from them. % @@ -68,7 +68,7 @@ This work is "maintained" (as per LPPL maintenance status) by This work consists of the files zref-vario.dtx, zref-vario.ins, - zref-vario.tex, + zref-vario-doc.tex, zref-vario-code.tex, and the files generated from them. diff --git a/macros/latex/contrib/zref-vario/zref-vario.pdf b/macros/latex/contrib/zref-vario/zref-vario.pdf deleted file mode 100644 index ef33353401..0000000000 Binary files a/macros/latex/contrib/zref-vario/zref-vario.pdf and /dev/null differ diff --git a/macros/latex/contrib/zref-vario/zref-vario.tex b/macros/latex/contrib/zref-vario/zref-vario.tex deleted file mode 100644 index 859519a2ef..0000000000 --- a/macros/latex/contrib/zref-vario/zref-vario.tex +++ /dev/null @@ -1,374 +0,0 @@ -% \iffalse meta-comment -% -% File: zref-vario.tex -% -% This file is part of the LaTeX package "zref-vario". -% -% Copyright (C) 2022-2023 Gustavo Barros -% -% It may be distributed and/or modified under the conditions of the -% LaTeX Project Public License (LPPL), either version 1.3c of this -% license or (at your option) any later version. The latest version -% of this license is in the file: -% -% https://www.latex-project.org/lppl.txt -% -% and version 1.3 or later is part of all distributions of LaTeX -% version 2005/12/01 or later. -% -% -% This work is "maintained" (as per LPPL maintenance status) by -% Gustavo Barros. -% -% This work consists of the files zref-vario.dtx, -% zref-vario.ins, -% zref-vario.tex, -% zref-vario-code.tex, -% and the files generated from them. -% -% The released version of this package is available from CTAN. -% -% ----------------------------------------------------------------------- -% -% The development version of the package can be found at -% -% https://github.com/gusbrs/zref-vario -% -% for those people who are interested. -% -% ----------------------------------------------------------------------- -% -% \fi - -\documentclass{l3doc} - -% The package itself *must* be loaded so that \GetFileInfo can pick up date -% and version data. -\usepackage{zref-vario} - -\usepackage[T1]{fontenc} - -\usepackage[sc]{mathpazo} -\linespread{1.05} -\usepackage[scale=.88]{tgheros} % sans -\usepackage[varqu,scaled=1.03]{inconsolata} % tt - -\usepackage{listings} - -\usepackage{microtype} - -\hypersetup{hidelinks} - -\NewDocumentCommand\opt{m}{\texttt{#1}} - -\NewDocumentCommand\username{m}{`\texttt{#1}'} - -\setlength{\marginparsep}{2\labelsep} - -\lstdefinestyle{code}{ - language=[LaTeX]TeX, - % moretexcs={ - % } -} -\lstdefinestyle{zrefvario}{ - style=code, - % moretexcs={ - % } -} -\lstset{ - style=zrefvario, - basicstyle=\ttfamily\small, - columns=fullflexible, - keepspaces, - xleftmargin=\leftmargin, - xrightmargin=.5\leftmargin, -} -\lstnewenvironment{zvexample}[1][]{% - \renewcommand{\lstlistingname}{Example}% - \lstset{#1}% -}{} - -\begin{document} - -\GetFileInfo{zref-vario.sty} - -\title{% - The \pkg{zref-vario} package% - \thanks{This file describes \fileversion, released \filedate.}% - \texorpdfstring{\\{}\medskip{}}{ - }% - User manual% - \texorpdfstring{\medskip{}}{}% -} - -\author{% - Gustavo Barros% - \thanks{\url{https://github.com/gusbrs/zref-vario}}% -} - -\date{\filedate} - -\maketitle - -\begin{center} - {\bfseries \abstractname\vspace{-.5em}\vspace{0pt}} -\end{center} - -\begin{quotation} - \pkg{zref-vario} offers a compatibility layer for \pkg{varioref} to be used - alongside \pkg{zref-clever}. It provides - ``\texttt{\textbackslash{}z}\dots{}'' counterparts to \pkg{varioref}'s main - reference commands, each of which essentially does some (scoped) setup for - \pkg{varioref}, then calls the original one. -\end{quotation} - -\bigskip{} - -\begin{center} - \textbf{EXPERIMENTAL} -\end{center} - -\tableofcontents - -\clearpage{} - -\section{Loading the package} - -As usual: - -\begin{zvexample} -\usepackage{zref-vario} -\end{zvexample} - -\pkg{zref-vario} loads \pkg{zref-clever}, and will load \pkg{varioref} at -\texttt{begindocument/before}, if it hasn't already been loaded. However, -considering \pkg{varioref} has known load order interaction with other -packages, prominently with \pkg{hyperref}, you may wish to load it explicitly -to ensure its load order requirements are met. - - -\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} - \end{syntax} -\end{function} - -\begin{function}{\zvpageref} - \begin{syntax} - \cs{zvpageref}\meta{*}\oarg{options}\marg{label} - \end{syntax} -\end{function} - -\begin{function}{\zvrefrange} - \begin{syntax} - \cs{zvrefrange}\meta{*}\oarg{options}\marg{label}\marg{label} - \end{syntax} -\end{function} - -\begin{function}{\zvpagerefrange} - \begin{syntax} - \cs{zvpagerefrange}\meta{*}\oarg{options}\marg{label}\marg{label} - \end{syntax} -\end{function} - -\begin{function}{\zfullref} - \begin{syntax} - \cs{zfullref}\meta{*}\oarg{options}\marg{label} - \end{syntax} -\end{function} - -These user commands work pretty much as their \pkg{varioref} -counterparts.\footnote{If you are not acquainted with them, see - \pkg{varioref}'s documentation.} Indeed, they are just wrappers around -them. As such, differently from \pkg{zref-clever}'s commands, these can -receive single labels as arguments, not lists of them. In all of them the -starred version inhibits hyperlinking, and they (locally) set \pkg{varioref}'s -\opt{nospace} option, so that the this syntax can be used unambiguously. - -All of them have a single optional argument, which can receive any of -\cs{zcref}'s options, and those are set for calls to \cs{zcref} or -\cs{zpageref} which are part of the building blocks of the reference formats -and strings set for \pkg{varioref}. However, there is indeed some potential -friction and caveats stemming from the use of these options, which were -designed to work for single calls of \cs{zcref}, to apply to \emph{pairs} of -them. Hence, whether each and every of these options is meaningful, useful, -or potentially harmful in this context depends on the case, and it is up to -the user to make proper use of them. Of course, one can always split the pair -using \cs{zcref} and then \cs{zvpageref}, \cs{zvpagerefrange}, or -\cs{zcpageref}, and have more control over each part. Anyway, the package -does what it says: passes the options along to the underlying call(s) to -\cs{zcref}.\footnote{Note that the options given to each call of these user - macros are set \emph{before} the call to the original \pkg{varioref} - counterpart. This means that options given to \cs{zcref} or \cs{zpageref} - in the strings and formats in \cs{zvLanguageSetup} will have precedence over - the former. Which is useful, so that we can distinguish to some degree the - first from the second call of \cs{zcref}/\cs{zpageref} done in the formats, - but does not eliminate the limitations which arise from the underlying - problem.} - -\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{Reference format} - -\begin{function}{\zvLanguageSetup} - \begin{syntax} - \cs{zvLanguageSetup}\marg{language}\marg{options} - \end{syntax} -\end{function} - -User interface for customization of ``strings'' and ``formats'' for -\meta{language}. \meta{language} must be known to \pkg{zref-clever}. The -\meta{options} are familiar to users of \pkg{varioref}: -\opt{reftextfaceafter}, \opt{reftextfacebefore}, \opt{reftextafter}, -\opt{reftextbefore}, \opt{reftextcurrent}, \opt{reftextfaraway}, -\opt{reftextpagerange}, \opt{reftextlabelrange}, \opt{vrefformat}, -\opt{vrefrangeformat}, and \opt{fullrefformat}.\footnote{For details, see - \pkg{varioref}'s documentation.} Their meaning is the same as the ones they -have in \pkg{varioref} and, indeed, they work by setting those \pkg{varioref} -macros to the values given to the corresponding options in -\cs{zvLanguageSetup}. If you are setting up a language which has no built-in -support, you should set at least the whole set of ``\texttt{reftext}\dots{}'' -options. Language independent default values are provided for the -``\dots{}\texttt{format}'' options (equivalent to the ones from -\pkg{varioref}, which are adequate for most use cases), so you may omit them. -But, if you need to adjust them, the default values can be overridden by -setting the corresponding options in \cs{zvLanguageSetup}. - -\begin{function}{\zvhyperlink} - \begin{syntax} - \cs{zvhyperlink}\marg{text} - \end{syntax} -\end{function} - -Inside the options of \cs{zvLanguageSetup}, and also inside the \opt{vcurrent} -and \opt{vother} options of \pkg{zref-vario}'s reference commands, -\cs{zvhyperlink} can be used to produce a hyperlink to the label of the -reference. For example, one could set \texttt{reftextafter=\{on the - \cs{zvhyperlink}\{next page\}\}} to get ``next page'' hyperlinked. -\cs{zvhyperlink} can be used regardless of \opt{hyperref} being enabled for -\pkg{zref-clever}, it will just pass on the \meta{text} argument if it is not. -On range reference commands, \cs{zvhyperlink} only produces a link when both -labels fall on the same page, in which case it hyperlinks to the first label. - -\bigskip{} - -As far as \pkg{zref-vario} is concerned, \pkg{varioref}'s options are (mostly) -not taken into account: the language options are disregarded (settings made -with \cs{zvLanguageSetup} are used instead), the \opt{nospace} option is -hard-coded (locally) for the ``\texttt{\textbackslash{}z}\dots{}'' commands, -and \opt{draft} and \opt{final} are typically given to \cs{documentclass}, -though they do affect \pkg{zref-vario}'s commands, just as they do with -\pkg{varioref}'s. - - -\section{Integration with \pkg{zref-check}} - -When package \pkg{zref-check} is loaded, \pkg{zref-vario} provides one further -option to its user commands: \opt{vcheck}. The purpose of this option is to -check the relative position of label and reference within the same page. It -can receive two values: \texttt{above} and \texttt{below}, being those the -names of the \pkg{zref-check}'s checks which are meaningful for the use case -at hand. Of course, these could also be performed with \cs{zcref}'s -\opt{check} option, which is available for \pkg{zref-vario}'s commands as -well. The difference here is that the check specified in \opt{vcheck} is only -performed when the referenced label -- or labels, in the case of a range -- -fall on the same page as the reference itself.\footnote{There's another - technical difference between them. \pkg{zref-check}'s checks, and hence - those of the \opt{check} option, make sure the whole reference passes each - check by setting labels both at the start and the end of the reference, and - verifying if each one of them passes the checks. But, since \pkg{varioref} - already has it's own mechanism to handle references which cross page - boundaries, \opt{vcheck}'s checks set only one label, at the end of the - reference, the same position \pkg{varioref} uses to check whether label and - reference are on the same page.} In other words, when \opt{vcurrent} would -be used (if provided). For this reason, only the commands which support -\opt{vcurrent} offer \pkg{vcheck}. Also, \opt{vcheck} cannot receive -\pkg{zref-check}'s options, as \opt{check} is able to, but the latter can be -used for the purpose of locally controlling the behavior of the checks -performed by \opt{vcheck}. Consult \pkg{zref-check}'s documentation for -details and limitations of these checks and envisaged workflows for their -reliable use. - - -\section{Acknowledgments} - -A number of people have contributed to \pkg{zref-vario}. Suggestions, -ideas, solutions to problems, bug reports or even encouragement were -generously provided by (in chronological order): - Matteo Ferrigato, % 'matteo339' - % 2023-01-02: https://github.com/gusbrs/zref-vario/issues/1 - Ulrike Fischer, - % 2023-01-02: https://tex.stackexchange.com/q/670399 (comments) - David Carlisle, - % 2023-01-02: https://chat.stackexchange.com/transcript/message/62684358#62684358 - % and following discussion. - and Joseph Wright. - % 2023-01-02: https://chat.stackexchange.com/transcript/message/62684358#62684358 - % and following discussion. - -The package's language settings have been provided or improved thanks to: - Matteo Ferrigato (Italian). % 'matteo339' - % 2023-01-02: https://github.com/gusbrs/zref-vario/issues/1 - -If I have inadvertently left anyone off the list I apologize, and please let -me know, so that I can correct the oversight. - -Thank you all very much! - - -\section{Change history} - -A change log with relevant changes for each version, eventual upgrade -instructions, and upcoming changes, is maintained in the package's repository, -at \url{https://github.com/gusbrs/zref-vario/blob/main/CHANGELOG.md}. The -change log is also distributed with the package's documentation through CTAN -upon release so, most likely, \texttt{texdoc zref-vario/changelog} should -provide easy local access to it. An archive of historical versions of the -package is also kept at \url{https://github.com/gusbrs/zref-vario/releases}. - -\end{document} -- cgit v1.2.3