summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/zref-clever/zref-clever.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/zref-clever/zref-clever.tex')
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever.tex133
1 files changed, 110 insertions, 23 deletions
diff --git a/macros/latex/contrib/zref-clever/zref-clever.tex b/macros/latex/contrib/zref-clever/zref-clever.tex
index a4e3ab8638..64d5028f62 100644
--- a/macros/latex/contrib/zref-clever/zref-clever.tex
+++ b/macros/latex/contrib/zref-clever/zref-clever.tex
@@ -591,13 +591,6 @@ the second reference none of them will. The package's default is
\texttt{nameinlink=tsingle}, and the option given without a value is
equivalent to \texttt{nameinlink=true}.
-\DescribeOption{preposinlink} %
-The \opt{preposinlink} option controls whether the \opt{preref} and
-\opt{postref} reference format options (see \zcref{sec:reference-format}) are
-included in the reference hyperlink or not. It is a boolean option. The
-package's default is \texttt{preposinlink=false}, and the option given without
-a value is equivalent to \texttt{preposinlink=true}.
-
\DescribeOption{lang} %
The \opt{lang} option controls the language used by \cs{zcref} when looking
for language-specific reference format options (see
@@ -932,8 +925,7 @@ more detail soon, and lists the scopes in which each is available.
type-specific) & listsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
& lastsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
& rangesep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
- & preref & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
- & postref & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & refbounds & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
\addlinespace
Typesetting & Name-sg & & $\bullet$ & $\bullet$ & \\
@@ -946,8 +938,8 @@ more detail soon, and lists the scopes in which each is available.
& name-pl-ab & & $\bullet$ & $\bullet$ & \\
\addlinespace
- Font & namefont & $\bullet$ & $\bullet$ & & \\
- & reffont & $\bullet$ & $\bullet$ & & \\
+ Font & namefont & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & reffont & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
\addlinespace
Other & cap & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
@@ -967,15 +959,28 @@ that which a standard \LaTeX{} \cs{ref} would typeset. A \pkg{zref-clever}
\begin{refformat}
\item \reffmt{ref-block} \(\equiv\)
-\item \reffmt{preref} \reffmt{ref} \reffmt{postref}
+\item \reffmt{preref*}
+ \raisebox{-\baselineskip}{\makebox[0pt]{\^{}}}%
+ \raisebox{-1.2\baselineskip}{\makebox[0pt]{\footnotesize{}hyperlink start}}
+ \reffmt{preref} \reffmt{ref} \reffmt{postref}
+ \raisebox{-\baselineskip}{\makebox[0pt]{\^{}}}%
+ \raisebox{-1.2\baselineskip}{\makebox[0pt]{\footnotesize{}hyperlink end}}
+ \reffmt{postref*}
\end{refformat}
-A \texttt{ref-block} is built for \emph{each} label given as argument to
-\cs{zcref}. When the \meta{labels} argument is comprised of multiple labels,
-each ``reference type group'', or \texttt{type-group} is potentially made from
-the combination of single reference blocks, ``reference block pairs'',
-``reference block lists'', or ``reference block ranges'', where each is
-respectively built as:
+Where the \opt{refbounds} option, which receives as value a comma separated
+list of four items in the form \texttt{\{preref*,preref,postref,postref*\}},
+sets the surrounding elements to \texttt{ref}.\footnote{As usual, if each of
+ the items contains start or end spaces, or commas anywhere, they must be
+ protected by a pair of braces. However, care is taken that empty items
+ don't need such protection. So you can set, for example, something like
+ \texttt{refbounds=\{(,{},{},)\}} to get parentheses around your references,
+ outside the hyperlink.} A \texttt{ref-block} is built for \emph{each} label
+given as argument to \cs{zcref}. When the \meta{labels} argument is comprised
+of multiple labels, each ``reference type group'', or \texttt{type-group} is
+potentially made from the combination of single reference blocks, ``reference
+block pairs'', ``reference block lists'', or ``reference block ranges'', where
+each is respectively built as:
\begin{refformat}
\item \reffmt{type-group} is a combination of:
@@ -1061,8 +1066,7 @@ mentioned above. These ``last resort'' option values are required by
language that \pkg{zref-clever} does not know and has no language file for, it
cannot guess what language that is, and thus has to provide some reasonable
``language agnostic'' default, at least for the options for which this makes
-sense (all the ``typesetting'' options, except for the \texttt{[Nn]ame-}
-ones). Users do not need to have access to this scope, since they know the
+sense. Users do not need to have access to this scope, since they know the
language of their document, or know the values they want for those options,
and can set them as general options, type-specific options, or language
options through the user interface provided for the purpose. But the
@@ -1081,11 +1085,90 @@ pairsep = {,`\textvisiblespace{}'} ,
listsep = {,`\textvisiblespace{}'} ,
lastsep = {,`\textvisiblespace{}'} ,
rangesep = {\textendash} ,
-preref = {} ,
-postref = {} ,
\end{zcexample}
+\subsection{Advanced reference formatting}
+
+The reference format options discussed above and presented in
+\zcref{tab:reference-format} should suffice for most needs. However, if more
+fine-grained control of the reference format is needed, this can be achieved
+through a more detailed specification of \opt{refbounds} for the different
+cases in which they may occur when a reference is processed. The options
+available for this purpose are presented in
+\zcref{tab:advanced-reference-format}.
+
+\begin{table}
+ \centering
+ \DeleteShortVerb \|
+ \begin{tabular}{l>{\ttfamily}lcccc}
+ \toprule
+ & & General & Type & \multicolumn{2}{c}{Language} \\
+ \cmidrule(lr){5-6}
+ & & & & Type & Default \\
+ & & (i) & (ii) & (iii) & (iv) \\
+
+ \midrule
+ Base & refbounds-first & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ options & refbounds-first-sg & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & refbounds-first-pb & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & refbounds-first-rb & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & refbounds-mid & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & refbounds-mid-rb & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & refbounds-mid-re & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & refbounds-last & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & refbounds-last-pe & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & refbounds-last-re & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+
+ \addlinespace
+ Derived & +refbounds-first & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ options & +refbounds-mid & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ (groups) & +refbounds-last & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & +refbounds-rb & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & +refbounds-re & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & +refbounds & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ \bottomrule
+ \end{tabular}
+ \caption{Advanced reference format options and their scopes}
+ \zlabel{tab:advanced-reference-format}
+\end{table}
+
+The ``base'' options are the actually operative ones, while the ``derived''
+options are convenience aliases to set multiple base options in one go. In
+the naming scheme of these options, as is easy to presume, ``\texttt{first}''
+refers to the first reference of a type-block, ``\texttt{mid}'' to the middle
+ones, and ``\texttt{last}'' to the last reference of the type-block. Less
+obviously, but hopefully still mnemonic enough, ``\texttt{sg}'' stands for
+``single'', ``\texttt{pb}'' and ``\texttt{pe}'' for ``pair begin'' and ``pair
+end'', and finally ``\texttt{rb}'' and ``\texttt{re}'' for ``range begin'' and
+``range end''. Each of them which receives as value a comma separated list of
+four items in the form \texttt{\{preref*,preref,postref,postref*\}}, just like
+\opt{refbounds}.
+
+The base options are mutually exclusive, which means, for example, that it is
+not sufficient to set \opt{refbounds-first} to define the behavior of all
+first references of a type block. \opt{refbounds-first} is the value used for
+the first reference when not single, not the beginning of a pair, and not the
+beginning of a range. Setting a group of them is the purpose of the derived
+options. Each of these sets all options under it. Some examples.
+\opt{+refbounds-first} sets \opt{refbounds-first}, \opt{refbounds-first-sg},
+\opt{refbounds-first-pb}, and \opt{refbounds-first-rg}. In turn,
+\opt{+refbounds-first-rb} sets \opt{refbounds-first-rb} and
+\opt{refbounds-first-rb}. And quite conveniently, \opt{+refbounds} sets
+\opt{+refbounds-first}, \opt{+refbounds-mid}, and \opt{+refbounds-last}, it is
+hence sufficient to set it to define the behavior of what is typeset around
+all references for the whole type-block. As you probably guessed by now, the
+\opt{refbounds} option presented in \zcref{tab:reference-format} is an alias
+of \opt{+refbounds}.
+
+Given that base and derived options are actually setting the same group of
+underlying options (the base ones), the order in which they are given is
+relevant: the last one prevails. The idea here is to use first the derived
+options to set some general defaults, and then change one or another base
+option to handle exceptions as needed. Of course, how best to use them
+depends on the case.
+
+
\section{Internationalization}
\zlabel{sec:internationalization}
@@ -1111,7 +1194,7 @@ the \emph{current} or \emph{main} language of the document, as defined by
will note that \zcref{tab:languages-and-aliases} contains only \pkg{babel}
language names.} Users can also set \opt{lang} to a specific language
directly, in which case \pkg{babel} and \pkg{polyglossia} are disregarded.
-\pkg{zref-clever} provides a number of built-in ``language file'', for the
+\pkg{zref-clever} provides a number of built-in ``language files'', for the
languages listed in \zcref{tab:languages-and-aliases}, which also includes the
declared aliases to those languages.
@@ -2190,11 +2273,13 @@ were generously provided by (in chronological order):
% 2021-08-20: https://tex.stackexchange.com/q/611424/105447 (comments)
% 2021-09-06: https://github.com/ho-tex/zref/issues/13
% 2021-10-26: https://github.com/latex3/latex2e/issues/687
+ % 2022-01-12: https://chat.stackexchange.com/transcript/message/60129233#60129233
Phelype Oleinik,
% 2021-08-20: https://tex.stackexchange.com/q/611370 (comments)
% 2021-09-09: https://tex.stackexchange.com/a/614704
% 2021-10-06: https://tex.stackexchange.com/a/617998
% 2021-10-21: https://github.com/latex3/latex2e/pull/699
+ % 2022-01-12: https://tex.stackexchange.com/questions/629946/#comment1571118_629946
Enrico Gregorio,
% 2021-08-20: https://tex.stackexchange.com/a/611385
% 2021-08-20: https://tex.stackexchange.com/q/611370/#comment1529282_611385
@@ -2205,6 +2290,8 @@ were generously provided by (in chronological order):
% 2021-09-09: https://github.com/latex3/latex3/pull/988
David Carlisle,
% 2021-10-10: https://tex.stackexchange.com/questions/618434/#comment1544401_618439
+ % 2022-01-12: https://chat.stackexchange.com/transcript/message/60129096#60129096
+ % and following discussion.
Frank Mittelbach,
% 2021-10-14: https://github.com/latex3/latex2e/issues/687
`\texttt{samcarter}',