diff options
author | Karl Berry <karl@freefriends.org> | 2023-01-03 20:49:43 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2023-01-03 20:49:43 +0000 |
commit | a5f735cf10cd43fcd0802645b25265969aa4863b (patch) | |
tree | c83cf7acac18f7e879b27ab1846ee61ef3016184 /Master/texmf-dist/doc/latex | |
parent | 215971f360ada9c3e366466566c635e6388c28e2 (diff) |
zref-clever (3jan23)
git-svn-id: svn://tug.org/texlive/trunk@65452 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex')
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md | 9 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/README.md | 2 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf | bin | 1283227 -> 1285432 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex | 2 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf | bin | 322543 -> 327352 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex | 130 |
6 files changed, 120 insertions, 23 deletions
diff --git a/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md b/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md index a11671dfedb..3215143ceaf 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md +++ b/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md @@ -1,6 +1,13 @@ # Changelog -## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.3.2...HEAD) +## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.3.3...HEAD) + +## [v0.3.3](https://github.com/gusbrs/zref-clever/compare/v0.3.2...v0.3.3) (2023-01-03) + +### Added +- New `reftype` option, to allow for local manual override of `countertype` + settings. +- Included some new How-tos to the User manual. ## [v0.3.2](https://github.com/gusbrs/zref-clever/compare/v0.3.1...v0.3.2) (2022-12-27) diff --git a/Master/texmf-dist/doc/latex/zref-clever/README.md b/Master/texmf-dist/doc/latex/zref-clever/README.md index b260c87ec06..0d7a610d5bc 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/README.md +++ b/Master/texmf-dist/doc/latex/zref-clever/README.md @@ -5,7 +5,7 @@ Author: Gustavo Barros Maintainer: Gustavo Barros -`zref-clever` provides an user interface for making LaTeX cross-references +`zref-clever` provides a user interface for making LaTeX cross-references which automates some of their typical features, thus easing their input in the document and improving the consistency of typeset results. A reference made with `\zcref` includes a "name" according to its "type" and lists of multiple 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 Binary files differindex 8b4cad12804..b9feccfdf8c 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf +++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex index e1bc9d02899..ba3a5eaaa23 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex +++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex @@ -4,7 +4,7 @@ % % This file is part of the LaTeX package "zref-clever". % -% Copyright (C) 2021-2022 Gustavo Barros +% Copyright (C) 2021-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 diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf Binary files differindex 3f975f70c9b..81b2d350ea8 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf +++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf 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 ac477475290..78d6cc7f03b 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex +++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex @@ -4,7 +4,7 @@ % % This file is part of the LaTeX package "zref-clever". % -% Copyright (C) 2021-2022 Gustavo Barros +% Copyright (C) 2021-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 @@ -103,14 +103,18 @@ RenewDocumentCommand, NewCommandCopy, ltx@gobble, + @currentcounter, zref@label, zref@wrapper@babel, zref@ifpropundefined, zref@setcurrent, + zref@newprop, + zref@addprop, beamer@old@zref@label, alt, beamer@nameslide, beamer@dummynameslide, + ordinal, } } \lstdefinestyle{zrefclever}{ @@ -207,7 +211,7 @@ \end{center} \begin{quotation} - \pkg{zref-clever} provides an user interface for making \LaTeX{} + \pkg{zref-clever} provides a user interface for making \LaTeX{} cross-references which automates some of their typical features, thus easing their input in the document and improving the consistency of typeset results. A reference made with \cs{zcref} includes a ``name'' according to @@ -814,9 +818,10 @@ optional argument of \cs{zcheck}, and can receive both checks and \zcref{sec:reference-format}). \DescribeOption{countertype} % +\DescribeOption{reftype} % The \opt{countertype} option allows to specify the ``reference type'' of each counter, which is stored as a label property when the label is set. This -``reference type'' is what determines how a reference to this label will +reference type is what determines how a reference to this label will eventually be typeset when it is referred to (see \zcref{sec:reference-types}). A value like \texttt{countertype = \{foo = bar\}} sets the \texttt{foo} counter to use the reference type \texttt{bar}. @@ -826,8 +831,14 @@ the same name as the counter, unless otherwise specified. Also, the default value of the option already sets appropriate types for basic \LaTeX{} counters, including those from the standard classes. Setting a counter type to an empty value removes any (explicit) type association for that counter, in -practice, this means it then uses a type equal to its name. Since this option -only affects how labels are set, it is not available in \cs{zcref}. +practice, this means it then uses a type equal to its name. The \opt{reftype} +option allows one to specify the reference type manually, regardless of the +current counter. This can be used to locally override any \opt{countertype} +settings of the package and, for those acquainted with it, is the equivalent +of \pkg{cleveref}'s optional argument to \cs{label}. Normally, you'd want to +use this option within a group, but if you must do otherwise, the default +value can be restored by setting the option without a value. Since these +options only affect how labels are set, they are not available in \cs{zcref}. \DescribeOption{\raisebox{-.2em}{\dbend}\ counterresetters} % \DescribeOption{counterresetby} % @@ -884,11 +895,12 @@ option, but a way to tell \pkg{zref-clever} a piece of information it has no means to retrieve automatically. The setting must correspond to the actual ``current counter'', meaning here ``the counter underlying \cs{@currentlabel}'' in a given situation. Also, when using the -\opt{currentcounter} option, make sure the setting is duly grouped because, if -set, it has precedence over \cs{@currentcounter} and, contrary to the later, -the former is not reset the next time \cs{refstepcounter} runs. Its default -value is, quite naturally, \cs{@currentcounter}. Since this option only -affects how labels are set, it is not available in \cs{zcref}. +\opt{currentcounter} option, take care that the setting is duly grouped +because, if set, it has precedence over \cs{@currentcounter} and, contrary to +the later, the former is not reset the next time \cs{refstepcounter} runs. +Its default value is, quite naturally, \cs{@currentcounter}. The default +value can be reset by calling the option with no value. Since this option +only affects how labels are set, it is not available in \cs{zcref}. \DescribeOption{nocompat} % Some packages, document classes, or LaTeX features may require specific @@ -997,7 +1009,7 @@ is to provide a rich set of ``handles'' for fine tuning the reference format but, at the same time, do not \emph{require} detailed setup by the users, unless they really want it. -With that in mind, we have settled with an user interface for reference +With that in mind, we have settled with a user interface for reference formatting which allows settings to be done in different scopes, with more or less overarching effects, and some precedence rules to regulate the relation of settings given in each of these scopes. There are four scopes in which @@ -1827,8 +1839,7 @@ package in the setup, the same procedure can be used with \cls{memoir}'s \subsection{\pkg{amsmath}} -\zctask{Make references to \pkg{amsmath} display math environments with - \cs{zcref}.} +\zctask{Make references to \pkg{amsmath} display math environments.} Given how \pkg{amsmath}'s display math environments work, they need to handle \cs{label} specially, and this support is quite hard-wired into the @@ -1867,10 +1878,48 @@ description of the \opt{amsmath} compatibility module at \end{zchowto} +\subsection{Overriding the reference type} + +\zctask{Make references to a system of equations, which should be referred to + in the plural.} + +Though, usually, setting the \opt{countertype} option may provide a more +general and convenient way to set the reference type of a given counter, +sometimes we just need to do it for a particular label or set of labels. The +\opt{reftype} option allows us to do so and set the reference type directly, +regardless of what the current counter is. + +\begin{zchowto}[caption={Overriding the reference type}] +\documentclass{article} +\usepackage{amsmath} +\usepackage{zref-clever} +\usepackage{hyperref} +\zcRefTypeSetup{pluralequation}{ + Name-sg = Equations , + name-sg = equations , + Name-pl = Equations , + name-pl = equations , +} +\begin{document} +\section{Section 1} +\begin{equation} + \zcsetup{reftype=pluralequation} + \zlabel{eq:1} + \begin{aligned} + A+B&=B+A\\ + C&=D+E\\ + E&=F + \end{aligned} +\end{equation} +\zcref{eq:1} +\end{document} +\end{zchowto} + + \subsection{\pkg{listings}} \zctask{Make references to a \env{lstlisting} environment from the - \pkg{listings} package with \cs{zcref}.} + \pkg{listings} package.} Being \env{lstlisting} a verbatim environment, setting labels inside it requires special treatment. \pkg{zref-clever}'s \opt{listings} compatibility @@ -1904,7 +1953,7 @@ description of the \opt{listings} compatibility module at \subsection{\pkg{enumitem}} \zctask{Setup a custom enumerate environment created with \pkg{enumitem} to be - referred to with \cs{zcref}.} + referred to.} Since the \texttt{enumerate} environment's counters are reset at each nesting level, but not with the standard machinery, we have to inform @@ -1956,8 +2005,7 @@ implicit counter-type association, and have to set it explicitly with the \subsection{\pkg{zref-xr}} -\zctask{Make references to labels set in an external document with - \cs{zcref}.} +\zctask{Make references to labels set in an external document.} \pkg{zref} itself offers this functionality with module \pkg{zref-xr}, and \pkg{zref-clever} is prepared to make use of it. Just a couple of details @@ -2002,6 +2050,42 @@ be the following. \end{document} \end{zchowto} + +\subsection{Ordinal references} + +\zctask{Typesetting the references as ordinal numbers.} + +This example is intended as an illustration of the flexibility \pkg{zref}'s +extensible referencing system grants us.\footnote{Though clearly simplified, + the example is less than academic. + See \url{https://tex.stackexchange.com/a/670088} for an application to add a + reference suffix needed in Turkish.} Getting references as ordinal numbers, +something that would be normally a tricky task, can be handled with a simple +custom \pkg{zref} property, which we then use to set \pkg{zref-clever}'s +\opt{ref} option. + +\begin{zchowto}[caption={Ordinal references}] +\documentclass{article} +\usepackage{zref-clever} +\usepackage{fmtcount} +\makeatletter +\zref@newprop{ordref}{\ordinal{\@currentcounter}} +\zref@addprop{main}{ordref} +\makeatother +\zcsetup{ref=ordref} +\begin{document} +\section{Section 1} +\zlabel{sec:section-1} +\begin{figure} +A figure. +\caption{Figure 1} +\zlabel{fig:figure-1} +\end{figure} +\zcref{sec:section-1,fig:figure-1} +\end{document} +\end{zchowto} + + \section{Limitations} \zlabel{sec:limitations} @@ -2354,7 +2438,7 @@ appear to break \pkg{cleveref}.\footnote{See, for example, Adding proper support for this is the business of \cls{beamer}, \pkg{zref}, and/or \pkg{hyperref}. Likely the former's really. But, taking advantage of -\pkg{zref}'s flexibility, as an user, you can have a work-around in the +\pkg{zref}'s flexibility, as a user, you can have a work-around in the meantime. \begin{zcworkaround}[caption={\cls{beamer}}] @@ -2437,7 +2521,7 @@ will remain one of the main assets of \pkg{zref-clever} as it matures. The name of the package makes no secret that a major inspiration for the kind of ``feel'' I strove to achieve has been Toby Cubitt's \pkg{cleveref}. -Indeed, I have been an user of \pkg{cleveref} for several years, and a happy +Indeed, I have been a user of \pkg{cleveref} for several years, and a happy one at that. But the role \pkg{cleveref} played in the development of \pkg{zref-clever} extends beyond the visible influence in the design of user facing functionality. Some technical solutions and, specially, the handling @@ -2464,6 +2548,7 @@ were generously provided by (in chronological order): % 2021-10-26: https://github.com/latex3/latex2e/issues/687 % 2022-01-12: https://chat.stackexchange.com/transcript/message/60129233#60129233 % 2022-04-09: https://github.com/latex3/hyperref/issues/229#issuecomment-1093870142 + % 2023-01-02: https://tex.stackexchange.com/q/670399 (comments) Phelype Oleinik, % 2021-08-20: https://tex.stackexchange.com/q/611370 (comments) % 2021-09-09: https://tex.stackexchange.com/a/614704 @@ -2485,6 +2570,8 @@ were generously provided by (in chronological order): % and following discussion. % 2022-12-26: https://chat.stackexchange.com/transcript/message/62644791#62644791 % and following discussion. + % 2023-01-02: https://chat.stackexchange.com/transcript/message/62684358#62684358 + % and following discussion. Frank Mittelbach, % 2021-10-14: https://github.com/latex3/latex2e/issues/687 \username{samcarter}, @@ -2502,8 +2589,11 @@ were generously provided by (in chronological order): % 2021-11-26: https://github.com/latex3/l3build/issues/215 Jürgen Spitzmüller, % 2021-11-28: https://github.com/gusbrs/zref-clever/issues/2 - and \username{niluxv}. + \username{niluxv}, % 2022-01-05: https://github.com/gusbrs/zref-clever/issues/4 + and Joseph Wright. + % 2023-01-02: https://chat.stackexchange.com/transcript/message/62684358#62684358 + % and following discussion. The package's language files have been provided or improved thanks to: Denis Bitouzé (French), |