diff options
author | Karl Berry <karl@freefriends.org> | 2021-12-07 21:26:00 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2021-12-07 21:26:00 +0000 |
commit | 5585fb9abcb65c03e4b01fb5c4fdfdafddc0c0b9 (patch) | |
tree | 45f6f90b058f81e3aa36bb5f6214e7eb225f6dc0 /Master/texmf-dist/doc | |
parent | 5e8e53b2bacdcff45386e7b106065cad6300e962 (diff) |
zref-clever (7dec21)
git-svn-id: svn://tug.org/texlive/trunk@61246 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md | 12 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/MANIFEST.md | 110 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf | bin | 1035367 -> 1040673 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 | 304271 -> 305580 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex | 246 |
6 files changed, 281 insertions, 89 deletions
diff --git a/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md b/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md index dc8ce5a3ebc..e190d38d68c 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md +++ b/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md @@ -1,8 +1,16 @@ # Changelog -## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.1.0-alpha...HEAD) +## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.1.1-alpha...HEAD) -## [v0.1.0-alpha] +## [v0.1.1-alpha](https://github.com/gusbrs/zref-clever/compare/v0.1.0-alpha...v0.1.1-alpha) (2021-12-07) + +### Changed +- Improvements to the French dictionary (see issue + [#1](https://github.com/gusbrs/zref-clever/issues/1)). +- Dropped the `subappendix` reference type. +- Improvements to documentation. + +## [v0.1.0-alpha](https://github.com/gusbrs/zref-clever/releases/tag/v0.1.0-alpha) (2021-00-24) ### Added - Initial release. diff --git a/Master/texmf-dist/doc/latex/zref-clever/MANIFEST.md b/Master/texmf-dist/doc/latex/zref-clever/MANIFEST.md index 98f72887da7..e40fb05bf09 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/MANIFEST.md +++ b/Master/texmf-dist/doc/latex/zref-clever/MANIFEST.md @@ -1,7 +1,7 @@ # Manifest for zref-clever This file is a listing of all files considered to be part of this package. -It is automatically generated with `texlua build.lua manifest`. +It is automatically generated with `l3build manifest`. ## Repository manifest @@ -125,174 +125,282 @@ different engines (pdfTeX, XeTeX, LuaTeX, etc.). * zc-workaround-breqn01.lvt * zc-zcref-options01.lvt * zc-LanguageSetup01.luatex.tlg +* zc-LanguageSetup01.luatexdev.tlg * zc-LanguageSetup01.tlg * zc-LanguageSetup01.xetex.tlg +* zc-LanguageSetup01.xetexdev.tlg * zc-RefTypeSetup01.luatex.tlg +* zc-RefTypeSetup01.luatexdev.tlg * zc-RefTypeSetup01.tlg * zc-RefTypeSetup01.xetex.tlg +* zc-RefTypeSetup01.xetexdev.tlg * zc-class-article01.luatex.tlg +* zc-class-article01.luatexdev.tlg * zc-class-article01.tlg * zc-class-article01.xetex.tlg +* zc-class-article01.xetexdev.tlg * zc-class-book01.luatex.tlg +* zc-class-book01.luatexdev.tlg * zc-class-book01.tlg * zc-class-book01.xetex.tlg +* zc-class-book01.xetexdev.tlg * zc-class-memoir01.luatex.tlg +* zc-class-memoir01.luatexdev.tlg * zc-class-memoir01.tlg * zc-class-memoir01.xetex.tlg +* zc-class-memoir01.xetexdev.tlg * zc-class-report01.luatex.tlg +* zc-class-report01.luatexdev.tlg * zc-class-report01.tlg * zc-class-report01.xetex.tlg +* zc-class-report01.xetexdev.tlg * zc-class-scrartcl01.luatex.tlg +* zc-class-scrartcl01.luatexdev.tlg * zc-class-scrartcl01.tlg * zc-class-scrartcl01.xetex.tlg +* zc-class-scrartcl01.xetexdev.tlg * zc-class-scrbook01.luatex.tlg +* zc-class-scrbook01.luatexdev.tlg * zc-class-scrbook01.tlg * zc-class-scrbook01.xetex.tlg +* zc-class-scrbook01.xetexdev.tlg * zc-class-scrreprt01.luatex.tlg +* zc-class-scrreprt01.luatexdev.tlg * zc-class-scrreprt01.tlg * zc-class-scrreprt01.xetex.tlg +* zc-class-scrreprt01.xetexdev.tlg * zc-compat-amsmath01.luatex.tlg +* zc-compat-amsmath01.luatexdev.tlg * zc-compat-amsmath01.tlg * zc-compat-amsmath01.xetex.tlg +* zc-compat-amsmath01.xetexdev.tlg * zc-compat-appendices01.luatex.tlg +* zc-compat-appendices01.luatexdev.tlg * zc-compat-appendices01.tlg * zc-compat-appendices01.xetex.tlg +* zc-compat-appendices01.xetexdev.tlg * zc-compat-appendix01.luatex.tlg +* zc-compat-appendix01.luatexdev.tlg * zc-compat-appendix01.tlg * zc-compat-appendix01.xetex.tlg +* zc-compat-appendix01.xetexdev.tlg * zc-compat-breqn01.luatex.tlg +* zc-compat-breqn01.luatexdev.tlg * zc-compat-breqn01.tlg * zc-compat-breqn01.xetex.tlg +* zc-compat-breqn01.xetexdev.tlg * zc-compat-enumitem01.luatex.tlg +* zc-compat-enumitem01.luatexdev.tlg * zc-compat-enumitem01.tlg * zc-compat-enumitem01.xetex.tlg +* zc-compat-enumitem01.xetexdev.tlg * zc-compat-koma-script01.luatex.tlg +* zc-compat-koma-script01.luatexdev.tlg * zc-compat-koma-script01.tlg * zc-compat-koma-script01.xetex.tlg +* zc-compat-koma-script01.xetexdev.tlg * zc-compat-listings01.luatex.tlg +* zc-compat-listings01.luatexdev.tlg * zc-compat-listings01.tlg * zc-compat-listings01.xetex.tlg +* zc-compat-listings01.xetexdev.tlg * zc-compat-memoir01.luatex.tlg +* zc-compat-memoir01.luatexdev.tlg * zc-compat-memoir01.tlg * zc-compat-memoir01.xetex.tlg +* zc-compat-memoir01.xetexdev.tlg * zc-compat-subcaption01.luatex.tlg +* zc-compat-subcaption01.luatexdev.tlg * zc-compat-subcaption01.tlg * zc-compat-subcaption01.xetex.tlg +* zc-compat-subcaption01.xetexdev.tlg * zc-compat-subfig01.luatex.tlg +* zc-compat-subfig01.luatexdev.tlg * zc-compat-subfig01.tlg * zc-compat-subfig01.xetex.tlg +* zc-compat-subfig01.xetexdev.tlg * zc-dictionaries01.tlg * zc-dictionaries02.luatex.tlg +* zc-dictionaries02.luatexdev.tlg * zc-dictionaries02.tlg * zc-dictionaries02.xetex.tlg +* zc-dictionaries02.xetexdev.tlg * zc-howto-amsmath01.luatex.tlg +* zc-howto-amsmath01.luatexdev.tlg * zc-howto-amsmath01.tlg * zc-howto-amsmath01.xetex.tlg +* zc-howto-amsmath01.xetexdev.tlg * zc-howto-enumitem01.luatex.tlg +* zc-howto-enumitem01.luatexdev.tlg * zc-howto-enumitem01.tlg * zc-howto-enumitem01.xetex.tlg +* zc-howto-enumitem01.xetexdev.tlg * zc-howto-listings01.luatex.tlg +* zc-howto-listings01.luatexdev.tlg * zc-howto-listings01.tlg * zc-howto-listings01.xetex.tlg +* zc-howto-listings01.xetexdev.tlg * zc-howto-newfloat01.luatex.tlg +* zc-howto-newfloat01.luatexdev.tlg * zc-howto-newfloat01.tlg * zc-howto-newfloat01.xetex.tlg +* zc-howto-newfloat01.xetexdev.tlg * zc-howto-newfloat02.luatex.tlg +* zc-howto-newfloat02.luatexdev.tlg * zc-howto-newfloat02.tlg * zc-howto-newfloat02.xetex.tlg +* zc-howto-newfloat02.xetexdev.tlg * zc-howto-newfloat03.luatex.tlg +* zc-howto-newfloat03.luatexdev.tlg * zc-howto-newfloat03.tlg * zc-howto-newfloat03.xetex.tlg +* zc-howto-newfloat03.xetexdev.tlg * zc-howto-newfloat04.luatex.tlg +* zc-howto-newfloat04.luatexdev.tlg * zc-howto-newfloat04.tlg * zc-howto-newfloat04.xetex.tlg +* zc-howto-newfloat04.xetexdev.tlg * zc-howto-newfloat05.luatex.tlg +* zc-howto-newfloat05.luatexdev.tlg * zc-howto-newfloat05.tlg * zc-howto-newfloat05.xetex.tlg +* zc-howto-newfloat05.xetexdev.tlg * zc-howto-newtheorem01.luatex.tlg +* zc-howto-newtheorem01.luatexdev.tlg * zc-howto-newtheorem01.tlg * zc-howto-newtheorem01.xetex.tlg +* zc-howto-newtheorem01.xetexdev.tlg * zc-howto-newtheorem02.luatex.tlg +* zc-howto-newtheorem02.luatexdev.tlg * zc-howto-newtheorem02.tlg * zc-howto-newtheorem02.xetex.tlg +* zc-howto-newtheorem02.xetexdev.tlg * zc-howto-newtheorem03.luatex.tlg +* zc-howto-newtheorem03.luatexdev.tlg * zc-howto-newtheorem03.tlg * zc-howto-newtheorem03.xetex.tlg +* zc-howto-newtheorem03.xetexdev.tlg * zc-howto-newtheorem04.luatex.tlg +* zc-howto-newtheorem04.luatexdev.tlg * zc-howto-newtheorem04.tlg * zc-howto-newtheorem04.xetex.tlg +* zc-howto-newtheorem04.xetexdev.tlg * zc-howto-zref-xr01.luatex.tlg +* zc-howto-zref-xr01.luatexdev.tlg * zc-howto-zref-xr01.tlg * zc-howto-zref-xr01.xetex.tlg +* zc-howto-zref-xr01.xetexdev.tlg * zc-label-options01.luatex.tlg +* zc-label-options01.luatexdev.tlg * zc-label-options01.tlg * zc-languages01.tlg * zc-opt-check01.luatex.tlg +* zc-opt-check01.luatexdev.tlg * zc-opt-check01.tlg * zc-opt-d01.tlg * zc-opt-g01.tlg * zc-opt-hyperref01.luatex.tlg +* zc-opt-hyperref01.luatexdev.tlg * zc-opt-hyperref01.tlg * zc-opt-hyperref01.xetex.tlg +* zc-opt-hyperref01.xetexdev.tlg * zc-opt-hyperref02.luatex.tlg +* zc-opt-hyperref02.luatexdev.tlg * zc-opt-hyperref02.tlg * zc-opt-hyperref02.xetex.tlg +* zc-opt-hyperref02.xetexdev.tlg * zc-opt-hyperref03.luatex.tlg +* zc-opt-hyperref03.luatexdev.tlg * zc-opt-hyperref03.tlg * zc-opt-hyperref03.xetex.tlg +* zc-opt-hyperref03.xetexdev.tlg * zc-opt-hyperref04.luatex.tlg +* zc-opt-hyperref04.luatexdev.tlg * zc-opt-hyperref04.tlg * zc-opt-hyperref04.xetex.tlg +* zc-opt-hyperref04.xetexdev.tlg * zc-opt-hyperref05.luatex.tlg +* zc-opt-hyperref05.luatexdev.tlg * zc-opt-hyperref05.tlg * zc-opt-hyperref05.xetex.tlg +* zc-opt-hyperref05.xetexdev.tlg * zc-opt-lang01.luatex.tlg +* zc-opt-lang01.luatexdev.tlg * zc-opt-lang01.tlg * zc-opt-lang01.xetex.tlg +* zc-opt-lang01.xetexdev.tlg * zc-opt-lang02.luatex.tlg +* zc-opt-lang02.luatexdev.tlg * zc-opt-lang02.tlg * zc-opt-lang02.xetex.tlg +* zc-opt-lang02.xetexdev.tlg * zc-opt-lang03.luatex.tlg +* zc-opt-lang03.luatexdev.tlg * zc-opt-lang03.tlg * zc-opt-lang03.xetex.tlg +* zc-opt-lang03.xetexdev.tlg * zc-opt-lang04.luatex.tlg +* zc-opt-lang04.luatexdev.tlg * zc-opt-lang04.tlg * zc-opt-lang04.xetex.tlg +* zc-opt-lang04.xetexdev.tlg * zc-opt-lang05.luatex.tlg +* zc-opt-lang05.luatexdev.tlg * zc-opt-lang05.tlg * zc-opt-lang05.xetex.tlg +* zc-opt-lang05.xetexdev.tlg * zc-opt-lang06.luatex.tlg +* zc-opt-lang06.luatexdev.tlg * zc-opt-lang06.tlg * zc-opt-lang06.xetex.tlg +* zc-opt-lang06.xetexdev.tlg * zc-opt-nocompat01.luatex.tlg +* zc-opt-nocompat01.luatexdev.tlg * zc-opt-nocompat01.tlg * zc-opt-nocompat01.xetex.tlg +* zc-opt-nocompat01.xetexdev.tlg * zc-opt-nocompat02.luatex.tlg +* zc-opt-nocompat02.luatexdev.tlg * zc-opt-nocompat02.tlg * zc-opt-nocompat02.xetex.tlg +* zc-opt-nocompat02.xetexdev.tlg * zc-opt-nocompat03.luatex.tlg +* zc-opt-nocompat03.luatexdev.tlg * zc-opt-nocompat03.tlg * zc-opt-nocompat03.xetex.tlg +* zc-opt-nocompat03.xetexdev.tlg * zc-opt-ref01.tlg * zc-opt-ref02.luatex.tlg +* zc-opt-ref02.luatexdev.tlg * zc-opt-ref02.tlg * zc-opt-ref02.xetex.tlg +* zc-opt-ref02.xetexdev.tlg * zc-opt-titleref01.luatex.tlg +* zc-opt-titleref01.luatexdev.tlg * zc-opt-titleref01.tlg * zc-opt-titleref01.xetex.tlg +* zc-opt-titleref01.xetexdev.tlg * zc-precedence-rules01.luatex.tlg +* zc-precedence-rules01.luatexdev.tlg * zc-precedence-rules01.tlg * zc-precedence-rules01.xetex.tlg +* zc-precedence-rules01.xetexdev.tlg * zc-sort01.tlg * zc-typeset01.luatex.tlg +* zc-typeset01.luatexdev.tlg * zc-typeset01.tlg * zc-typeset01.xetex.tlg +* zc-typeset01.xetexdev.tlg * zc-workaround-breqn01.luatex.tlg +* zc-workaround-breqn01.luatexdev.tlg * zc-workaround-breqn01.tlg * zc-workaround-breqn01.xetex.tlg +* zc-workaround-breqn01.xetexdev.tlg * zc-zcref-options01.luatex.tlg +* zc-zcref-options01.luatexdev.tlg * zc-zcref-options01.tlg * zc-zcref-options01.xetex.tlg +* zc-zcref-options01.xetexdev.tlg ## TDS manifest 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 b8105bc9e2c..f8d0003a960 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 a258484cccb..a4ebabd625e 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 @@ -24,7 +24,7 @@ % zref-clever.ins, % zref-clever.tex, % zref-clever-code.tex, -% and the derived files listed in MANIFEST.md. +% and the files listed in MANIFEST.md. % % The released version of this package is available from CTAN. % 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 1b0c6f93f92..84f9a28b55e 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 c2fa9f19b2c..4da3b2453d1 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex +++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex @@ -24,7 +24,7 @@ % zref-clever.ins, % zref-clever.tex, % zref-clever-code.tex, -% and the derived files listed in MANIFEST.md. +% and the files listed in MANIFEST.md. % % The released version of this package is available from CTAN. % @@ -56,6 +56,8 @@ \usepackage{listings} \usepackage{microtype} +% TEMP work-around for https://github.com/schlcht/microtype/issues/4 +\microtypesetup{nopatch=item} \hypersetup{hidelinks} @@ -120,12 +122,14 @@ \newcounter{zchowto} \lstnewenvironment{zchowto}[1][]{% \renewcommand{\lstlistingname}{How-to}% + \renewcommand*\theHlstlisting{ht.\thelstlisting}% \lstset{#1}% \setcounter{lstlisting}{\value{zchowto}}% }{} \newcounter{zcworkaround} \lstnewenvironment{zcworkaround}[1][]{% \renewcommand{\lstlistingname}{Work-around}% + \renewcommand*\theHlstlisting{wa.\thelstlisting}% \lstset{#1}% \setcounter{lstlisting}{\value{zcworkaround}}% }{} @@ -163,6 +167,9 @@ \title{% The \pkg{zref-clever} package% \thanks{This file describes \fileversion, released \filedate.}% + \texorpdfstring{\\{}\medskip{}}{ - }% + User manual% + \texorpdfstring{\medskip{}}{}% } \author{% @@ -174,7 +181,11 @@ \maketitle -\begin{abstract} +\begin{center} + {\bfseries \abstractname\vspace{-.5em}\vspace{0pt}} +\end{center} + +\begin{quotation} \pkg{zref-clever} provides an 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 @@ -183,17 +194,22 @@ compressed into ranges when due. The reference format is highly and easily customizable, both globally and locally. \pkg{zref-clever} is based on \pkg{zref}'s extensible referencing system. -\end{abstract} +\end{quotation} + +\bigskip{} \begin{center} - \small \textbf{EXPERIMENTAL} Please read \zcref{sec:warning} carefully. \end{center} +\clearpage{} + \tableofcontents +\clearpage{} + \section{Introduction} Cross-referencing is an area which lends itself quite naturally to automation. @@ -237,12 +253,11 @@ carried over to \pkg{zref}, neither by the \pkg{zref} itself nor by other packages. \pkg{zref-clever} tries to cover this gap, by bringing a number of existing -features available for the standard referencing system to \pkg{zref}, and -hopefully making \pkg{zref} more accessible, and interesting, to the average -user. And the package's name makes it clear that the core of the envisaged -feature set is that of \pkg{cleveref}, even though the attempt was less one of -replicating functionality per se than that of having it as a successful point -of reference, from where we could then try to tap into \pkg{zref}'s potential. +features available for the standard referencing system to \pkg{zref}. And the +package's name makes it clear that the core of the envisaged feature set is +that of \pkg{cleveref}, even though the attempt was less one of replicating +functionality per se than that of having it as a successful point of +reference, from where we could then try to tap into \pkg{zref}'s potential. Indeed, although there is a significant intersection, the features of \pkg{zref-clever} are neither a superset nor a subset of those of \pkg{cleveref}. There are things either of them can do that the other can't. @@ -254,16 +269,16 @@ local options. Considering that \pkg{zref} itself offers the \pkg{zref-titleref} module, and that the integration with \pkg{zref-check} allows \pkg{zref-clever} to make -context sensitive references, akin to those of \pkg{varioref}, a significant -part of the most prominent automation features available to the standard -referencing system is thus brought to \pkg{zref}, working under a single -consistent underlying infrastructure and user interface. Alas, there are -limitations, of course (see \zcref{sec:limitations}). Still, all in all, -hopefully \pkg{zref-clever} can be the missing piece for \pkg{zref} to fulfill -the promise insinuated by the ``z'' in its name, and be your ``last ref''. +context sensitive references, a significant part of the most prominent +automation features available to the standard referencing system is thus +brought to \pkg{zref}, working under a single consistent underlying +infrastructure and user interface. There are some limitations, of course (see +\zcref{sec:limitations}), and it may be your cup of tea or not. Still, all in +all, hopefully \pkg{zref-clever} can make \pkg{zref} more accessible, and +interesting, to the average user. -\subsection{Warning} +\section{Warning} \zlabel{sec:warning} This package is in its early days, and should be considered experimental. By @@ -289,7 +304,7 @@ As usual: \end{zcexample} -\subsection{Dependencies} +\section{Dependencies} \pkg{zref-clever} requires \pkg{zref}, and \LaTeX{} kernel 2021-11-15, or newer. It also needs \pkg{l3keys2e} and \pkg{ifdraft}. Some packages are @@ -341,9 +356,9 @@ effects if ungrouped, e.g.\ in the preamble. \cs{zcRefTypeSetup}\marg{type}\marg{options} \end{syntax} \end{function} -Sets type-specific reference format options (see \zcref{sec:ref-format-opts}). -Just as for \cs{zcsetup}, the settings performed by \cs{zcRefTypeSetup} are -local, within the current group. +Sets type-specific reference format options (see +\zcref{sec:reference-format}). Just as for \cs{zcsetup}, the settings +performed by \cs{zcRefTypeSetup} are local, within the current group. \bigskip{} @@ -355,12 +370,20 @@ of arguments by it and/or processing by \pkg{l3keys}, particularly with regard to brace-stripping and space-trimming. Furthermore, \pkg{zref-clever} loads \pkg{zref}'s \pkg{zref-user} module by -default. So you also have its user commands available out of the box, notably -\cs{zlabel}, but also \cs{zref} and \cs{zpageref} themselves. +default. So you also have its user commands available out of the box, +including \cs{zref} and \cs{zpageref}, but notably: +\begin{function}{\zlabel} + \begin{syntax} + \cs{zlabel}\marg{label} + \end{syntax} +\end{function} +Sets \meta{label} for referencing with \cs{zref} and, thus, also \cs{zcref}. +\cs{zlabel} is provided by \pkg{zref-user} and is the counterpart of +\cs{label} for \pkg{zref}'s referencing system. -\subsection{Options} +\section{Options} \zlabel{sec:options} \pkg{zref-clever} is highly configurable, offering a lot of flexibility in @@ -376,7 +399,7 @@ as a whole; and ``reference format options'', which control the detail of reference formatting, including type-specific and language-specific settings. This section covers the first group (for the second one, see -\zcref{sec:ref-format-opts}). General options can be set globally either as +\zcref{sec:reference-format}). General options can be set globally either as package options at load-time (see \zcref{sec:loading-package}) or by means of \cs{zcsetup} in the preamble (see \zcref{sec:user-interface}). They can also be set locally with \cs{zcsetup} along the document or through the optional @@ -570,7 +593,7 @@ equivalent to \texttt{nameinlink=true}. \DescribeOption{preposinlink} % The \opt{preposinlink} option controls whether the \opt{refpre} and -\opt{refpos} reference format options (see \zcref{sec:ref-format-opts}) are +\opt{refpos} 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}. @@ -578,7 +601,7 @@ 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 -\zcref{sec:ref-format-opts}). The default value, \texttt{current}, uses the +\zcref{sec:reference-format}). The default value, \texttt{current}, uses the current language, as defined by \pkg{babel} or \pkg{polyglossia} (or \texttt{english} if none of them is loaded). Value \texttt{main} uses the main document language, as defined by \pkg{babel} or \pkg{polyglossia} (or @@ -620,8 +643,8 @@ is equivalent to \texttt{nudge=true} and the package's default is a comma separated list of elements, and recognizes values \texttt{multitype}, \texttt{comptosing}, \texttt{gender}, and \texttt{all}. The \texttt{multitype} nudge warns when the reference is composed by multiple type -blocks (see \zcref{sec:ref-format-opts}). The \texttt{comptosing} nudge let's -you know when multiple labels of the same type have been compressed to a +blocks (see \zcref{sec:reference-format}). The \texttt{comptosing} nudge +let's you know when multiple labels of the same type have been compressed to a singular type name form. It can be combined with the \opt{sg} option, which is the way to tell \cs{zcref} you know it's a singular and so not to nudge if a compression to singular occurs, but to nudge if the contrary occurs, that @@ -640,7 +663,7 @@ the ``nudging'' feature. \DescribeOption{font} % The \opt{font} option can receive font styling commands to change the appearance of the whole reference list (see also the \opt{namefont} and -\opt{reffont} reference format options in \zcref{sec:ref-format-opts}). It +\opt{reffont} reference format options in \zcref{sec:reference-format}). It does not affect the content of the \opt{note}, however. The option is intended exclusively for commands that only change font attributes: style, family, shape, weight, size, color, etc. Anything else, particularly commands @@ -656,7 +679,7 @@ The \opt{titleref} option receives no value and, when given, loads \DescribeOption{note} % The \opt{note} option receives as value some text to be typeset at the end of the whole reference list. It is separated from it by \opt{notesep} (see -\zcref{sec:ref-format-opts}). +\zcref{sec:reference-format}). \DescribeOption{check} % Provides integration of \pkg{zref-clever} with the \pkg{zref-check} package. @@ -667,7 +690,7 @@ both checks and \cs{zcheck}'s options. And the checks are performed for each label in \marg{labels} received as argument by \cs{zcref}. See the User manual of \pkg{zref-check} for details. The checks done by the \opt{check} option in \cs{zcref} comprise the complete reference, including the \opt{note} -(see \zcref{sec:ref-format-opts}). If \pkg{zref-check} was not loaded in the +(see \zcref{sec:reference-format}). If \pkg{zref-check} was not loaded in the preamble, at begin document the option is made no-op and issues a warning. \DescribeOption{countertype} % @@ -763,10 +786,8 @@ available modules and details about each of them, see \opt{nocompat} without a value (or an empty one). This is a preamble only option. -\section{Reference format} -\zlabel{sec:reference-format} -\subsection{Reference types} +\section{Reference types} \zlabel{sec:reference-types} A ``reference type'' is the basic \pkg{zref-clever} setup unit for specifying @@ -834,7 +855,7 @@ the \cs{appendix}. One more observation about ``reference types'' is due here. A \emph{type} is not really ``defined'' in the sense a variable or a function is. It is more of a ``string'' which \pkg{zref-clever} uses to look for a whole set of -type-specific reference format options (see \zcref{sec:ref-format-opts}). +type-specific reference format options (see \zcref{sec:reference-format}). Each of these options individually may be ``set'' or not, ``defined'' or not. And, depending on the setup and the relevant precedence rules for this, some of them may be required and some not. In practice, \pkg{zref-clever} uses the @@ -842,8 +863,8 @@ of them may be required and some not. In practice, \pkg{zref-clever} uses the compilation warning when it cannot find a suitable value. -\subsection{Reference format options} -\zlabel{sec:ref-format-opts} +\section{Reference format} +\zlabel{sec:reference-format} Formatting how the reference is to be typeset is, quite naturally, a big part of the user interface of \pkg{zref-clever}. In this area, we tried to balance @@ -1070,7 +1091,7 @@ of these language packages, or to a language specified directly by the user. This is primarily relevant for reference format options, particularly reference type \emph{names} (though not only, since most reference format options can have language-specific values, or ``translations'', see -\zcref{sec:ref-format-opts}). But other features of the package also cater +\zcref{sec:reference-format}). But other features of the package also cater for language specific needs. As far as language selection is concerned, if the language is declared and @@ -1211,7 +1232,7 @@ the user. \cs{zcDeclareLanguageAlias} is preamble only. \end{syntax} \end{function} Sets language-specific reference format options for \meta{language} (see -\zcref{sec:ref-format-opts}), be they type-specific or not. \meta{language} +\zcref{sec:reference-format}), be they type-specific or not. \meta{language} must be already known to \pkg{zref-clever}. Besides reference format options, \cs{zcLanguageSetup} knows three other keys: \opt{type}, \opt{case}, and \opt{gender}. The first two work like a ``switch'' affecting the options @@ -1226,7 +1247,7 @@ For \opt{case} this means the default declension case, which is the first element of the list provided to the \opt{declension} option in \cs{zcDeclareLanguage}. For \opt{type} this means ``default translations'', which are language-specific but not type-specific option values (see -\zcref{sec:ref-format-opts}). An empty valued \texttt{type=} key can also +\zcref{sec:reference-format}). An empty valued \texttt{type=} key can also ``unset'' the type. The \opt{gender} key sets the gender of the current \texttt{type} (provided the value it receives is one of the declared genders for \meta{language}). \cs{zcLanguageSetup} is preamble only. @@ -1384,49 +1405,68 @@ set around a cross-reference ``task'' we'd like to perform with \subsection{Context sensitive references} \zctask{Make cross-references which are sensitive to the relative position - between the reference and the label being referred to, à la \pkg{varioref}.} - -\pkg{varioref}'s \cs{vref} provides for varied references for three different -basic cases: when the reference and the label are on the same page, it -typesets a plain reference; when the reference and the label are in contiguous -pages (next, previous, or facing), it typesets the reference and a fixed -string corresponding to the relative position; when the reference and the -label are in different non-contiguous pages, it typesets a regular reference -and a page reference. The same end result, but with a different user -interface concept can be achieved through \pkg{zref-clever}'s integration with -\pkg{zref-check}. For this, the later must be loaded, which can be most -conveniently done with the \opt{check} option in the preamble. With that in -place, the different cases could be covered by the following examples: + between the reference and the label being referred to.} +It is frequently useful to make a reference to both a document element and its +page. For example: +\begin{zcexample} +\zcref{fig:1} on \zcpageref{fig:1} +\end{zcexample} + +However, while this works well when the object and the reference are somewhat +distant, we may want to adjust this to something different when the label and +the reference are close to each other. If both are on the same page, we may +want to drop the \cs{zcpageref}, or replace it with ``above'' or ``below''. +And, if both are on contiguous pages, then something like ``on the following +page'' or ``on the preceding page'' may be preferred. Since we don't usually +know the relative position of the reference to the label, particularly for +floats, making these kinds of adjustments manually is an uphill battle, and +error prone, in the absence of some support for it. + +\pkg{zref-clever}'s integration with \pkg{zref-check} offers some assistance +in making these kinds of references, by providing checks for the relation +between the reference and the label. For example, you may use: \begin{zcexample} -\zcref[check=thispage]{fig:1} \zcref[check=nextpage,note={on the following page}]{fig:1} -\zcref[check=prevpage,note={on the preceding page}]{fig:1} -\zcref[check=facing,note={on the facing page}]{fig:1} +\end{zcexample} +and if \texttt{fig:1} is not on the next page relative to the reference, a +compilation warning can be issued by \pkg{zref-check} (according to the +package's options), so that the problem can be easily identified and +corrected. Evidently, this does not fully automate the typeset results, but +it does automate the checking that the reference context is the intended one. + +And to make use of this feature, one does not need to rely on compiling the +document, make one such reference according to the current state of things, +and then adjusting them over and over, as the document gets edited. This +feature is best used within a certain workflow, which starts by making a +standard reference, but adding the \texttt{pagegap} check to it: +\begin{zcexample} \zcref[check=pagegap]{fig:1} on \zcpageref{fig:1} \end{zcexample} -And, similarly for the cases of \cs{vpageref}: - +During the initial editing of the document, this reference will be formally +correct, even if less than ideal in certain cases. At a certain point, when +you choose to give finishing touches to your document, then you can cater for +\pkg{zref-check}'s warnings (the package has options to control them, for +example, enabling warnings only when the \opt{draft} option is not in use). +The \texttt{pagegap} check will pass if there's one or more pages between the +reference and the label, in which case, that reference is already what we +want. However, if the referenced object lies in the previous page, the same +page, or the next page, the \texttt{pagegap} check will issue a warning. Thus +telling us if there's an opportunity, or need, to adjust the context +information of the reference. Then we can go with one of the below, according +to the situation: \begin{zcexample} -\zcref[noref,check=thispage,note={on this page}]{fig:1} -\zcref[noref,check=nextpage,note={on the following page}]{fig:1} -\zcref[noref,check=prevpage,note={on the preceding page}]{fig:1} -\zcref[noref,check=facing,note={on the facing page}]{fig:1} -\zcref[noref,check=pagegap]{fig:1} on \zcpageref{fig:1} +\zcref[check=thispage]{fig:1} +\zcref[check=above,note={above}]{fig:1} +\zcref[check=below,note={below}]{fig:1} +\zcref[check=nextpage,note={on the following page}]{fig:1} +\zcref[check=prevpage,note={on the preceding page}]{fig:1} +\zcref[check=facing,note={on the facing page}]{fig:1} \end{zcexample} -Since \cs{zcref} can receive multiple labels, and make ranges out of them, it -is not difficult to extend these examples to the functionality of -\cs{vrefrange} and \cs{vpagerefrange}. - -Evidently, this does not fully automate the typeset results, but it does -automate the checking that the reference context is the intended one. If the -relation between the reference and the label does not correspond to the -specified one, a compilation warning is issued (according to the options given -to \pkg{zref-check}), so that the problem can be easily identified and -corrected. See \pkg{zref-check}'s documentation for details, and further -available checks. +See \pkg{zref-check}'s documentation for details, and further available +checks. \subsection{\cs{newtheorem}} @@ -1783,10 +1823,7 @@ be the following. \end{document} \end{zchowto} -\section{Compatibility} -\zlabel{sec:compatibility} - -\subsection{Limitations} +\section{Limitations} \zlabel{sec:limitations} Being based on \pkg{zref} entails one quite sizable advantage for @@ -1852,7 +1889,7 @@ whether \pkg{zref-clever} is able to provide some specific support when a reasonable way to do so is within reach. -\subsection{Compatibility modules} +\section{Compatibility modules} \zlabel{sec:comp-modules} This section gives a description of each compatibility module provided by @@ -2043,7 +2080,7 @@ This module just sets appropriate \opt{countertype} and \opt{counterresetby} for the \texttt{subfigure} and \texttt{subtable} counters. -\subsection{Work-arounds} +\section{Work-arounds} \marginpar{\raggedleft\raisebox{-1.5ex}{\dbend}}As should be clear by now, the use of \pkg{zref}'s \cs{zlabel} and thus of \pkg{zref-clever} may occasionally @@ -2142,9 +2179,48 @@ be in their absence. Besides these more general acknowledgments, a number of people have contributed to \pkg{zref-clever}, whether they are aware of it or not. Suggestions, ideas, solutions to problems, bug reports or even encouragement -were generously provided by: Ulrike Fischer, Frank Mittelbach, Phelype -Oleinik, Jonathan P.\ Spratte, Enrico Gregorio, Steven B.\ Segletes, -\texttt{@samcarter}, Alan Munn, Florent Rougon, and David Carlisle. +were generously provided by (in chronological order): + Ulrike Fischer, + % 2021-07-03: It's Ulrike's fault :-) : https://tex.stackexchange.com/questions/603514/#comment1513982_603514 + % 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 + 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 + Enrico Gregorio, + % 2021-08-20: https://tex.stackexchange.com/a/611385 + % 2021-08-20: https://tex.stackexchange.com/q/611370/#comment1529282_611385 + Steven B.\ Segletes, + % 2021-08-20: https://tex.stackexchange.com/a/611373 + Jonathan P.\ Spratte, + % 2021-09-09: https://tex.stackexchange.com/a/614719 + % 2021-09-09: https://github.com/latex3/latex3/pull/988 + David Carlisle, + % 2021-10-10: https://tex.stackexchange.com/questions/618434/#comment1544401_618439 + Frank Mittelbach, + % 2021-10-14: https://github.com/latex3/latex2e/issues/687 + \texttt{@samcarter}, + % 2021-10-14: https://chat.stackexchange.com/transcript/message/59361777#59361777 + % 2021-10-21: https://chat.stackexchange.com/transcript/message/59418309#59418309 + Alan Munn, + % 2021-10-14: https://chat.stackexchange.com/transcript/message/59364073#59364073 + % 2021-10-21: https://chat.stackexchange.com/transcript/message/59418189#59418189 + Florent Rougon, + % https://github.com/frougon/xcref has been an useful reference for + % declension support. + Denis Bitouzé, + % 2021-11-25: https://github.com/gusbrs/zref-clever/issues/1 + Marcel Krüger, + % 2021-11-26: https://github.com/latex3/l3build/issues/215 + and Jürgen Spitzmüller. + % 2021-11-28: https://github.com/gusbrs/zref-clever/issues/2 + +The package's dictionaries have been provided or improved thanks to: + Denis Bitouzé (French). + % 2021-11-25: https://github.com/gusbrs/zref-clever/issues/1 If I have inadvertently left anyone off the list I apologize, and please let me know, so that I can correct the oversight. |