summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/zref-clever
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2021-12-08 03:02:13 +0000
committerNorbert Preining <norbert@preining.info>2021-12-08 03:02:13 +0000
commit0bfca40c9f89076ad634464a530fcc3e55d1d4e1 (patch)
tree7114d7d6b3ef883e247cfa80d6d36d0938b7c4f0 /macros/latex/contrib/zref-clever
parent6336c19969656f3ee5f0b0fed00aaf64369a40e7 (diff)
CTAN sync 202112080302
Diffstat (limited to 'macros/latex/contrib/zref-clever')
-rw-r--r--macros/latex/contrib/zref-clever/CHANGELOG.md12
-rw-r--r--macros/latex/contrib/zref-clever/MANIFEST.md110
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever-code.pdfbin1035367 -> 1040673 bytes
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever-code.tex2
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever.dtx224
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever.ins4
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever.pdfbin304271 -> 305580 bytes
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever.tex246
8 files changed, 406 insertions, 192 deletions
diff --git a/macros/latex/contrib/zref-clever/CHANGELOG.md b/macros/latex/contrib/zref-clever/CHANGELOG.md
index dc8ce5a3eb..e190d38d68 100644
--- a/macros/latex/contrib/zref-clever/CHANGELOG.md
+++ b/macros/latex/contrib/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/macros/latex/contrib/zref-clever/MANIFEST.md b/macros/latex/contrib/zref-clever/MANIFEST.md
index 98f72887da..e40fb05bf0 100644
--- a/macros/latex/contrib/zref-clever/MANIFEST.md
+++ b/macros/latex/contrib/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/macros/latex/contrib/zref-clever/zref-clever-code.pdf b/macros/latex/contrib/zref-clever/zref-clever-code.pdf
index b8105bc9e2..f8d0003a96 100644
--- a/macros/latex/contrib/zref-clever/zref-clever-code.pdf
+++ b/macros/latex/contrib/zref-clever/zref-clever-code.pdf
Binary files differ
diff --git a/macros/latex/contrib/zref-clever/zref-clever-code.tex b/macros/latex/contrib/zref-clever/zref-clever-code.tex
index a258484ccc..a4ebabd625 100644
--- a/macros/latex/contrib/zref-clever/zref-clever-code.tex
+++ b/macros/latex/contrib/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/macros/latex/contrib/zref-clever/zref-clever.dtx b/macros/latex/contrib/zref-clever/zref-clever.dtx
index 024aa50a99..ac9d81f44e 100644
--- a/macros/latex/contrib/zref-clever/zref-clever.dtx
+++ b/macros/latex/contrib/zref-clever/zref-clever.dtx
@@ -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.
%
@@ -60,41 +60,54 @@
% \DoNotIndex{\c@,\cl@,\c@enumN,\p@}
% \DoNotIndex{\the}
%
+% \NewDocumentCommand\githubissue{m}{^^A
+% issue~\href{https://github.com/gusbrs/zref-clever/issues/#1}{\##1}}
+%
+% ^^A Currently just for keeping semantic markup on this.
+% \NewDocumentCommand\contributor{m}{#1}
%
% \NewDocumentCommand\opt{m}{\texttt{#1}}
%
-% \pdfstringdefDisableCommands{%
+% \pdfstringdefDisableCommands{^^A
% \def\opt#1{#1}
% }
%
% ^^A Have the Index at 'section' level rather than 'part'. Otherwise it is
% ^^A just the same definition from 'l3doc.cls'.
-% \IndexPrologue{%
+% \IndexPrologue{^^A
% \section*{Index}
% \markboth{Index}{Index}
% \addcontentsline{toc}{section}{Index}
% The italic numbers denote the pages where the corresponding entry is
% described, numbers underlined point to the definition, all others indicate
-% the places where it is used.%
+% the places where it is used.^^A
% }
%
%
% \GetFileInfo{zref-clever.sty}
%
-% \title{%
-% The \pkg{zref-clever} package implementation%
-% \thanks{This file describes \fileversion, released \filedate.}%
+% \title{^^A
+% The \pkg{zref-clever} package^^A
+% \thanks{This file describes \fileversion, released \filedate.}^^A
+% \texorpdfstring{\\{}\medskip{}}{ - }^^A
+% Code documentation^^A
+% \texorpdfstring{\medskip{}}{}^^A
% }
%
-% \author{%
-% Gustavo Barros%
-% \thanks{\url{https://github.com/gusbrs/zref-clever}}%
+% \author{^^A
+% Gustavo Barros^^A
+% \thanks{\url{https://github.com/gusbrs/zref-clever}}^^A
% }
%
% \date{\filedate}
%
% \maketitle
%
+% \begin{center}
+% \textbf{EXPERIMENTAL}
+% \end{center}
+%
+%
% \tableofcontents
%
%
@@ -120,14 +133,14 @@
% release). Finally, a couple of changes came with the 2021-11-15 kernel
% release, which are important here. First, a fix was made to the new hook
% management system (\pkg{ltcmdhooks}), with implications to the hook we add
-% to \cs{appendix} (see \url{https://tex.stackexchange.com/q/617905} and
-% \url{https://github.com/latex3/latex2e/pull/699}, thanks Phelype Oleinik).
-% Second, the support for \cs{@currentcounter} has been improved, including
-% \cs{footnote} and \pkg{amsmath} (see
-% \url{https://github.com/latex3/latex2e/issues/687}, thanks Frank Mittelbach
-% and Ulrike Fischer). Hence, since we would not be able to go much backwards
-% without special handling anyway, we make the cut at the 2021-11-15 kernel
-% release.
+% to \cs{appendix} (by \contributor{Phelype Oleinik} at
+% \url{https://tex.stackexchange.com/q/617905} and
+% \url{https://github.com/latex3/latex2e/pull/699}). Second, the support for
+% \cs{@currentcounter} has been improved, including \cs{footnote} and
+% \pkg{amsmath} (by \contributor{Frank Mittelbach} and \contributor{Ulrike
+% Fischer} at \url{https://github.com/latex3/latex2e/issues/687}). Hence,
+% since we would not be able to go much backwards without special handling
+% anyway, we make the cut at the 2021-11-15 kernel release.
%
% \begin{macrocode}
\providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
@@ -146,7 +159,7 @@
%
% Identify the package.
% \begin{macrocode}
-\ProvidesExplPackage {zref-clever} {2021-11-24} {0.1.0-alpha}
+\ProvidesExplPackage {zref-clever} {2021-12-07} {0.1.1-alpha}
{Clever LaTeX cross-references based on zref}
% \end{macrocode}
%
@@ -200,9 +213,9 @@
% \emph{more reliable} than \cs{@currentcounter}, \texttt{thecounter} is meant
% to be kept as an \emph{option} (\opt{ref} option), in case there's need to
% use \pkg{zref-clever} together with \cs{labelformat}. Based on the
-% definition of \cs{@currentlabel} done inside \cs{refstepcounter} in `texdoc
-% source2e', section `ltxref.dtx'. We just drop the \cs[no-index]{p@...}
-% prefix.
+% definition of \cs{@currentlabel} done inside \cs{refstepcounter} in
+% \texttt{texdoc source2e}, section \texttt{ltxref.dtx}. We just drop the
+% \cs[no-index]{p@...} prefix.
%
% \begin{macrocode}
\zref@newprop { thecounter }
@@ -360,9 +373,9 @@
% call. I'll stay with the \texttt{e} variant, since conceptually it is what
% I want (\texttt{x} itself is not expandable), and this package is anyway not
% compatible with older kernels for which the performance penalty of the
-% \texttt{e} expansion would ensue (see also
-% \url{https://tex.stackexchange.com/q/611370/#comment1529282_611385}, thanks
-% Enrico Gregorio, aka `egreg').
+% \texttt{e} expansion would ensue (helpful comment by \contributor{Enrico
+% Gregorio}, aka `egreg' at
+% \url{https://tex.stackexchange.com/q/611370/#comment1529282_611385}).
% \begin{macrocode}
\cs_generate_variant:Nn \@@_get_enclosing_counters_value:n { e }
% \end{macrocode}
@@ -1560,9 +1573,9 @@
% existence of the property itself, as far as \pkg{zref} is concerned. This
% because typesetting relies on the check \cs{zref@ifrefcontainsprop}, which
% \emph{presumes} the property is defined and silently expands the \emph{true}
-% branch if it is not (see \url{https://github.com/ho-tex/zref/issues/13},
-% thanks Ulrike Fischer). Therefore, before adding anything to
-% \cs{l_@@_ref_property_tl}, check if first here with
+% branch if it is not (insightful comments by \contributor{Ulrike Fischer} at
+% \url{https://github.com/ho-tex/zref/issues/13}). Therefore, before adding
+% anything to \cs{l_@@_ref_property_tl}, check if first here with
% \cs{zref@ifpropundefined}: close it at the door.
%
%
@@ -2018,10 +2031,11 @@
% polluting the markup too much given that, for languages that need it, it may
% get to be used frequently.
%
-% Thanks \texttt{@samcarter} and Alan Munn for useful comments about
-% declension on the TeX.SX chat. Also, Florent Rougon's efforts in this area,
-% with the \pkg{xcref} package (\url{https://github.com/frougon/xcref}), have
-% been an insightful source to frame the problem in general terms.
+% \contributor{\texttt{@samcarter}} and \contributor{Alan Munn} provided
+% useful comments about declension on the TeX.SX chat. Also,
+% \contributor{Florent Rougon}'s efforts in this area, with the \pkg{xcref}
+% package (\url{https://github.com/frougon/xcref}), have been an insightful
+% source to frame the problem in general terms.
%
% \begin{macrocode}
\tl_new:N \l_@@_ref_decl_case_tl
@@ -2137,7 +2151,8 @@
% \url{https://tex.stackexchange.com/a/489570}). It can be set in \cs{zcref}
% and, for global settings, with \cs{zcsetup}. Note that, technically, the
% ``raw'' options are already available as \cs{@raw@opt@\meta{package}.sty}
-% (see \url{https://tex.stackexchange.com/a/618439}, thanks David Carlisle).
+% (helpful comment by \contributor{David Carlisle} at
+% \url{https://tex.stackexchange.com/a/618439}).
%
% \begin{macrocode}
\tl_new:N \l_@@_ref_typeset_font_tl
@@ -2258,6 +2273,26 @@
}
% \end{macrocode}
%
+% One interesting comment I received (by \contributor{Denis Bitouzé}, at
+% \githubissue{1}) about the most appropriate type for \texttt{paragraph} and
+% \texttt{subparagraph} counters was that the reader of the document does not
+% care whether that particular document structure element has been introduced
+% by \cs{paragraph} or, e.g.\ by the \cs{subsubsection} command. This is a
+% difference the author knows, as they're using \LaTeX{}, but to the reader
+% the difference between them is not really relevant, and it may be just
+% confusing to refer to them by different names. In this case the type for
+% \texttt{paragraph} and \texttt{subparagraph} should just be
+% \texttt{section}. I don't have a strong opinion about this, and the matter
+% was not pursued further. Besides, I presume not many people would set
+% \texttt{secnumdepth} so high to start with. But, for the time being, I left
+% the \texttt{paragraph} type for them, since there is actually a visual
+% difference to the reader between the \cs{subsubsection} and \cs{paragraph}
+% in the standard classes: up to the former, the sectioning commands break a
+% line before the following text, while, from the later on, the sectioning
+% commands and the following text are part of the same line. So,
+% \cs{paragraph} is actually different from ``just a shorter way to write
+% \cs{subsubsubsection}''.
+%
%
% \subsubsection*{\opt{counterresetters} option}
%
@@ -2577,9 +2612,10 @@
% value'' (\texttt{key}). This distinction is captured internally by the
% lower-level key parsing, but must be made explicit at \cs{keys_set:nn} by
% means of the \texttt{.default:V} property of the key in \cs{keys_define:nn}.
-% For the technique and some discussion about it, see
-% \url{https://tex.stackexchange.com/q/614690} (thanks Jonathan P.\ Spratte,
-% aka `Skillmon', and Phelype Oleinik) and
+% For the technique, by \contributor{Jonathan P.\ Spratte}, aka `Skillmon',
+% and some discussion about it, including further insights by
+% \contributor{Phelype Oleinik}, see
+% \url{https://tex.stackexchange.com/q/614690} and
% \url{https://github.com/latex3/latex3/pull/988}.
%
% \begin{macrocode}
@@ -3490,20 +3526,21 @@
% One further thing to discuss here -- to keep this ``on record'' -- is
% inhibition of compression for individual labels. It is not difficult to
% handle it at the infrastructure side, what gets sloppy is the user facing
-% syntax to signal such inhibition. For some possible alternatives for this
-% (and good ones at that) see \url{https://tex.stackexchange.com/q/611370}
-% (thanks Enrico Gregorio, Phelype Oleinik, and Steven B.\ Segletes). Yet
-% another alternative would be an option receiving the label(s) not to be
-% compressed, this would be a repetition, but would keep the syntax clean.
-% All in all, probably the best is simply not to allow individual inhibition
-% of compression. We can already control compression of each \cs{zcref} call
-% with existing options, this should be enough. I don't think the small extra
-% flexibility individual label control for this would grant is worth the
-% syntax disruption it would entail. Anyway, it would be easy to deal with
-% this in case the need arose, by just adding another condition (coming from
-% whatever the chosen syntax was) when we check for
-% \cs{@@_labels_in_sequence:nn} in \cs{@@_typeset_refs_not_last_of_type:}.
-% But I remain unconvinced of the pertinence of doing so.
+% syntax to signal such inhibition. For some possible alternatives for this,
+% suggested by \contributor{Enrico Gregorio}, \contributor{Phelype Oleinik},
+% and \contributor{Steven B.\ Segletes} (and good ones at that) see
+% \url{https://tex.stackexchange.com/q/611370}. Yet another alternative would
+% be an option receiving the label(s) not to be compressed, this would be a
+% repetition, but would keep the syntax clean. All in all, probably the best
+% is simply not to allow individual inhibition of compression. We can already
+% control compression of each \cs{zcref} call with existing options, this
+% should be enough. I don't think the small extra flexibility individual
+% label control for this would grant is worth the syntax disruption it would
+% entail. Anyway, it would be easy to deal with this in case the need arose,
+% by just adding another condition (coming from whatever the chosen syntax
+% was) when we check for \cs{@@_labels_in_sequence:nn} in
+% \cs{@@_typeset_refs_not_last_of_type:}. But I remain unconvinced of the
+% pertinence of doing so.
%
%
% \subsection*{Variables}
@@ -4991,9 +5028,10 @@
% the command being hooked at contains a double hash mark (\texttt{\#\#}) the
% patch to add the hook, if it needs to be done with the \cs{scantokens}
% method, may fail noisily (see \url{https://tex.stackexchange.com/q/617905},
-% thanks Phelype Oleinik). The 2021-11-15 kernel release already handle this
-% gracefully (see \url{https://github.com/latex3/latex2e/pull/699}, thanks
-% Phelype Oleinik).
+% with a detailed explanation and possible workaround by \contributor{Phelype
+% Oleinik}). The 2021-11-15 kernel release already handles this gracefully,
+% thanks to fix by \contributor{Phelype Oleinik} at
+% \url{https://github.com/latex3/latex2e/pull/699}.
%
%
% \subsection{\opt{appendices}}
@@ -5716,8 +5754,17 @@
%
% \section{Dictionaries}
%
+% Initial values for the English, German, French, Portuguese, and Spanish,
+% dictionaries have been provided by the author. Translations available for
+% document elements' names in other packages have been an useful reference for
+% the purpose, namely: \pkg{babel}, \pkg{cleveref}, \pkg{translator}, and
+% \pkg{translations}.
+%
+%
% \subsection{English}
%
+% English dictionary has been initially provided by the author.
+%
% \begin{macrocode}
%<*package>
\zcDeclareLanguage { english }
@@ -5786,12 +5833,6 @@ type = appendix ,
Name-pl = Appendices ,
name-pl = appendices ,
-type = subappendix ,
- Name-sg = Appendix ,
- name-sg = appendix ,
- Name-pl = Appendices ,
- name-pl = appendices ,
-
type = page ,
Name-sg = Page ,
name-sg = page ,
@@ -5946,6 +5987,8 @@ type = solution ,
%
% \subsection{German}
%
+% German dictionary has been initially provided by the author.
+%
% \begin{macrocode}
%<*package>
\zcDeclareLanguage
@@ -6065,21 +6108,6 @@ type = appendix ,
Name-sg = Anhangs ,
Name-pl = Anhänge ,
-type = subappendix ,
- gender = m ,
- case = N ,
- Name-sg = Anhang ,
- Name-pl = Anhänge ,
- case = A ,
- Name-sg = Anhang ,
- Name-pl = Anhänge ,
- case = D ,
- Name-sg = Anhang ,
- Name-pl = Anhängen ,
- case = G ,
- Name-sg = Anhangs ,
- Name-pl = Anhänge ,
-
type = page ,
gender = f ,
case = N ,
@@ -6430,6 +6458,14 @@ type = solution ,
%
% \subsection{French}
%
+% French dictionary has been initially provided by the author, and has been
+% improved thanks to Denis Bitouzé (\githubissue{1}) and participants of the
+% Groupe francophone des Utilisateurs de \TeX{} (GUTenberg) (at
+% \url{https://groups.google.com/g/gut_fr/c/rNLm6weGcyg}) and the
+% \texttt{fr.comp.text.tex} (at
+% \url{https://groups.google.com/g/fr.comp.text.tex/c/Fa11Tf6MFFs}) mailing
+% lists.
+%
% \begin{macrocode}
%<*package>
\zcDeclareLanguage [ gender = { f , m } ] { french }
@@ -6497,20 +6533,13 @@ type = appendix ,
Name-pl = Annexes ,
name-pl = annexes ,
-type = subappendix ,
- gender = f ,
- Name-sg = Annexe ,
- name-sg = annexe ,
- Name-pl = Annexes ,
- name-pl = annexes ,
-
type = page ,
gender = f ,
Name-sg = Page ,
name-sg = page ,
Name-pl = Pages ,
name-pl = pages ,
- rangesep = {\textendash} ,
+ rangesep = {-} ,
type = line ,
gender = f ,
@@ -6641,11 +6670,11 @@ type = algorithm ,
name-pl = algorithmes ,
type = listing ,
- gender = f ,
- Name-sg = Liste ,
- name-sg = liste ,
- Name-pl = Listes ,
- name-pl = listes ,
+ gender = m ,
+ Name-sg = Listing ,
+ name-sg = listing ,
+ Name-pl = Listings ,
+ name-pl = listings ,
type = exercise ,
gender = m ,
@@ -6670,6 +6699,11 @@ type = solution ,
%
% \subsection{Portuguese}
%
+% Portuguese dictionary provided by the author, who's a native speaker of
+% (Brazilian) Portuguese. I do expect this to be sufficiently general, but if
+% Portuguese speakers from other places feel the need for a Portuguese
+% variant, please let me know.
+%
% \begin{macrocode}
%<*package>
\zcDeclareLanguage [ gender = { f , m } ] { portuguese }
@@ -6740,13 +6774,6 @@ type = appendix ,
Name-pl = Apêndices ,
name-pl = apêndices ,
-type = subappendix ,
- gender = m ,
- Name-sg = Apêndice ,
- name-sg = apêndice ,
- Name-pl = Apêndices ,
- name-pl = apêndices ,
-
type = page ,
gender = f ,
Name-sg = Página ,
@@ -6923,6 +6950,8 @@ type = solution ,
%
% \subsection{Spanish}
%
+% Spanish dictionary has been initially provided by the author.
+%
% \begin{macrocode}
%<*package>
\zcDeclareLanguage [ gender = { f , m } ] { spanish }
@@ -6986,13 +7015,6 @@ type = appendix ,
Name-pl = Apéndices ,
name-pl = apéndices ,
-type = subappendix ,
- gender = m ,
- Name-sg = Apéndice ,
- name-sg = apéndice ,
- Name-pl = Apéndices ,
- name-pl = apéndices ,
-
type = page ,
gender = f ,
Name-sg = Página ,
diff --git a/macros/latex/contrib/zref-clever/zref-clever.ins b/macros/latex/contrib/zref-clever/zref-clever.ins
index 71259f4751..46d9982dc4 100644
--- a/macros/latex/contrib/zref-clever/zref-clever.ins
+++ b/macros/latex/contrib/zref-clever/zref-clever.ins
@@ -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.
%
@@ -70,7 +70,7 @@ This work consists of the files zref-clever.dtx,
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/macros/latex/contrib/zref-clever/zref-clever.pdf b/macros/latex/contrib/zref-clever/zref-clever.pdf
index 1b0c6f93f9..84f9a28b55 100644
--- a/macros/latex/contrib/zref-clever/zref-clever.pdf
+++ b/macros/latex/contrib/zref-clever/zref-clever.pdf
Binary files differ
diff --git a/macros/latex/contrib/zref-clever/zref-clever.tex b/macros/latex/contrib/zref-clever/zref-clever.tex
index c2fa9f19b2..4da3b2453d 100644
--- a/macros/latex/contrib/zref-clever/zref-clever.tex
+++ b/macros/latex/contrib/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.