texlive[63428] Master/texmf-dist: zref-clever (28may22)

commits+karl at tug.org commits+karl at tug.org
Sat May 28 22:21:04 CEST 2022


Revision: 63428
          http://tug.org/svn/texlive?view=revision&revision=63428
Author:   karl
Date:     2022-05-28 22:21:04 +0200 (Sat, 28 May 2022)
Log Message:
-----------
zref-clever (28may22)

Modified Paths:
--------------
    trunk/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md
    trunk/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf
    trunk/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf
    trunk/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex
    trunk/Master/texmf-dist/source/latex/zref-clever/zref-clever.dtx
    trunk/Master/texmf-dist/tex/latex/zref-clever/zref-clever.sty

Modified: trunk/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md	2022-05-28 20:20:51 UTC (rev 63427)
+++ trunk/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md	2022-05-28 20:21:04 UTC (rev 63428)
@@ -1,7 +1,12 @@
 # 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)
 
 ### Changed

Modified: trunk/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf
===================================================================
(Binary files differ)

Modified: trunk/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf
===================================================================
(Binary files differ)

Modified: trunk/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex	2022-05-28 20:20:51 UTC (rev 63427)
+++ trunk/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex	2022-05-28 20:21:04 UTC (rev 63428)
@@ -300,6 +300,74 @@
 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 @@
 
 
 \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 @@
 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}}

Modified: trunk/Master/texmf-dist/source/latex/zref-clever/zref-clever.dtx
===================================================================
--- trunk/Master/texmf-dist/source/latex/zref-clever/zref-clever.dtx	2022-05-28 20:20:51 UTC (rev 63427)
+++ trunk/Master/texmf-dist/source/latex/zref-clever/zref-clever.dtx	2022-05-28 20:21:04 UTC (rev 63428)
@@ -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 at 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 at label} be \cs{label}.  This has to come after
 % \pkg{nameref}.  Other classes packages also redefine \cs{ltx at 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},

Modified: trunk/Master/texmf-dist/tex/latex/zref-clever/zref-clever.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/zref-clever/zref-clever.sty	2022-05-28 20:20:51 UTC (rev 63427)
+++ trunk/Master/texmf-dist/tex/latex/zref-clever/zref-clever.sty	2022-05-28 20:21:04 UTC (rev 63428)
@@ -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 }



More information about the tex-live-commits mailing list.