% \iffalse meta-comment
%
% File: zref-vario.dtx
%
% This file is part of the LaTeX package "zref-vario".
%
% Copyright (C) 2022-2024 gusbrs
%
% 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 gusbrs.
%
% 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
%
% \iffalse
%<*driver>
\documentclass{l3doc}
% Have \GetFileInfo pick up date and version data and used in the
% documentation.
\usepackage{zref-vario}
\begin{document}
\DocInput{zref-vario.dtx}
\end{document}
%</driver>
% \fi
%
% \DoNotIndex{\\,\{,\}}
%
% \NewDocumentCommand\githubissue{m}{^^A
% issue~\href{https://github.com/gusbrs/zref-vario/issues/#1}{\##1}}
%
% \NewDocumentCommand\githubPR{m}{^^A
% PR~\href{https://github.com/gusbrs/zref-vario/pull/#1}{\##1}}
%
% \NewDocumentCommand\contributor{m}{#1}
% \NewDocumentCommand\username{m}{`\texttt{#1}'}
%
% \NewDocumentCommand\opt{m}{\texttt{#1}}
%
% \pdfstringdefDisableCommands{^^A
% \def\opt#1{#1}
% }
%
% ^^A Have the Index at 'section' level rather than 'part'. Otherwise it is
% ^^A just the same definition from 'l3doc.cls'.
% \IndexPrologue{^^A
% \section*{Index}
% \markboth{Index}{Index}
% \addcontentsline{toc}{section}{Index}
% The italic numbers denote the pages where the corresponding entry is
% described, numbers underlined point to the definition, all others indicate
% the places where it is used.^^A
% }
%
%
% \GetFileInfo{zref-vario.sty}
%
% \title{^^A
% The \pkg{zref-vario} package^^A
% \texorpdfstring{\\{}\medskip{}}{ - }^^A
% Code documentation^^A
% \texorpdfstring{\medskip{}}{}^^A
% }
%
% \author{^^A
% \texorpdfstring{\texttt{gusbrs}\\[0.8em]
% \url{https://github.com/gusbrs/zref-vario}\\
% \url{https://www.ctan.org/pkg/zref-vario}}{gusbrs}}
%
% \date{Version \fileversion\ -- \filedate}
%
% \maketitle
%
% \begin{center}
% \textbf{EXPERIMENTAL}
% \end{center}
%
%
% \tableofcontents
%
% \clearpage{}
%
% \section{Initial setup}
%
% Start the \pkg{DocStrip} guards.
% \begin{macrocode}
%<*package>
% \end{macrocode}
%
% Identify the internal prefix (\LaTeX3 \pkg{DocStrip} convention).
% \begin{macrocode}
%<@@=zrefvario>
% \end{macrocode}
%
%
% \begin{macrocode}
\def\zrefvario@required@kernel{2023-11-01}
\NeedsTeXFormat{LaTeX2e}[\zrefvario@required@kernel]
\providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
\IfFormatAtLeastTF{\zrefvario@required@kernel}
{}
{%
\PackageError{zref-vario}{LaTeX kernel too old}
{%
'zref-vario' requires a LaTeX kernel \zrefvario@required@kernel\space or newer.%
}%
}%
% \end{macrocode}
%
%
% Identify the package.
% \begin{macrocode}
\ProvidesExplPackage {zref-vario} {2024-11-25} {0.1.12}
{Extended LaTeX page cross-references with varioref and zref-clever}
% \end{macrocode}
%
%
% Required packages.
%
% \begin{macrocode}
\RequirePackage { zref-clever } [ 2022-01-28 ] % v0.2.0-alpha
\RequirePackage { varioref }
% \end{macrocode}
%
% Also note that, contrary to \pkg{zref-clever}, \pkg{zref-vario} is
% incompatible with \pkg{cleveref}, because the latter patches \pkg{varioref}
% in ways that break \pkg{zref-vario}.
%
%
% \begin{macro}
% {
% \l_@@_tmpa_tl ,
% \l_@@_tmpb_tl ,
% }
% Temporary scratch variables.
% \begin{macrocode}
\tl_new:N \l_@@_tmpa_tl
\tl_new:N \l_@@_tmpb_tl
% \end{macrocode}
% \end{macro}
%
%
% \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.
%
% \begin{macro}[EXP]{\@@_ref_opt_default_cs:nn}
% \begin{syntax}
% \cs{@@_ref_opt_default_cs:nn} \Arg{option} \Arg{signature}
% \end{syntax}
% \begin{macrocode}
\cs_new:Npn \@@_ref_opt_default_cs:nn #1#2
{ @@_ref_opt_default_ #1 : #2 }
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}[EXP]{\@@_base_lang:n}
% \begin{syntax}
% \cs{@@_base_lang:n} \Arg{language}
% \end{syntax}
% \begin{macrocode}
\cs_new:Npn \@@_base_lang:n #1
{
\zrefclever_language_if_declared:nTF {#1}
{ \tl_use:c { \zrefclever_language_varname:n {#1} } }
{ zv_unknown_language }
}
\cs_generate_variant:Nn \@@_base_lang:n { e }
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\l_@@_ref_language_tl}
% An internal version of \cs{l_zrefclever_ref_language_tl}, since we need to
% retreive the current value of the variable in multiple places.
% \begin{macrocode}
\tl_new:N \l_@@_ref_language_tl
\tl_set:Nn \l_@@_ref_language_tl { \l_zrefclever_ref_language_tl }
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\@@_ref_opt_name_lang_tl:nn}
% \begin{syntax}
% \cs{@@_ref_opt_name_lang_tl:nn} \Arg{lang} \Arg{option}
% \end{syntax}
% \begin{macrocode}
\cs_new:Npn \@@_ref_opt_name_lang_tl:nn #1#2
{ g_@@_ref_opt_lang_ \@@_base_lang:n {#1} _ #2 _tl }
\cs_generate_variant:Nn \@@_ref_opt_name_lang_tl:nn { en }
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\@@_ref_opt_name_lang_cs:nnn}
% \begin{syntax}
% \cs{@@_ref_opt_name_lang_cs:nnn} \Arg{lang} \Arg{option} \Arg{signature}
% \end{syntax}
% \begin{macrocode}
\cs_new:Npn \@@_ref_opt_name_lang_cs:nnn #1#2#3
{ @@_ref_opt_lang_ \@@_base_lang:n {#1} _ #2 : #3 }
\cs_generate_variant:Nn \@@_ref_opt_name_lang_cs:nnn { enn }
% \end{macrocode}
% \end{macro}
%
%
% Retrieving options values.
%
% \begin{macro}
% {
% \@@_ref_opt_tl_get:nnN ,
% \@@_ref_opt_cs_get:nnnN ,
% }
% \begin{syntax}
% \cs{@@_ref_opt_tl_get:nnN} \Arg{lang} \Arg{option} \Arg{tl var to set}
% \cs{@@_ref_opt_cs_get:nnnN} \Arg{lang} \Arg{option}
% ~~\Arg{cs signature} \Arg{cs to set}
% \end{syntax}
% \begin{macrocode}
\cs_new_protected:Npn \@@_ref_opt_tl_get:nnN #1#2#3
{
\tl_if_exist:cTF
{ \@@_ref_opt_name_lang_tl:nn {#1} {#2} }
{
\tl_set_eq:Nc #3
{ \@@_ref_opt_name_lang_tl:nn {#1} {#2} }
}
{
\tl_set_eq:Nc #3
{ \@@_ref_opt_name_lang_tl:nn { zv_unknown_language } {#2} }
}
}
\cs_generate_variant:Nn \@@_ref_opt_tl_get:nnN { enN }
\cs_new_protected:Npn \@@_ref_opt_cs_get:nnnN #1#2#3#4
{
\cs_if_exist:cTF
{ \@@_ref_opt_name_lang_cs:nnn {#1} {#2} {#3} }
{
\cs_set_eq:Nc #4
{ \@@_ref_opt_name_lang_cs:nnn {#1} {#2} {#3} }
}
{
\cs_if_exist:cTF
{ \@@_ref_opt_default_cs:nn {#2} {#3} }
{
\cs_set_eq:Nc #4
{ \@@_ref_opt_default_cs:nn {#2} {#3} }
}
{
\cs_set_eq:Nc #4
{
\@@_ref_opt_name_lang_cs:nnn
{ zv_unknown_language } {#2} {#3}
}
}
}
}
\cs_generate_variant:Nn \@@_ref_opt_cs_get:nnnN { ennN }
% \end{macrocode}
% \end{macro}
%
%
% Handle the options set of the user commands, and add support for
% \pkg{varioref} optional arguments. All commands can receive the same set of
% options \cs{zcref} can, and these are processed the same way and
% ``consumed'' by any \cs{zcref} or \cs{zcpageref} calls. Besides those,
% \opt{vother} is made available for \cs{zvpageref}, corresponding to its
% second optional argument, and \opt{vcurrent} which is available to all
% commands except \cs{fullref}, corresponding to their first optional
% arguments. The distinction between \cs{l_@@_reftextcurrent_tl} and
% \cs{l_@@_vref_reftextcurrent_tl} is in their default/initial values. The
% default values for the optional arguments of \cs{vpageref}, \cs{vrefrange},
% and \cs{vpagerefrange} are set to \cs{reftextcurrent}, while the default
% value of the optional argument of \cs{vref} is empty.
%
% \begin{macrocode}
\tl_new:N \l_@@_reftextcurrent_tl
\tl_set:Nn \l_@@_reftextcurrent_tl { \reftextcurrent }
\tl_new:N \l_@@_vref_reftextcurrent_tl
\tl_new:N \l_@@_reftextother_tl
\keys_define:nn { zref-vario/current }
{
vcurrent .code:n =
{
\tl_set:Nn \l_@@_reftextcurrent_tl {#1}
\tl_set:Nn \l_@@_vref_reftextcurrent_tl {#1}
} ,
vcurrent .value_required:n = true ,
}
\keys_define:nn { zref-vario/other }
{
vother .tl_set:N = \l_@@_reftextother_tl ,
vother .value_required:n = true ,
}
% \end{macrocode}
%
% See \url{https://github.com/latex3/latex3/issues/1254}.
% ^^A zref-vario/ref
% ^^A zref-vario/ref-oneoptarg
% ^^A zref-vario/ref-twooptargs
% \begin{macrocode}
\keys_define:nn { zref-vario }
{
ref .inherit:n =
{ zref-clever/reference } ,
ref-oneoptarg .inherit:n =
{ zref-clever/reference , zref-vario/current } ,
ref-twooptargs .inherit:n =
{ zref-clever/reference , zref-vario/current , zref-vario/other } ,
}
% \end{macrocode}
%
%
% \begin{macro}[int]{\zvLanguageSetup}
% User interface for setting ``strings'' (\texttt{reftext\dots{}} options) and
% ``formats'' (\texttt{\dots{}format} options) for each language.
% \begin{syntax}
% \cs{zvLanguageSetup}\marg{language}\marg{options}
% \end{syntax}
% \begin{macrocode}
\tl_new:N \l_@@_setup_language_tl
\seq_new:N \g_@@_setup_languages_seq
\NewDocumentCommand \zvLanguageSetup { m m }
{
\AddToHook { begindocument/before }
{
\group_begin:
\zrefclever_language_if_declared:nTF {#1}
{
\tl_set:Nn \l_@@_setup_language_tl {#1}
\keys_set:nn { zref-vario/langsetup } {#2}
\seq_gput_right:Ne \g_@@_setup_languages_seq
{ \@@_base_lang:n {#1} }
}
{ \msg_warning:nnn { zref-vario } { unknown-language-setup } {#1} }
\group_end:
}
}
\msg_new:nnn { zref-vario } { unknown-language-setup }
{
Language~'#1'~is~unknown~\msg_line_context:.~Can't~set~it~up.~
The~language~must~be~declared~for~'zref-clever',~see~its~documentation.
}
\@onlypreamble \zvLanguageSetup
% \end{macrocode}
% \end{macro}
%
%
% \begin{macrocode}
\cs_new_protected:Npn \@@_opt_tl_gset:Nn #1#2
{
\tl_if_exist:NF #1
{ \tl_new:N #1 }
\tl_gset:Nn #1 {#2}
}
\cs_generate_variant:Nn \@@_opt_tl_gset:Nn { cn }
% \end{macrocode}
%
% \begin{macrocode}
\keys_define:nn { zref-vario/langsetup }
{
reftextfaceafter .code:n =
{
\@@_opt_tl_gset:cn
{
\@@_ref_opt_name_lang_tl:en
{ \l_@@_setup_language_tl }
{ reftextfaceafter }
} {#1}
} ,
reftextfacebefore .code:n =
{
\@@_opt_tl_gset:cn
{
\@@_ref_opt_name_lang_tl:en
{ \l_@@_setup_language_tl }
{ reftextfacebefore }
} {#1}
} ,
reftextafter .code:n =
{
\@@_opt_tl_gset:cn
{
\@@_ref_opt_name_lang_tl:en
{ \l_@@_setup_language_tl }
{ reftextafter }
} {#1}
} ,
reftextbefore .code:n =
{
\@@_opt_tl_gset:cn
{
\@@_ref_opt_name_lang_tl:en
{ \l_@@_setup_language_tl }
{ reftextbefore }
} {#1}
} ,
reftextcurrent .code:n =
{
\@@_opt_tl_gset:cn
{
\@@_ref_opt_name_lang_tl:en
{ \l_@@_setup_language_tl }
{ reftextcurrent }
} {#1}
} ,
reftextfaraway .code:n =
{
\cs_gset_nopar:cpn
{
\@@_ref_opt_name_lang_cs:enn
{ \l_@@_setup_language_tl }
{ reftextfaraway } { n }
}
##1
{#1}
} ,
reftextpagerange .code:n =
{
\cs_gset_nopar:cpn
{
\@@_ref_opt_name_lang_cs:enn
{ \l_@@_setup_language_tl }
{ reftextpagerange } { nn }
}
##1##2
{#1}
} ,
reftextlabelrange .code:n =
{
\cs_gset_nopar:cpn
{
\@@_ref_opt_name_lang_cs:enn
{ \l_@@_setup_language_tl }
{ reftextlabelrange } { nn }
}
##1##2
{#1}
} ,
vrefformat .code:n =
{
\cs_gset_nopar:cpn
{
\@@_ref_opt_name_lang_cs:enn
{ \l_@@_setup_language_tl }
{ vrefformat } { nn }
}
##1##2
{#1}
} ,
vrefrangeformat .code:n =
{
\cs_gset_nopar:cpn
{
\@@_ref_opt_name_lang_cs:enn
{ \l_@@_setup_language_tl }
{ vrefrangeformat } { nnn }
}
##1##2##3
{#1}
} ,
fullrefformat .code:n =
{
\cs_gset_nopar:cpn
{
\@@_ref_opt_name_lang_cs:enn
{ \l_@@_setup_language_tl }
{ fullrefformat } { n }
}
##1
{#1}
} ,
}
% \end{macrocode}
%
%
% Default reference formats for all languages. These will be used by
% \cs{@@_ref_opt_cs_get:nnnN}, unless a language specific setting for the same
% format has been set. \cs{zreftextfaraway} is defined so it can be called
% with different arguments in \cs{zvpageref} (where it is alone) and in
% \cs{zfullref} (where it is the second of the pair).
%
% \begin{macrocode}
\cs_new_nopar:cpn
{ \@@_ref_opt_default_cs:nn { vrefformat } { nn } } #1#2
{
\zcref {#2} ~
\zvpageref [ S=false, typeset=both, vcurrent={#1} ] {#2}
}
\cs_new_nopar:cpn
{ \@@_ref_opt_default_cs:nn { vrefrangeformat } { nnn } } #1#2#3
{
\reftextlabelrange {#2} {#3} ~
\zvpagerefrange [ S=false, typeset=both, vcurrent={#1} ] {#2} {#3}
}
\cs_new_nopar:cpn
{ \@@_ref_opt_default_cs:nn { fullrefformat } { n } } #1
{
\zcref {#1} ~
\zreftextfaraway [ S=false, typeset=both ] {#1}
}
\NewDocumentCommand \zreftextfaraway { s O { } m }
{ \zref@wrapper@babel \@@_zreftextfaraway:nnn {#3} {#1} {#2} }
\cs_new_protected:Npn \@@_zreftextfaraway:nnn #1#2#3
{
\group_begin:
\keys_set:nn { zref-vario/ref } {#3}
\bool_if:nT {#2}
{
\keys_set:nn { zref-vario/ref } { nohyperref }
\bool_set_false:N \l_@@_hyperlink_bool
}
\tl_set:Nn \l_@@_linklabel_tl {#1}
\@@_varioref_setup:
\reftextfaraway {#1}
\group_end:
}
% \end{macrocode}
%
%
% Warnings and values for missing strings / unknown languages.
%
% \begin{macrocode}
\group_begin:
\tl_set:Nn \l_@@_setup_language_tl { zv_unknown_language }
\AddToHook { begindocument/before }
{
\keys_set:nn { zref-vario/langsetup }
{
reftextfaceafter =
{
\msg_warning:nnee { zref-vario } { missing-string }
{ reftextfaceafter } { \l_@@_ref_language_tl }
\zref@default
} ,
reftextfacebefore =
{
\msg_warning:nnee { zref-vario } { missing-string }
{ reftextfacebefore } { \l_@@_ref_language_tl }
\zref@default
} ,
reftextafter =
{
\msg_warning:nnee { zref-vario } { missing-string }
{ reftextafter } { \l_@@_ref_language_tl }
\zref@default
} ,
reftextbefore =
{
\msg_warning:nnee { zref-vario } { missing-string }
{ reftextbefore } { \l_@@_ref_language_tl }
\zref@default
} ,
reftextcurrent =
{
\msg_warning:nnee { zref-vario } { missing-string }
{ reftextcurrent } { \l_@@_ref_language_tl }
\zref@default
} ,
reftextfaraway =
{
\msg_warning:nnee { zref-vario } { missing-string }
{ reftextfaraway } { \l_@@_ref_language_tl }
\zref@default
} ,
reftextpagerange =
{
\msg_warning:nnee { zref-vario } { missing-string }
{ reftextpagerange } { \l_@@_ref_language_tl }
\zref@default
} ,
reftextlabelrange =
{
\msg_warning:nnee { zref-vario } { missing-string }
{ reftextlabelrange } { \l_@@_ref_language_tl }
\zref@default
} ,
}
}
\group_end:
\msg_new:nnn { zref-vario } { missing-string }
{ Missing~'#1'~string~for~language~'#2'~\msg_line_context:. }
% \end{macrocode}
%
%
% A general initial warning in case the language is altogether not set up.
%
% \begin{macrocode}
\AddToHook { begindocument/before }
{
\AddToHook { begindocument }
{
\seq_if_in:NeF \g_@@_setup_languages_seq
{ \@@_base_lang:e { \l_@@_ref_language_tl } }
{
\msg_warning:nne { zref-vario } { language-not-setup }
{ \l_@@_ref_language_tl }
}
}
}
\msg_new:nnn { zref-vario } { language-not-setup }
{
Language~'#1'~is~not~set~up~for~'zref-vario'.~
See~documentation~for~'\iow_char:N\\zvLanguageSetup'.
}
% \end{macrocode}
%
%
%
% Provide proper hyperlinking for the ``nearby'' page references.
% \pkg{hyperref} makes \cs{vref} a \emph{single} link, including both the
% standard and the page reference (see Ulrike Fischer's answer and discussion
% in the comments at \url{https://tex.stackexchange.com/a/655106}). However,
% it does not provide the same treatment to \cs{vpageref}, where there's no
% linking at all for nearby pages, to \cs{vrefrange}, \cs{vpagerefrange}, or
% \cs{vnameref}. In my view, this makes \pkg{hyperref} inconsistent.
% \pkg{cleveref} indeed discusses the issue in the ``Known Bugs and
% Work-Arounds'' section, mentioning two problems. The first, that the page
% reference does not honor the \texttt{nameinlink} option, which it is
% actually the same behavior we get from \cs{vnameref}. The second, that
% nearby page references are not included in the links or hyperlinked when by
% themselves. This latter problem may be considered undesirable, and even a
% ``bug'', but at least \pkg{cleveref}'s behavior in this regard is
% consistent.
%
% This is actually tricky and I think the best alternative here is to not even
% try to make a single link of both references, as \pkg{hyperref} does for
% \cs{vref}. But rather to offer ways to hyperlink the ``nearby'' page
% references separately, which is something that can work for paired
% references and for standalone page references just as well.
% \cs{zvhyperlink} is provided for such purpose, and is meant to be used
% either in the reference format settings of \cs{zvLanguageSetup}, or in the
% \opt{vcurrent} and \opt{vother} options of the reference commands. It only
% makes a hyperlink if used in one such place (technically, if
% \cs{l_@@_linklabel_tl} is not empty), if \cs{l_@@_hyperlink_bool} is true
% (to control for starred variants) and if \pkg{hyperref} and
% \pkg{zref-hyperref} are loaded, otherwise it passes on its argument
% untouched.
%
%
% \begin{macrocode}
\bool_new:N \g_@@_zref_hyperref_loaded_bool
\bool_new:N \l_@@_hyperlink_bool
\AddToHook { package/zref-hyperref/after }
{
\AddToHook { package/hyperref/after }
{
\bool_gset_true:N \g_@@_zref_hyperref_loaded_bool
\bool_set_true:N \l_@@_hyperlink_bool
}
}
\tl_new:N \l_@@_linklabel_tl
% \end{macrocode}
%
% \begin{macro}[int]{\zvhyperlink}
% \begin{syntax}
% \cs{zvhyperlink}\marg{text}
% \end{syntax}
% \begin{macrocode}
\NewDocumentCommand \zvhyperlink { m }
{ \@@_hyperlink:n {#1} }
\cs_new_protected:Npn \@@_hyperlink:n #1
{
\bool_lazy_all:nTF
{
{ \g_@@_zref_hyperref_loaded_bool }
{ \l_@@_hyperlink_bool }
{ ! \tl_if_empty_p:V \l_@@_linklabel_tl }
}
{
\hyperlink
{ \zref@extractdefault { \l_@@_linklabel_tl } { anchor } { } }
{#1}
}
{#1}
}
% \end{macrocode}
% \end{macro}
%
%
%
% \section{User interface}
%
% \begin{macro}
% {
% \@@_vref_pagenum:Nn ,
% \@@_vrefpagenum:Nn ,
% \@@_vref_label:n ,
% }
% These three small functions are responsible for ``connecting''
% \pkg{varioref} with \pkg{zref}, instead of with the standard referencing
% system. They are meant to locally replace their \pkg{varioref}
% counterparts: \cs{vref@pagenum}, \cs{vrefpagenum}, and \cs{vref@label}.
% \begin{macrocode}
\cs_new_protected:Npn \@@_vref_pagenum:Nn #1#2
{
\exp_args:NNNo \exp_args:NNo \cs_set_nopar:Npn #1
{ \zref@extractdefault {#2} { \l_@@_pageprop_tl } { ?? } }
}
\cs_new_protected:Npn \@@_vrefpagenum:Nn #1#2
{
\zref@refused {#2}
\@@_vref_pagenum:Nn #1 {#2}
}
\cs_new_protected:Npn \@@_vref_label:n #1
{ \zref@labelbyprops {#1} { \l_@@_pageprop_tl } }
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_varioref_setup:}
% Sets things up for \pkg{varioref} to work with \pkg{zref}/\pkg{zref-clever}.
% It is pretty straightforward, but it is the core of the package.
% \cs{l_@@_varioref_setup_bool} ensures this setup runs only once in case of
% nested calls to the package's commands.
% \begin{macrocode}
\bool_new:N \l_@@_varioref_setup_bool
\cs_new_protected:Npn \@@_varioref_setup:
{
\bool_if:NF \l_@@_varioref_setup_bool
{
\bool_set_true:N \l_@@_varioref_setup_bool
\@vrefhandlespacefalse
\cs_set_eq:NN \vref@pagenum \@@_vref_pagenum:Nn
\cs_set_eq:NN \vrefpagenum \@@_vrefpagenum:Nn
\cs_set_eq:NN \vref@label \@@_vref_label:n
\@@_ref_opt_tl_get:enN
{ \l_@@_ref_language_tl }
{ reftextfaceafter }
\reftextfaceafter
\@@_ref_opt_tl_get:enN
{ \l_@@_ref_language_tl }
{ reftextfacebefore }
\reftextfacebefore
\@@_ref_opt_tl_get:enN
{ \l_@@_ref_language_tl }
{ reftextafter }
\reftextafter
\@@_ref_opt_tl_get:enN
{ \l_@@_ref_language_tl }
{ reftextbefore }
\reftextbefore
\@@_ref_opt_tl_get:enN
{ \l_@@_ref_language_tl }
{ reftextcurrent }
\reftextcurrent
\@@_ref_opt_cs_get:ennN
{ \l_@@_ref_language_tl }
{ reftextfaraway } { n }
\reftextfaraway
\@@_ref_opt_cs_get:ennN
{ \l_@@_ref_language_tl }
{ reftextpagerange } { nn }
\reftextpagerange
\@@_ref_opt_cs_get:ennN
{ \l_@@_ref_language_tl }
{ reftextlabelrange } { nn }
\reftextlabelrange
\@@_ref_opt_cs_get:ennN
{ \l_@@_ref_language_tl }
{ vrefformat } { nn }
\vrefformat
\@@_ref_opt_cs_get:ennN
{ \l_@@_ref_language_tl }
{ vrefrangeformat } { nnn }
\vrefrangeformat
\@@_ref_opt_cs_get:ennN
{ \l_@@_ref_language_tl }
{ fullrefformat } { n }
\fullrefformat
}
}
% \end{macrocode}
% \end{macro}
%
%
% User commands.
%
% \begin{macro}[int]{\zvref}
% \begin{syntax}
% \cs{zvref}\meta{*}\oarg{options}\marg{label}
% \end{syntax}
% \begin{macrocode}
\NewDocumentCommand \zvref { s O { } m }
{ \zref@wrapper@babel \@@_zvref:nnn {#3} {#1} {#2} }
\cs_new_protected:Npn \@@_zvref:nnn #1#2#3
{
\group_begin:
\keys_set:nn { zref-vario/ref-oneoptarg } {#3}
\bool_if:nT {#2}
{
\keys_set:nn { zref-vario/ref } { nohyperref }
\bool_set_false:N \l_@@_hyperlink_bool
}
\tl_set:Nn \l_@@_linklabel_tl {#1}
\@@_varioref_setup:
\@@_vref:Vn \l_@@_vref_reftextcurrent_tl {#1}
\group_end:
}
% \end{macrocode}
% ``Ideally'', we'd be using \cs{vref} here, but \pkg{hyperref} redefines
% \cs{vref@star} and \cs{vr@f}, hard-coding what was supposed to be
% configurable\dots{}, so we use \cs{vrefformat} instead, which is the
% original definition of \cs{vref@star}, and \cs{vr@f} also boils down to
% \cs{vref@star} when \cs{@vrefhandlespace} is false, which is our case.
% \begin{macrocode}
\cs_new_protected:Npn \@@_vref:nn #1#2
{ \vrefformat {#1} {#2} }
\cs_generate_variant:Nn \@@_vref:nn { Vn }
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}[int]{\zvpageref}
% \begin{syntax}
% \cs{zvpageref}\meta{*}\oarg{options}\marg{label}
% \end{syntax}
% \begin{macrocode}
\NewDocumentCommand \zvpageref { s O { } m }
{ \zref@wrapper@babel \@@_zvpageref:nnn {#3} {#1} {#2} }
\cs_new_protected:Npn \@@_zvpageref:nnn #1#2#3
{
\group_begin:
\keys_set:nn { zref-vario/ref-twooptargs } {#3}
\bool_if:nT {#2}
{
\keys_set:nn { zref-vario/ref } { nohyperref }
\bool_set_false:N \l_@@_hyperlink_bool
}
\tl_set:Nn \l_@@_linklabel_tl {#1}
\@@_varioref_setup:
\@@_vpageref:VVn \l_@@_reftextcurrent_tl
\l_@@_reftextother_tl {#1}
\bool_lazy_and:nnT
{ \g_@@_zrefcheck_available_bool }
{ \l_@@_with_vcheck_bool }
{
\zrefcheck_zrefvario_label:
\vref@pagenum \l_@@_tmpa_tl { \the\c@vrcnt @vr }
\vrefpagenum \l_@@_tmpb_tl {#1}
\tl_if_eq:NNT \l_@@_tmpa_tl \l_@@_tmpb_tl
{
\zrefcheck_zrefvario_run_check_on_label:Vn
\l_@@_vcheck_tl {#1}
}
}
\group_end:
}
\cs_new_protected:Npn \@@_vpageref:nnn #1#2#3
{ \vpageref [{#1}] [#2] {#3} }
\cs_generate_variant:Nn \@@_vpageref:nnn { VVn }
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}[int]{\zvrefrange}
% \begin{syntax}
% \cs{zvrefrange}\meta{*}\oarg{options}\marg{label}\marg{label}
% \end{syntax}
% \begin{macrocode}
\NewDocumentCommand \zvrefrange { s O { } m m }
{
\zref@wrapper@babel
{ \zref@wrapper@babel \@@_zvrefrange:nnnn {#3} }
{#4} {#1} {#2}
}
\cs_new_protected:Npn \@@_zvrefrange:nnnn #1#2#3#4
{
\group_begin:
\keys_set:nn { zref-vario/ref-oneoptarg } {#4}
\bool_if:nT {#3}
{
\keys_set:nn { zref-vario/ref } { nohyperref }
\bool_set_false:N \l_@@_hyperlink_bool
}
\@@_varioref_setup:
\vpagerefcompare {#1} {#2}
{ \tl_set:Nn \l_@@_linklabel_tl {#1} } { }
\@@_vrefrange:Vnn \l_@@_reftextcurrent_tl {#1} {#2}
\group_end:
}
\cs_new_protected:Npn \@@_vrefrange:nnn #1#2#3
{ \vrefrange [{#1}] {#2} {#3} }
\cs_generate_variant:Nn \@@_vrefrange:nnn { Vnn }
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}[int]{\zvpagerefrange}
% \begin{syntax}
% \cs{zvpagerefrange}\meta{*}\oarg{options}\marg{label}\marg{label}
% \end{syntax}
% \begin{macrocode}
\NewDocumentCommand \zvpagerefrange { s O { } m m }
{
\zref@wrapper@babel
{ \zref@wrapper@babel \@@_zvpagerefrange:nnnn {#3} }
{#4} {#1} {#2}
}
\cs_new_protected:Npn \@@_zvpagerefrange:nnnn #1#2#3#4
{
\group_begin:
\keys_set:nn { zref-vario/ref-oneoptarg } {#4}
\bool_if:nT {#3}
{
\keys_set:nn { zref-vario/ref } { nohyperref }
\bool_set_false:N \l_@@_hyperlink_bool
}
\@@_varioref_setup:
\vpagerefcompare {#1} {#2}
{ \tl_set:Nn \l_@@_linklabel_tl {#1} } { }
\@@_vpagerefrange:Vnn \l_@@_reftextcurrent_tl {#1} {#2}
\bool_lazy_and:nnT
{ \g_@@_zrefcheck_available_bool }
{ \l_@@_with_vcheck_bool }
{
\zrefcheck_zrefvario_label:
\vrefpagenum \l_@@_tmpa_tl {#1}
\vrefpagenum \l_@@_tmpb_tl {#2}
\tl_if_eq:NNT \l_@@_tmpa_tl \l_@@_tmpb_tl
{
\vref@pagenum \l_@@_tmpa_tl { \the\c@vrcnt @vr }
\tl_if_eq:NNT \l_@@_tmpa_tl \l_@@_tmpb_tl
{
\zrefcheck_zrefvario_run_check_on_label:Vn
\l_@@_vcheck_tl {#1}
\zrefcheck_zrefvario_run_check_on_label:Vn
\l_@@_vcheck_tl {#2}
}
}
}
\group_end:
}
\cs_new_protected:Npn \@@_vpagerefrange:nnn #1#2#3
{ \vpagerefrange [{#1}] {#2} {#3} }
\cs_generate_variant:Nn \@@_vpagerefrange:nnn { Vnn }
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}[int]{\zfullref}
% \begin{syntax}
% \cs{zfullref}\meta{*}\oarg{options}\marg{label}
% \end{syntax}
% \begin{macrocode}
\NewDocumentCommand \zfullref { s O { } m }
{ \zref@wrapper@babel \@@_zfullref:nnn {#3} {#1} {#2} }
\cs_new_protected:Npn \@@_zfullref:nnn #1#2#3
{
\group_begin:
\keys_set:nn { zref-vario/ref } {#3}
\bool_if:nT {#2}
{
\keys_set:nn { zref-vario/ref } { nohyperref }
\bool_set_false:N \l_@@_hyperlink_bool
}
\tl_set:Nn \l_@@_linklabel_tl {#1}
\@@_varioref_setup:
\fullref {#1}
\group_end:
}
% \end{macrocode}
% \end{macro}
%
%
%
% \section{\pkg{zref-check} integration}
%
% Integration with \pkg{zref-check}. \opt{vcheck}, differently from
% \opt{check}, receives only two values \texttt{above} and \texttt{below},
% since these are the only two checks which make sense for \pkg{zref-vario}.
% This means that it also does not take \cs{zcheck}'s options, but these can
% always be passed to \opt{check}. Besides this, \opt{vcheck}'s check should
% only be done when label(s) and reference are in the same page, that is, when
% \opt{vcurrent} is used. Furthermore, since \pkg{varioref} handles the case
% where the reference crosses page boundaries, we only set one label for the
% purpose, and this is done at the end of the reference, because that's the
% point \pkg{varioref} itself uses to check if label and reference are in the
% same page.
%
% \begin{macrocode}
\bool_new:N \g_@@_zrefcheck_available_bool
\bool_new:N \l_@@_with_vcheck_bool
\tl_new:N \l_@@_vcheck_tl
\AddToHook { begindocument/before }
{
\IfPackageLoadedTF { zref-check }
{
\IfPackageAtLeastTF { zref-check } { 2022-02-08 }
{
\bool_gset_true:N \g_@@_zrefcheck_available_bool
\keys_define:nn { zref-vario/current }
{
vcheck .choices:nn =
{ above , below }
{
\bool_set_true:N \l_@@_with_vcheck_bool
\tl_set:NV \l_@@_vcheck_tl \l_keys_choice_tl
} ,
}
}
{
\bool_gset_false:N \g_@@_zrefcheck_available_bool
\keys_define:nn { zref-vario/current }
{
vcheck .code:n =
{ \msg_warning:nn { zref-vario } { zref-check-unavailable } } ,
}
}
}
{
\bool_gset_false:N \g_@@_zrefcheck_available_bool
\keys_define:nn { zref-vario/current }
{
vcheck .code:n =
{ \msg_warning:nn { zref-vario } { zref-check-unavailable } } ,
}
}
}
\msg_new:nnn { zref-vario } { zref-check-unavailable }
{
Option~'vcheck'~is~only~available~when~'zref-check'~is~loaded~
and~newer~than~'2022-02-08~v0.2.4'.
}
% \end{macrocode}
%
%
% \section{Languages}
%
% Localization for the languages provided by the author, except where
% otherwise stated. However, I could only do so thanks to \pkg{varioref}, in
% particular for languages I don't really know. So, credits go to the
% contributors of \pkg{varioref}. Of course, if any native speaker would like
% to review these, or contribute new ones, it is much welcome. Note, however,
% that since \pkg{zref-vario} depends on \pkg{zref-clever} and piggybacks on
% its language infrastructure, it only makes sense to provide localization
% here for languages already supported by \pkg{zref-clever}.
%
%
% \begin{macrocode}
\zvLanguageSetup { english }
{
reftextfaceafter =
{on~the~\zvhyperlink{\reftextvario{facing}{next}~page}} ,
reftextfacebefore =
{on~the~\zvhyperlink{\reftextvario{facing}{preceding}~page}} ,
reftextafter =
{on~the~\zvhyperlink{\reftextvario{following}{next}~page}} ,
reftextbefore =
{on~the~\zvhyperlink{\reftextvario{preceding}{previous}~page}} ,
reftextcurrent =
{on~\reftextvario{}{the~}\zvhyperlink{\reftextvario{this}{current}~page}} ,
reftextfaraway = {on~\zcpageref{#1}} ,
reftextpagerange = {on~\zcpageref[range]{#1,#2}} ,
reftextlabelrange = {\zcref[range]{#1,#2}} ,
}
% \end{macrocode}
%
%
% \begin{macrocode}
\zvLanguageSetup { german }
{
reftextfaceafter = {auf~der~\zvhyperlink{nächsten~Seite}} ,
reftextfacebefore = {auf~der~\zvhyperlink{vorherigen~Seite}} ,
reftextafter = {auf~der~\zvhyperlink{nächsten~Seite}} ,
reftextbefore = {auf~der~\zvhyperlink{vorherigen~Seite}} ,
reftextcurrent = {auf~\zvhyperlink{dieser~Seite}} ,
reftextfaraway = {auf~\zcpageref[d=D,g=f]{#1}} ,
reftextpagerange = {auf~den~\zcpageref[range,d=D,g=f]{#1,#2}} ,
reftextlabelrange = {\zcref[range]{#1,#2}} ,
}
% \end{macrocode}
%
%
% \begin{macrocode}
\zvLanguageSetup { french }
{
reftextfaceafter =
{\zvhyperlink{page~\reftextvario{ci-contre}{suivante}}} ,
reftextfacebefore =
{\zvhyperlink{page~\reftextvario{ci-contre}{précédente}}} ,
reftextafter = {\zvhyperlink{page~suivante}} ,
reftextbefore = {\zvhyperlink{page~précédente}} ,
reftextcurrent = {de~la~\zvhyperlink{présente~page}} ,
reftextfaraway = {\zcpageref[g=f]{#1}} ,
reftextpagerange = {\zcpageref[range,g=f]{#1,#2}} ,
reftextlabelrange = {\zcref[range]{#1,#2}} ,
}
% \end{macrocode}
%
%
% \begin{macrocode}
\zvLanguageSetup { portuguese }
{
reftextfaceafter =
{na~\zvhyperlink{\reftextvario{página~oposta}{próxima~página}}} ,
reftextfacebefore =
{na~\zvhyperlink{página~\reftextvario{oposta}{anterior}}} ,
reftextafter =
{na~\zvhyperlink{\reftextvario{página~seguinte}{próxima~página}}} ,
reftextbefore =
{na~\zvhyperlink{página~\reftextvario{anterior}{precedente}}} ,
reftextcurrent = {\zvhyperlink{nesta~página}} ,
reftextfaraway = {na~\zcpageref[g=f]{#1}} ,
reftextpagerange = {nas~\zcpageref[range,g=f]{#1,#2}} ,
reftextlabelrange = {\zcref[range]{#1,#2}} ,
}
% \end{macrocode}
%
%
% \begin{macrocode}
\zvLanguageSetup { spanish }
{
reftextfaceafter = {en~la~\zvhyperlink{página~siguiente}} ,
reftextfacebefore = {en~la~\zvhyperlink{página~anterior}} ,
reftextafter = {en~la~\zvhyperlink{página~siguiente}} ,
reftextbefore = {en~la~\zvhyperlink{página~anterior}} ,
reftextcurrent = {en~\zvhyperlink{esta~página}} ,
reftextfaraway = {en~la~\zcpageref[g=f]{#1}} ,
reftextpagerange = {en~las~\zcpageref[range,g=f]{#1,#2}} ,
reftextlabelrange = {\zcref[range]{#1,#2}} ,
}
% \end{macrocode}
%
%
% \begin{macrocode}
\zvLanguageSetup { dutch }
{
reftextfaceafter =
{op~de~\zvhyperlink{\reftextvario{rechter~pagina}{pagina~hiernaast}}} ,
reftextfacebefore =
{op~de~\zvhyperlink{\reftextvario{linker~pagina}{pagina~hiernaast}}} ,
reftextafter =
{op~de~\zvhyperlink{\reftextvario{volgende~pagina}{pagina~hierna}}} ,
reftextbefore =
{op~de~\zvhyperlink{\reftextvario{vorige~pagina}{pagina~hiervoor}}} ,
reftextcurrent = {op~\zvhyperlink{deze~pagina}} ,
reftextfaraway = {op~\zcpageref[g=f]{#1}} ,
reftextpagerange = {op~\zcpageref[range,g=f]{#1,#2}} ,
reftextlabelrange = {\zcref[range]{#1,#2}} ,
}
% \end{macrocode}
%
%
% Italian localization improved thanks to \contributor{Matteo Ferrigato} (at
% \githubissue{1}).
%
% \begin{macrocode}
\zvLanguageSetup { italian }
{
reftextfaceafter =
{nella~\zvhyperlink{pagina~\reftextvario{a~fianco}{successiva}}} ,
reftextfacebefore =
{nella~\zvhyperlink{pagina~\reftextvario{a~fianco}{precedente}}} ,
reftextafter =
{nella~\zvhyperlink{pagina~\reftextvario{seguente}{successiva}}} ,
reftextbefore = {nella~\zvhyperlink{pagina~precedente}} ,
reftextcurrent = {in~\zvhyperlink{questa~pagina}} ,
reftextfaraway = {a~\zcpageref[g=f]{#1}} ,
reftextpagerange = {nelle~\zcpageref[range,g=f]{#1,#2}} ,
reftextlabelrange = {\zcref[range]{#1,#2}} ,
}
% \end{macrocode}
%
%
% Swedish localization initially provided by \contributor{\username{Timmyfox}}
% (at \githubissue{3}).
%
% \begin{macrocode}
\zvLanguageSetup { swedish }
{
reftextfaceafter =
{på~\zvhyperlink{\reftextvario{motstående}{nästa}~sida}} ,
reftextfacebefore =
{på~\zvhyperlink{\reftextvario{motstående}{föregående}~sida}} ,
reftextafter =
{på~\zvhyperlink{\reftextvario{följande}{nästa}~sida}} ,
reftextbefore =
{på~\zvhyperlink{föregående~sida}} ,
reftextcurrent =
{på~\zvhyperlink{\reftextvario{den~här~sidan}{denna~sida}}} ,
reftextfaraway = {på~\zcpageref{#1}} ,
reftextpagerange = {på~\zcpageref[range]{#1,#2}} ,
reftextlabelrange = {\zcref[range]{#1,#2}} ,
}
% \end{macrocode}
%
%
% \begin{macrocode}
%</package>
% \end{macrocode}
%
%
% \PrintIndex
%