From 92fb6a7b05ab3758893224d3473dfc4eb6f35e6c Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 28 May 2022 20:21:04 +0000 Subject: zref-clever (28may22) git-svn-id: svn://tug.org/texlive/trunk@63428 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/doc/latex/zref-clever/CHANGELOG.md | 7 +- .../doc/latex/zref-clever/zref-clever-code.pdf | Bin 1255628 -> 1258005 bytes .../doc/latex/zref-clever/zref-clever.pdf | Bin 311667 -> 316250 bytes .../doc/latex/zref-clever/zref-clever.tex | 90 ++++++++++++++++++--- .../source/latex/zref-clever/zref-clever.dtx | 8 +- .../tex/latex/zref-clever/zref-clever.sty | 2 +- 6 files changed, 92 insertions(+), 15 deletions(-) diff --git a/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md b/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md index 2a3f9bdbc4a..ae677ca3118 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md +++ b/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md @@ -1,6 +1,11 @@ # Changelog -## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.3.0...HEAD) +## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.3.1...HEAD) + +## [v0.3.1](https://github.com/gusbrs/zref-clever/compare/v0.3.0...v0.3.1) (2022-05-28) + +### Added +- "`zref-clever` for the impatient" section to User manual. ## [v0.3.0](https://github.com/gusbrs/zref-clever/compare/v0.2.2-alpha...v0.3.0) (2022-04-22) diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf index de4ac178cff..ae52fa41e22 100644 Binary files a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf and b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf differ diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf index 213e51bf6b6..5a6aadba29c 100644 Binary files a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf and b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf differ diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex index ee00821c16a..2ebf1b67395 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex +++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex @@ -300,6 +300,74 @@ priority over backward compatibility. So, if you choose to use this package, you should be ready to accommodate to eventual upstream changes. +\section{\pkg{zref-clever} for the impatient} + +\pkg{zref-clever} is based on \pkg{zref}'s referencing system which, though +independent of the standard one, is very similar to it in its user interface. +Indeed, to use \pkg{zref}, instead of setting a \cs{label} and making a +\cs{ref}, one would set a \cs{zlabel} and make \cs{zref}s to it, in pretty +much the same way as for the standard system. \pkg{zref-clever} introduces +the more featureful \cs{zcref} for making references, but relies on +\pkg{zref}'s \cs{zlabel} for label setting. + +A basic document using \pkg{zref-clever} is shown in \zcref{how:basic} which, +despite the small necessary adjustments, should feel very familiar to any +\LaTeX{} user acquainted with the standard referencing system: + +\begin{zchowto}[caption={Basic usage},label={how:basic}] +\documentclass{article} +\usepackage{zref-clever} +\usepackage{hyperref} +\begin{document} +\section{Section 1} +\zlabel{sec:section-1} +\begin{figure} + A figure. + \caption{Figure 1} + \zlabel{fig:figure-1} +\end{figure} +A reference to \zcref{sec:section-1}. \zcref[S]{fig:figure-1} shows some +interesting information. +A page reference can be done with either \zcpageref{sec:section-1} or with +\zcref[page]{sec:section-1}. +A reference can also be made to multiple labels, as in \zcref{sec:section-1, + fig:figure-1}. +\end{document} +\end{zchowto} + +The references in the document of \zcref{how:basic} illustrate one of the main +features of \pkg{zref-clever}, which is to include an appropriate ``type +name'' of the reference, alongside of the reference itself. The document +renders its references as: +\begin{quote} + A reference to section 1. Figure 1 shows some interesting information. A + page reference can be done with either page 1 or with page 1. A reference + can also be made to multiple labels, as in section 1 and figure 1. +\end{quote} + +\zcref[S]{how:basic} also illustrates the use the optional argument of +\cs{zcref} to modulate the behavior of the reference. In particular, the +\opt{S} option is one you should get acquainted with from the start, as it +ensures that the type name of a reference is properly capitalized and not +abbreviated, and it is meant to be used in references made at the beginning of +a sentence. + +But \pkg{zref-clever} is highly customizable, and several other options exist, +and multiple places where you can set them: + +\begin{itemize} +\item The optional argument of \cs{zcref}: for individual references. +\item \cs{zcsetup}: for settings meant to affect all references. +\item \cs{zcRefTypeSetup}: to customize the behavior of each reference type. +\item \cs{zcLanguageSetup}: for language-specific settings. +\end{itemize} + +For the list of available options, and for these different scopes in which +they can be used, see \zcref{sec:user-interface, sec:options, + sec:reference-format, sec:internationalization}. Other usage examples are +available at \zcref{sec:how-tos}. + + \section{Loading the package} \zlabel{sec:loading-package} @@ -1520,6 +1588,7 @@ it's up to you. \section{How-tos} +\zlabel{sec:how-tos} This section gathers some usage examples, or ``how-tos'', of cases which may require some \pkg{zref-clever} setup, or usage adjustments, and each item is @@ -2185,16 +2254,17 @@ use of \pkg{zref}'s \cs{zlabel} and thus of \pkg{zref-clever} may occasionally require some adjustments, since it does not enjoy the universal support the standard referencing system does. The compatibility modules presented in \zcref{sec:comp-modules} go a long way in ensuring the user has to worry very -little about it, but they cannot hopefully go all the way. Not only because -this kind of support will never be exhaustive, but also since, sometimes, -given the way certain features are implemented by packages or document -classes, there may not be a reasonable way to provide this support, from our -side. But, still, most of the time, it is still ``viable'' to get there, if -one really wishes to do so. So, this section keeps track of some known -recipes, which I don't think belong in \pkg{zref-clever} itself, but which you -may choose to use. Note that this list is intended to spare users from having -to reinvent the wheel every time someone needs something of the sort, but from -\pkg{zref-clever}'s perspective, their status is ``not supported''. +little about it, but they cannot be expected to go all the way. Not only +because this kind of support will never be exhaustive, but also since, +sometimes, given the way certain features are implemented by packages or +document classes, there may not be a reasonable way to provide this support, +from our side. But, still, most of the time, it is still ``viable'' to get +there, if one really wishes to do so. So, this section keeps track of some +known recipes, which I don't think belong in \pkg{zref-clever} itself, but +which you may choose to use. Note that this list is intended to spare users +from having to reinvent the wheel every time someone needs something of the +sort, but from \pkg{zref-clever}'s perspective, their status is ``not +supported''. \subsection*{\pkg{breqn}} diff --git a/Master/texmf-dist/source/latex/zref-clever/zref-clever.dtx b/Master/texmf-dist/source/latex/zref-clever/zref-clever.dtx index 79eb3dd2852..e0d04a1264c 100644 --- a/Master/texmf-dist/source/latex/zref-clever/zref-clever.dtx +++ b/Master/texmf-dist/source/latex/zref-clever/zref-clever.dtx @@ -165,7 +165,7 @@ % % Identify the package. % \begin{macrocode} -\ProvidesExplPackage {zref-clever} {2022-04-22} {0.3.0} +\ProvidesExplPackage {zref-clever} {2022-05-28} {0.3.1} {Clever LaTeX cross-references based on zref} % \end{macrocode} % @@ -7979,8 +7979,10 @@ % actually responsible for setting the labels inside \pkg{amsmath}'s math % environments. And, after that, redefine it to be \cs{@@_ltxlabel:n} % instead. We must handle \pkg{hyperref} here, which comes very late in the -% preamble, and which loads \pkg{nameref} at \texttt{begindocument}, which in -% turn, lets \cs{ltx@label} be \cs{label}. This has to come after +% preamble, and which loads \pkg{nameref} at \texttt{begindocument} (though +% this has changed recently 2022-05-16, see +% \url{https://github.com/latex3/hyperref/commit/a011ba9308a1b047dc151796de557da0bb22abaa}), +% which in turn, lets \cs{ltx@label} be \cs{label}. This has to come after % \pkg{nameref}. Other classes packages also redefine \cs{ltx@label}, which % may cause some trouble. A \texttt{grep} on \texttt{texmf-dist} returns hits % for: \file{thm-restate.sty}, \file{smartref.sty}, \file{jmlrbook.cls}, diff --git a/Master/texmf-dist/tex/latex/zref-clever/zref-clever.sty b/Master/texmf-dist/tex/latex/zref-clever/zref-clever.sty index 8bc23d4330c..f56c716521a 100644 --- a/Master/texmf-dist/tex/latex/zref-clever/zref-clever.sty +++ b/Master/texmf-dist/tex/latex/zref-clever/zref-clever.sty @@ -53,7 +53,7 @@ }% \endinput }% -\ProvidesExplPackage {zref-clever} {2022-04-22} {0.3.0} +\ProvidesExplPackage {zref-clever} {2022-05-28} {0.3.1} {Clever LaTeX cross-references based on zref} \RequirePackage { zref-base } \RequirePackage { zref-user } -- cgit v1.2.3