summaryrefslogtreecommitdiff
path: root/macros/latex/contrib
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib')
-rw-r--r--macros/latex/contrib/dccpaper/README.md2
-rw-r--r--macros/latex/contrib/dccpaper/dccpaper.dtx24
-rw-r--r--macros/latex/contrib/dccpaper/dccpaper.pdfbin344973 -> 350338 bytes
-rw-r--r--macros/latex/contrib/tutodoc/code/tutodoc-locale-main-french.cfg.sty4
-rw-r--r--macros/latex/contrib/tutodoc/code/tutodoc.sty57
-rw-r--r--macros/latex/contrib/tutodoc/doc/tutodoc-en.pdfbin709681 -> 713562 bytes
-rw-r--r--macros/latex/contrib/tutodoc/doc/tutodoc-en.tex41
-rw-r--r--macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdfbin746351 -> 748226 bytes
-rw-r--r--macros/latex/contrib/tutodoc/doc/tutodoc-fr.tex45
-rw-r--r--macros/latex/contrib/zref-clever/CHANGELOG.md12
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever-code.pdfbin880835 -> 890025 bytes
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever-doc.pdfbin227507 -> 228899 bytes
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever-doc.tex100
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever.dtx256
14 files changed, 373 insertions, 168 deletions
diff --git a/macros/latex/contrib/dccpaper/README.md b/macros/latex/contrib/dccpaper/README.md
index 0d52a8434a..b1181bc202 100644
--- a/macros/latex/contrib/dccpaper/README.md
+++ b/macros/latex/contrib/dccpaper/README.md
@@ -73,7 +73,7 @@ A makefile is provided which you can use with the Make utility:
## Licence
-Copyright 2023 Digital Curation Centre, University of Edinburgh.
+Copyright 2024 Digital Curation Centre, University of Edinburgh.
This work consists of the image files dccpaper-by.eps and
dccpaper-by.pdf, the documented LaTeX file dccpaper.dtx and a Makefile.
diff --git a/macros/latex/contrib/dccpaper/dccpaper.dtx b/macros/latex/contrib/dccpaper/dccpaper.dtx
index de8e3b88cc..7218660813 100644
--- a/macros/latex/contrib/dccpaper/dccpaper.dtx
+++ b/macros/latex/contrib/dccpaper/dccpaper.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%<*internal|ijdc9|ijdc14|idcc|base>
-\def\Version{2023/08/11 v2.4}
+\def\Version{2024/08/23 v2.5}
%</internal|ijdc9|ijdc14|idcc|base>
%<*internal>
\iffalse
@@ -246,7 +246,7 @@ See: http://www.latex-project.org/lppl.txt
\endpreamble
\postamble
-Copyright (C) 2023 Digital Curation Centre, University of Edinburgh
+Copyright (C) 2024 Digital Curation Centre, University of Edinburgh
<info@dcc.ac.uk>
\endpostamble
@@ -546,16 +546,16 @@ Use this for a conference preprint.
\subsection{International Digital Curation Conference}
\begin{framed}\noindent
-To emulate a 2024 conference paper/extended abstract, use the \textsf{ijdc-v14}
-class with the \key{conference} option.
+To emulate a conference paper/extended abstract from 2024 onwards, use the
+\textsf{ijdc-v14} class with the \key{conference} option.
\end{framed}
The class is loaded in the usual way with
\lstinline|\documentclass[$\meta{options}$]{idcc}|.
Two types of option are available. The first relates to the conference to which the submission will be made:
\begin{description}[font=\normalfont]
- \item[\key{15}, \key{16}, .~.~.~, \key{22}, \key{24}]
- Use this to select the year of the conference, e.g.\@ \key{24} for 2024.
+ \item[\key{15}, \key{16}, .~.~.~, \key{24}, \key{25}]
+ Use this to select the year of the conference, e.g.\@ \key{25} for 2025.
\end{description}
The second relates to the type of submission:
@@ -871,6 +871,8 @@ Any acknowledgements should be placed in a section immediately before the refere
\section{Appendix A: Change History}
\begin{description}
+\item[v2.5] 2024-08-23\\
+Added details of IDCC 2025.
\item[v2.4] 2023-08-11\\
Added details of and update documentation for IDCC 2024.
\item[v2.3] 2022-01-27\\
@@ -1097,7 +1099,7 @@ Fully funded, part funded (subsidised) or delegate fee.
%<readme>## Licence
%<readme>
%<*driver|readme>
-Copyright 2023 Digital Curation Centre, University of Edinburgh.
+Copyright 2024 Digital Curation Centre, University of Edinburgh.
This work consists of the image files dccpaper-by.eps and
dccpaper-by.pdf, the documented LaTeX file dccpaper.dtx and a Makefile.
@@ -1520,9 +1522,15 @@ the University of Edinburgh on behalf of the Digital Curation Centre. ISSN:
\DeclareOption{24}{%
\def\dccp@publ@short{IDCC}
\def\dccp@publ@msg{The 18th \dccp@publ@long\ takes place on 19--21 February
- 2024 in Edinburgh, Scotland.\par\bigskip URL: \url{https://www.dcc.ac.uk/events/18th-international-digital-curation-conference}}
+ 2024 in Edinburgh, Scotland.\par\bigskip URL: \url{https://www.dcc.ac.uk/events/idcc24}}
\def\dccp@subject{18th \dccp@publ@long, 2024}
}
+\DeclareOption{25}{%
+ \def\dccp@publ@short{IDCC25}
+ \def\dccp@publ@msg{The 19th \dccp@publ@long\ takes place on 17--19 February
+ 2025 in The Hague, Netherlands.\par\bigskip URL: \url{https://www.dcc.ac.uk/events/idcc25}}
+ \def\dccp@subject{19th \dccp@publ@long, 2025}
+}
\ProcessOptions\relax
% \end{macrocode}
diff --git a/macros/latex/contrib/dccpaper/dccpaper.pdf b/macros/latex/contrib/dccpaper/dccpaper.pdf
index 3cd33ff6fa..310af05b12 100644
--- a/macros/latex/contrib/dccpaper/dccpaper.pdf
+++ b/macros/latex/contrib/dccpaper/dccpaper.pdf
Binary files differ
diff --git a/macros/latex/contrib/tutodoc/code/tutodoc-locale-main-french.cfg.sty b/macros/latex/contrib/tutodoc/code/tutodoc-locale-main-french.cfg.sty
index c639e1e9e0..5c97cb2f18 100644
--- a/macros/latex/contrib/tutodoc/code/tutodoc-locale-main-french.cfg.sty
+++ b/macros/latex/contrib/tutodoc/code/tutodoc-locale-main-french.cfg.sty
@@ -8,8 +8,8 @@
\NewDocumentCommand{\tutodoc@trans@note@title}{}{Note}
\NewDocumentCommand{\tutodoc@trans@tip@title}{}{Astuce}
\NewDocumentCommand{\tutodoc@trans@important@title}{}{Important}
-\NewDocumentCommand{\tutodoc@trans@caution@title}{}{Caution}
-\NewDocumentCommand{\tutodoc@trans@warn@title}{}{Danger}
+\NewDocumentCommand{\tutodoc@trans@caution@title}{}{Mise ~ en ~ garde}
+\NewDocumentCommand{\tutodoc@trans@warn@title}{}{Avertissement}
\NewDocumentCommand{\tutodoc@trans@chges@pb}{}{Problème}
\NewDocumentCommand{\tutodoc@trans@chges@break}{}{Bifurcation}
\NewDocumentCommand{\tutodoc@trans@chges@fix}{}{Réparation}
diff --git a/macros/latex/contrib/tutodoc/code/tutodoc.sty b/macros/latex/contrib/tutodoc/code/tutodoc.sty
index 5e0ea7a0fb..a27e1a7ac6 100644
--- a/macros/latex/contrib/tutodoc/code/tutodoc.sty
+++ b/macros/latex/contrib/tutodoc/code/tutodoc.sty
@@ -21,31 +21,42 @@
marginparwidth = 2cm,
marginparsep = 2mm,
heightrounded
-]{geometry}[2020-01-02]
+]{geometry}%
+ [2020-01-02]
+
+\RequirePackage[raggedright]%
+ {titlesec}%
+ [2021/07/05]
-\RequirePackage[raggedright]{titlesec}[2021/07/05]
\RequirePackage{tocbasic}
-\RequirePackage{xcolor}[2022/06/12]
-\RequirePackage{hyperref}[2023-02-07]
+\RequirePackage{xcolor}%
+ [2022/06/12]
+
+\RequirePackage{hyperref}%
+ [2023-02-07]
% We delegate the management of quoting to the `csquotes' package,
% which takes care of the linguistic parameters.
-\RequirePackage{csquotes}[2022-09-14]
+\RequirePackage{csquotes}%
+ [2022-09-14]
-\RequirePackage{amsthm}[2017/09]
+\RequirePackage{amsthm}%
+ [2017/09]
-\RequirePackage{clrstrip}[2021-08-28]
+\RequirePackage{clrstrip}%
+ [2021-08-28]
\RequirePackage{tcolorbox}[2023/06/19]
\tcbuselibrary{minted, breakable, skins}
-\RequirePackage{marginnote}[2023-09-07]
+\RequirePackage{marginnote}%
+ [2023-09-07]
% -- LOCALE LANG -- %
@@ -808,8 +819,8 @@
%%%
% prototype::
% #1 : the color of the margin note
-% #2 : the first material (a date or nothing)
-% #3 : the second material (a version number or nothing)
+% #2 : the first material (a version number or nothing)
+% #3 : the second material (a date or nothing)
% #4 : the last negative vertical spacing for the 2nd rule
%
% :action: this macro factorizes the printing of the changes
@@ -829,15 +840,19 @@
\IfBlankTF{#2}{}{
\par
- \__tdoc_translate_date:n { #2 }
+ #2
\par
}
- \vspace{1pt}
+ \IfBlankTF{#3}{}{
+ \IfBlankTF{#2}{}{
+ \vspace{1pt}
+ }
- \par
- #3
- \par
+ \par
+ \__tdoc_translate_date:n { #3 }
+ \par
+ }
\vspace{#4}
\rule{1.65cm}{.95pt}
@@ -871,8 +886,8 @@
%%%
\cs_new:Npn \__tdoc_translate_date_process:w #1 - #2 - #3 \q_stop {
\tutodoc@trans@date{#1}
- {#2}
- {#3}
+ {#2}
+ {#3}
}
@@ -895,9 +910,9 @@
%%%
\NewDocumentCommand{\tdocversion}{O{blue} m O{}}{
\tutodoc@new@change@margin{#1} % Color
- {#3} % Date
- {#2} % Version
- {-4.25pt} % Last negative vertical spacing
+ {#2} % Version
+ {#3} % Date
+ {-4.25pt} % Last negative vertical spacing
}
@@ -919,7 +934,7 @@
}
-% -- CHANGES - WHAT?
+% -- CHANGES - WHAT? -- %
% :: MESSAGES :: %
diff --git a/macros/latex/contrib/tutodoc/doc/tutodoc-en.pdf b/macros/latex/contrib/tutodoc/doc/tutodoc-en.pdf
index 6124b97c99..84a98f1e35 100644
--- a/macros/latex/contrib/tutodoc/doc/tutodoc-en.pdf
+++ b/macros/latex/contrib/tutodoc/doc/tutodoc-en.pdf
Binary files differ
diff --git a/macros/latex/contrib/tutodoc/doc/tutodoc-en.tex b/macros/latex/contrib/tutodoc/doc/tutodoc-en.tex
index f6449b959c..371b905d97 100644
--- a/macros/latex/contrib/tutodoc/doc/tutodoc-en.tex
+++ b/macros/latex/contrib/tutodoc/doc/tutodoc-en.tex
@@ -1,4 +1,4 @@
-
+
% -------------------- %
% -- RESOURCES USED -- %
% -------------------- %
@@ -266,8 +266,8 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-version-n-change-unclassifiable.tex}
-\begin{tdoctopic}{Unclassifiable}
+\begin{filecontents*}[overwrite]{examples-version-n-change-user-choice.tex}
+\begin{tdoctopic}{It's my choice}
% This is where the point needs to be put.
\item Info 1...
\item Info 2...
@@ -343,9 +343,9 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...
\begin{document}
-\title{Le package \texttt{tutodoc} - Documentation de type tutoriel}
+\title{The \texttt{tutodoc} package - Tutorial-type documentation}
\author{Christophe BAL}
-\date{\ordinalnum{1} Jan. 2024 - Version 1.1.0}
+\date{23 Aug. 2024 - Version 1.2.0}
\maketitle
@@ -582,7 +582,6 @@ The \tdocenv{tdocwarn} environment is used to warn the user of a trap to avoid.
\tdoclatexinput[sbs]{examples-focus-warn.tex}
-\newpage
\section{Specify packages, classes, macros or environments}
Here's what you can type semantically.
@@ -794,7 +793,6 @@ To obtain renderings by importing the code from an external file, instead of typ
\end{tdocexa}
-\newpage
\section{Use cases in \LaTeX}
Documenting a package or a class is done efficiently using use cases showing both the code and the corresponding result.
@@ -873,9 +871,9 @@ Here are some examples.
\begin{tdocwarn}
With default formatting, if the code begins with an opening bracket, the default option must be explicitly indicated.
\tdocdocbasicinput{examples-listing-strange.tex}
-
+
\smallskip
-
+
Another method is to use the \tdocmacro{string} primitive.
\tdocdocbasicinput{examples-listing-strange-bis.tex}
\end{tdocwarn}
@@ -943,7 +941,6 @@ The \tdocmacro{tdoclatexinput} macro, shown below, expects the path of a file an
% ------------------ %
-\newpage
\subsection{Imported codes put into practice} \label{tdoc-latexshow}
\begin{tdocexa}[Showcase]
@@ -1101,7 +1098,6 @@ during the latest changes.
% ------------------ %
-\newpage
\begin{tdocexa}[For fixes]
\leavevmode
@@ -1115,7 +1111,7 @@ during the latest changes.
\begin{tdocexa}[Chosen topics]
\leavevmode
- \tdoclatexinput[sbs]{examples-version-n-change-unclassifiable.tex}
+ \tdoclatexinput[sbs]{examples-version-n-change-user-choice.tex}
\end{tdocexa}
@@ -1151,9 +1147,26 @@ Blo, blo, blo...
Blu, blu, blu...
\end{tdoclatex}
-\newpage
\section{History}
+\tdocversion{1.2.0}[2024-08-23]
+
+\begin{tdocupdate}
+ \item \tdocmacro{tdocversion}
+ \begin{enumerate}
+ \item The version number is above the date.
+
+ \item The spacing is better managed when the date is absent.
+ \end{enumerate}
+\end{tdocupdate}
+
+
+\begin{tdocfix}
+ \item Content highlighting: the French translations of \tdocinEN*{caution} and \tdocinEN*{danger} were incorrect.
+\end{tdocfix}
+
+\tdocsep
+
\tdocversion{1.1.0}[2024-01-06]
\begin{tdocnew}
@@ -1183,5 +1196,5 @@ Blu, blu, blu...
First public version of the project.
+
\end{document}
- \ No newline at end of file
diff --git a/macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdf b/macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdf
index a8691e1e8d..d0a970abec 100644
--- a/macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdf
+++ b/macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdf
Binary files differ
diff --git a/macros/latex/contrib/tutodoc/doc/tutodoc-fr.tex b/macros/latex/contrib/tutodoc/doc/tutodoc-fr.tex
index ae9f99c300..8291ce4b4a 100644
--- a/macros/latex/contrib/tutodoc/doc/tutodoc-fr.tex
+++ b/macros/latex/contrib/tutodoc/doc/tutodoc-fr.tex
@@ -266,8 +266,8 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-version-n-change-unclassifiable.tex}
-\begin{tdoctopic}{Inclassable}
+\begin{filecontents*}[overwrite]{examples-version-n-change-user-choice.tex}
+\begin{tdoctopic}{C'est mon choix}
% Ici le point s'impose.
\item Info 1...
\item Info 2...
@@ -341,7 +341,7 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...
\title{Le package \texttt{tutodoc} - Documentation de type tutoriel}
\author{Christophe BAL}
-\date{1\ier{} Janv. 2024 - Version 1.1.0}
+\date{23 Août 2024 - Version 1.2.0}
\maketitle
@@ -671,18 +671,18 @@ Il est parfois utile d'obtenir directement le rendu d'un code dans la documentat
\subsection{Avec une bande colorée}
\begin{tdocexa}[Avec les textes par défaut]
- Il peut être utile de montrer un rendu réel directement dans un document
+ Il peut être utile de montrer un rendu réel directement dans un document.
\footnote{
Typiquement lorsque l'on fait une démo.
- }.
+ }
Ceci se tape via \tdocenv{tdocshowcase} comme suit.
\tdoclatexinput[code]{examples-showcase-default.tex}
- On obtient alors le rendu suivant
+ On obtient alors le rendu suivant.
\footnote{
En coulisse, la bande est créée sans effort grâce au package \tdocpack{clrstrip}.
- }.
+ }
\medskip
@@ -889,9 +889,9 @@ Voici des exemples d'utilisation.
\begin{tdocwarn}
Avec la mise en forme par défaut, si le code commence par un crochet ouvrant, il faudra indiquer explicitement l'option par défaut.
\tdocdocbasicinput{examples-listing-strange.tex}
-
+
\smallskip
-
+
Une autre méthode consiste à utiliser la primitive \tdocmacro{string}.
\tdocdocbasicinput{examples-listing-strange-bis.tex}
\end{tdocwarn}
@@ -1059,10 +1059,10 @@ On peut au choix dater quelque chose, ou bien le versionner, dans ce second cas
\begin{tdocwarn}
- Seul l'emploi du format numérique \tdocinlatex+YYYY-MM-DD+ est vérifié
+ Seul l'emploi du format numérique \tdocinlatex+YYYY-MM-DD+ est vérifié,
\footnote{
Techniquement, vérifier la validité d'une date, via \LaTeX3, ne présente pas de difficulté.
- },
+ }
et ceci est un choix ! Pourquoi cela ? Tout simplement car dater et versionner des explications devrait se faire de façon semi-automatisée afin d'éviter tout bug humain.
% \footnote{
% L'auteur de \tdocpack{tutodoc} est entrain de mettre en place un ensemble d'outils permettant une telle semi-automatisation.
@@ -1132,11 +1132,10 @@ lors des derniers changements.
\begin{tdocexa}[Thématiques aux choix]
\leavevmode
- \tdoclatexinput[sbs]{examples-version-n-change-unclassifiable.tex}
+ \tdoclatexinput[sbs]{examples-version-n-change-user-choice.tex}
\end{tdocexa}
-\newpage
\section{Décorations}
Finissons cette documentation avec de petites outils de mise en forme pouvant rendre de grands services.
@@ -1169,9 +1168,26 @@ Blo, blo, blo...
Blu, blu, blu...
\end{tdoclatex}
-\newpage
\section{Historique}
+\tdocversion{1.2.0}[2024-08-23]
+
+\begin{tdocupdate}
+ \item \tdocmacro{tdocversion}
+ \begin{enumerate}
+ \item Le numéro de version est au-dessus de la date.
+
+ \item L'espacement est mieux géré lorsque la date est absente.
+ \end{enumerate}
+\end{tdocupdate}
+
+
+\begin{tdocfix}
+ \item Mise en avant de contenus : les traductions françaises de \tdocinEN*{caution} et \tdocinEN*{danger} étaient erronées.
+\end{tdocfix}
+
+\tdocsep
+
\tdocversion{1.1.0}[2024-01-06]
\begin{tdocnew}
@@ -1201,4 +1217,5 @@ Blu, blu, blu...
Première version publique du projet.
+
\end{document}
diff --git a/macros/latex/contrib/zref-clever/CHANGELOG.md b/macros/latex/contrib/zref-clever/CHANGELOG.md
index 3cf6c73b25..80b15591be 100644
--- a/macros/latex/contrib/zref-clever/CHANGELOG.md
+++ b/macros/latex/contrib/zref-clever/CHANGELOG.md
@@ -1,6 +1,16 @@
# Changelog
-## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.4.5...HEAD)
+## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.4.6...HEAD)
+
+## [v0.4.6](https://github.com/gusbrs/zref-clever/compare/v0.4.5...v0.4.6) (2024-08-23)
+
+### Fixed
+- Fix sorting of appendix references.
+
+### Changed
+- The `counterresetters` option now receives a full comma separated list of
+ counters as value, instead of working by incrementally adding values to the
+ list.
## [v0.4.5](https://github.com/gusbrs/zref-clever/compare/v0.4.4...v0.4.5) (2024-05-20)
diff --git a/macros/latex/contrib/zref-clever/zref-clever-code.pdf b/macros/latex/contrib/zref-clever/zref-clever-code.pdf
index 09b441eeb1..4dc41ff5a8 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-doc.pdf b/macros/latex/contrib/zref-clever/zref-clever-doc.pdf
index 5594a06fb3..e6c24bc473 100644
--- a/macros/latex/contrib/zref-clever/zref-clever-doc.pdf
+++ b/macros/latex/contrib/zref-clever/zref-clever-doc.pdf
Binary files differ
diff --git a/macros/latex/contrib/zref-clever/zref-clever-doc.tex b/macros/latex/contrib/zref-clever/zref-clever-doc.tex
index e088c49915..7b8e27a15b 100644
--- a/macros/latex/contrib/zref-clever/zref-clever-doc.tex
+++ b/macros/latex/contrib/zref-clever/zref-clever-doc.tex
@@ -245,20 +245,23 @@ where it lies.
But the plethora of existing features, packages and document classes which, in
one way or another, extends this basic functionality is a clear indication of
-a demand for more automation. Just to name the most popular: \pkg{cleveref},
-\pkg{hyperref}, \pkg{titleref}, \pkg{nameref}, \pkg{varioref}, \pkg{fancyref},
+a demand for more automation. Just to name the some of the most popular:
+\pkg{cleveref}, \pkg{nameref}, \pkg{titleref}, \pkg{varioref}, \pkg{fancyref},
and the kernel's \cs{labelformat}.
-However, the standard cross-referencing system stores two, and only two,
-properties with the label: the printed representation of the counter last
-incremented with \cs{refstepcounter} and the page. Of course, out of the
-mentioned desire to automate more, the need arose to store more information
-about the label to support this: the title or caption of the referenced
-object; its counter or, even better, its ``type'', that is, whether it is a
-section, chapter, figure, etc.; its hyperlink anchor, and so on. Thus those
-two property ``fields'' of the standard label became quite a disputed real
-state. And the packages in this area of functionality were bound to step on
-each other's toes as a result.
+However, the standard cross-referencing system traditionally stored two, and
+only two, properties with the label: the printed representation of the counter
+last incremented with \cs{refstepcounter} and the page.\footnote{Nowadays, it
+ stores 5, so that \pkg{hyperref} and \pkg{nameref} no longer need to
+ redefine \cs{label}.} Of course, out of the mentioned desire to automate
+more, the need arose to store more information about the label to support
+this: the title or caption of the referenced object; its counter or, even
+better, its ``type'', that is, whether it is a section, chapter, figure, etc.;
+its hyperlink anchor, and so on. Thus those two property ``fields'' of the
+standard label became quite a disputed real state. And the packages in this
+area of functionality, or which somehow depended on extending the
+cross-referencing mechanism, were bound to step on each other's toes as a
+result.
Out of this conundrum, Heiko Oberdiek eventually developed \pkg{zref}, which
implements an extensible referencing system, making the labels store a
@@ -890,30 +893,31 @@ know the counter associated with a particular label but also information on
any counter whose stepping may trigger its resetting, or its ``enclosing
counters''. This information is not easily retrievable from the counter
itself but is (normally) stored with the counter that does the resetting. The
-\opt{counterresetters} option adds counter names, received as a comma
-separated list, to the list of counters \pkg{zref-clever} uses to search for
-``enclosing counters'' of the counter for which a label is being set.
-Unfortunately, not every counter gets reset through the standard machinery for
-this, including some \LaTeX{} kernel ones (e.g. the \texttt{enumerate}
-environment counters). For those, there is really no way to retrieve this
-information directly, so we have to just tell \pkg{zref-clever} about them.
-And that's what the \opt{counterresetby} option is made for. It receives a
-comma separated list of \texttt{key=value} pairs, in which \texttt{key} is the
-counter, and \texttt{value} is its ``enclosing counter'', that is, the counter
-whose stepping results in its resetting. This is not really an ``option'' in
-the sense of ``user choice'', it is more of a way to inform \pkg{zref-clever}
-of something it cannot know or automatically find in general. One cannot
-place arbitrary information there, or \pkg{zref-clever} can be thoroughly
-confused. The setting must correspond to the actual resetting behavior of the
-involved counters. \opt{counterresetby} has precedence over the search done
-in the \opt{counterresetters} list. The default value of
-\opt{counterresetters} includes the counters for sectioning commands of the
-standard classes which, in most cases, should be the relevant ones for
-cross-referencing purposes. The default value of \opt{counterresetby}
-includes the \texttt{enumerate} environment counters. So, hopefully, you
-don't need to ever bother with either of these options. But, if you do, they
-are here. Use them with caution though. Since these options only affect how
-labels are set, they are not available in \cs{zcref}.
+\opt{counterresetters} option receives a full comma separated list of counter
+names, which \pkg{zref-clever} uses to search for ``enclosing counters'' of
+the counter for which a label is being set. The order matters (see code
+documentation for details), and you should also take care to start from the
+initial value set by the package. Unfortunately, not every counter gets reset
+through the standard machinery for this, including some \LaTeX{} kernel ones
+(e.g. the \texttt{enumerate} environment counters). For those, there is
+really no way to retrieve this information directly, so we have to just tell
+\pkg{zref-clever} about them. And that's what the \opt{counterresetby} option
+is made for. It receives a comma separated list of \texttt{key=value} pairs,
+in which \texttt{key} is the counter, and \texttt{value} is its ``enclosing
+counter'', that is, the counter whose stepping results in its resetting. This
+is not really an ``option'' in the sense of ``user choice'', it is more of a
+way to inform \pkg{zref-clever} of something it cannot know or automatically
+find in general. One cannot place arbitrary information there, or
+\pkg{zref-clever} can be thoroughly confused. The setting must correspond to
+the actual resetting behavior of the involved counters. \opt{counterresetby}
+has precedence over the search done in the \opt{counterresetters} list. The
+default value of \opt{counterresetters} includes the counters for sectioning
+commands of the standard classes which, in most cases, should be the relevant
+ones for cross-referencing purposes. The default value of
+\opt{counterresetby} includes the \texttt{enumerate} environment counters.
+So, hopefully, you don't need to ever bother with either of these options.
+But, if you do, they are here. Use them with caution though. Since these
+options only affect how labels are set, they are not available in \cs{zcref}.
\DescribeOption{\raisebox{.4em}{\dbend}\ currentcounter} %
\LaTeX{}'s \cs{refstepcounter} sets two variables which potentially affect the
@@ -2242,12 +2246,12 @@ A figure.
\section{Limitations}
\zlabel{sec:limitations}
-Being based on \pkg{zref} entails one quite sizable advantage for
+Being based on \pkg{zref} entails one significant advantage for
\pkg{zref-clever}: the extensible referencing system of the former allows
\pkg{zref-clever} to store and retrieve the information it needs to work
-without having to redefine some core \LaTeX{} commands. This alone makes for
-reduced compatibility problems and less load order issues than the average
-package in this functionality area. On the other hand, being based on
+without having to redefine some core \LaTeX{} commands. Which leads to less
+compatibility problems and load order issues than some traditional
+cross-reference related packages. On the other hand, being based on
\pkg{zref} also does impair the supported scope of \pkg{zref-clever}. Not
because of any particular limitation of either, but because any class or
package which implements some special handling for reference labels
@@ -2347,18 +2351,21 @@ for numbering and \cs{appendixname} for chapter's names. In sum, we'd like to
refer to the appendix sectioning commands as ``appendices'' rather than
``chapters'' or ``sections''. Since the sectioning commands are the same as
before \cs{appendix}, and so are their underlying counters, we must configure
-the counter type of the sectioning counters to \texttt{appendix}. And this is
-what this compatibility module does, and it uses a \pkg{ltcmdhooks} hook on
-\cs{appendix} for the purpose. Hence, this module applies to any document
+the counter type of the sectioning counters to \texttt{appendix}. Also, the
+sorting of appendix labels relative to those in the rest of the document
+requires attention, which is done by setting the main sectioning level counter
+as being reset by an internal counter with the \opt{counterresetby} option.
+And this is what this compatibility module does, using a \pkg{ltcmdhooks} hook
+on \cs{appendix} for the purpose. Hence, this module applies to any document
class or package which provides that command.
\DescribeOption{appendices} %
This module implements support for the \env{appendices} and
\env{subappendices} environments provided by the \pkg{appendix} package, and
also by \cls{memoir}. The task is the same as for the \texttt{appendix}
-module: set proper counter types for the sectioning counters. This module
-employs environment hooks to \env{appendices} and \env{subappendices} and a
-command hook to \cs{appendix} for the purpose.
+module: set proper counter types for the sectioning counters and ensuring
+proper sorting of labels. This module employs environment hooks to
+\env{appendices} and \env{subappendices}.
\DescribeOption{memoir} %
This compatibility module provides support for some of \cls{memoir}'s
@@ -2641,6 +2648,7 @@ were generously provided by (in chronological order):
% 2023-11-09: https://github.com/gusbrs/zref-clever/issues/20
% 2024-01-20: https://github.com/gusbrs/zref-clever/pull/25
% 2024-05-04: https://github.com/gusbrs/zref-clever/pull/27
+ % 2024-07-19: https://github.com/gusbrs/zref-clever/pull/32
and Lars Madsen.
% 2023-07-24: https://chat.stackexchange.com/transcript/message/64039717#64039717
% and following discussion.
diff --git a/macros/latex/contrib/zref-clever/zref-clever.dtx b/macros/latex/contrib/zref-clever/zref-clever.dtx
index 9c1d73a5a2..155d7141ee 100644
--- a/macros/latex/contrib/zref-clever/zref-clever.dtx
+++ b/macros/latex/contrib/zref-clever/zref-clever.dtx
@@ -171,7 +171,7 @@
%
% Identify the package.
% \begin{macrocode}
-\ProvidesExplPackage {zref-clever} {2024-05-20} {0.4.5}
+\ProvidesExplPackage {zref-clever} {2024-08-23} {0.4.6}
{Clever LaTeX cross-references based on zref}
% \end{macrocode}
%
@@ -374,19 +374,34 @@
% there is no possible verification mechanism for this.
%
%
-% \begin{macro}[EXP]{\@@_get_enclosing_counters_value:n}
-% Recursively generate a \emph{sequence} of ``enclosing counters'' values,
-% for a given \meta{counter} and leave it in the input stream. This
-% function must be expandable, since it gets called from \cs{zref@newprop}
-% and is the one responsible for generating the desired information when
-% the label is being set. Note that the order in which we are getting this
-% information is reversed, since we are navigating the counter reset chain
-% bottom-up. But it is very hard to do otherwise here where we need
-% expandable functions, and easy to handle at the reading side.
+% \begin{macro}[EXP]
+% {
+% \@@_get_enclosing_counters:n ,
+% \@@_get_enclosing_counters_value:n ,
+% }
+% Recursively generate a \emph{sequence} of ``enclosing counters'' and
+% values, for a given \meta{counter} and leave it in the input stream.
+% These functions must be expandable, since they get called from
+% \cs{zref@newprop} and are the ones responsible for generating the desired
+% information when the label is being set. Note that the order in which we
+% are getting this information is reversed, since we are navigating the
+% counter reset chain bottom-up. But it is very hard to do otherwise here
+% where we need expandable functions, and easy to handle at the reading
+% side.
% \begin{syntax}
+% \cs{@@_get_enclosing_counters:n} \Arg{counter}
% \cs{@@_get_enclosing_counters_value:n} \Arg{counter}
% \end{syntax}
% \begin{macrocode}
+\cs_new:Npn \@@_get_enclosing_counters:n #1
+ {
+ \cs_if_exist:cT { c@ \@@_counter_reset_by:n {#1} }
+ {
+ { \@@_counter_reset_by:n {#1} }
+ \@@_get_enclosing_counters:e
+ { \@@_counter_reset_by:n {#1} }
+ }
+ }
\cs_new:Npn \@@_get_enclosing_counters_value:n #1
{
\cs_if_exist:cT { c@ \@@_counter_reset_by:n {#1} }
@@ -406,16 +421,18 @@
% Gregorio}, aka `egreg' at
% \url{https://tex.stackexchange.com/q/611370/#comment1529282_611385}).
% \begin{macrocode}
+\cs_generate_variant:Nn \@@_get_enclosing_counters:n { e }
\cs_generate_variant:Nn \@@_get_enclosing_counters_value:n { e }
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}[EXP]{\@@_counter_reset_by:n}
-% Auxiliary function for \cs{@@_get_enclosing_counters_value:n}, and useful
-% on its own standing. It is broken in parts to be able to use the
-% expandable mapping functions. \cs{@@_counter_reset_by:n} leaves in the
-% stream the ``enclosing counter'' which resets \meta{counter}.
+% Auxiliary function for \cs{@@_get_enclosing_counters:n} and
+% \cs{@@_get_enclosing_counters_value:n}, and useful on its own standing.
+% It is broken in parts to be able to use the expandable mapping functions.
+% \cs{@@_counter_reset_by:n} leaves in the stream the ``enclosing counter''
+% which resets \meta{counter}.
% \begin{syntax}
% \cs{@@_counter_reset_by:n} \Arg{counter}
% \end{syntax}
@@ -461,6 +478,14 @@
\zref@addprop \ZREF@mainlist { zc@enclval }
% \end{macrocode}
%
+% The \texttt{zc@enclcnt} property is provided for the purpose of easing the
+% debugging of counter reset chains, thus it is not added \texttt{main}
+% property list by default.
+% \begin{macrocode}
+\zref@newprop { zc@enclcnt }
+ { \@@_get_enclosing_counters:e \l_@@_current_counter_tl }
+% \end{macrocode}
+%
%
% Another piece of information we need is the page numbering format being used
% by \cs{thepage}, so that we know when we can (or not) group a set of page
@@ -3883,37 +3908,70 @@
%
% \cs{l_@@_counter_resetters_seq} is used by \cs{@@_counter_reset_by:n} to
% populate the \texttt{zc@enclval} property, and stores the list of counters
-% which are potential ``enclosing counters'' for other counters. This option
-% is constructed such that users can only \emph{add} items to the variable.
-% There would be little gain and some risk in allowing removal, and the syntax
-% of the option would become unnecessarily more complicated. Besides, users
-% can already override, for any particular counter, the search done from the
-% set in \cs{l_@@_counter_resetters_seq} with the \opt{counterresetby} option.
+% which are potential ``enclosing counters'' for other counters.
+%
+% Note that, as far as \LaTeX{} is concerned, a given counter can be reset by
+% \emph{any number of counters}. \cs{counterwithin} just adds a new
+% ``within-counter'' for ``counter'' without removing any other existing ones.
+% However, the data structure of \pkg{zref-clever} can only account for
+% \emph{one} enclosing counter. In a way, this is hard to circumvent, because
+% the underlying counter reset behavior works ``top-down'', but when looking
+% to a label built from a given counter we need to infer the enclosing
+% counters ``bottom-up''. As a result, the reset chain we find is path
+% dependent or, more formally, what \cs{@@_counter_reset_by:n} returns depends
+% on the order in which it searches the list of
+% \cs{l_@@_counter_resetters_seq}, since it stops on the first match. This
+% representation mismatch should not be a problem in most cases. But one
+% should be aware of the limits it imposes.
+%
+% Consider the following case: the \cls{book} class sets, by default
+% \texttt{figure} and \texttt{table} counters to be reset every
+% \texttt{chapter}, \texttt{section} is also reset every \texttt{chapter}, of
+% course. Suppose now we say
+% \cs{counterwithin}\texttt{\{figure\}\{section\}}. Technically,
+% \texttt{figure} is being reset every \texttt{section} and every
+% \texttt{chapter}, but since \texttt{section} is also reset every
+% \texttt{chapter}, the original ``\texttt{chapter} resets \texttt{figure}''
+% behavior is now redundant. Innocuous, but is still there. Now, suppose we
+% want to find which counter is resetting \texttt{figure} using
+% \cs{@@_counter_reset_by:n}. If \texttt{chapter} comes before
+% \texttt{section} in \cs{l_@@_counter_resetters_seq}, \texttt{chapter} will
+% be returned, and that's not what we want. That's the reason
+% \opt{counterresetters} initial value goes bottom-up in the sectioning level,
+% since we'd expect the nesting of the reset chain to \emph{typically} work
+% top-down.
+%
+% If, despite all this, unexpected results still ensue, users can take care to
+% ``clean'' redundant resetting settings with \cs{counterwithout}. Besides,
+% users can already override, for any particular counter, the search done from
+% the set in \cs{l_@@_counter_resetters_seq} with the \opt{counterresetby}
+% option.
+%
+% For the above reasons, since order matters, the \opt{counterresetters}
+% option can only be set by the full list of counters. In other words, users
+% wanting to change this should take the initial value as their starting base.
+%
+% The \texttt{zc@enclcnt} \pkg{zref} property, not included by default in the
+% \texttt{main} property list, is provided for the purpose of easing the
+% debugging of counter reset chains. So, by adding
+% \cs{zref@addprop}\texttt{\{main\}\{zc@enclcnt\}} you can inspect what the
+% values in the \texttt{zc@enclval} property correspond to.
%
% \begin{macrocode}
\seq_new:N \l_@@_counter_resetters_seq
\keys_define:nn { zref-clever/label }
{
counterresetters .code:n =
- {
- \clist_map_inline:nn {#1}
- {
- \seq_if_in:NnF \l_@@_counter_resetters_seq {##1}
- {
- \seq_put_right:Nn
- \l_@@_counter_resetters_seq {##1}
- }
- }
- } ,
+ { \seq_set_from_clist:Nn \l_@@_counter_resetters_seq {#1} } ,
counterresetters .initial:n =
{
- part ,
- chapter ,
- section ,
- subsection ,
- subsubsection ,
- paragraph ,
subparagraph ,
+ paragraph ,
+ subsubsection ,
+ subsection ,
+ section ,
+ chapter ,
+ part ,
},
counterresetters .value_required:n = true ,
}
@@ -7754,11 +7812,45 @@
% appendix to ``end'', but in this case, of course, we can hook into the
% environment instead.
%
+% For the record, \url{https://tex.stackexchange.com/a/724742} is of
+% interest.
+%
% \begin{macrocode}
\@@_compat_module:nn { appendix }
{
+ \newcounter { zc@appendix }
+ \cs_if_exist:cTF { chapter }
+ {
+ \@@_zcsetup:e
+ {
+ counterresetby =
+ {
+% \end{macrocode}
+% In case someone did something like
+% \texttt{\textbackslash{}counterwithin\{chapter\}\{part\}}. Harmless
+% otherwise.
+% \begin{macrocode}
+ zc@appendix = \@@_counter_reset_by:n { chapter } ,
+ chapter = zc@appendix ,
+ } ,
+ }
+ }
+ {
+ \cs_if_exist:cT { section }
+ {
+ \@@_zcsetup:e
+ {
+ counterresetby =
+ {
+ zc@appendix = \@@_counter_reset_by:n { section } ,
+ section = zc@appendix ,
+ } ,
+ }
+ }
+ }
\AddToHook { cmd / appendix / before }
{
+ \setcounter { zc@appendix } { 1 }
\@@_zcsetup:n
{
countertype =
@@ -7797,26 +7889,28 @@
{
\@@_if_package_loaded:nT { appendix }
{
- \newcounter { zc@appendix }
- \newcounter { zc@save@appendix }
- \setcounter { zc@appendix } { 0 }
- \setcounter { zc@save@appendix } { 0 }
- \cs_if_exist:cTF { chapter }
- {
- \@@_zcsetup:n
- { counterresetby = { chapter = zc@appendix } }
- }
- {
- \cs_if_exist:cT { section }
- {
- \@@_zcsetup:n
- { counterresetby = { section = zc@appendix } }
- }
- }
\AddToHook { env / appendices / begin }
{
- \stepcounter { zc@save@appendix }
- \setcounter { zc@appendix } { \value { zc@save@appendix } }
+% \end{macrocode}
+% Technically, the \env{appendices} environment can be called multiple times.
+% By default, successive calls keep track of numbering and start where the
+% previous one left off. Which means just setting the \texttt{zc@appendix}
+% counter to 1 is enough for things to work, since the distinction between the
+% calls and the sorting of their respective references will depend on the
+% underlying sectioning. \pkg{appendix}'s documentation however, provides a
+% way to restart from A at each call (by redefining \cs{restoreapp} to do
+% nothing). In this case, the references inside different calls to
+% \env{appendices} get to be identical in every way, including printed form,
+% counter value, enclosing counters, etc., despite being different. We could
+% keep track of different calls to \env{appendices} by having the
+% \texttt{zc@appendix} counter be ``stepped'' at each call. Doing so would
+% mean though that \cs{zcref} would distingish things which are typeset
+% identically, granting some arguably weird results. True, the user
+% \emph{can} change the printed form for each \env{appendices} call,
+% e.g. redefining \cs{thechapter}, but in this case, they are responsible for
+% keeping track of this.
+% \begin{macrocode}
+ \setcounter { zc@appendix } { 1 }
\@@_zcsetup:n
{
countertype =
@@ -7832,13 +7926,36 @@
}
\AddToHook { env / appendices / end }
{ \setcounter { zc@appendix } { 0 } }
- \AddToHook { cmd / appendix / before }
+ \newcounter { zc@subappendix }
+ \cs_if_exist:cTF { chapter }
{
- \stepcounter { zc@save@appendix }
- \setcounter { zc@appendix } { \value { zc@save@appendix } }
+ \@@_zcsetup:e
+ {
+ counterresetby =
+ {
+ zc@subappendix = \@@_counter_reset_by:n { section } ,
+ section = zc@subappendix ,
+ } ,
+ }
+ }
+ {
+ \@@_zcsetup:e
+ {
+ counterresetby =
+ {
+ zc@subappendix = \@@_counter_reset_by:n { subsection } ,
+ subsection = zc@subappendix ,
+ } ,
+ }
}
\AddToHook { env / subappendices / begin }
{
+% \end{macrocode}
+% The \env{subappendices} environment, on the other hand, appears not to
+% support multiple calls inside the same chapter/section (the counter is reset
+% by default). Either way, the same reasoning applies.
+% \begin{macrocode}
+ \setcounter { zc@subappendix } { 1 }
\@@_zcsetup:n
{
countertype =
@@ -7851,6 +7968,8 @@
} ,
}
}
+ \AddToHook { env / subappendices / end }
+ { \setcounter { zc@subappendix } { 0 } }
\msg_info:nnn { zref-clever } { compat-package } { appendix }
}
}
@@ -7977,10 +8096,13 @@
}
% \end{macrocode}
% \pkg{amsmath} does use \cs{refstepcounter} for the \texttt{equation} counter
-% throughout and does set \cs{@currentcounter} for \cs{tag}s. But we still
-% have to manually reset \opt{currentcounter} to default because, since we had
-% to manually set \opt{currentcounter} to \texttt{parentequation} in
-% \env{subequations}, we also have to manually set it to \env{equation} in
+% throughout and supposedly sets \cs{@currentcounter} for \cs{tag}s (I'm not
+% sure if it works in all environments, though. Once I tried to remove the
+% explicit \opt{currentcounter} setting and several labels to \cs{tag}s ended
+% up with type \texttt{section}. But I didn't investigate this further). But
+% we still have to manually reset \opt{currentcounter} to default because,
+% since we had to manually set \opt{currentcounter} to \texttt{parentequation}
+% in \env{subequations}, we also have to manually set it to \env{equation} in
% environments which may be used within it. The \env{xxalignat} environment
% is not included, because it is ``starred'' by default (i.e.\ unnumbered),
% and does not display or accepts labels or tags anyway. The \env{-ed}
@@ -8041,6 +8163,18 @@
% doing special handling inside \cs{zcref}, but the feature is very cool, so
% it's worth it.
%
+% Note that this support comes at a little cost. \opt{showonlyrefs} works by
+% setting a special \cs{MT@newlabel} for each label referenced with
+% \cs{eqref}. Now, \cs{eqref} is a specialized reference command, only used
+% to refer to equations, so it sets \cs{MT@newlabel} unconditionally on the
+% first run. \cs{zcref}, on the other hand, is a general purpose reference
+% command, used to reference labels of any type. But we wouldn't want to set
+% \cs{MT@newlabel} indiscriminately for all referenced labels in the document,
+% so we need to test for its type. Alas, the label must exist before its type
+% can be tested, thus we cannot set \cs{MT@newlabel} on the first run, only on
+% the second. In sum, since \cs{eqref} requires 3 runs to work, \cs{zcref}
+% needs 4.
+%
% \begin{macrocode}
\bool_new:N \l_@@_mathtools_loaded_bool
\@@_compat_module:nn { mathtools }