diff options
Diffstat (limited to 'macros/latex/contrib')
-rw-r--r-- | macros/latex/contrib/dccpaper/README.md | 2 | ||||
-rw-r--r-- | macros/latex/contrib/dccpaper/dccpaper.dtx | 24 | ||||
-rw-r--r-- | macros/latex/contrib/dccpaper/dccpaper.pdf | bin | 344973 -> 350338 bytes | |||
-rw-r--r-- | macros/latex/contrib/tutodoc/code/tutodoc-locale-main-french.cfg.sty | 4 | ||||
-rw-r--r-- | macros/latex/contrib/tutodoc/code/tutodoc.sty | 57 | ||||
-rw-r--r-- | macros/latex/contrib/tutodoc/doc/tutodoc-en.pdf | bin | 709681 -> 713562 bytes | |||
-rw-r--r-- | macros/latex/contrib/tutodoc/doc/tutodoc-en.tex | 41 | ||||
-rw-r--r-- | macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdf | bin | 746351 -> 748226 bytes | |||
-rw-r--r-- | macros/latex/contrib/tutodoc/doc/tutodoc-fr.tex | 45 | ||||
-rw-r--r-- | macros/latex/contrib/zref-clever/CHANGELOG.md | 12 | ||||
-rw-r--r-- | macros/latex/contrib/zref-clever/zref-clever-code.pdf | bin | 880835 -> 890025 bytes | |||
-rw-r--r-- | macros/latex/contrib/zref-clever/zref-clever-doc.pdf | bin | 227507 -> 228899 bytes | |||
-rw-r--r-- | macros/latex/contrib/zref-clever/zref-clever-doc.tex | 100 | ||||
-rw-r--r-- | macros/latex/contrib/zref-clever/zref-clever.dtx | 256 |
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 Binary files differindex 3cd33ff6fa..310af05b12 100644 --- a/macros/latex/contrib/dccpaper/dccpaper.pdf +++ b/macros/latex/contrib/dccpaper/dccpaper.pdf 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 Binary files differindex 6124b97c99..84a98f1e35 100644 --- a/macros/latex/contrib/tutodoc/doc/tutodoc-en.pdf +++ b/macros/latex/contrib/tutodoc/doc/tutodoc-en.pdf 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 Binary files differindex a8691e1e8d..d0a970abec 100644 --- a/macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdf +++ b/macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdf 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 Binary files differindex 09b441eeb1..4dc41ff5a8 100644 --- a/macros/latex/contrib/zref-clever/zref-clever-code.pdf +++ b/macros/latex/contrib/zref-clever/zref-clever-code.pdf diff --git a/macros/latex/contrib/zref-clever/zref-clever-doc.pdf b/macros/latex/contrib/zref-clever/zref-clever-doc.pdf Binary files differindex 5594a06fb3..e6c24bc473 100644 --- a/macros/latex/contrib/zref-clever/zref-clever-doc.pdf +++ b/macros/latex/contrib/zref-clever/zref-clever-doc.pdf 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 } |