diff options
| author | Norbert Preining <norbert@preining.info> | 2023-06-15 03:03:06 +0000 |
|---|---|---|
| committer | Norbert Preining <norbert@preining.info> | 2023-06-15 03:03:06 +0000 |
| commit | 9eb6f85105699320d8cbdbb33bcdc88c41ea709a (patch) | |
| tree | 6e85740b17273391cbcf76437e1241588db70329 /macros/latex | |
| parent | 68da45b74eea591538f6378878a0dca04e541bb9 (diff) | |
CTAN sync 202306150303
Diffstat (limited to 'macros/latex')
48 files changed, 1195 insertions, 1024 deletions
diff --git a/macros/latex/contrib/quizztex/README.md b/macros/latex/contrib/quizztex/README.md index e2932aecd6..a155eec3f3 100644 --- a/macros/latex/contrib/quizztex/README.md +++ b/macros/latex/contrib/quizztex/README.md @@ -1,6 +1,6 @@ -QuizzTex is a package to create quizz with 'Who Wants to Be a Millionaire ?' design for example. +QuizzTex is a package to create quizzes with 'Who Wants to Be a Millionaire ?' design for example. ---------------------------------------------------------------------------------------------------------------- -QuizzTex est un package pour présenter des quizz à la manière de 'Qui veut gagner des Millions ?' par exemple. +QuizzTex est un package pour présenter des quizzes à la manière de 'Qui veut gagner des Millions ?' par exemple. ---------------------------------------------------------------------------------------------------------------- Author.......: Cédric Pierquet email........: cpierquet@outlook.fr diff --git a/macros/latex/contrib/quizztex/doc/quizztex-doc-fr.pdf b/macros/latex/contrib/quizztex/doc/quizztex-doc-fr.pdf Binary files differindex 0efb41dbda..ba6fe2362c 100644 --- a/macros/latex/contrib/quizztex/doc/quizztex-doc-fr.pdf +++ b/macros/latex/contrib/quizztex/doc/quizztex-doc-fr.pdf diff --git a/macros/latex/contrib/quizztex/doc/quizztex-doc-fr.tex b/macros/latex/contrib/quizztex/doc/quizztex-doc-fr.tex index 4fdbee28ab..07f784376b 100644 --- a/macros/latex/contrib/quizztex/doc/quizztex-doc-fr.tex +++ b/macros/latex/contrib/quizztex/doc/quizztex-doc-fr.tex @@ -4,8 +4,8 @@ \documentclass[french,a4paper,11pt]{article} \usepackage[margin=2cm,includefoot]{geometry} -\def\TPversion{0.1.0} -\def\TPdate{13 juin 2023} +\def\TPversion{0.1.1} +\def\TPdate{14 juin 2023} \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage{amsmath,amssymb} @@ -88,7 +88,7 @@ morekeywords={\QuizzMillions,\QuizzPrendrePlace},% keywordstyle={\color{green!50!black}},% classoffset=3,% - morekeywords={Largeur,Marge,Hauteurs,Couleur,CouleurFond,CouleurLettre,CouleurTexte,Bonne,Mauvaise,Choix,CoulBonne,CoulChoix,CoulMauvaise,Affichage,EspacementV,OffsetV,Decorations,AffChoix,Jokers,AffJokers,CodeAvant,Offset,Theme,Type,Effet},% + morekeywords={Largeur,Marge,Hauteurs,Couleur,CouleurFond,CouleurLettre,CouleurTexte,Bonne,Mauvaise,Choix,CoulBonne,CoulChoix,CoulMauvaise,Affichage,EspacementV,OffsetV,Decorations,AffChoix,Jokers,AffJokers,CodeAvant,Offset,Theme,Type,Effet,PositionJokers,Points},% keywordstyle={\color{orange}} },% #1 @@ -169,16 +169,14 @@ \vspace{1cm} -\hfill\QuizzPrendrePlace[Largeur=13cm,Choix=C,Affichage=Choix] +\hfill\QuizzPrendrePlace[Largeur=13cm,Choix=C,Affichage=Choix,CodeAvant={\large\bfseries\sffamily},Points=3/24] {Quelle partie de l'œuf dois-je cuisiner pour préparer avec succès une mayonnaise ?} {Le violet} {Le bleu} {Le jaune} {Le rouge}\hfill~ - - \vspace{0.5cm} -%\hfill{}\textit{Merci à Denis Bitouzé et à Gilles Le Bourhis pour leurs retours et idées !} +\hfill{}\textit{Merci à Patrick Bideault pour ses retours et conseils !} \smallskip @@ -207,6 +205,10 @@ \section{Historique} +\verb|v0.1.1|~:~~~~Amélioration de la gestion des hauteurs + modification de la clé \Cle{CodeAvant}. + +\verb| |~:~~~~Ajout d'une clé \Cle{PositionJokers}. + \verb|v0.1.0|~:~~~~Version initiale. \newpage @@ -317,6 +319,10 @@ Le code se charge d'ajuster la hauteur des cartouches, et la hauteur des cartouc \smallskip Il est cependant possible de préciser une hauteur manuelle globale, ou une hauteur pour le cartouche \textit{Question} et une hauteur pour les cartouches \textit{Réponses}. + +\smallskip + +\cmaj{0.1.1} Désormais la position par défaut des \textsf{Jokers} est centrée en-dessous des cartouches, mais celle-ci peut être modifiée (on peut également les enlever !). \end{importantblock} \subsection{Couleurs prédéfinies} @@ -324,7 +330,7 @@ Il est cependant possible de préciser une hauteur manuelle globale, ou une haut \begin{tipblock} Les couleurs (HTML) définies et utilisées par le package \packagetex!quizztex! et pour l'environnement \motcletex!\QuizzMillions! sont : -\begin{itemize} +\begin{itemize}[leftmargin=*] \item \verb!\definecolor{ColorFondWWTBAM}{HTML}{5E57A4} ! : \textcolor{ColorFondWWTBAM}{\textsf{\textbf{Fond par défaut}}} \item \verb!\definecolor{ColorBonneWWTBAM}{HTML}{0AC759} ! : \textcolor{ColorBonneWWTBAM}{\textsf{\textbf{Fond de la bonne réponse}}} \item \verb!\definecolor{ColorMauvaiseWWTBAM}{HTML}{F1901C}! : \textcolor{ColorMauvaiseWWTBAM}{\textsf{\textbf{Fond de la mauvaise réponse}}} @@ -346,7 +352,7 @@ L'utilisateur qui souhaite modifier les couleurs devra être attentif à la coor Le premier argument, optionnel et entre \texttt{[...]}, propose les \Cle{clés} suivantes : \begin{itemize} - \item \Cle{Largeur} := largeur (avec unité) sans les Jokers, du Quizz ; \hfill{}défaut : \Cle{14cm} + \item \Cle{Largeur} := largeur (avec unité) totale avec Jokers éventuels, du Quizz ; \hfill{}défaut : \Cle{14cm} \item \Cle{Marge} := marge gauche/droite (avec unité) ; \hfill{}défaut : \Cle{0.5cm} \item \Cle{Hauteurs} := hauteurs des cartouches (\motcletex!auto! ou \motcletex!global! ou \motcletex!Quest/Réponses!) ; @@ -368,7 +374,10 @@ Le premier argument, optionnel et entre \texttt{[...]}, propose les \Cle{clés} \item \Cle{AffChoix} := réponses à afficher (pour le 50/50 par exemple) ; \hfill{}défaut \Cle{ABCD} \item \Cle{Jokers} := booléen pour afficher les Jokers ; \hfill{}défaut \Cle{true} \item \Cle{AffJokers} : = Jokers à marquer comme disponibles ; \hfill{}défaut \Cle{50.TEL.PUB} - \item \Cle{CodeAvant} : = code à appliqer à tous les cartouches ; \hfill{}défaut \Cle{\textbackslash bfseries\textbackslash large\textbackslash sffamily} + \item \cmaj{0.1.1} \Cle{PositionJokers} : = position, parmi \motcletex!gauche/centre/droite!, pour les Jokers ; + + \hfill{}défaut \Cle{centre} + \item \cmaj{0.1.1} \Cle{CodeAvant} : = code à appliquer à tous les cartouches ; \hfill{}défaut \Cle{} \item \Cle{Effet} := booléen pour utiliser un petit effet de dégradé.\hfill{}défaut \Cle{true} \end{itemize} \vspace*{-\baselineskip}\leavevmode @@ -389,8 +398,8 @@ Les cinq arguments obligatoires correspondent à la question et aux réponses, s \end{DemoCode} \begin{DemoCode}[] -%hauteurs manuelles -\QuizzMillions[Hauteurs=2cm/1.5cm] +%hauteurs manuelles, police modifiée, Jokers à droite +\QuizzMillions[Hauteurs=2cm/1.5cm,CodeAvant=\large\bfseries\sffamily, PositionJokers=droite] {Quelle partie de l'\oe{}uf dois-je cuisiner pour préparer avec succès une mayonnaise ?} {Le violet} {Le bleu} {Le jaune} {Le rouge} @@ -429,8 +438,8 @@ Les cinq arguments obligatoires correspondent à la question et aux réponses, s \end{DemoCode} \begin{DemoCode}[] -%avec jokers déjà utlisés et 50:50 -\QuizzMillions[AffJokers=PUB.TEL,AffChoix=AC] +%avec Jokers (à gauche) déjà utlisés et 50:50 +\QuizzMillions[AffJokers=PUB.TEL,AffChoix=AC,PositionJokers=gauche] {Quelle partie de l'\oe{}uf dois-je cuisiner pour préparer avec succès une mayonnaise ?} {Le violet} {Le bleu} {Le jaune} {Le rouge} @@ -438,7 +447,7 @@ Les cinq arguments obligatoires correspondent à la question et aux réponses, s \begin{DemoCode}[] %avec couleurs modifiées et police modifiée -\QuizzMillions[Couleur=black,CouleurFond=gray,CodeAvant={\LARGE\ttfamily}] +\QuizzMillions[Couleur=black,CouleurFond=gray,CodeAvant={\LARGE\ttfamily}, AffJokers={}] {On considère la fonction $\mathtt{f}$ définie sur $\mathbb{R}$ par $\mathtt{f(x)=2\,\text{e}^{2x}}$. On a :} {$\mathtt{f'(x)=4\,\text{e}^{2x}}$} {$\mathtt{f'(x)=2\,\text{e}^{2x}}$} @@ -490,6 +499,10 @@ Le code se charge d'ajuster la hauteur des cartouches, et la hauteur des cartouc \smallskip Il est cependant possible de préciser une hauteur manuelle globale, ou une hauteur pour le cartouche \textit{Question} et une hauteur pour les cartouches \textit{Réponses}. + +\smallskip + +La police pour le thème et le score est fixée (large/gras/sans serif). \end{importantblock} \subsection{Couleurs prédéfinies} @@ -497,7 +510,7 @@ Il est cependant possible de préciser une hauteur manuelle globale, ou une haut \begin{tipblock} Les couleurs (HTML) définies et utilisées par le package \packagetex!quizztex! et pour l'environnement \motcletex!\QuizzMillions! sont : -\begin{itemize} +\begin{itemize}[leftmargin=*] \item \verb!definecolor{ColorFondTLMVPSP}{HTML}{4E52E3} ! : \textcolor{ColorFondTLMVPSP}{\textsf{\textbf{Fond par défaut}}} \item \verb!\definecolor{ColorBonneTLMVPSP}{HTML}{00E519} ! : \textcolor{ColorBonneTLMVPSP}{\textsf{\textbf{Fond de la bonne réponse}}} \item \verb!\definecolor{ColorMauvaiseTLMVPSP}{HTML}{FF9F3F}! : \textcolor{ColorMauvaiseTLMVPSP}{\textsf{\textbf{Fond de la mauvaise réponse}}} @@ -539,9 +552,12 @@ Le premier argument, optionnel et entre \texttt{[...]}, propose les \Cle{clés} \item \Cle{Affichage} := type d'affichage, parmi \motcletex!Choix/Sol/PropSol! ; \hfill{}défaut \Cle{} \item \Cle{EspacementV} := espacement vertical entre les cartouches ; \hfill{}défaut \Cle{8pt} %\item \Cle{OffsetV} := =6pt,% + \item \cmaj{0.1.1} \Cle{Points} := points dans le cartouche (si non vide) sous la forme \motcletex!haut/bas! ; + + \hfill{}défaut \Cle{} \item \Cle{Theme} := pour afficher un cartouche \textsf{Thème} sous le Quizz ; \hfill{}défaut \Cle{} \item \Cle{Type} = type de réponse, parmi \motcletex!Duo/Carre/Cash! ; \hfill{}défaut \Cle{Carre} - \item \Cle{CodeAvant} : = code à appliqer à tous les cartouches ; \hfill{}défaut \Cle{\textbackslash bfseries\textbackslash large\textbackslash sffamily} + \item \cmaj{0.1.1} \Cle{CodeAvant} : = code à appliquer à tous les cartouches ; \hfill{}défaut \Cle{} \item \Cle{Effet} := booléen pour utiliser un petit effet de dégradé.\hfill{}défaut \Cle{true} \end{itemize} \vspace*{-\baselineskip}\leavevmode @@ -562,8 +578,8 @@ Les cinq arguments obligatoires correspondent à la question et aux réponses, s \end{DemoCode} \begin{DemoCode}[] -%hauteurs manuelles, avec thème -\QuizzPrendrePlace[Hauteurs=2cm/1.5cm,Theme={Cuisine}] +%hauteurs manuelles, avec thème et police modifiée +\QuizzPrendrePlace[Hauteurs=2cm/1.5cm,Theme={Cuisine}, CodeAvant=\large\bfseries\sffamily] {Quelle partie de l'\oe{}uf dois-je cuisiner pour préparer avec succès une mayonnaise ?} {Le violet} {Le bleu} {Le jaune} {Le rouge} @@ -602,8 +618,8 @@ Les cinq arguments obligatoires correspondent à la question et aux réponses, s \end{DemoCode} \begin{DemoCode}[] -%avec couleurs modifiées et police modifiée -\QuizzPrendrePlace[Couleur=black,CouleurFond=gray,CodeAvant={\LARGE\ttfamily}, Theme={Cuisine}] +%avec couleurs modifiées et police modifiée et points +\QuizzPrendrePlace[Couleur=black,CouleurFond=gray,CodeAvant={\LARGE\ttfamily}, Theme={Cuisine},Points=12/26] {On considère la fonction $\mathtt{f}$ définie sur $\mathbb{R}$ par $\mathtt{f(x)=2\,\text{e}^{2x}}$. On a :} {$\mathtt{f'(x)=4\,\text{e}^{2x}}$} {$\mathtt{f'(x)=2\,\text{e}^{2x}}$} diff --git a/macros/latex/contrib/quizztex/tex/quizztex.sty b/macros/latex/contrib/quizztex/tex/quizztex.sty index e6079c5cf8..e5e42b9454 100644 --- a/macros/latex/contrib/quizztex/tex/quizztex.sty +++ b/macros/latex/contrib/quizztex/tex/quizztex.sty @@ -4,7 +4,8 @@ % : 'Tout le monde veut prendre sa place' is a Tradematk from Air Productions. \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{quizztex}[2023/06/13 0.1.0 Construire des quizz 'comme dans les jeux' ] +\ProvidesPackage{quizztex}[2023/06/14 0.1.1 Construire des quizz 'comme dans les jeux' ] +%0.1.1 Amélioration de la gestion des réponses dans WWTBAM + Position des Jokers (cc P. Bideault ;-)) %0.1.0 Version initiale %------Packages utiles @@ -87,7 +88,8 @@ OffsetV=\setlength{\OffsetVwwtbam}{#1},% AffChoix=\def\AffChoixWWTBAM{#1},% AffJokers=\def\AffJokersWWTBAM{#1},% - CodeAvant=\def\CodeAvantWWTBAM{#1} + CodeAvant=\def\CodeAvantWWTBAM{#1},% + PositionJokers=\def\PosJokersWWTBAM{#1} } \setKVdefault[wwtbam]{% @@ -111,8 +113,14 @@ AffChoix=ABCD,% Jokers=true,% AffJokers=50.TEL.PUB,% - CodeAvant=\bfseries\large\sffamily,% - Effet=true + %CodeAvant=\bfseries\large\sffamily,% + CodeAvant={},% + Effet=true,% + PositionJokers=centre +} + +\NewDocumentCommand\LettreChoixMillions{ m }{% + \textcolor{\CouleurLettreWWTBAM}{\large\sffamily\bfseries{\vphantom{Q}#1}\,:}% } \NewDocumentCommand\QuizzMillions{ O{} m m m m m }{%clés + questions + 4 réponses @@ -186,7 +194,14 @@ %dimensions de base \ifboolKV[wwtbam]{Jokers} {% - \setlength{\largeurwwtbam}{\largeurwwtbam-1.4cm}% + \IfStrEq{\PosJokersWWTBAM}{droite}% + {% + \addtolength{\largeurwwtbam}{-1.4cm}% + }{}% + \IfStrEq{\PosJokersWWTBAM}{gauche}% + {% + \addtolength{\largeurwwtbam}{-1.4cm}% + }{}% }% {}% \setlength{\largeurboitequestionwwtbam}{\largeurwwtbam-2\margeexterieurewwtbam-15mm}% @@ -199,13 +214,13 @@ %BlocQuestion \sbox{\boitequestionwwtbam}{\parbox{\the\texteboitequestionwwtbam}{\centering\CodeAvantWWTBAM #2}}\settoboxtotalheight{\hauteurboitequestionwwtbam}{\boitequestionwwtbam}% %BlocRépA - \sbox{\boitereponseawwtbam}{\parbox{\the\texteboitereponsewwtbam}{\CodeAvantWWTBAM #3}}\settoboxtotalheight{\hauteurboitereponseawwtbam}{\boitereponseawwtbam}% + \sbox{\boitereponseawwtbam}{\parbox{\the\texteboitereponsewwtbam}{\LettreChoixMillions{A} \CodeAvantWWTBAM #3}}\settoboxtotalheight{\hauteurboitereponseawwtbam}{\boitereponseawwtbam}% %BlocRépB - \sbox{\boitereponsebwwtbam}{\parbox{\the\texteboitereponsewwtbam}{\CodeAvantWWTBAM #4}}\settoboxtotalheight{\hauteurboitereponsebwwtbam}{\boitereponsebwwtbam}% + \sbox{\boitereponsebwwtbam}{\parbox{\the\texteboitereponsewwtbam}{\LettreChoixMillions{B} \CodeAvantWWTBAM #4}}\settoboxtotalheight{\hauteurboitereponsebwwtbam}{\boitereponsebwwtbam}% %BlocRépC - \sbox{\boitereponsecwwtbam}{\parbox{\the\texteboitereponsewwtbam}{\CodeAvantWWTBAM #5}}\settoboxtotalheight{\hauteurboitereponsecwwtbam}{\boitereponsecwwtbam}% + \sbox{\boitereponsecwwtbam}{\parbox{\the\texteboitereponsewwtbam}{\LettreChoixMillions{C} \CodeAvantWWTBAM #5}}\settoboxtotalheight{\hauteurboitereponsecwwtbam}{\boitereponsecwwtbam}% %BlocRépD - \sbox{\boitereponsedwwtbam}{\parbox{\the\texteboitereponsewwtbam}{\CodeAvantWWTBAM #6}}\settoboxtotalheight{\hauteurboitereponsedwwtbam}{\boitereponsedwwtbam}% + \sbox{\boitereponsedwwtbam}{\parbox{\the\texteboitereponsewwtbam}{\LettreChoixMillions{D} \CodeAvantWWTBAM #6}}\settoboxtotalheight{\hauteurboitereponsedwwtbam}{\boitereponsedwwtbam}% %hauteurréponses \pgfmathsetlength{\hauteurmaxboitereponsewwtbam}{max(\hauteurboitereponseawwtbam,\hauteurboitereponsebwwtbam,\hauteurboitereponsecwwtbam,\hauteurboitereponsedwwtbam)}% %hauteur des boîtes @@ -216,9 +231,22 @@ \setlength{\niveauABwwtbam}{0.5\HauteurQuest+0.5\HauteurReponse+\EspacementVwwtbam}% %Hrepcd \setlength{\niveauCDwwtbam}{0.5\HauteurQuest+1.5\HauteurReponse+2\EspacementVwwtbam}% - %Hjoker - \setlength{\HauteurNivJok}{0.5\niveauABwwtbam+0.5\niveauCDwwtbam}% - %hauteurquestion + %niveaujoker milieu + \IfStrEq{\PosJokersWWTBAM}{centre}% + {% + \setlength{\HauteurNivJok}{\niveauCDwwtbam+0.5\HauteurReponse+0.5\EspacementVwwtbam+0.35cm}% + }% + {}% + \IfStrEq{\PosJokersWWTBAM}{droite}% + {% + \setlength{\HauteurNivJok}{0.5\niveauABwwtbam+0.5\niveauCDwwtbam}% + }% + {}% + \IfStrEq{\PosJokersWWTBAM}{gauche}% + {% + \setlength{\HauteurNivJok}{0.5\niveauABwwtbam+0.5\niveauCDwwtbam}% + }% + {}% }% {% \IfSubStr{\HauteursWWTBAM}{/}% @@ -230,8 +258,21 @@ \setlength{\niveauABwwtbam}{0.5\HauteurQuest+0.5\HauteurReponse+\EspacementVwwtbam}% %Hrepcd \setlength{\niveauCDwwtbam}{0.5\HauteurQuest+1.5\HauteurReponse+2\EspacementVwwtbam}% - %Hjoker - \setlength{\HauteurNivJok}{0.5\niveauABwwtbam+0.5\niveauCDwwtbam}% + \IfStrEq{\PosJokersWWTBAM}{centre}% + {% + \setlength{\HauteurNivJok}{\niveauCDwwtbam+0.5\HauteurReponse+0.5\EspacementVwwtbam+0.35cm}% + }% + {}% + \IfStrEq{\PosJokersWWTBAM}{droite}% + {% + \setlength{\HauteurNivJok}{0.5\niveauABwwtbam+0.5\niveauCDwwtbam}% + }% + {}% + \IfStrEq{\PosJokersWWTBAM}{gauche}% + {% + \setlength{\HauteurNivJok}{0.5\niveauABwwtbam+0.5\niveauCDwwtbam}% + }% + {}% }% \begin{tikzpicture} %styles @@ -244,6 +285,29 @@ \coordinate (CartoucheReponseB) at ({0.9cm},{-(\the\niveauABwwtbam)}) ;% \coordinate (CartoucheReponseC) at ({-0.5*\the\largeurwwtbam+\the\margeexterieurewwtbam+0.9cm},{-(\the\niveauCDwwtbam)}) ;% \coordinate (CartoucheReponseD) at ({0.9cm},{-(\the\niveauCDwwtbam)}) ; + \IfStrEq{\PosJokersWWTBAM}{centre}% + {% + \coordinate (CartoucheJokerTEL) at ({0},{-(\the\HauteurNivJok)}) ; + \coordinate (CartoucheJokerCC) at ({-1.15cm},{-(\the\HauteurNivJok)}) ; + \coordinate (CartoucheJokerPUB) at ({1.15cm},{-(\the\HauteurNivJok)}) ; + }% + {}% + \IfStrEq{\PosJokersWWTBAM}{droite}% + {% + \coordinate (CartoucheJokerTEL) at ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)}) ; + \coordinate (CartoucheJokerCC) at ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)+0.55cm}) ; + \coordinate (CartoucheJokerPUB) at ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)-0.55cm}) ; + + }% + {}% + \IfStrEq{\PosJokersWWTBAM}{gauche}% + {% + \coordinate (CartoucheJokerTEL) at ({-0.5*(\the\largeurwwtbam)-0.75cm},{-(\the\HauteurNivJok)}) ; + \coordinate (CartoucheJokerCC) at ({-0.5*(\the\largeurwwtbam)-0.75cm},{-(\the\HauteurNivJok)+0.55cm}) ; + \coordinate (CartoucheJokerPUB) at ({-0.5*(\the\largeurwwtbam)-0.75cm},{-(\the\HauteurNivJok)-0.55cm}) ; + + }% + {}% %test % \draw[red,fill=yellow] (CartoucheQuestion) circle[radius=2pt] node {question} ; % \draw[red,fill=yellow] (CartoucheReponseA) circle[radius=2pt] node {A} ; @@ -296,7 +360,7 @@ %labels réponses \IfSubStr{\AffChoixWWTBAM}{A} {% - \draw (CartoucheReponseA) node[StyleCourtoucheReponse] {\raisebox{-0.05em}{\textcolor{\CouleurLettreWWTBAM}{\large\sffamily\bfseries\vphantom{Q}A\,:}} {\CodeAvantWWTBAM #3}} ;% + \draw (CartoucheReponseA) node[StyleCourtoucheReponse] {\LettreChoixMillions{A} \CodeAvantWWTBAM #3} ;% \ifboolKV[wwtbam]{Decorations}% {% \node[StyleDecoration] at ($(CartoucheReponseA)+(-0.25,0)$) {} ;% @@ -306,7 +370,7 @@ {}% \IfSubStr{\AffChoixWWTBAM}{B} {% - \draw (CartoucheReponseB) node[StyleCourtoucheReponse] {\raisebox{-0.05em}{\textcolor{\CouleurLettreWWTBAM}{\large\sffamily\bfseries\vphantom{Q}B\,:}} {\CodeAvantWWTBAM #4}} ; + \draw (CartoucheReponseB) node[StyleCourtoucheReponse] {\LettreChoixMillions{B} \CodeAvantWWTBAM #4} ; \ifboolKV[wwtbam]{Decorations} {% \node[StyleDecoration] at ($(CartoucheReponseB)+(-0.25,0)$) {} ; @@ -316,7 +380,7 @@ {}% \IfSubStr{\AffChoixWWTBAM}{C} {% - \draw (CartoucheReponseC) node[StyleCourtoucheReponse] {\raisebox{-0.05em}{\textcolor{\CouleurLettreWWTBAM}{\large\sffamily\bfseries\vphantom{Q}C\,:}} {\CodeAvantWWTBAM #5}} ; + \draw (CartoucheReponseC) node[StyleCourtoucheReponse] {\LettreChoixMillions{C} \CodeAvantWWTBAM #5} ; \ifboolKV[wwtbam]{Decorations} {% \node[StyleDecoration] at ($(CartoucheReponseC)+(-0.25,0)$) {} ; @@ -326,7 +390,7 @@ {}% \IfSubStr{\AffChoixWWTBAM}{D} {% - \draw (CartoucheReponseD) node[StyleCourtoucheReponse] {\raisebox{-0.05em}{\textcolor{\CouleurLettreWWTBAM}{\large\sffamily\bfseries\vphantom{Q}D\,:}} {\CodeAvantWWTBAM #6}} ; + \draw (CartoucheReponseD) node[StyleCourtoucheReponse] {\LettreChoixMillions{D} \CodeAvantWWTBAM #6} ; \ifboolKV[wwtbam]{Decorations} {% \node[StyleDecoration] at ($(CartoucheReponseD)+(-0.25,0)$) {} ; @@ -340,55 +404,55 @@ %50/50 \ifboolKV[wwtbam]{Effet} {% - \filldraw[draw=\CouleurWWTBAM,thick,shading=axis,left color=\CouleurFondWWTBAM!90!black,right color=\CouleurFondWWTBAM!75,shading angle=45] ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)+0.55cm}) ellipse (0.65cm and 0.35cm) ; + \filldraw[draw=\CouleurWWTBAM,thick,shading=axis,left color=\CouleurFondWWTBAM!90!black,right color=\CouleurFondWWTBAM!75,shading angle=45] (CartoucheJokerCC) ellipse (0.65cm and 0.35cm) ; }% {% - \draw[\CouleurWWTBAM,thick,fill=\CouleurFondDWWTBAM] ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)+0.55cm}) ellipse (0.65cm and 0.35cm) ; + \draw[\CouleurWWTBAM,thick,fill=\CouleurFondDWWTBAM] (CartoucheJokerCC) ellipse (0.65cm and 0.35cm) ; }% \begin{scope} - \clip ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)+0.55cm}) ellipse (0.65cm and 0.35cm) ; - \draw ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)+0.55cm}) node[font=\bfseries\sffamily,\CouleurTexteWWTBAM] {50:50} ; + \clip (CartoucheJokerCC) ellipse (0.65cm and 0.35cm) ; + \draw (CartoucheJokerCC) node[font=\bfseries\sffamily,\CouleurTexteWWTBAM] {50:50} ; \IfSubStr{\AffJokersWWTBAM}{50}% {}% {% - \draw[ultra thick,red] ($({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)+0.55cm})+(-0.65,0.35)$)--++(1.3,-0.7) ; - \draw[ultra thick,red] ($({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)+0.55cm})+(-0.65,-0.35)$)--++(1.3,0.7) ; + \draw[ultra thick,red] ($(CartoucheJokerCC)+(-0.65,0.35)$)--++(1.3,-0.7) ; + \draw[ultra thick,red] ($(CartoucheJokerCC)+(-0.65,-0.35)$)--++(1.3,0.7) ; }% \end{scope} %appel \ifboolKV[wwtbam]{Effet} {% - \filldraw[draw=\CouleurWWTBAM,thick,shading=axis,left color=\CouleurFondWWTBAM!90!black,right color=\CouleurFondWWTBAM!75,shading angle=45] ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)}) ellipse (0.65cm and 0.35cm) ; + \filldraw[draw=\CouleurWWTBAM,thick,shading=axis,left color=\CouleurFondWWTBAM!90!black,right color=\CouleurFondWWTBAM!75,shading angle=45] (CartoucheJokerTEL) ellipse (0.65cm and 0.35cm) ; }% {% - \draw[\CouleurWWTBAM,thick,fill=\CouleurFondDWWTBAM] ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)}) ellipse (0.65cm and 0.35cm) ; + \draw[\CouleurWWTBAM,thick,fill=\CouleurFondDWWTBAM] (CartoucheJokerTEL) ellipse (0.65cm and 0.35cm) ; }% \begin{scope} - \clip ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)}) ellipse (0.65cm and 0.35cm) ; - \draw ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)}) node[\CouleurTexteWWTBAM] {\faPhone} ; + \clip (CartoucheJokerTEL) ellipse (0.65cm and 0.35cm) ; + \draw (CartoucheJokerTEL) node[\CouleurTexteWWTBAM] {\faPhone} ; \IfSubStr{\AffJokersWWTBAM}{TEL}% {}% {% - \draw[ultra thick,red] ($({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)})+(-0.65,0.35)$)--++(1.3,-0.7) ; - \draw[ultra thick,red] ($({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)})+(-0.65,-0.35)$)--++(1.3,0.7) ; + \draw[ultra thick,red] ($(CartoucheJokerTEL)+(-0.65,0.35)$)--++(1.3,-0.7) ; + \draw[ultra thick,red] ($(CartoucheJokerTEL)+(-0.65,-0.35)$)--++(1.3,0.7) ; }% \end{scope} %public \ifboolKV[wwtbam]{Effet} {% - \filldraw[draw=\CouleurWWTBAM,thick,shading=axis,left color=\CouleurFondWWTBAM!90!black,right color=\CouleurFondWWTBAM!75,shading angle=45] ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)-0.55cm}) ellipse (0.65cm and 0.35cm) ; + \filldraw[draw=\CouleurWWTBAM,thick,shading=axis,left color=\CouleurFondWWTBAM!90!black,right color=\CouleurFondWWTBAM!75,shading angle=45] (CartoucheJokerPUB) ellipse (0.65cm and 0.35cm) ; }% {% - \draw[\CouleurWWTBAM,thick,fill=\CouleurFondDWWTBAM] ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)-0.55cm}) ellipse (0.65cm and 0.35cm) ; + \draw[\CouleurWWTBAM,thick,fill=\CouleurFondDWWTBAM] (CartoucheJokerPUB) ellipse (0.65cm and 0.35cm) ; }% \begin{scope} - \clip ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)-0.55cm}) ellipse (0.65cm and 0.35cm) ; - \draw ({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)-0.55cm}) node[\CouleurTexteWWTBAM] {\faDiagnoses\!\!\raisebox{-0.2em}{\faDiagnoses}\!\!\faDiagnoses} ; + \clip (CartoucheJokerPUB) ellipse (0.65cm and 0.35cm) ; + \draw (CartoucheJokerPUB) node[\CouleurTexteWWTBAM] {\faDiagnoses\!\!\raisebox{-0.2em}{\faDiagnoses}\!\!\faDiagnoses} ; \IfSubStr{\AffJokersWWTBAM}{PUB}% {}% {% - \draw[ultra thick,red] ($({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)-0.55cm})+(-0.65,0.35)$)--++(1.3,-0.7) ; - \draw[ultra thick,red] ($({0.5*(\the\largeurwwtbam)+0.75cm},{-(\the\HauteurNivJok)-0.55cm})+(-0.65,-0.35)$)--++(1.3,0.7) ; + \draw[ultra thick,red] ($(CartoucheJokerPUB)+(-0.65,0.35)$)--++(1.3,-0.7) ; + \draw[ultra thick,red] ($(CartoucheJokerPUB)+(-0.65,-0.35)$)--++(1.3,0.7) ; }% \end{scope} }% @@ -466,7 +530,9 @@ Offset=\setlength{\OffsetVtlmvpsp}{#1},% CodeAvant=\def\CodeAvantTLMVPSP{#1},% Theme=\def\ThemeTLMVPSP{#1},% - Type=\def\TypeTLMVPSP{#1} + Type=\def\TypeTLMVPSP{#1},% + Points=\def\PointsTLMVPSP{#1},% + EchellePoints=\def\EchellePointsTLMVPSP{#1} } \setKVdefault[TLMVPSP]{% @@ -486,11 +552,13 @@ Cadre=false,% EspacementV=8pt,% Offset=6pt,% - CodeAvant=\bfseries,% + %CodeAvant=\bfseries\large\sffamily,% + CodeAvant={},% Theme={},% Type=Carre,% Effet=true,% - CodeAvant=\bfseries\large\sffamily + Points={},% + EchellePoints=1 } \NewDocumentCommand\QuizzPrendrePlace{ O{} m m m m m }{%clés + questions + 4 réponses @@ -726,8 +794,14 @@ {% \draw[rounded corners=3.5pt,thick,\CouleurTLMVPSP,opacity=0.25] ($({-0.5*(\the\LargeurTheme)},{(-0.5*(\the\HauteurTheme)-\the\HauteurNivTheme)})+(-1.25pt,-1.25pt)$) rectangle++ ($({\the\LargeurTheme},{\the\HauteurTheme})+(2.5pt,2.5pt)$) ; \draw[rounded corners=2pt,\CouleurTLMVPSP,thick,fill=white] ({-0.5*(\the\LargeurTheme)},{(-0.5*(\the\HauteurTheme)-\the\HauteurNivTheme)}) rectangle++ ({\the\LargeurTheme},{\the\HauteurTheme}) ; - \draw (0,{-\the\HauteurNivTheme}) node[text=\CouleurTLMVPSP] {\CodeAvantTLMVPSP\ThemeTLMVPSP} ; + \draw (0,{-\the\HauteurNivTheme}) node[text=\CouleurTLMVPSP,font=\bfseries\large\sffamily] {\ThemeTLMVPSP} ; }% + \IfSubStr{\PointsTLMVPSP}{/}% + {% + \StrCut{\PointsTLMVPSP}{/}{\PtsChallenger}{\PtsChampion}% + \draw ({-0.275*(\the\margemilieulmvpsp)},{\the\niveauCDtlmvpsp-0.5*(\the\HauteurReponse)+\the\margemilieulmvpsp-1pt}) node[inner sep=0pt,below right=2pt,text=\CouleurTexteTLMVPSP,font=\bfseries\large\sffamily,scale=\EchellePointsTLMVPSP] {\PtsChallenger} ; + \draw ({0.275*(\the\margemilieulmvpsp)},{\the\niveauCDtlmvpsp-0.5*(\the\HauteurReponse)+1pt}) node[inner sep=0pt,above left=2pt,text=\CouleurTexteTLMVPSP,font=\bfseries\large\sffamily,scale=\EchellePointsTLMVPSP] {\PtsChampion} ; + }{}% \end{tikzpicture}% } diff --git a/macros/latex/contrib/runcode/README b/macros/latex/contrib/runcode/README index 4b75754042..010d8f4484 100644 --- a/macros/latex/contrib/runcode/README +++ b/macros/latex/contrib/runcode/README @@ -1,4 +1,4 @@ -LaTeX Package: runcode 2023/01/18 v1.8 +LaTeX Package: runcode 2023/06/13 v1.9 ---------------------------------------- The runcode package enables the execution of source code (e.g., R, Julia, Matlab, shell, Python, etc.) and embed the results in the pdf file diff --git a/macros/latex/contrib/runcode/runcode.pdf b/macros/latex/contrib/runcode/runcode.pdf Binary files differindex 405f5a26fd..0a84593cf2 100644 --- a/macros/latex/contrib/runcode/runcode.pdf +++ b/macros/latex/contrib/runcode/runcode.pdf diff --git a/macros/latex/contrib/runcode/runcode.sty b/macros/latex/contrib/runcode/runcode.sty index ae859085b4..21e85f9908 100644 --- a/macros/latex/contrib/runcode/runcode.sty +++ b/macros/latex/contrib/runcode/runcode.sty @@ -4,7 +4,7 @@ % % This package is based on an ongoing work by Haim Bar and HaiYing Wang, and comments and questions are welcome! -\ProvidesPackage{runcode}[2023/01/18 runcode v1.8] +\ProvidesPackage{runcode}[2023/06/13 runcode v1.9] \newif\ifruncode % Change to \runcodefalse if you want to suspend code execution @@ -313,13 +313,17 @@ % \inln{Arg #1}{Arg #2}[Arg #3] is used to execute short source code % and embed resulting output. % Arg #1 is the executable program; -% Arg #2 is the source code -% Arg #3 is the type output (if skipped or with empty value the default type is +% Arg #2 is the source code; +% Arg #3 is the output file name (optional); +% Arg #4 is the type output (if skipped or with empty value the default type is % inline; vbox = verbatim in a box); -\NewDocumentCommand{\inln}{m m O{inline}}{\- - \stepcounter{codeOutput}\unskip - \unskip\setvalue{\tmpname}{\generated/\jobname_inln\thecodeOutput}\unskip\unskip\unskip +\NewDocumentCommand{\inln}{m m O{} O{inline}}{\- + \unskip + \ifthenelse{\isempty{#3}} + {\stepcounter{codeOutput}\unskip\unskip\setvalue{\tmpname}{\generated/\jobname_inln\thecodeOutput}\unskip\unskip\unskip} + {\unskip\setvalue{\tmpname}{\generated/#3}\unskip\unskip\unskip} + \unskip\unskip\unskip \ifruncode % cache mode - don't try to run the code, just get the previous results \IfBeginWith{#2}{```}{\ifruncode\immediate\write18{#1 > \tmpname.tex}\unskip\fi} {\newwrite\tempfile @@ -332,7 +336,7 @@ \fi % end cache mode \IfFileExists{\tmpname.tex} {\checkZeroBytes{\tmpname.tex}\unskip - \ifstrequal{#3}{vbox} + \ifstrequal{#4}{vbox} {\begin{tcolorbox} \ifminted\unskip \inputminted{text}{\tmpname.tex}\unskip @@ -354,7 +358,7 @@ {\runExtCode{#1}{#2}{#3}[#4]} } -\NewDocumentCommand{\inlnR}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","R","\tmpname.txt")'} m O{inline}}{\IfBeginWith{#2}{```}{\inln{python3 -c 'from talk2stat.talk2stat import client;rc0="""#2""";rc0=rc0.lstrip("```").rstrip("```");client("./","R",f"```{rc0}```")'}{#2}[#3]}{\inln{#1}{#2}[#3]}} +\NewDocumentCommand{\inlnR}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","R","\tmpname.txt")'} m O{} O{inline}}{\IfBeginWith{#2}{```}{\inln{python3 -c 'from talk2stat.talk2stat import client;rc0="""#2""";rc0=rc0.lstrip("```").rstrip("```");client("./","R",f"```{rc0}```")'}{#2}[#3][#4]}{\inln{#1}{#2}[#3][#4]}} \NewDocumentCommand{\runJulia}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","julia","#2")'} m m O{}} { @@ -364,7 +368,7 @@ {\runExtCode{#1}{#2}{#3}[#4]} } -\NewDocumentCommand{\inlnJulia}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","julia","\tmpname.txt")'} m O{inline}}{\IfBeginWith{#2}{```}{\inln{python3 -c 'from talk2stat.talk2stat import client;rc0="""#2""";rc0=rc0.lstrip("```").rstrip("```");client("./","julia",f"```{rc0}```")'}{#2}[#3]}{\inln{#1}{#2}[#3]}} +\NewDocumentCommand{\inlnJulia}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","julia","\tmpname.txt")'} m O{} O{inline}}{\IfBeginWith{#2}{```}{\inln{python3 -c 'from talk2stat.talk2stat import client;rc0="""#2""";rc0=rc0.lstrip("```").rstrip("```");client("./","julia",f"```{rc0}```")'}{#2}[#3][#4]}{\inln{#1}{#2}[#3][#4]}} \NewDocumentCommand{\runMatlab}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","matlab","#2")'} m m O{}} { @@ -374,7 +378,7 @@ {\runExtCode{#1}{#2}{#3}[#4]} } -\NewDocumentCommand{\inlnMatlab}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","matlab","\tmpname.txt")'} m O{inline}}{\IfBeginWith{#2}{```}{\inln{python3 -c 'from talk2stat.talk2stat import client;rc0="""#2""";rc0=rc0.lstrip("```").rstrip("```");client("./","matlab",f"```{rc0}```")'}{#2}[#3]}{\inln{#1}{#2}[#3]}} +\NewDocumentCommand{\inlnMatlab}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","matlab","\tmpname.txt")'} m O{} O{inline}}{\IfBeginWith{#2}{```}{\inln{python3 -c 'from talk2stat.talk2stat import client;rc0="""#2""";rc0=rc0.lstrip("```").rstrip("```");client("./","matlab",f"```{rc0}```")'}{#2}[#3][#4]}{\inln{#1}{#2}[#3][#4]}} \NewDocumentCommand{\runPython}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","python","#2")'} m m O{}} @@ -385,7 +389,7 @@ {\runExtCode{#1}{#2}{#3}[#4]} } -\NewDocumentCommand{\inlnPython}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","python","\tmpname.txt")'} m O{inline}}{\IfBeginWith{#2}{```}{\inln{python3 -c 'from talk2stat.talk2stat import client;rc0="""#2""";rc0=rc0.lstrip("```").rstrip("```");client("./","python",f"```{rc0}```")'}{#2}[#3]}{\inln{#1}{#2}[#3]}} +\NewDocumentCommand{\inlnPython}{O{python3 -c 'from talk2stat.talk2stat import client; client("./","python","\tmpname.txt")'} m O{} O{inline}}{\IfBeginWith{#2}{```}{\inln{python3 -c 'from talk2stat.talk2stat import client;rc0="""#2""";rc0=rc0.lstrip("```").rstrip("```");client("./","python",f"```{rc0}```")'}{#2}[#3][#4]}{\inln{#1}{#2}[#3][#4]}} %%%%%%%% diff --git a/macros/latex/contrib/runcode/runcode.tex b/macros/latex/contrib/runcode/runcode.tex index 8751d4234e..04c67fd5a2 100644 --- a/macros/latex/contrib/runcode/runcode.tex +++ b/macros/latex/contrib/runcode/runcode.tex @@ -1,4 +1,4 @@ -% LaTeX Package: runcode 2023/01/18 v1.8 +% LaTeX Package: runcode 2023/06/13 v1.9 % % Copyright (C) 2020-2022 by Haim Bar and HaiYing Wang % @@ -49,7 +49,7 @@ package’s github repository, at \url{https://github.com/Ossifragus/runcode}. \end{abstract} \section{Installation} -\label{sec:org1037dff} +\label{sec:org8c6be84} You can simply put the runcode.sty file in the \LaTeX{} project folder. The server mode requires the @@ -65,9 +65,9 @@ compiling a \LaTeX{} document. \section{Usage} -\label{sec:org325e4fc} +\label{sec:org951dfd0} \subsection{Load the package:} -\label{sec:orgbccebff} +\label{sec:org516e8f6} \begin{minted}[]{latex} \usepackage[options]{runcode} \end{minted} @@ -139,7 +139,7 @@ be customized with \texttt{\textbackslash{}tcbset}, \end{minted} \subsection{Basic commands:} -\label{sec:org88340c8} +\label{sec:org917f9dc} \begin{itemize} \item \texttt{\textbackslash{}runExtCode\{Arg1\}\{Arg2\}\{Arg3\}[Arg4]} runs an external code. @@ -182,14 +182,15 @@ value \texttt{vbox} \end{itemize} \end{itemize} -\item \texttt{\textbackslash{}inln\{Arg1\}\{Arg2\}[Arg3]} is designed for simple calculations; it runs +\item \texttt{\textbackslash{}inln\{Arg1\}\{Arg2\}[Arg3][Arg4]} is designed for simple calculations; it runs one command (or a short batch) and displays the output within the text. \begin{itemize} \item \texttt{Arg1} is the executable program or programming language. \item \texttt{Arg2} is the source code. -\item \texttt{Arg3} is the output type. +\item \texttt{Arg3} is the output file name (optional); +\item \texttt{Arg4} is the output type. \begin{itemize} \item \texttt{inline} (or skipped or with empty value) = embed result in text. \item \texttt{vbox} = verbatim in a box. @@ -198,7 +199,7 @@ text. \end{itemize} \subsection{Language specific shortcuts:} -\label{sec:org591e87e} +\label{sec:org7b04bad} \href{https://julialang.org/}{Julia} \begin{itemize} @@ -211,7 +212,7 @@ text. \item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command \texttt{\textbackslash{}runExtCode}. \end{itemize} -\item \texttt{\textbackslash{}inlnJulia[Arg1]\{Arg2\}[Arg3]} runs \href{https://julialang.org/}{Julia} +\item \texttt{\textbackslash{}inlnJulia[Arg1]\{Arg2\}[Arg3][Arg4]} runs \href{https://julialang.org/}{Julia} source code (\texttt{Arg2}) and displays the output in line. \begin{itemize} \item \texttt{Arg1} is optional and uses the \href{https://julialang.org/}{Julia} @@ -221,7 +222,7 @@ If the \href{https://julialang.org/}{Julia} source code is wrapped between "\texttt{```}" on both sides (as in the markdown grammar), then it will be implemented directly; otherwise the code will be written to a file on the disk and then be called. -\item \texttt{Arg3} has the same effect as that of the basic command \texttt{\textbackslash{}inln}. +\item \texttt{Arg3} and \texttt{Arg4} have the same effects as those of the basic command \texttt{\textbackslash{}inln}. \end{itemize} \end{itemize} @@ -238,7 +239,7 @@ default. \item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command \texttt{\textbackslash{}runExtCode}. \end{itemize} -\item \texttt{\textbackslash{}inlnMatLab[Arg1]\{Arg2\}[Arg3]} runs +\item \texttt{\textbackslash{}inlnMatLab[Arg1]\{Arg2\}[Arg3][Arg4]} runs \href{https://www.mathworks.com/products/matlab.html}{MatLab} source code (\texttt{Arg2}) and displays the output in line. \begin{itemize} @@ -252,7 +253,7 @@ code to run. If the code is wrapped between "```" on both sides (as in the markdown grammar), then it will be implemented directly; otherwise the code will be written to a file on the disk and then be called. -\item \texttt{Arg3} has the same effect as that of the basic command \texttt{\textbackslash{}inln}. +\item \texttt{Arg3} and \texttt{Arg4} have the same effects as those of the basic command \texttt{\textbackslash{}inln}. \end{itemize} \end{itemize} @@ -268,7 +269,7 @@ will be written to a file on the disk and then be called. \item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command \texttt{\textbackslash{}runExtCode}. \end{itemize} -\item \texttt{\textbackslash{}inlnPython[Arg1]\{Arg2\}[Arg3]} runs +\item \texttt{\textbackslash{}inlnPython[Arg1]\{Arg2\}[Arg3][Arg4]} runs \href{https://www.python.org/}{Python} source code (\texttt{Arg2}) and displays the output in line. \begin{itemize} @@ -279,7 +280,7 @@ If the \href{https://www.python.org/}{Python} source code is wrapped between "```" on both sides (as in the markdown grammar), then it will be implemented directly; otherwise the code will be written to a file on the disk and then be called. -\item \texttt{Arg3} has the same effect as that of the basic command \texttt{\textbackslash{}inln}. +\item \texttt{Arg3} and \texttt{Arg4} have the same effects as those of the basic command \texttt{\textbackslash{}inln}. \end{itemize} \item \texttt{\textbackslash{}runPythonBatch[Arg1][Arg2]} runs an external \href{https://www.python.org/}{Python} code file in batch mode (without a @@ -308,7 +309,7 @@ installed via \texttt{pip3 install dill}. \item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command \texttt{\textbackslash{}runExtCode}. \end{itemize} -\item \texttt{\textbackslash{}inlnR[Arg1]\{Arg2\}[Arg3]} runs \href{https://www.r-project.org/}{R} +\item \texttt{\textbackslash{}inlnR[Arg1]\{Arg2\}[Arg3][Arg4]} runs \href{https://www.r-project.org/}{R} source code (\texttt{Arg2}) and displays the output in line. \begin{itemize} \item \texttt{Arg1} is optional and uses the \href{https://www.r-project.org/}{R} @@ -318,14 +319,16 @@ If the \href{https://www.r-project.org/}{R} source code is wrapped between "```" on both sides (as in the markdown grammar), then it will be implemented directly; otherwise the code will be written to a file on the disk and then be called. -\item \texttt{Arg3} has the same effect as that of the basic command \texttt{\textbackslash{}inln}. +\item \texttt{Arg3} and \texttt{Arg4} have the same effects as those of the basic command \texttt{\textbackslash{}inln}. \end{itemize} \end{itemize} \section{Revisions} -\label{sec:orgf884e2e} +\label{sec:orgdd95675} \begin{itemize} +\item v1.9, June 13, 2023: Update \texttt{\textbackslash{}inln} command; the optional \texttt{Arg3} is the output +file name and the optional \texttt{Arg4} is the output type. \item v1.8, January 18, 2023, add support to \href{https://ctan.org/pkg/listings?lang=en}{listings.} \item v1.7, August 20, 2022: changed the tmp/ folder to generated/ in order to conform with CTAN suggestions; renamed the troubleshooting file. @@ -344,7 +347,7 @@ code files, zero bytes in output files.) \end{itemize} \section{Contributing} -\label{sec:org0dce33b} +\label{sec:orge68f2c0} We welcome your contributions to this package by opening issues on GitHub and/or making a pull request. We also appreciate more example documents written using \texttt{runcode}. diff --git a/macros/latex/contrib/tagpdf/README.md b/macros/latex/contrib/tagpdf/README.md index 5b4a1b211f..bb0353de51 100644 --- a/macros/latex/contrib/tagpdf/README.md +++ b/macros/latex/contrib/tagpdf/README.md @@ -1,6 +1,6 @@ #tagpdf — A package to create tagged pdf -Packageversion: 0.98h -Packagedate: 2023/06/06 +Packageversion: 0.98i +Packagedate: 2023/06/14 Author: Ulrike Fischer ## License diff --git a/macros/latex/contrib/tagpdf/tagpdf-backend.dtx b/macros/latex/contrib/tagpdf/tagpdf-backend.dtx index 5b6acbf34f..a9c4763358 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-backend.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf-backend.dtx @@ -47,13 +47,13 @@ % }^^A % } % -% \date{Version 0.98h, released 2023-06-06} +% \date{Version 0.98i, released 2023-06-14} % \maketitle % \begin{implementation} % \begin{macrocode} %<@@=tag> %<*luatex> -\ProvidesExplFile {tagpdf-luatex.def} {2023-06-06} {0.98h} +\ProvidesExplFile {tagpdf-luatex.def} {2023-06-14} {0.98i} {tagpdf~driver~for~luatex} % \end{macrocode} % \section{Loading the lua} @@ -158,8 +158,8 @@ local ProvidesLuaModule = { name = "tagpdf", - version = "0.98h", --TAGVERSION - date = "2023-06-06", --TAGDATE + version = "0.98i", --TAGVERSION + date = "2023-06-14", --TAGDATE description = "tagpdf lua code", license = "The LATEX Project Public License 1.3c" } @@ -890,6 +890,25 @@ end % \end{macrocode} % \end{macro} % +% \begin{macro}{ltx.@@.func.update_mc_attributes} +% This updates the mc-attributes of a box. It should only be used on boxes +% which don't contain structure elements. +% The arguments are a box, the mc-num and the type (as a number) +% \begin{macrocode} +local function @@_update_mc_attributes (head,mcnum,type) + for n in node.traverse(head) do + node.set_attribute(n,mccntattributeid,mcnum) + node.set_attribute(n,mctypeattributeid,type) + if n.id == HLIST or n.id == VLIST then + @@_update_mc_attributes (n.list,mcnum,type) + end + end + return head +end +ltx.@@.func.update_mc_attributes = @@_update_mc_attributes +% \end{macrocode} +% \end{macro} +% % \begin{macro}{ltx.@@.func.mark_page_elements} % This is the main traversing function. See the lua comment for more details. % \begin{macrocode} diff --git a/macros/latex/contrib/tagpdf/tagpdf-checks.dtx b/macros/latex/contrib/tagpdf/tagpdf-checks.dtx index 39b786ee41..81fd2c8d95 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-checks.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf-checks.dtx @@ -48,7 +48,7 @@ % }^^A % } % -% \date{Version 0.98h, released 2023-06-06} +% \date{Version 0.98i, released 2023-06-14} % \maketitle % \begin{documentation} % \section{Commands} @@ -66,6 +66,18 @@ % are |mc_tag|, |struct_tag|, |struct_id| and |struct_num|. % \end{function} % +% \begin{function}[pTF,EXP]{\tag_if_box_tagged:N} +% \begin{syntax} +% \cs{tag_if_box_tagged:N}\Arg{box} +% \end{syntax} +% This tests if a box contains tagging commands. +% It relies currently on that the code that saved the box correctly set +% the command \verb+\l_tag_box_\int_use:N #1_tl+ to a positive value. +% The LaTeX commands will do that automatically +% at some time but it is in the responsability of the user to +% ensure that when using low-level code. +% If the internal command doesn't exist the box is assumed to be tagged. +% \end{function} % \section{Description of log messages} % \subsection{\cs{ShowTagging} command} % \begin{tabular}{lll} @@ -300,7 +312,7 @@ % \begin{macrocode} %<@@=tag> %<*header> -\ProvidesExplPackage {tagpdf-checks-code} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-checks-code} {2023-06-14} {0.98i} {part of tagpdf - code related to checks, conditionals, debugging and messages} %</header> % \end{macrocode} @@ -529,7 +541,7 @@ % % \section{User conditionals} % \begin{macro}[pTF]{\tag_if_active:} -% This is a test it tagging is active. This allows packages +% This tests if tagging is active. This allows packages % to add conditional code. % The test is true if all booleans, the global and the two local one are true. % @@ -556,6 +568,34 @@ \prg_return_false: } } +%</package> +% \end{macrocode} +% \end{macro} +% +% \begin{macro}[pTF]{\tag_if_box_tagged:N} +% This tests if a box contains tagging commands. +% It relies on that the code that saved the box correctly set +% \verb+\l_tag_box_<box number>_tl+ to a positive value. +% The LaTeX commands will do that automatically +% at some time but it is in the responsability of the user to +% ensure that when using low-level code. +% If the internal command doesn't exist the box is assumed to be tagged. +% \begin{macrocode} +%<*base> +\prg_new_conditional:Npnn \tag_if_box_tagged:N #1 {p,T,F,TF} + { + \tl_if_exist:cTF {l_tag_box_\int_use:N #1_tl} + { + \int_compare:nNnTF {\tl_use:c{l_tag_box_\int_use:N #1_tl}}>{0} + { \prg_return_true: } + { \prg_return_false: } + } + { + \prg_return_true: + % warning?? + } + } +%</base> % \end{macrocode} % \end{macro} % @@ -566,6 +606,7 @@ % \begin{macro}[TF]{\@@_check_if_active_mc:,\@@_check_if_active_struct:} % This checks if mc are active. % \begin{macrocode} +%<*package> \prg_new_conditional:Npnn \@@_check_if_active_mc: {T,F,TF} { \bool_lazy_and:nnTF { \g_@@_active_mc_bool } { \l_@@_active_mc_bool } diff --git a/macros/latex/contrib/tagpdf/tagpdf-code.pdf b/macros/latex/contrib/tagpdf/tagpdf-code.pdf Binary files differindex 8fd8bc7541..5784294ea4 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-code.pdf +++ b/macros/latex/contrib/tagpdf/tagpdf-code.pdf diff --git a/macros/latex/contrib/tagpdf/tagpdf-data.dtx b/macros/latex/contrib/tagpdf/tagpdf-data.dtx index e66712cc7f..57dc3d356e 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-data.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf-data.dtx @@ -47,7 +47,7 @@ % }^^A % } % -% \date{Version 0.98h, released 2023-06-06} +% \date{Version 0.98i, released 2023-06-14} % \maketitle % \begin{documentation} % This files contains a various data files which are read in @@ -60,7 +60,7 @@ % It lists the new tag, the rolemap and the namespace of the rolemap. % \begin{macrocode} %<*ns-latex> -%% \ProvidesExplFile {tagpdf-ns-latex.def} {2023-06-06} {0.98h} +%% \ProvidesExplFile {tagpdf-ns-latex.def} {2023-06-14} {0.98i} %% {latex} {https://www.latex-project.org/ns/dflt/2022}{} title, Title, pdf2, part, Title, pdf2, @@ -92,7 +92,7 @@ text, P, pdf2, % It is bound to change % \begin{macrocode} %<*ns-latex-book> -%% \ProvidesExplFile {tagpdf-ns-latex-book.def} {2023-06-06} {0.98h} +%% \ProvidesExplFile {tagpdf-ns-latex-book.def} {2023-06-14} {0.98i} %% {latex-book} {https://www.latex-project.org/ns/book/2022}{} chapter, H1,pdf2, section, H2,pdf2, @@ -108,7 +108,7 @@ subparagraph, H6,pdf2, % It is bound to change a lot! % \begin{macrocode} %<*ns-latex-inline> -%% \ProvidesExplFile {tagpdf-ns-latex-inline.def} {2023-06-06} {0.98h} +%% \ProvidesExplFile {tagpdf-ns-latex-inline.def} {2023-06-14} {0.98i} %% {latex-inline} {https://www.latex-project.org/ns/inline/2022}{} chapter, Span, pdf2, section, Span, pdf2, @@ -122,7 +122,7 @@ P, Span, pdf2, % \section{The pdf namespace data} % \begin{macrocode} %<*ns-pdf> -%% \ProvidesExplFile {tagpdf-ns-pdf.def} {2023-06-06} {0.98h} +%% \ProvidesExplFile {tagpdf-ns-pdf.def} {2023-06-14} {0.98i} %% {pdf} {http://iso.org/pdf/ssn}{} StructTreeRoot,StructTreeRoot,pdf,D, Document,Document,pdf,D, @@ -190,7 +190,7 @@ Strong,Span,pdf,I, % \section{The pdf 2.0 namespace data} % \begin{macrocode} %<*ns-pdf2> -%% \ProvidesExplFile {tagpdf-ns-pdf2.def} {2023-06-06} {0.98h} +%% \ProvidesExplFile {tagpdf-ns-pdf2.def} {2023-06-14} {0.98i} %% {pdf2} {http://iso.org/pdf2/ssn}{} Document,Document,pdf2,D, Part,Part,pdf2,G, @@ -246,7 +246,7 @@ Strong,Strong,pdf2,I, % \section{The mathml namespace data} % \begin{macrocode} %<*ns-mathml> -%% \ProvidesExplFile {tagpdf-ns-mathml.def} {2023-06-06} {0.98h} +%% \ProvidesExplFile {tagpdf-ns-mathml.def} {2023-06-14} {0.98i} % {mathml}{http://www.w3.org/1998/Math/MathML}{} abs,abs,mathml, and,and,mathml, @@ -481,7 +481,7 @@ xor,xor,mathml, % This will perhaps change in future. % \begin{macrocode} %<*parent-child> -%% \ProvidesExplFile {tagpdf-parent-child.csv} {2023-06-06} {0.98h} +%% \ProvidesExplFile {tagpdf-parent-child.csv} {2023-06-14} {0.98i} ,,,StructTreeRoot,Document,Art,Part,Div,Sect,BlockQuote,NonStruct,TOC,TOCI,Index,Private,Quote,Note,Reference,BibEntry,P,Hn,H,Lbl,Code,Span,Link,Annot,Form,Ruby,RB,RT,RP,Warichu,WT,WP,L,LI,LBody,Table,TR,TH,TD,THead,TBody,TFoot,Caption,Figure,Formula,MC Document,both,document level,1,0..n,∅,‡,‡,∅,0..n,‡,∅,∅,∅,0..n,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅ Art,1.7,grouping,∅,0..n,∅,‡,‡,0..n,0..n,‡,∅,∅,∅,0..n,∅,0..n,∅,∅,∅,0..1,0..1,∅,∅,∅,0..n,0..n,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,0..n,∅,∅,0..n,0..n,∅,∅,∅,0..n,0..n,∅,∅ @@ -536,7 +536,7 @@ MC,both,---,∅,∅,∅,∅,∅,∅,0..n,‡,∅,∅,∅,0..n,0..n,0..n,0..n,0.. % This will perhaps change in future. % \begin{macrocode} %<*parent-child-2> -%% \ProvidesExplFile {tagpdf-parent-child-2.csv} {2023-06-06} {0.98h} +%% \ProvidesExplFile {tagpdf-parent-child-2.csv} {2023-06-14} {0.98i} ,,,StructTreeRoot,Document,DocumentFragment,Art,Part,Div,Sect,Aside,BlockQuote,NonStruct,TOC,TOCI,Index,Private,Title,Sub,Quote,Note,Reference,BibEntry,P,Hn,H,Lbl,Code,Em,Strong,Span,Link,Annot,Form,Ruby,RB,RT,RP,Warichu,WT,WP,FENote,L,LI,LBody,Table,TR,TH,TD,THead,TBody,TFoot,Caption,Figure,Formula,math,mathml,Artifact,MC Document,both,document level,1,0..n,0..n,∅,‡,‡,∅,0..n,0..n,‡,∅,∅,∅,0..n,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,0..n,∅ DocumentFragment,2.0,document level,∅,0..n,0..n,0..n,‡,‡,0..n,0..n,0..n,‡,∅,∅,∅,0..n,∅,∅,∅,∅*,∅,∅,∅,∅,∅,∅,∅*,∅,∅,∅,∅*,∅*,∅,∅,∅,∅,∅,∅,∅,∅,∅*,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅,∅*,∅,∅,∅,∅,0..n,∅ diff --git a/macros/latex/contrib/tagpdf/tagpdf-mc-generic.dtx b/macros/latex/contrib/tagpdf/tagpdf-mc-generic.dtx index a82cb68524..97732c57bf 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-mc-generic.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf-mc-generic.dtx @@ -46,7 +46,7 @@ % }^^A % } % -% \date{Version 0.98h, released 2023-06-06} +% \date{Version 0.98i, released 2023-06-14} % \maketitle % \begin{documentation} % \end{documentation} @@ -55,11 +55,11 @@ % \begin{macrocode} %<@@=tag> %<*generic> -\ProvidesExplPackage {tagpdf-mc-code-generic} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-mc-code-generic} {2023-06-14} {0.98i} {part of tagpdf - code related to marking chunks - generic mode} %</generic> %<*debug> -\ProvidesExplPackage {tagpdf-debug-generic} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-debug-generic} {2023-06-14} {0.98i} {part of tagpdf - debugging code related to marking chunks - generic mode} %</debug> % \end{macrocode} @@ -657,6 +657,7 @@ % \end{macrocode} % \end{macro} % +% % \begin{macro}{\tag_mc_begin:n,\tag_mc_end:} % These are the core public commands to open and close an mc. % They don't need to be in the same group or grouping level, @@ -664,7 +665,7 @@ % the state is passed to the end command through a global var and % a global boolean. % \begin{macrocode} -%<base>\cs_new_protected:Npn \tag_mc_begin:n #1 { \@@_whatsits: } +%<base>\cs_new_protected:Npn \tag_mc_begin:n #1 { \@@_whatsits: \int_gincr:N \c@g_@@_MCID_abs_int } %<base>\cs_new_protected:Nn \tag_mc_end:{ \@@_whatsits: } %<*generic|debug> %<*generic> diff --git a/macros/latex/contrib/tagpdf/tagpdf-mc-luacode.dtx b/macros/latex/contrib/tagpdf/tagpdf-mc-luacode.dtx index cf70950a28..261a3ff73f 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-mc-luacode.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf-mc-luacode.dtx @@ -46,7 +46,7 @@ % }^^A % } % -% \date{Version 0.98h, released 2023-06-06} +% \date{Version 0.98i, released 2023-06-14} % \maketitle % \begin{implementation} % The code is splitted into three parts: code shared by all engines, @@ -86,7 +86,7 @@ % \begin{macrocode} %<@@=tag> %<*luamode> -\ProvidesExplPackage {tagpdf-mc-code-lua} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-mc-code-lua} {2023-06-14} {0.98i} {tagpdf - mc code only for the luamode } %</luamode> % \end{macrocode} @@ -375,6 +375,22 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\tag_mc_reset_box:N} +% This allows to reset the mc-attributes in box. On base and generic mode it should do +% nothing. +% \begin{macrocode} +\cs_set_protected:Npn \tag_mc_reset_box:N #1 + { + \lua_now:e + { + local~type=tex.getattribute(luatexbase.attributes.g_@@_mc_type_attr) + local~mc=tex.getattribute(luatexbase.attributes.g_@@_mc_cnt_attr) + ltx.__tag.func.update_mc_attributes(tex.getbox(\int_use:N #1),mc,type) + } + } +% \end{macrocode} +% \end{macro} +% % \begin{macro}{ \@@_get_data_mc_tag: } % The command to retrieve the current mc tag. % TODO: Perhaps this should use the attribute instead. diff --git a/macros/latex/contrib/tagpdf/tagpdf-mc-shared.dtx b/macros/latex/contrib/tagpdf/tagpdf-mc-shared.dtx index 2096e11d30..9c9d4ec735 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-mc-shared.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf-mc-shared.dtx @@ -46,7 +46,7 @@ % }^^A % } % -% \date{Version 0.98h, released 2023-06-06} +% \date{Version 0.98i, released 2023-06-14} % \maketitle % \begin{documentation} % \section{Public Commands} @@ -111,6 +111,13 @@ % Determines if a mc-chunk is open. % \end{function} +% \begin{function}[ EXP,added=2023-06-11]{\tag_mc_reset_box:N} +% \begin{syntax} +% \cs{tag_mc_reset:N} \Arg{box} +% \end{syntax} +% This resets in lua mode the mc attributes to the one currently in use. +% It does nothing in generic mode. +% \end{function} % % \section{Public keys} % The following keys can be used with |\tag_mc_begin:n|, |\tagmcbegin|, @@ -174,7 +181,7 @@ % \begin{macrocode} %<@@=tag> %<*header> -\ProvidesExplPackage {tagpdf-mc-code-shared} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-mc-code-shared} {2023-06-14} {0.98i} {part of tagpdf - code related to marking chunks - code shared by generic and luamode } %</header> @@ -192,18 +199,34 @@ % % \begin{variable}{g_@@_MCID_abs_int} % \begin{macrocode} -%<*shared> +%<*base> \newcounter { g_@@_MCID_abs_int } % \end{macrocode} % \end{variable} +% \begin{macro}{\@@_get_data_mc_counter:} +% This command allows \cs{tag_get:n} to get the current +% state of the mc counter with the keyword |mc_counter|. +% By comparing the numbers it can be used to check the number of +% structure commands in a piece of code. +% \begin{macrocode} +\cs_new:Npn \@@_get_data_mc_counter: + { + \int_use:N \c@g_@@_MCID_abs_int + } +%</base> +% \end{macrocode} +% \end{macro} % -% \begin{macro}{\_@@_get_mc_abs_cnt:} +% +% \begin{macro}{\@@_get_mc_abs_cnt:} % A (expandable) function to get the current value of the cnt. +% TODO: duplicate of the previous one, this should be cleaned up. % \begin{macrocode} -\cs_new:Npn \_@@_get_mc_abs_cnt: { \int_use:N \c@g_@@_MCID_abs_int } +%<*shared> +\cs_new:Npn \@@_get_mc_abs_cnt: { \int_use:N \c@g_@@_MCID_abs_int } % \end{macrocode} % \end{macro} -% +% % \begin{variable}{\g_@@_MCID_tmp_bypage_int} % The following hold the temporary by page number assigned to a mc. % It must be defined in the shared code to avoid problems with labels. @@ -362,7 +385,13 @@ %</shared> % \end{macrocode} % \end{macro} -% +% \begin{macro}{\tag_mc_reset_box:N} +% This allows to reset the mc-attributes in box. On base and generic mode it should do +% nothing. +% \begin{macrocode} +%<base>\cs_new_protected:Npn \tag_mc_reset_box:N #1 {} +% \end{macrocode} +% \end{macro} % \begin{macro}{\tag_mc_end_push:, \tag_mc_begin_pop:n} % % \begin{macrocode} @@ -410,7 +439,7 @@ } % \end{macrocode} % \end{macro} -% +% % \subsection{Keys} % This are the keys where the code can be shared between the modes. % diff --git a/macros/latex/contrib/tagpdf/tagpdf-roles.dtx b/macros/latex/contrib/tagpdf/tagpdf-roles.dtx index 5876c4ba32..fcfd5f7534 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-roles.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf-roles.dtx @@ -46,7 +46,7 @@ % }^^A % } % -% \date{Version 0.98h, released 2023-06-06} +% \date{Version 0.98i, released 2023-06-14} % \maketitle % \begin{documentation} % \begin{function} @@ -98,7 +98,7 @@ % \begin{macrocode} %<@@=tag> %<*header> -\ProvidesExplPackage {tagpdf-roles-code} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-roles-code} {2023-06-14} {0.98i} {part of tagpdf - code related to roles and structure names} %</header> % \end{macrocode} diff --git a/macros/latex/contrib/tagpdf/tagpdf-space.dtx b/macros/latex/contrib/tagpdf/tagpdf-space.dtx index 6e751618ee..e6b5e02513 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-space.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf-space.dtx @@ -46,7 +46,7 @@ % }^^A % } % -% \date{Version 0.98h, released 2023-06-06} +% \date{Version 0.98i, released 2023-06-14} % \maketitle % \begin{documentation} % \begin{function}{interwordspace (setup-key)} @@ -64,7 +64,7 @@ % \begin{macrocode} %<@@=tag> %<*header> -\ProvidesExplPackage {tagpdf-space-code} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-space-code} {2023-06-14} {0.98i} {part of tagpdf - code related to real space chars} %</header> % \end{macrocode} diff --git a/macros/latex/contrib/tagpdf/tagpdf-struct.dtx b/macros/latex/contrib/tagpdf/tagpdf-struct.dtx index 542671bd15..d2bb7a2b08 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-struct.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf-struct.dtx @@ -46,7 +46,7 @@ % }^^A % } % -% \date{Version 0.98h, released 2023-06-06} +% \date{Version 0.98i, released 2023-06-14} % \maketitle % \begin{documentation} % \section{Public Commands} @@ -247,7 +247,7 @@ % \begin{macrocode} %<@@=tag> %<*header> -\ProvidesExplPackage {tagpdf-struct-code} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-struct-code} {2023-06-14} {0.98i} {part of tagpdf - code related to storing structure} %</header> % \end{macrocode} @@ -978,6 +978,20 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\@@_get_data_struct_counter:} +% this command allows \cs{tag_get:n} to get the current +% state of the structure counter with the keyword |struct_counter|. +% By comparing the numbers it can be used to check the number of +% structure commands in a piece of code. +% \begin{macrocode} +%<*base> +\cs_new:Npn \@@_get_data_struct_counter: + { + \int_use:N \c@g_@@_struct_abs_int + } +%</base> +% \end{macrocode} +% \end{macro} % \section{Keys} % This are the keys for the user commands. % we store the tag in a variable. But we should be careful, it is only reliable @@ -1726,7 +1740,7 @@ % \section{Attributes and attribute classes} % \begin{macrocode} %<*header> -\ProvidesExplPackage {tagpdf-attr-code} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-attr-code} {2023-06-14} {0.98i} {part of tagpdf - code related to attributes and attribute classes} %</header> % \end{macrocode} diff --git a/macros/latex/contrib/tagpdf/tagpdf-tree.dtx b/macros/latex/contrib/tagpdf/tagpdf-tree.dtx index 61f6db544a..393a7c359f 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-tree.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf-tree.dtx @@ -47,13 +47,13 @@ % }^^A % } % -% \date{Version 0.98h, released 2023-06-06} +% \date{Version 0.98i, released 2023-06-14} % \maketitle % \begin{implementation} % \begin{macrocode} %<@@=tag> %<*header> -\ProvidesExplPackage {tagpdf-tree-code} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-tree-code} {2023-06-14} {0.98i} {part of tagpdf - code related to writing trees and dictionaries to the pdf} %</header> % \end{macrocode} diff --git a/macros/latex/contrib/tagpdf/tagpdf-user.dtx b/macros/latex/contrib/tagpdf/tagpdf-user.dtx index 8ebd1813dd..be082172ef 100644 --- a/macros/latex/contrib/tagpdf/tagpdf-user.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf-user.dtx @@ -46,7 +46,7 @@ % }^^A % } % -% \date{Version 0.98h, released 2023-06-06} +% \date{Version 0.98i, released 2023-06-14} % \maketitle % \begin{documentation} % \section{Setup commands} @@ -250,7 +250,7 @@ % \begin{macrocode} %<@@=tag> %<*header> -\ProvidesExplPackage {tagpdf-user} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-user} {2023-06-14} {0.98i} {tagpdf - user commands} %</header> % \end{macrocode} @@ -517,6 +517,16 @@ % or do a first step to apply tagpdf commands to document commands. % This part should be regularly revisited to check if the code should go to a % better place or can be improved. +% +% \subsection{new ref system} +% Until l3ref is in the kernel, we provide a definition for \cs{newlabeldata} in +% the aux-file to avoid errors if a document switches between tagging and non-tagging. +% \begin{macrocode} +%</package> +%<base>\AddToHook{begindocument} +%<base> {\immediate\write\@mainaux{\string\providecommand\string\newlabeldata[2]{}}} +%<*package> +% \end{macrocode} % \subsection{Document structure} % \begin{macro}{\g_@@_root_default_tl,activate (setup-key)} % \begin{macrocode} @@ -840,9 +850,11 @@ \bool_gset_false:N \g_@@_in_mc_bool } \tag_mc_begin:n {artifact} + \tag_stop:n{headfoot} } \cs_new_protected:Npn \@@_exclude_headfoot_end: { + \tag_start:n{headfoot} \tag_mc_end: \bool_if:NTF \g_@@_mode_lua_bool { @@ -869,10 +881,12 @@ } \tag_struct_begin:n{tag=Artifact,attribute-class=@@/attr/#1} \tag_mc_begin:n {artifact=#1} + \tag_stop:n{headfoot} } \cs_new_protected:Npn \@@_exclude_struct_headfoot_end: { + \tag_start:n{headfoot} \tag_mc_end: \tag_struct_end: \bool_if:NTF \g_@@_mode_lua_bool diff --git a/macros/latex/contrib/tagpdf/tagpdf.dtx b/macros/latex/contrib/tagpdf/tagpdf.dtx index b4c9e55090..b5898d0ed4 100644 --- a/macros/latex/contrib/tagpdf/tagpdf.dtx +++ b/macros/latex/contrib/tagpdf/tagpdf.dtx @@ -92,7 +92,7 @@ % \begin{macrocode} %<@@=tag> %<*package> -\ProvidesExplPackage {tagpdf} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf} {2023-06-14} {0.98i} { A package to experiment with pdf tagging } \bool_if:nF @@ -118,7 +118,7 @@ % \end{macrocode} %<*debug> % \begin{macrocode} -\ProvidesExplPackage {tagpdf-debug} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-debug} {2023-06-14} {0.98i} { debug code for tagpdf } \@ifpackageloaded{tagpdf}{}{\PackageWarning{tagpdf-debug}{tagpdf~not~loaded,~quitting}\endinput} % \end{macrocode} @@ -141,7 +141,7 @@ % we define a base package with dummy functions % \begin{macrocode} %<*base> -\ProvidesExplPackage {tagpdf-base} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdf-base} {2023-06-14} {0.98i} {part of tagpdf - provide base, no-op versions of the user commands } %</base> % \end{macrocode} diff --git a/macros/latex/contrib/tagpdf/tagpdf.pdf b/macros/latex/contrib/tagpdf/tagpdf.pdf Binary files differindex a75c6a78db..329b97b8a5 100644 --- a/macros/latex/contrib/tagpdf/tagpdf.pdf +++ b/macros/latex/contrib/tagpdf/tagpdf.pdf diff --git a/macros/latex/contrib/tagpdf/tagpdf.tex b/macros/latex/contrib/tagpdf/tagpdf.tex index 27cd1d128d..1ee0abb181 100644 --- a/macros/latex/contrib/tagpdf/tagpdf.tex +++ b/macros/latex/contrib/tagpdf/tagpdf.tex @@ -16,8 +16,8 @@ } \DebugBlocksOff \makeatletter -\def\UlrikeFischer@package@version{0.98h} -\def\UlrikeFischer@package@date{2023-06-06} +\def\UlrikeFischer@package@version{0.98i} +\def\UlrikeFischer@package@date{2023-06-14} \makeatother \documentclass[bibliography=totoc,a4paper]{article} @@ -298,6 +298,9 @@ structures can be inspected and be compared by the l3build checks.% \section{Changes} + +This section lists only important changes. More can be found in the \texttt{CHANGELOG.MD} and by checking the git commits. + \subsection{Changes in 0.3} @@ -509,12 +512,6 @@ added. The ID of a structure can be retrieved with |\tag_get:n| see~\ref{sec:retrieve}. -\subsection{Changes in version 0.98d} -The main change is from now on every structure has an ID and an IDtree is -added. The ID of a structure can be retrieved with |\tag_get:n| -see~\ref{sec:retrieve}. - - \subsection{Changes in version 0.98e} \begin{itemize} @@ -1211,16 +1208,30 @@ In \emph{generic mode}, where marked content command shouldn't be nested, it wor In \emph{lua mode} it tests if the mc-attribute is currently unset. You can't test the nesting level with it! + + +\begin{docCommand}{tag_mc_reset_box:N}{\marg{box}}\end{docCommand} + +In lua mode this command will process the given box and reset all mc related attributes in the box to the current values. +This means that if the box is used all its contents will be a kid of the current structure. +This should (probably) only be used on boxes which don't contain tagging commands. +See below section~\ref{sec:savebox} for more details. + + \subsubsection{Retrieving data} \label{sec:retrieve} With more elaborate tagging the need arise to retrieve and store current data. \begin{docCommand}{tag_get:n}{\marg{key word}}\end{docCommand} -This (expandable) command give back some variables. Currently the working key words are \verb+mc_tag+, \verb+struct_tag+, -\verb+struct_id+ and \verb+struct_num+. The ID is a string and returned including parentheses. -\verb+struct_num+ returns a number and works also if only \pkg{tagpdf-base} has been loaded, but then doesn't give the same output: if \pkg{tagpdf} is loaded and tagging is active, \verb+struct_num+ gives the number of currently -active structure, so it reverts to the parent number if a structure is closed. If only \pkg{tagpdf-base} is loaded -nesting of structure is not tracked and so the command gives back the number of the last structure that has been created. +This (expandable) command give back some variables. Currently the working key words are +\begin{itemize} +\item \verb+mc_tag+: the tag name of the current mc-chunk +\item \verb+struct_tag+: the tag name of the current structure +\item \verb+struct_id+: The ID of the current structure. This is a string and is returned including parentheses. +\item \verb+struct_num+: This returns a number and works also if only \pkg{tagpdf-base} has been loaded, but then doesn't give the same output: if \pkg{tagpdf} is loaded and tagging is active, \verb+struct_num+ gives the number of currently active structure, so it reverts to the parent number if a structure is closed. If only \pkg{tagpdf-base} is loaded nesting of structure is not tracked and so the command gives back the number of the last structure that has been created. +\item \verb+struct_counter+: This returns a number and works also if only \pkg{tagpdf-base} has been loaded. It gives back the state of the absolute structure counter and so number of the last structure that has been created. This can be used to detect if in a piece of code there are structure commands. Be aware that this is a \LaTeX{} counter and so reset in some places. +\item \verb+mc_counter+: This returns a number and works also if only \pkg{tagpdf-base} has been loaded. It gives back the state of the absolute mc-counter and so number of the last mc-chunk that has been created. This can be used to detect if in a piece of code there are mc-commands. +\end{itemize} \subsubsection{Luamode: global or not global -- that is the question}\label{sec:global-local} @@ -2209,7 +2220,7 @@ This is in pdftex a primitive. It inserts the dummy space glyph. \pkg{tagpdf} de necessary to surround destinations with a dummy structure (a Span or an Artifact) to get the right page number. - +\section{Storing and reusing boxes}\label{sec:savebox} \section{Accessibility is not only tagging} diff --git a/macros/latex/contrib/tagpdf/tagpdfdocu-patches.sty b/macros/latex/contrib/tagpdf/tagpdfdocu-patches.sty index 4f14e73b1a..0628a46660 100644 --- a/macros/latex/contrib/tagpdf/tagpdfdocu-patches.sty +++ b/macros/latex/contrib/tagpdf/tagpdfdocu-patches.sty @@ -1,5 +1,5 @@ %\RequirePackage[enable-debug]{expl3}[2018/06/14] -\ProvidesExplPackage {tagpdfdocu-patches} {2023-06-06} {0.98h} +\ProvidesExplPackage {tagpdfdocu-patches} {2023-06-14} {0.98i} {patches/commands for the tagpdf documentation} \RequirePackage{etoolbox,xpatch} diff --git a/macros/latex/contrib/zref-check/CHANGELOG.md b/macros/latex/contrib/zref-check/CHANGELOG.md index f812c8b76c..b9c41de170 100644 --- a/macros/latex/contrib/zref-check/CHANGELOG.md +++ b/macros/latex/contrib/zref-check/CHANGELOG.md @@ -1,6 +1,12 @@ # Changelog -## [Unreleased](https://github.com/gusbrs/zref-check/compare/v0.3.2...HEAD) +## [Unreleased](https://github.com/gusbrs/zref-check/compare/v0.3.3...HEAD) + +## [v0.3.3](https://github.com/gusbrs/zref-check/compare/v0.3.2...v0.3.3) (2023-06-14) + +### Changed +- Improvements to User manual. +- Simplify regression tests. ## [v0.3.2](https://github.com/gusbrs/zref-check/compare/v0.3.1...v0.3.2) (2022-07-07) diff --git a/macros/latex/contrib/zref-check/zref-check-code.pdf b/macros/latex/contrib/zref-check/zref-check-code.pdf Binary files differindex 24e4f653b9..fdd972c94d 100644 --- a/macros/latex/contrib/zref-check/zref-check-code.pdf +++ b/macros/latex/contrib/zref-check/zref-check-code.pdf diff --git a/macros/latex/contrib/zref-check/zref-check-code.tex b/macros/latex/contrib/zref-check/zref-check-code.tex index 5645430295..02cb8b5c82 100644 --- a/macros/latex/contrib/zref-check/zref-check-code.tex +++ b/macros/latex/contrib/zref-check/zref-check-code.tex @@ -4,7 +4,7 @@ % % This file is part of the LaTeX package "zref-check". % -% Copyright (C) 2021-2022 Gustavo Barros +% Copyright (C) 2021-2023 Gustavo Barros % % It may be distributed and/or modified under the conditions of the % LaTeX Project Public License (LPPL), either version 1.3c of this @@ -22,7 +22,7 @@ % % This work consists of the files zref-check.dtx, % zref-check.ins, -% zref-check.tex, +% zref-check-doc.tex, % zref-check-code.tex, % and the files generated from them. % diff --git a/macros/latex/contrib/zref-check/zref-check.pdf b/macros/latex/contrib/zref-check/zref-check-doc.pdf Binary files differindex b3d67a8f98..64afffc6f2 100644 --- a/macros/latex/contrib/zref-check/zref-check.pdf +++ b/macros/latex/contrib/zref-check/zref-check-doc.pdf diff --git a/macros/latex/contrib/zref-check/zref-check-doc.tex b/macros/latex/contrib/zref-check/zref-check-doc.tex new file mode 100644 index 0000000000..420ec0f900 --- /dev/null +++ b/macros/latex/contrib/zref-check/zref-check-doc.tex @@ -0,0 +1,501 @@ +% \iffalse meta-comment +% +% File: zref-check.tex +% +% This file is part of the LaTeX package "zref-check". +% +% Copyright (C) 2021-2022 Gustavo Barros +% +% It may be distributed and/or modified under the conditions of the +% LaTeX Project Public License (LPPL), either version 1.3c of this +% license or (at your option) any later version. The latest version +% of this license is in the file: +% +% https://www.latex-project.org/lppl.txt +% +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% +% This work is "maintained" (as per LPPL maintenance status) by +% Gustavo Barros. +% +% This work consists of the files zref-check.dtx, +% zref-check.ins, +% zref-check-doc.tex, +% zref-check-code.tex, +% and the files generated from them. +% +% The released version of this package is available from CTAN. +% +% ----------------------------------------------------------------------- +% +% The development version of the package can be found at +% +% https://github.com/gusbrs/zref-check +% +% for those people who are interested. +% +% ----------------------------------------------------------------------- +% +% \fi + +\documentclass{l3doc} + +% Have \GetFileInfo pick up date and version data +\usepackage{zref-check} + +\setlength{\marginparsep}{2\labelsep} + +\NewDocumentCommand\opt{m}{\texttt{#1}} + +\begin{document} + +\GetFileInfo{zref-check.sty} + +\title{% + The \pkg{zref-check} package% + \thanks{This file describes \fileversion, released \filedate.}% +} + +\author{% + Gustavo Barros% + \thanks{\url{https://github.com/gusbrs/zref-check}}% +} + +\date{\filedate} + +\maketitle + +\begin{abstract} + \pkg{zref-check} provides an user interface for making \LaTeX{} + cross-references flexibly, while allowing to have them checked for + consistency with the document structure as typeset. Statements such as + ``above'', ``on the next page'', ``previously'', ``as will be discussed'', + ``on the previous chapter'' and so on can be given to \cs{zcheck} in + free-form, and a set of ``checks'' can be specified to be run against a + given \texttt{label}, which will result in a warning at compilation time if + any of these checks fail. \cs{zctarget} and the \texttt{zcregion} + environment are also defined as a means to easily set label targets to + arbitrary places in the text which can be referred to by \cs{zcheck}. +\end{abstract} + +\tableofcontents + + +\section{Introduction} + +The \pkg{zref-check} package provides an user interface for making \LaTeX{} +cross-references exploiting document contextual information to enrich the way +the reference can be rendered, but at the same time ensuring the means that +these cross-references can be done consistently with the document structure. + +The usual \LaTeX{} cross-reference is done by referring to a \texttt{label}, +associated with one or another document structural element, and this reference +will typeset for you some content based on the information which is stored in +that label. \cs{zcheck}, the main user command of \pkg{zref-check}, has a +somewhat different concept. Instead of trying to provide the text to be +typeset based on the contextual information, \cs{zcheck} lets the user supply +an arbitrary text and specify one or more checks to be done on the label(s) +being referred to. If any of the checks fails, a warning is issued upon +compilation, so that the user can go back to that cross-reference and correct +it as needed, without having to rely on burdensome and error prone manual +proof-reading. + +This grants a much increased flexibility for the cross-reference text, which +means in practice that the writing style, the variety of expressions you may +use for similar situations, does not need to be sacrificed for the +convenience. \cs{zcheck}'s cross-references do not need to ``feel'' automated +to be consistently checked. Localization is also not an issue, since the +cross-reference text is provided directly by the user. Separating +``typesetting'' from ``checking'' also means there is a lot of document +context we can leverage for this purpose (see Section~\ref{sec:checks}). + +A standard \LaTeX{} cross-reference is made to refer to specific numbered +document elements -- chapters, sections, figures, tables, equations, etc. The +cross-reference will normally produce that number (which is the element's +``id'') and, eventually, its ``type'' (the counter). We may also refer to the +page that element occurs and even its ``title'' (in which case, atypically, we +may even get to refer to an unnumbered section, provided we also implicitly +supply by some means the ``id''). + +For references to these usual specific document elements, \pkg{zref-check} +caters for a particular kind of cross-reference which is common: +\emph{relational} statements based on them. \cs{zcheck} can typeset and +meaningfully check cross-references such as ``above'', ``on the next page'', +``on the facing page'', ``on the previous section'', ``later on this chapter'' +and so on. After all, if your reference is being made on page 2 and refers to +something on the same page, ``on this page'' reads much better than ``on +page~2''. If you are writing chapter~4, ``on the previous chapter'' sounds +nicer than ``on chapter~3''. + +However, there is yet another kind of ``looser'' cross-reference we routinely +do in our documents. Expressions such as ``previously'', ``as mentioned +before'', ``as will be discussed'', and so on, are a powerful discursive +instrument, which enriches the text, by offering hints to the arguments' +threads, without necessarily pressing them too hard onto the reader. So, we +might not want to say ``on footnote 57, pag.~34'', but prefer ``previously'', +not ``on Section 3.4'', but rather ``below'', or ``later on''. Besides, we +also may refer to certain passages in the text in this way, rather than to +numbered document elements. And this kind of reference is not only hard to +check and find, but also to fix. After all, if you are making one such +reference, you are taking that statement as a premisse at the current point in +the text. So, if that reference is missing, or relocated, you may need to +bring in the support to the premisse for your argument to close, rather than +just ``adjust the reference text''. \pkg{zref-check} also provides support +for this kind of cross-reference, allowing for them to be consistently +verified. + + +\section{Loading the package} +\label{sec:loading-package} + +\pkg{zref-check} can be loaded with the usual: + +\begin{syntax} + \cs{usepackage}|{zref-check}| +\end{syntax} + +The package does not accept load-time options, package options must be set +using \cs{zrefchecksetup} (see Section~\ref{sec:user-interface}). + + +\section{Dependencies} + +\pkg{zref} is required, of course, but in particular, its modules +\pkg{zref-user} and \pkg{zref-abspage} are loaded by default. \pkg{ifdraft} +(from the \pkg{oberdiek} bundle) is also loaded by default. A \LaTeX{} kernel +later than 2021-06-01 is required, since we rely on the new hook system from +\pkg{ltcmdhooks} for the sectioning checks. If \pkg{hyperref} is loaded and +option \pkg{hyperref} is given, \pkg{zref-check} makes use of it, but it does +not load the package for you. + + +\section{User interface} +\label{sec:user-interface} + +\begin{function}{\zcheck} + \begin{syntax} + \cs{zcheck}\oarg{checks/options}\marg{labels}\marg{text} + \end{syntax} + Typesets \meta{text}, as given, while performing a list of \meta{checks} on + each of the \meta{labels}. When \pkg{hyperref} support is enabled, + \meta{text} will be made a hyperlink to \emph{the first} \meta{label} in + \meta{labels}. The starred version of the command does the same as the + plain one, just does not form a link. The \meta{options} are (mostly) the + same as those of the package, and can be given to local effect. + \meta{checks} and \meta{options} can be given side by side as a comma + separated list in the optional argument. \meta{labels} is also a comma + separated list. +\end{function} + +\begin{function}{\zctarget} + \begin{syntax} + \cs{zctarget}\marg{label}\marg{text} + \end{syntax} + Typesets \meta{text}, as given, and places a pair of \texttt{zlabel}s, one + at the start of \meta{text}, using \meta{label} as label name, another one + (internal) at the end of \meta{text}. +\end{function} + + +\begin{function}{zcregion} + \begin{syntax} + |\begin{zcregion}|\marg{label} + | ...| + |\end{zcregion}| + \end{syntax} + An environment that does the same as \cs{zctarget}, for cases of longer + stretches of text. +\end{function} + + +\begin{function}{\zrefchecksetup} + \begin{syntax} + \cs{zrefchecksetup}\marg{options} + \end{syntax} + Sets \pkg{zref-check}'s options (see Section~\ref{sec:options}). +\end{function} + +\bigskip{} + +All user commands of \pkg{zref-check} have their \marg{label} arguments +protected for \pkg{babel} active characters using \pkg{zref}'s +\cs{zref@wrapper@babel}, so that we should have equivalent support in that +regard, as \pkg{zref} itself does. \pkg{zref-check} depends on \pkg{zref}, as +the name entails, which means it is able to work with \pkg{zref} labels, in +general created by \cs{zlabel}, but also with \cs{zctarget} and the +\texttt{zcregion} environment provided by this package. + + +\section{Checks} +\label{sec:checks} + +\pkg{zref-check} provides several ``checks'' to be used with \cs{zcheck}. The +checks may be combined in a \cs{zcheck} call, e.g.\ \opt{[close, after]}, or +\opt{[thischap, before]}. In this case, each check in \meta{checks} is +performed against each of the \meta{labels}. This is done independently for +each check, which means, in practice, that the checks bear a logical +\texttt{AND} relation to the others. Whether the combination is meaningful, +is up to the user. As is the correspondence between the \meta{checks} and the +\meta{text} in \cs{zcheck}. + +The use of checks which perform ``within the page'' comparisons -- namely +\opt{above} and \opt{below} and, through them, \opt{before} and \opt{after} -- +comes with some caveats you should be acquainted with. +Section~\ref{sec:within-page-checks} discusses their limitations and expands +on the expected workflow for their use to ensure reliable results. + +Note that the naming convention of the checks adopts the perspective of +\cs{zcheck}. That is, the name of the check describes the position of the +label being referred to, relative to the \cs{zcheck} call being made. For +example, the \opt{before} check should issue no message if +\cs{ztarget}|{mylabel}{...}| occurs before +\cs{zcheck}|[before]{mylabel}{...}|. + +The available checks are the following: + +\begin{description}[leftmargin=0pt, itemindent=0pt, align=right, labelsep=1em, + font=\MacroFont] + +\item[thispage] \meta{label} occurs on the same page as \cs{zcheck}. + +\item[prevpage] \meta{label} occurs on the previous page relative to + \cs{zcheck}. + +\item[nextpage] \meta{label} occurs on the next page relative to \cs{zcheck}. + +\item[otherpage] \meta{label} occurs on a page different from that of + \cs{zcheck}, that is, it does \emph{not} occur on \opt{thispage}. + +\item[pagegap] There is a page gap between \meta{label} and \cs{zcheck}, in + other words, \meta{label} does \emph{not} occur on \opt{thispage}, + \opt{prevpage} or \opt{nextpage}. + +\item[facing] On a \texttt{twoside} document, both \meta{label} and + \cs{zcheck} fall onto a double spread, each on one of the two facing pages. + +\item[above] \meta{label} and \cs{zcheck} are both on the same page, and + \meta{label} occurs ``above'' \cs{zcheck}. + +\item[below] \meta{label} and \cs{zcheck} are both on the same page, and + \meta{label} occurs ``below'' \cs{zcheck}. + +\item[pagesbefore] \meta{label} occurs on any page before the one of + \cs{zcheck}. + +\item[ppbefore] Convenience alias for \opt{pagesbefore}. + +\item[pagesafter] \meta{label} occurs on any page after the one of + \cs{zcheck}. + +\item[ppafter] Convenience alias for \opt{pagesafter}. + +\item[before] Either \opt{above} or \opt{pagesbefore}. + +\item[after] Either \opt{below} or \opt{pagesafter}. + +\item[thischap] \meta{label} occurs on the same chapter as \cs{zcheck}. + +\item[prevchap] \meta{label} occurs on the previous chapter relative to the + one of \cs{zcheck}. + +\item[nextchap] \meta{label} occurs on the next chapter relative to the one of + \cs{zcheck}. + +\item[chapsbefore] \meta{label} occurs on any chapter before the one of + \cs{zcheck}. + +\item[chapsafter] \meta{label} occurs on any chapter after the one of + \cs{zcheck}. + +\item[thissec] \meta{label} occurs on the same section as \cs{zcheck}. + +\item[prevsec] \meta{label} occurs on the previous section (of the same + chapter) relative to the one of \cs{zcheck}. + +\item[nextsec] \meta{label} occurs on the next section (of the same chapter) + relative to the one of \cs{zcheck}. + +\item[secsbefore] \meta{label} occurs on any section (of the same chapter) + before the one of \cs{zcheck}. + +\item[secsafter] \meta{label} occurs on any section (of the same chapter) + after the one of \cs{zcheck}. + +\item[close] \meta{label} occurs within a page range from \opt{closerange} + pages before the one of \cs{zcheck} to \opt{closerange} pages after it + (about the \opt{closerange} option, see Section~\ref{sec:options}). + +\item[far] Not \opt{close}. + +\end{description} + + +\section{Options} +\label{sec:options} + +Options are a standard \texttt{key=value} comma separated list, and can be set +globally either as \cs{usepackage}\oarg{options} at load-time (see +Section~\ref{sec:loading-package}), or by means of \cs{zrefchecksetup} (see +Section~\ref{sec:user-interface}) in the preamble. Most options can also be +used with local effects, through the optional argument of \cs{zcheck}. + +\DescribeOption{hyperref} % +Controls the use of \pkg{hyperref} by \pkg{zref-check} and takes values +\opt{auto}, \opt{true}, \opt{false}. The default value, \opt{auto}, makes +\pkg{zref-check} use \pkg{hyperref} if it is loaded, meaning \cs{zcheck} can +be hyperlinked to the \emph{first label} in \meta{labels}. \opt{true} does +the same thing, but warns if \pkg{hyperref} is not loaded (\pkg{hyperref} is +never loaded for you). In either of these cases, if \pkg{hyperref} is loaded, +module \pkg{zref-hyperref} is also loaded by \pkg{zref-check}. \opt{false} +means not to use \pkg{hyperref} regardless of its availability. This is a +preamble only option, but \cs{zcheck} provides granular control of +hyperlinking by means of its starred version. + + +\DescribeOption{msglevel} % +Sets the level of messages issued by \cs{zcheck} failed checks and takes +values \opt{warn}, \opt{info}, \opt{none}, \opt{infoifdraft}, +\opt{warniffinal}. The default value, \opt{warn}, issues messages both to the +terminal and to the log file, \opt{info} issues messages to the log file only, +\opt{none} suppresses all messages. \opt{infoifdraft} corresponds to +\opt{info} if option \opt{draft} is passed to \cs{documentclass}, and to +\opt{warn} otherwise. \opt{warniffinal} corresponds to \opt{warn} if option +\opt{final} is (explicitly) passed to \cs{documentclass} and \opt{info} +otherwise. \opt{ignore} is provided as convenience alias for +\opt{msglevel=none} for local use only. This option only affects the messages +issued by the checks in \cs{zcheck}, not other messages or warnings of the +package. In particular, it does not affect warnings issued for undefined +labels, which just use \cs{zref@refused} and thus are the same as standard +\LaTeX{} ones for this purpose. + + +\DescribeOption{onpage} % +Allows to control the messaging style for ``within page checks'', and takes +values \opt{labelseq}, \opt{msg}, \opt{labelseqifdraft}, \opt{msgiffinal}. +The default, \opt{labelseq}, uses the labels' shipout sequence, as retrieved +from the \file{.aux} file, to infer relative position within the page. +\opt{msg} also uses the same method for checking relative position, but issues +a (different) message \emph{even if the check passes}, to provide a simple +workflow for robust checking of ``false negatives'', considering the label +sequence is not fool proof (for details and workflow recommendations, see +Section~\ref{sec:within-page-checks}). \opt{msg} also issues its messages at +the same level defined in \opt{msglevel}. \opt{labelseqifdraft} corresponds +to \opt{labelseq} if option \opt{draft} is passed to \cs{documentclass} and to +\opt{msg} otherwise. \opt{msgiffinal} corresponds to \opt{msg} if option +\opt{final} is (explicitly) passed to \cs{documentclass}, and to +\opt{labelseq} otherwise. + + +\DescribeOption{closerange} % +Defines the width of the range of pages, relative to the reference, that are +considered ``close'' by the \opt{close} check. Takes a positive integer as +value, with default 5. + + +\section{Limitations} + +There are three qualitatively different kinds of checks being used by +\cs{zcheck}, according to the source and reliability of the information they +mobilize: page number checks, within page checks, and sectioning checks. + +\subsection{Page number checks} + +Page number checks -- \opt{thispage}, \opt{prevpage}, \opt{nextpage}, +\opt{pagesbefore}, \opt{pagesafter}, \opt{facing} -- use the \texttt{abspage} +property provided by the \pkg{zref-abspage} module. This is a solid piece of +information, on which we can rely upon. However, despite that, page number +checks may still become ill-defined, if the \meta{text} argument in +\cs{zcheck}, when typeset, crosses page boundaries, starting in one page, and +finishing in another. The same can happen with the text in \cs{zctarget} and +the \texttt{zcregion} environment. + +This is why the user commands of this package set a pair or labels around +\meta{text}. So, when checking \cs{zcheck} against a regular \texttt{zlabel} +both the start and the end of the \meta{text} are checked against the label, +and the check fails if either of them fails. When checking \cs{zcheck} +against a \cs{zctarget} or a \texttt{zcregion}, both beginnings and ends are +checked against each other two by two, and if any of them fails, the check +fails. In other words, if a page number checks passes, we know that the +entire \meta{text} arguments pass it. + +This is a corner case (albeit relevant) which must be taken care of, and it is +possible to do so robustly. Hence, we can expect reliable results in these +tests. + + +\subsection{Within page checks} +\label{sec:within-page-checks} + +When both label and reference fall on the same page things become much +trickier. This is basically the case of the checks \opt{above} and +\opt{below} (and, through them, \opt{before} and \opt{after}). There is no +equally reliable information (that I know of) as we have for the page number +checks for this, especially when floats come into play. Which, of course, is +the interesting case to handle. + +To infer relative position of label and reference on the same page, +\pkg{zref-check} uses the labels' shipout sequence, which is retrieved at +load-time from the order in which the labels occur in the \file{.aux} file. +Indeed, \pkg{zref} writes labels to the \file{.aux} file at shipout (and, +hence, in shipout order), and needs to do so, because a number of its +properties are only available at that point. + +However, even if this method will buy us a correct check for a regular float +on a regular page (which, to be fair, is a good result), it is not difficult +do conceive situations in which this sequence may not be meaningful, or even +correct, for the case. A number of cases which may do so are: two column +documents, text wrapping, scaling, overlays, etc. (I don't know if those make +the method fail, I just don't know if they don't). Therefore, the +\texttt{labelseq} should be taken as a \emph{proxy} and not fully reliable, +meaning that the user should be watchful of its results. + +For this reason, \pkg{zref-check} provides an easy way to do so, by allowing +specific control of the messaging style of the checks which do within page +comparisons though the option \opt{onpage}. The concern is not really with +false positives (getting a warning when it was not due), but with false +negatives (not getting a warning when it was due). Hence, setting +\opt{onpage} to \opt{msg} at a final typesetting stage (or just set it to +\opt{labelseqifdraft} or \opt{msgiffinal} if that's part of your workflow) +provides a way to easily identify all cases of such checks (failing or +passing), and double-check them. In case the test is passing though, the +message is different from that of a failing check, to quickly convey why you +are getting the message. This option can also be set at the local level, if +the page in question is known to be problematic, or just atypical. + + +\subsection{Sectioning checks} + +The information used by sectioning checks is provided by means of dedicated +counters for chapters and sections, similarly as standard counters for them, +but which are stepped and reset regardless of whether these sectioning +commands are numbered or not (that is, starred or not). And this for two +reasons. First, we don't need the absolute counter value to be able to make +the kind of relative statement we want to do here. Second, this allows us to +have these checks work for numbered and unnumbered sectioning commands without +having to worry about how those are used within the document. + +The caveat is that the package does this by hooking into \cs{chapter} and +\cs{section}, which poses two restrictions for the proper working of these +checks. First, we are using the new hook system for this, as provided by +\pkg{ltcmdhooks}, which means a \LaTeX{} kernel later than 2021-06-01 is +required. Second, since we are hooking into \cs{chapter} and \cs{section}, +these checks presume these commands are being used by the document class for +this purpose (either directly, or internally as, for example, KOMA-Script's +\cs{addchap} and \cs{addsec} do). If that's not the case, additional setup +may be needed for these checks to work as expected. + + +\section{Change history} + +A change log with relevant changes for each version, eventual upgrade +instructions, and upcoming changes, is maintained in the package's repository, +at \url{https://github.com/gusbrs/zref-check/blob/main/CHANGELOG.md}. The +change log is also distributed with the package's documentation through CTAN +upon release so, most likely, \texttt{texdoc zref-check/changelog} should +provide easy local access to it. An archive of historical versions of the +package is also kept at \url{https://github.com/gusbrs/zref-check/releases}. + + +\end{document} diff --git a/macros/latex/contrib/zref-check/zref-check.dtx b/macros/latex/contrib/zref-check/zref-check.dtx index 9bc53031c7..58eb421cdd 100644 --- a/macros/latex/contrib/zref-check/zref-check.dtx +++ b/macros/latex/contrib/zref-check/zref-check.dtx @@ -4,7 +4,7 @@ % % This file is part of the LaTeX package "zref-check". % -% Copyright (C) 2021-2022 Gustavo Barros +% Copyright (C) 2021-2023 Gustavo Barros % % It may be distributed and/or modified under the conditions of the % LaTeX Project Public License (LPPL), either version 1.3c of this @@ -22,7 +22,7 @@ % % This work consists of the files zref-check.dtx, % zref-check.ins, -% zref-check.tex, +% zref-check-doc.tex, % zref-check-code.tex, % and the files generated from them. % @@ -54,435 +54,6 @@ % \fi % % -% \begin{documentation} -% -% \section{Introduction} -% -% The \pkg{zref-check} package provides an user interface for making \LaTeX{} -% cross-references exploiting document contextual information to enrich the -% way the reference can be rendered, but at the same time ensuring the means -% that these cross-references can be done consistently with the document -% structure. -% -% The usual \LaTeX{} cross-reference is done by referring to a \texttt{label}, -% associated with one or another document structural element, and this -% reference will typeset for you some content based on the information which -% is stored in that label. \cs{zcheck}, the main user command of -% \pkg{zref-check}, has a somewhat different concept. Instead of trying to -% provide the text to be typeset based on the contextual information, -% \cs{zcheck} lets the user supply an arbitrary text and specify one or more -% checks to be done on the label(s) being referred to. If any of the checks -% fails, a warning is issued upon compilation, so that the user can go back to -% that cross-reference and correct it as needed, without having to rely on -% burdensome and error prone manual proof-reading. -% -% This grants a much increased flexibility for the cross-reference text, which -% means in practice that the writing style, the variety of expressions you may -% use for similar situations, does not need to be sacrificed for the -% convenience. \cs{zcheck}'s cross-references do not need to ``feel'' -% automated to be consistently checked. Localization is also not an issue, -% since the cross-reference text is provided directly by the user. Separating -% ``typesetting'' from ``checking'' also means there is a lot of document -% context we can leverage for this purpose (see Section~\ref{sec:checks}). -% -% A standard \LaTeX{} cross-reference is made to refer to specific numbered -% document elements -- chapters, sections, figures, tables, equations, etc. -% The cross-reference will normally produce that number (which is the -% element's ``id'') and, eventually, its ``type'' (the counter). We may also -% refer to the page that element occurs and even its ``title'' (in which case, -% atypically, we may even get to refer to an unnumbered section, provided we -% also implicitly supply by some means the ``id''). -% -% For references to these usual specific document elements, \pkg{zref-check} -% caters for a particular kind of cross-reference which is common: -% \emph{relational} statements based on them. \cs{zcheck} can typeset and -% meaningfully check cross-references such as ``above'', ``on the next page'', -% ``on the facing page'', ``on the previous section'', ``later on this -% chapter'' and so on. After all, if your reference is being made on page 2 -% and refers to something on the same page, ``on this page'' reads much better -% than ``on page~2''. If you are writing chapter~4, ``on the previous -% chapter'' sounds nicer than ``on chapter~3''. -% -% However, there is yet another kind of ``looser'' cross-reference we -% routinely do in our documents. Expressions such as ``previously'', ``as -% mentioned before'', ``as will be discussed'', and so on, are a powerful -% discursive instrument, which enriches the text, by offering hints to the -% arguments' threads, without necessarily pressing them too hard onto the -% reader. So, we might not want to say ``on footnote 57, pag.~34'', but -% prefer ``previously'', not ``on Section 3.4'', but rather ``below'', or -% ``later on''. Besides, we also may refer to certain passages in the text in -% this way, rather than to numbered document elements. And this kind of -% reference is not only hard to check and find, but also to fix. After all, -% if you are making one such reference, you are taking that statement as a -% premisse at the current point in the text. So, if that reference is -% missing, or relocated, you may need to bring in the support to the premisse -% for your argument to close, rather than just ``adjust the reference text''. -% \pkg{zref-check} also provides support for this kind of cross-reference, -% allowing for them to be consistently verified. -% -% -% \section{Loading the package} -% \label{sec:loading-package} -% -% \pkg{zref-check} can be loaded with the usual: -% -% \begin{syntax} -% \cs{usepackage}|{zref-check}| -% \end{syntax} -% -% The package does not accept load-time options, package options must be set -% using \cs{zrefchecksetup} (see Section~\ref{sec:user-interface}). -% -% -% \section{Dependencies} -% -% \pkg{zref} is required, of course, but in particular, its modules -% \pkg{zref-user} and \pkg{zref-abspage} are loaded by default. \pkg{ifdraft} -% (from the \pkg{oberdiek} bundle) is also loaded by default. A \LaTeX{} -% kernel later than 2021-06-01 is required, since we rely on the new hook -% system from \pkg{ltcmdhooks} for the sectioning checks. If \pkg{hyperref} -% is loaded and option \pkg{hyperref} is given, \pkg{zref-check} makes use of -% it, but it does not load the package for you. -% -% -% \section{User interface} -% \label{sec:user-interface} -% -% \begin{function}{\zcheck} -% \begin{syntax} -% \cs{zcheck}\oarg{checks/options}\marg{labels}\marg{text} -% \end{syntax} -% Typesets \meta{text}, as given, while performing a list of \meta{checks} -% on each of the \meta{labels}. When \pkg{hyperref} support is enabled, -% \meta{text} will be made a hyperlink to \emph{the first} \meta{label} in -% \meta{labels}. The starred version of the command does the same as the -% plain one, just does not form a link. The \meta{options} are (mostly) the -% same as those of the package, and can be given to local effect. -% \meta{checks} and \meta{options} can be given side by side as a comma -% separated list in the optional argument. \meta{labels} is also a comma -% separated list. -% \end{function} -% -% \begin{function}{\zctarget} -% \begin{syntax} -% \cs{zctarget}\marg{label}\marg{text} -% \end{syntax} -% Typesets \meta{text}, as given, and places a pair of \texttt{zlabel}s, one -% at the start of \meta{text}, using \meta{label} as label name, another one -% (internal) at the end of \meta{text}. -% \end{function} -% -% -% \begin{function}{zcregion} -% \begin{syntax} -% |\begin{zcregion}|\marg{label} -% | ...| -% |\end{zcregion}| -% \end{syntax} -% An environment that does the same as \cs{zctarget}, for cases of longer -% stretches of text. -% \end{function} -% -% -% \begin{function}{\zrefchecksetup} -% \begin{syntax} -% \cs{zrefchecksetup}\marg{options} -% \end{syntax} -% Sets \pkg{zref-check}'s options (see Section~\ref{sec:options}). -% \end{function} -% -% \bigskip{} -% -% All user commands of \pkg{zref-check} have their \marg{label} arguments -% protected for \pkg{babel} active characters using \pkg{zref}'s -% \cs{zref@wrapper@babel}, so that we should have equivalent support in that -% regard, as \pkg{zref} itself does. \pkg{zref-check} depends on \pkg{zref}, -% as the name entails, which means it is able to work with \pkg{zref} labels, -% in general created by \cs{zlabel}, but also with \cs{zctarget} and the -% \texttt{zcregion} environment provided by this package. -% -% -% \section{Checks} -% \label{sec:checks} -% -% \pkg{zref-check} provides several ``checks'' to be used with \cs{zcheck}. -% The checks may be combined in a \cs{zcheck} call, e.g.\ \opt{[close, -% after]}, or \opt{[thischap, before]}. In this case, each check in -% \meta{checks} is performed against each of the \meta{labels}. This is done -% independently for each check, which means, in practice, that the checks bear -% a logical \texttt{AND} relation to the others. Whether the combination is -% meaningful, is up to the user. As is the correspondence between the -% \meta{checks} and the \meta{text} in \cs{zcheck}. -% -% The use of checks which perform ``within the page'' comparisons -- namely -% \opt{above} and \opt{below} and, through them, \opt{before} and \opt{after} -% -- comes with some caveats you should be acquainted with. -% Section~\ref{sec:within-page-checks} discusses their limitations and expands -% on the expected workflow for their use to ensure reliable results. -% -% Note that the naming convention of the checks adopts the perspective of -% \cs{zcheck}. That is, the name of the check describes the position of the -% label being referred to, relative to the \cs{zcheck} call being made. For -% example, the \opt{before} check should issue no message if -% \cs{ztarget}|{mylabel}{...}| occurs before -% \cs{zcheck}|[before]{mylabel}{...}|. -% -% The available checks are the following: -% -% \begin{description}[leftmargin=0pt, itemindent=0pt, align=right, -% labelsep=1em, font=\MacroFont] -% -% \item[thispage] \meta{label} occurs on the same page as \cs{zcheck}. -% -% \item[prevpage] \meta{label} occurs on the previous page relative to -% \cs{zcheck}. -% -% \item[nextpage] \meta{label} occurs on the next page relative to -% \cs{zcheck}. -% -% \item[otherpage] \meta{label} occurs on a page different from that of -% \cs{zcheck}, that is, it does \emph{not} occur on \opt{thispage}. -% -% \item[pagegap] There is a page gap between \meta{label} and \cs{zcheck}, in -% other words, \meta{label} does \emph{not} occur on \opt{thispage}, -% \opt{prevpage} or \opt{nextpage}. -% -% \item[facing] On a \texttt{twoside} document, both \meta{label} and -% \cs{zcheck} fall onto a double spread, each on one of the two facing -% pages. -% -% \item[above] \meta{label} and \cs{zcheck} are both on the same page, and -% \meta{label} occurs ``above'' \cs{zcheck}. -% -% \item[below] \meta{label} and \cs{zcheck} are both on the same page, and -% \meta{label} occurs ``below'' \cs{zcheck}. -% -% \item[pagesbefore] \meta{label} occurs on any page before the one of -% \cs{zcheck}. -% -% \item[ppbefore] Convenience alias for \opt{pagesbefore}. -% -% \item[pagesafter] \meta{label} occurs on any page after the one of -% \cs{zcheck}. -% -% \item[ppafter] Convenience alias for \opt{pagesafter}. -% -% \item[before] Either \opt{above} or \opt{pagesbefore}. -% -% \item[after] Either \opt{below} or \opt{pagesafter}. -% -% \item[thischap] \meta{label} occurs on the same chapter as \cs{zcheck}. -% -% \item[prevchap] \meta{label} occurs on the previous chapter relative to the -% one of \cs{zcheck}. -% -% \item[nextchap] \meta{label} occurs on the next chapter relative to the one -% of \cs{zcheck}. -% -% \item[chapsbefore] \meta{label} occurs on any chapter before the one of -% \cs{zcheck}. -% -% \item[chapsafter] \meta{label} occurs on any chapter after the one of -% \cs{zcheck}. -% -% \item[thissec] \meta{label} occurs on the same section as \cs{zcheck}. -% -% \item[prevsec] \meta{label} occurs on the previous section (of the same -% chapter) relative to the one of \cs{zcheck}. -% -% \item[nextsec] \meta{label} occurs on the next section (of the same chapter) -% relative to the one of \cs{zcheck}. -% -% \item[secsbefore] \meta{label} occurs on any section (of the same chapter) -% before the one of \cs{zcheck}. -% -% \item[secsafter] \meta{label} occurs on any section (of the same chapter) -% after the one of \cs{zcheck}. -% -% \item[close] \meta{label} occurs within a page range from \opt{closerange} -% pages before the one of \cs{zcheck} to \opt{closerange} pages after it -% (about the \opt{closerange} option, see Section~\ref{sec:options}). -% -% \item[far] Not \opt{close}. -% -% \end{description} -% -% -% -% \section{Options} -% \label{sec:options} -% -% Options are a standard \texttt{key=value} comma separated list, and can be -% set globally either as \cs{usepackage}\oarg{options} at load-time (see -% Section~\ref{sec:loading-package}), or by means of \cs{zrefchecksetup} (see -% Section~\ref{sec:user-interface}) in the preamble. Most options can also be -% used with local effects, through the optional argument of \cs{zcheck}. -% -% \DescribeOption{hyperref} % -% Controls the use of \pkg{hyperref} by \pkg{zref-check} and takes values -% \opt{auto}, \opt{true}, \opt{false}. The default value, \opt{auto}, makes -% \pkg{zref-check} use \pkg{hyperref} if it is loaded, meaning \cs{zcheck} can -% be hyperlinked to the \emph{first label} in \meta{labels}. \opt{true} does -% the same thing, but warns if \pkg{hyperref} is not loaded (\pkg{hyperref} is -% never loaded for you). In either of these cases, if \pkg{hyperref} is -% loaded, module \pkg{zref-hyperref} is also loaded by \pkg{zref-check}. -% \opt{false} means not to use \pkg{hyperref} regardless of its availability. -% This is a preamble only option, but \cs{zcheck} provides granular control of -% hyperlinking by means of its starred version. -% -% -% \DescribeOption{msglevel} % -% Sets the level of messages issued by \cs{zcheck} failed checks and takes -% values \opt{warn}, \opt{info}, \opt{none}, \opt{infoifdraft}, -% \opt{warniffinal}. The default value, \opt{warn}, issues messages both to -% the terminal and to the log file, \opt{info} issues messages to the log file -% only, \opt{none} suppresses all messages. \opt{infoifdraft} corresponds to -% \opt{info} if option \opt{draft} is passed to \cs{documentclass}, and to -% \opt{warn} otherwise. \opt{warniffinal} corresponds to \opt{warn} if option -% \opt{final} is (explicitly) passed to \cs{documentclass} and \opt{info} -% otherwise. \opt{ignore} is provided as convenience alias for -% \opt{msglevel=none} for local use only. This option only affects the -% messages issued by the checks in \cs{zcheck}, not other messages or warnings -% of the package. In particular, it does not affect warnings issued for -% undefined labels, which just use \cs{zref@refused} and thus are the same as -% standard \LaTeX{} ones for this purpose. -% -% -% \DescribeOption{onpage} % -% Allows to control the messaging style for ``within page checks'', and takes -% values \opt{labelseq}, \opt{msg}, \opt{labelseqifdraft}, \opt{msgiffinal}. -% The default, \opt{labelseq}, uses the labels' shipout sequence, as retrieved -% from the \file{.aux} file, to infer relative position within the page. -% \opt{msg} also uses the same method for checking relative position, but -% issues a (different) message \emph{even if the check passes}, to provide a -% simple workflow for robust checking of ``false negatives'', considering the -% label sequence is not fool proof (for details and workflow recommendations, -% see Section~\ref{sec:within-page-checks}). \opt{msg} also issues its -% messages at the same level defined in \opt{msglevel}. \opt{labelseqifdraft} -% corresponds to \opt{labelseq} if option \opt{draft} is passed to -% \cs{documentclass} and to \opt{msg} otherwise. \opt{msgiffinal} corresponds -% to \opt{msg} if option \opt{final} is (explicitly) passed to -% \cs{documentclass}, and to \opt{labelseq} otherwise. -% -% -% \DescribeOption{closerange} % -% Defines the width of the range of pages, relative to the reference, that are -% considered ``close'' by the \opt{close} check. Takes a positive integer as -% value, with default 5. -% -% -% \section{Limitations} -% -% There are three qualitatively different kinds of checks being used by -% \cs{zcheck}, according to the source and reliability of the information they -% mobilize: page number checks, within page checks, and sectioning checks. -% -% -% \subsection{Page number checks} -% -% Page number checks -- \opt{thispage}, \opt{prevpage}, \opt{nextpage}, -% \opt{pagesbefore}, \opt{pagesafter}, \opt{facing} -- use the -% \texttt{abspage} property provided by the \pkg{zref-abspage} module. This -% is a solid piece of information, on which we can rely upon. However, -% despite that, page number checks may still become ill-defined, if the -% \meta{text} argument in \cs{zcheck}, when typeset, crosses page boundaries, -% starting in one page, and finishing in another. The same can happen with -% the text in \cs{zctarget} and the \texttt{zcregion} environment. -% -% This is why the user commands of this package set a pair or labels around -% \meta{text}. So, when checking \cs{zcheck} against a regular -% \texttt{zlabel} both the start and the end of the \meta{text} are checked -% against the label, and the check fails if either of them fails. When -% checking \cs{zcheck} against a \cs{zctarget} or a \texttt{zcregion}, both -% beginnings and ends are checked against each other two by two, and if any of -% them fails, the check fails. In other words, if a page number checks -% passes, we know that the entire \meta{text} arguments pass it. -% -% This is a corner case (albeit relevant) which must be taken care of, and it -% is possible to do so robustly. Hence, we can expect reliable results in -% these tests. -% -% -% \subsection{Within page checks} -% \label{sec:within-page-checks} -% -% When both label and reference fall on the same page things become much -% trickier. This is basically the case of the checks \opt{above} and -% \opt{below} (and, through them, \opt{before} and \opt{after}). There is no -% equally reliable information (that I know of) as we have for the page number -% checks for this, especially when floats come into play. Which, of course, -% is the interesting case to handle. -% -% To infer relative position of label and reference on the same page, -% \pkg{zref-check} uses the labels' shipout sequence, which is retrieved at -% load-time from the order in which the labels occur in the \file{.aux} file. -% Indeed, \pkg{zref} writes labels to the \file{.aux} file at shipout (and, -% hence, in shipout order), and needs to do so, because a number of its -% properties are only available at that point. -% -% However, even if this method will buy us a correct check for a regular float -% on a regular page (which, to be fair, is a good result), it is not difficult -% do conceive situations in which this sequence may not be meaningful, or even -% correct, for the case. A number of cases which may do so are: two column -% documents, text wrapping, scaling, overlays, etc. (I don't know if those -% make the method fail, I just don't know if they don't). Therefore, the -% \texttt{labelseq} should be taken as a \emph{proxy} and not fully reliable, -% meaning that the user should be watchful of its results. -% -% For this reason, \pkg{zref-check} provides an easy way to do so, by allowing -% specific control of the messaging style of the checks which do within page -% comparisons though the option \opt{onpage}. The concern is not really with -% false positives (getting a warning when it was not due), but with false -% negatives (not getting a warning when it was due). Hence, setting -% \opt{onpage} to \opt{msg} at a final typesetting stage (or just set it to -% \opt{labelseqifdraft} or \opt{msgiffinal} if that's part of your workflow) -% provides a way to easily identify all cases of such checks (failing or -% passing), and double-check them. In case the test is passing though, the -% message is different from that of a failing check, to quickly convey why you -% are getting the message. This option can also be set at the local level, if -% the page in question is known to be problematic, or just atypical. -% -% -% \subsection{Sectioning checks} -% -% The information used by sectioning checks is provided by means of dedicated -% counters for chapters and sections, similarly as standard counters for them, -% but which are stepped and reset regardless of whether these sectioning -% commands are numbered or not (that is, starred or not). And this for two -% reasons. First, we don't need the absolute counter value to be able to make -% the kind of relative statement we want to do here. Second, this allows us -% to have these checks work for numbered and unnumbered sectioning commands -% without having to worry about how those are used within the document. -% -% The caveat is that the package does this by hooking into \cs{chapter} and -% \cs{section}, which poses two restrictions for the proper working of these -% checks. First, we are using the new hook system for this, as provided by -% \pkg{ltcmdhooks}, which means a \LaTeX{} kernel later than 2021-06-01 is -% required. Second, since we are hooking into \cs{chapter} and \cs{section}, -% these checks presume these commands are being used by the document class for -% this purpose (either directly, or internally as, for example, KOMA-Script's -% \cs{addchap} and \cs{addsec} do). If that's not the case, additional setup -% may be needed for these checks to work as expected. -% -% -% -% \section{Change history} -% -% A change log with relevant changes for each version, eventual upgrade -% instructions, and upcoming changes, is maintained in the package's -% repository, at -% \url{https://github.com/gusbrs/zref-check/blob/main/CHANGELOG.md}. The -% change log is also distributed with the package's documentation through CTAN -% upon release so, most likely, \texttt{texdoc zref-check/changelog} should -% provide easy local access to it. An archive of historical versions of the -% package is also kept at \url{https://github.com/gusbrs/zref-check/releases}. -% -% -% -% \end{documentation} -% -% -% \begin{implementation} % % \section{Initial setup} % @@ -501,6 +72,7 @@ % the new hook system in \pkg{ltcmdhooks}, which was released with the % 2021/06/01 \LaTeX{} kernel. % \begin{macrocode} +\NeedsTeXFormat{LaTeX2e} \providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion} \IfFormatAtLeastTF{2021-06-01} {} @@ -516,7 +88,7 @@ % % Identify the package. % \begin{macrocode} -\ProvidesExplPackage {zref-check} {2022-07-07} {0.3.2} +\ProvidesExplPackage {zref-check} {2023-06-14} {0.3.3} {Flexible cross-references with contextual checks based on zref} % \end{macrocode} % @@ -531,18 +103,15 @@ % % \section{\pkg{zref} setup} % -% \begin{variable}{\g_@@_abschap_int, \g_@@_abssec_int} -% Provide absolute counters for section and chapter, and respective -% \pkg{zref} properties, so that we can make checks about relation of -% chapters/sections regardless of internal counters, since we don't get -% those for the unnumbered (starred) ones. Thanks Ulrike Fischer for -% suggestions at TeX.SX about the proper place to make the hooks for this -% purpose. +% Provide absolute counters for section and chapter, and respective \pkg{zref} +% properties, so that we can make checks about relation of chapters/sections +% regardless of internal counters, since we don't get those for the unnumbered +% (starred) ones. Thanks Ulrike Fischer for suggestions at TeX.SX about the +% proper place to make the hooks for this purpose. % \begin{macrocode} \newcounter { zc@abschap } \newcounter { zc@abssec } [ zc@abschap ] % \end{macrocode} -% \end{variable} % % % If the documentclass does not define \cs{chapter} the only thing that @@ -2404,13 +1973,9 @@ % \end{macro} % % -% -% % \begin{macrocode} %</package> % \end{macrocode} % % \PrintIndex % -% \end{implementation} -% diff --git a/macros/latex/contrib/zref-check/zref-check.ins b/macros/latex/contrib/zref-check/zref-check.ins index fe58b39e69..e0511ea791 100644 --- a/macros/latex/contrib/zref-check/zref-check.ins +++ b/macros/latex/contrib/zref-check/zref-check.ins @@ -4,7 +4,7 @@ % % This file is part of the LaTeX package "zref-check". % -% Copyright (C) 2021-2022 Gustavo Barros +% Copyright (C) 2021-2023 Gustavo Barros % % It may be distributed and/or modified under the conditions of the % LaTeX Project Public License (LPPL), either version 1.3c of this @@ -22,7 +22,7 @@ % % This work consists of the files zref-check.dtx, % zref-check.ins, -% zref-check.tex, +% zref-check-doc.tex, % zref-check-code.tex, % and the files generated from them. % @@ -50,7 +50,7 @@ This file was generated from file(s) of the LaTeX package "zref-check". -Copyright (C) 2021-2022 Gustavo Barros +Copyright (C) 2021-2023 Gustavo Barros It may be distributed and/or modified under the conditions of the LaTeX Project Public License (LPPL), either version 1.3c of this @@ -68,7 +68,7 @@ This work is "maintained" (as per LPPL maintenance status) by This work consists of the files zref-check.dtx, zref-check.ins, - zref-check.tex, + zref-check-doc.tex, zref-check-code.tex, and the files generated from them. diff --git a/macros/latex/contrib/zref-check/zref-check.tex b/macros/latex/contrib/zref-check/zref-check.tex deleted file mode 100644 index de1cdb8225..0000000000 --- a/macros/latex/contrib/zref-check/zref-check.tex +++ /dev/null @@ -1,94 +0,0 @@ -% \iffalse meta-comment -% -% File: zref-check.tex -% -% This file is part of the LaTeX package "zref-check". -% -% Copyright (C) 2021-2022 Gustavo Barros -% -% It may be distributed and/or modified under the conditions of the -% LaTeX Project Public License (LPPL), either version 1.3c of this -% license or (at your option) any later version. The latest version -% of this license is in the file: -% -% https://www.latex-project.org/lppl.txt -% -% and version 1.3 or later is part of all distributions of LaTeX -% version 2005/12/01 or later. -% -% -% This work is "maintained" (as per LPPL maintenance status) by -% Gustavo Barros. -% -% This work consists of the files zref-check.dtx, -% zref-check.ins, -% zref-check.tex, -% zref-check-code.tex, -% and the files generated from them. -% -% The released version of this package is available from CTAN. -% -% ----------------------------------------------------------------------- -% -% The development version of the package can be found at -% -% https://github.com/gusbrs/zref-check -% -% for those people who are interested. -% -% ----------------------------------------------------------------------- -% -% \fi - -\documentclass{l3doc} - -% Have \GetFileInfo pick up date and version data -\usepackage{zref-check} - -\NewDocumentCommand\opt{m}{\texttt{#1}} -% Temporary workaround for 'l3doc' bug. -% https://github.com/latex3/latex3/issues/1111 -% FIXME Remove when fixed upstream. -\NewDocElement[ - macrolike = false , - printtype = \textit{opt.} , -]{Option}{optiondesc} - -\begin{document} - -\GetFileInfo{zref-check.sty} - -\title{% - The \pkg{zref-check} package% - \thanks{This file describes \fileversion, released \filedate.}% -} - -\author{% - Gustavo Barros% - \thanks{\url{https://github.com/gusbrs/zref-check}}% -} - -\date{\filedate} - -\maketitle - -\begin{abstract} - \pkg{zref-check} provides an user interface for making \LaTeX{} - cross-references flexibly, while allowing to have them checked for - consistency with the document structure as typeset. Statements such as - ``above'', ``on the next page'', ``previously'', ``as will be discussed'', - ``on the previous chapter'' and so on can be given to \cs{zcheck} in - free-form, and a set of ``checks'' can be specified to be run against a - given \texttt{label}, which will result in a warning at compilation time if - any of these checks fail. \cs{zctarget} and the \texttt{zcregion} - environment are also defined as a means to easily set label targets to - arbitrary places in the text which can be referred to by \cs{zcheck}. -\end{abstract} - -\tableofcontents - -\DisableImplementation - -\DocInput{zref-check.dtx} - -\end{document} diff --git a/macros/latex/contrib/zref-clever/CHANGELOG.md b/macros/latex/contrib/zref-clever/CHANGELOG.md index 8cbd673f55..7c02e101a0 100644 --- a/macros/latex/contrib/zref-clever/CHANGELOG.md +++ b/macros/latex/contrib/zref-clever/CHANGELOG.md @@ -1,6 +1,38 @@ # Changelog -## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.3.6...HEAD) +## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.4.0...HEAD) + +## [v0.4.0](https://github.com/gusbrs/zref-clever/compare/v0.3.6...v0.4.0) (2023-06-14) + +### Added +- `labelhook` option, controlling whether to set a `\zlabel` alongside a + standard `\label`. This option uses the kernel's new `label` hook, which + significantly improves and simplifies the task of setting a `\zlabel` in + places where this is not directly supported. The option is enabled by + default, and strongly recommended. It is not expected that this change will + bring backward compatibility problems, `\zlabel`s continue to work just as + before, and the places where a `\label` is required will also continue to + work the same way. The only case I see where you might need to adjust + existing documents is if you already had both `\label`s and `\zlabel`s with + the same names, in which case now you'll have a duplicate `zlabel` and will + indeed have to correct it. Also, you may be interested in taking a look at + the "`\label` or `\zlabel`?" section of the User manual, since the option + opens the possibility of a different approach in label setting in your + documents. + +### Changed +- Given the new `labelhook` option and the fact that it requires both the new + `label` hook and the new hooks with options released in the latest LaTeX + kernel, the kernel version required by `zref-clever` has been bumped to + 2023-06-01. + +### Removed +- Given the new `labelhook` option, the parts of compatibility modules which + provided for setting `\zlabel`s with `\label` in places where the former is + not supported have been removed. These would conflict with the new option, + and the use of the `label` hook for this purpose renders them unnecessary + and is superior in every aspect. Namely, the compatibility modules changed + in this fashion are: `amsmath`, `memoir`, and `listings`. ## [v0.3.6](https://github.com/gusbrs/zref-clever/compare/v0.3.5...v0.3.6) (2023-02-21) 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 87eb00b7d8..f2e55277a1 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-code.tex b/macros/latex/contrib/zref-clever/zref-clever-code.tex index ba3a5eaaa2..ec9210dd67 100644 --- a/macros/latex/contrib/zref-clever/zref-clever-code.tex +++ b/macros/latex/contrib/zref-clever/zref-clever-code.tex @@ -22,7 +22,7 @@ % % This work consists of the files zref-clever.dtx, % zref-clever.ins, -% zref-clever.tex, +% zref-clever-doc.tex, % zref-clever-code.tex, % and the files generated from them. % diff --git a/macros/latex/contrib/zref-clever/zref-clever-doc.pdf b/macros/latex/contrib/zref-clever/zref-clever-doc.pdf Binary files differnew file mode 100644 index 0000000000..46429193c9 --- /dev/null +++ b/macros/latex/contrib/zref-clever/zref-clever-doc.pdf diff --git a/macros/latex/contrib/zref-clever/zref-clever.tex b/macros/latex/contrib/zref-clever/zref-clever-doc.tex index 138e4e938e..23645f429e 100644 --- a/macros/latex/contrib/zref-clever/zref-clever.tex +++ b/macros/latex/contrib/zref-clever/zref-clever-doc.tex @@ -22,7 +22,7 @@ % % This work consists of the files zref-clever.dtx, % zref-clever.ins, -% zref-clever.tex, +% zref-clever-doc.tex, % zref-clever-code.tex, % and the files generated from them. % @@ -331,7 +331,11 @@ Indeed, to use \pkg{zref}, instead of setting a \cs{label} and making a \cs{ref}, one would set a \cs{zlabel} and make \cs{zref}s to it, in pretty much the same way as for the standard system. \pkg{zref-clever} introduces the more featureful \cs{zcref} for making references, but relies on -\pkg{zref}'s \cs{zlabel} for label setting. +\pkg{zref}'s \cs{zlabel} for label setting. \pkg{zref-clever} provides that a +\cs{label} also sets a \cs{zlabel} with the same name using the kernel's +\texttt{label} hook (see the \opt{labelhook} option in \zcref{sec:options}), +so that you can use it too with standard \cs{label}s (see the +\zcref{sec:label-or-zlabel} for discussion). A basic document using \pkg{zref-clever} is shown in \zcref{how:basic} which, despite the small necessary adjustments, should feel very familiar to any @@ -403,7 +407,7 @@ available at \zcref{sec:how-tos}. The package does not accept load-time options, package options must be set using \cs{zcsetup} (see \zcref{sec:user-interface}). -\pkg{zref-clever} requires a recent \LaTeX{} kernel (2021-11-15 or newer) and +\pkg{zref-clever} requires a recent \LaTeX{} kernel (2023-06-01 or newer) and the packages \pkg{zref}, including some of its modules, and \pkg{ifdraft}. It also requires UTF-8 input encoding, which has been the kernel's default for some time. @@ -411,7 +415,7 @@ some time. \section{Dependencies} -\pkg{zref-clever} requires \pkg{zref}, and \LaTeX{} kernel 2021-11-15, or +\pkg{zref-clever} requires \pkg{zref}, and \LaTeX{} kernel 2023-06-01, or newer. It also needs \pkg{ifdraft}. Some packages are leveraged by \pkg{zref-clever} if they are present, but are not loaded by default or required by it, namely: \pkg{hyperref}, \pkg{zref-check}, and \pkg{zref}'s @@ -487,6 +491,49 @@ Sets \meta{label} for referencing with \cs{zref} and, thus, also \cs{zcref}. \cs{label} for \pkg{zref}'s referencing system. +\section{\cs{label} or \cs{zlabel}?} +\zlabel{sec:label-or-zlabel} + +Technically, \pkg{zref}'s referencing system, and thus also \pkg{zref-clever}, +require a label set with \cs{zlabel} to make a reference. However, the +\opt{labelhook} option (see \zcref{sec:options}) leverages the kernel's +\texttt{label} hook to also set a \cs{zlabel} when a standard \cs{label} is +called, so that we can simply use \cs{label}s in our document and refer to +them with either referencing system. Indeed, in some places the use of +\cs{label} this way may be required (see +\zcref{sec:limitations,sec:comp-modules}). That given, which is to be +preferred: use \cs{label} all around or normally use \cs{zlabel} and, +occasionally resort to \cs{label} where required? I guess it depends, but we +can reason the pros and cons of both alternatives. + +Simply using \cs{label} across your document clearly speaks for convenience. +You don't have to worry with the exceptional case where a \cs{zlabel} may not +work or setting it is not possible. You can use either referencing system for +your labels as desired. Your favorite editor may have some facilities to ease +the insertion of labels, but does not support \cs{zlabel}. And so on. The +only disadvantage I can see with this approach is that two labels end up in +the \file{.aux} file which, arguably, may be seen as a redundancy, or waste. + +It is probably fair to consider this redundancy, in most use cases, as a +negligible cost. But you may disagree, or the size of your document or your +requirements may say otherwise, in which case you may prefer the second +approach and use \cs{zlabel} normally, with some occasional \cs{label} where +needed. Known relevant cases where \cs{label} is required are documented in +the manual (see \zcref{sec:how-tos,sec:limitations,sec:comp-modules}), but +some trial and error can easily cover the gap for the remaining cases. They +are also rare cases. So finding out where \cs{label} is required should not +be much of a trouble either. + +I think the first approach does deserve the status of ``recommended'' for +normal use cases and documents. Despite that, note that the examples of this +manual typically use the second approach. There's a historic reason for this, +since most of them were created before the kernel's \texttt{label} hook was +available, so that it was really the only approach. However, I'll keep the +examples this way, notwithstanding this recommendation, because it is also +important to document the limitations of directly using \cs{zlabel}, for those +who may want to use the second approach. + + \section{Options} \zlabel{sec:options} @@ -906,6 +953,19 @@ Its default value is, quite naturally, \cs{@currentcounter}. The default value can be reset by calling the option with no value. Since this option only affects how labels are set, it is not available in \cs{zcref}. +\DescribeOption{\raisebox{.4em}{\dbend}\ labelhook} % +\opt{labelhook} is a boolean option which controls whether \pkg{zref-clever} +uses the kernel's \texttt{label} hook to, whenever a standard \cs{label} is +called, also set a \cs{zlabel} with the same name. The package's default +value is \texttt{true} so that one can use \cs{label}s along the document and +refer to them (also) with \pkg{zref} and \pkg{zref-clever} reference commands. +This value is not only the default, but also a recommended value. Disabling +this option means you are on your own to handle cases where \cs{zlabel} does +not work, which are not many, but can be tricky to deal with where they occur. +Since this option only affects how labels are set, it is not available in +\cs{zcref}. See \zcref{sec:label-or-zlabel} for some discussion of different +labeling approaches this options allows for. + \DescribeOption{nocompat} % Some packages, document classes, or LaTeX features may require specific support to work with \pkg{zref-clever} (see \zcref{sec:limitations}). @@ -1845,14 +1905,19 @@ package in the setup, the same procedure can be used with \cls{memoir}'s \zctask{Make references to \pkg{amsmath} display math environments.} -Given how \pkg{amsmath}'s display math environments work, they need to handle -\cs{label} specially, and this support is quite hard-wired into the -environments, but it is not extended to \cs{zlabel}. \pkg{zref-clever}'s -\opt{amsmath} compatibility module provides that a \cs{label} used inside -these environments set both a regular \cs{label} and a \cs{zlabel}, so that we -can refer to the equations with both referencing systems. Note the use of -\cs{zlabel} for \env{subequations} though. For more details, see the -description of the \opt{amsmath} compatibility module at +\pkg{amsmath}'s display math environments have their contents processed twice, +once for measuring and the second does the final typesetting. Hence, +\pkg{amsmath} needs to handle \cs{label} specially inside these environments, +otherwise we'd have duplicate labels all around, and indeed it does redefine +\cs{label} locally inside them. Alas, the same treatment is not granted to +\cs{zlabel}. Therefore, you must use \cs{label} (not \cs{zlabel}) inside +\pkg{amsmath}'s display math environments, and the \opt{labelhook} option +provides that a \cs{label} sets both a regular \cs{label} and a \cs{zlabel}, +so that we can refer to the equations with both referencing systems. The +following environments are subject to this usage restriction: \env{equation}, +\env{align}, \env{alignat}, \env{flalign}, \env{xalignat}, \env{gather}, +\env{multline}, and their respective starred versions. For more details, see +the description of the \opt{amsmath} compatibility module at \zcref{sec:comp-modules}. \begin{zchowto}[caption={\pkg{amsmath}},label={how:amsmath}] @@ -1870,7 +1935,7 @@ description of the \opt{amsmath} compatibility module at A^{(1)}_l =\begin{cases} n!,&\text{if }l =1\\ 0,&\text{otherwise}.\end{cases} \end{equation*} -\begin{subequations}\zlabel{eq:3} +\begin{subequations}\label{eq:3} \begin{align} A+B&=B+A\\ C&=D+E\label{eq:3b}\\ @@ -1926,14 +1991,13 @@ regardless of what the current counter is. \pkg{listings} package.} Being \env{lstlisting} a verbatim environment, setting labels inside it -requires special treatment. \pkg{zref-clever}'s \opt{listings} compatibility -module provides that a label given to the \opt{label} option gets set with -both a regular \cs{label} and a \cs{zlabel}, so that we can refer to it with -both referencing systems. Setting labels for specific lines of the -environment can be done with \cs{zlabel} directly, subject to the same -escaping as for the standard \cs{label}. For more details, see the -description of the \opt{listings} compatibility module at -\zcref{sec:comp-modules}. +requires special treatment. \pkg{zref-clever}'s \opt{labelhook} option +provides that a label given to the \opt{label} option gets set with both a +regular \cs{label} and a \cs{zlabel}, so that we can refer to it with both +referencing systems. Setting labels for specific lines of the environment can +be done with \cs{zlabel} directly, subject to the same escaping as for the +standard \cs{label}. For more details, see the description of the +\opt{listings} compatibility module at \zcref{sec:comp-modules}. \begin{zchowto}[caption={\pkg{listings}},label={how:listings},escapeinside=`'] \documentclass{article} @@ -2101,7 +2165,50 @@ with the \opt{label type} option. This is \zcref{th:theo} on \zcpageref{th:theo} and it is titled ``\zcref[noname,ref=title]{th:theo}''. \end{mytheo} -\end{document}\end{zchowto} +\end{document} +\end{zchowto} + + +\subsection{\pkg{breqn}} + +\zctask{Make references to \pkg{breqn} math environments.} + +\pkg{breqn}'s math environments \env{dgroup}, \env{dmath}, \env{dseries}, and +\env{darray} offer a \opt{label} option (plus \opt{labelprefix}) for the +purpose of label setting. \pkg{breqn}'s documentation says the following +about the use of \cs{label} inside its environments: \textquote{Use of the + normal \cs{label} command instead of the \opt{label} option works, I think, + most of the time (untested)}. My light testing suggests the same is true +for \cs{zlabel}, which can then be used directly in these environments. +Either way, given the \opt{labelhook} option, we can just use \pkg{breqn}'s +\opt{label} option and be at ease. Also, \pkg{breqn} does not use +\cs{refstepcounter} to increment the equation counters and, as a result, fails +to set \pkg{hyperref} anchors for the equations (thus affecting standard +labels too). You may wish to use the work-around provided by Heiko Oberdiek +at \url{https://tex.stackexchange.com/a/241150}. + +\begin{zchowto}[caption={\pkg{breqn}},label={how:breqn}] +\documentclass{article} +\usepackage{zref-clever} +\usepackage{breqn} +\usepackage{hyperref} +% From https://tex.stackexchange.com/a/241150. +\usepackage{etoolbox} +\makeatletter +\patchcmd\eq@setnumber{\stepcounter}{\refstepcounter}{}{% + \errmessage{Patching \noexpand\eq@setnumber failed}} +\makeatother +\begin{document} +\section{Section 1} +\begin{dmath}[label={eq:1}] + f(x)=\frac{1}{x} \condition{for $x\neq 0$} +\end{dmath} +\begin{dmath}[labelprefix={eq:},label={2}] + H_2^2 = x_1^2 + x_1 x_2 + x_2^2 - q_1 - q_2 +\end{dmath} +\zcref{eq:1, eq:2} +\end{document} +\end{zchowto} \subsection{Ordinal references} @@ -2181,6 +2288,15 @@ verbatim-like environments it depends on how they are defined and whether they provide a proper place or option to do so. But other places may be problematic too, for example, \pkg{amsmath} display math environments also handle \cs{label} specially and the same work is not done for \cs{zlabel}. +Classes and packages may offer label setting by means of arguments or options, +and those usually only cater for the standard referencing system, etc. +Fortunately for us, the \texttt{label} hook introduced by the \LaTeX{} kernel +in the 2023-06-01 release improves the situation considerably. +\pkg{zref-clever} makes use of it with the \opt{labelhook} option, enabled by +default, so that a standard \cs{label} also sets a \cs{zlabel} with the same +name, thus providing a very general and reliable way to deal with these places +where setting a \cs{zlabel} directly is problematic: just set a standard +label. Regarding the second, a correctly set \cs{@currentcounter} is critical for the task of \pkg{zref-clever}: the reference type will depend on that and, @@ -2198,7 +2314,7 @@ which at least allows for some viable work-arounds when the value of to set it, depends on the case. Still, \cs{refstepcounter} is ubiquitous enough a tool that we can count on \cs{@currentcounter} most of the time. -All in all, most things work, but some things don't. And if the later will +All in all, most things work, but some things may not. And if the later will eventually work depends essentially on whether support for \pkg{zref} is provided by the relevant packages and classes or not. Or, failing that, whether \pkg{zref-clever} is able to provide some specific support when a @@ -2260,62 +2376,22 @@ features with support for the following: i) set counter types for counters \texttt{subfigure}, \texttt{subtable}, and \texttt{poemline} (used in the \env{verse} environment); ii) configure resetting behavior (\opt{counterresetby} option) for \texttt{subfigure} and \texttt{subtable} -counters; iii) provide that the \meta{label} arguments to environments -\env{sidecaption} and \env{sidecontcaption} and commands \cs{bitwonumcaption}, -\cs{bionenumcaption}, and \cs{bicaption} \emph{also} set a \cs{zlabel} of the -same name; iv) provide the \pkg{zref} property ``\texttt{subcaption}'' so that +counters; iii) provide the \pkg{zref} property ``\texttt{subcaption}'' so that we can refer to, for example, \texttt{\cs{zcref}[ref=subcaption]\{subcap-1\}} -to emulate the functionality of \cls{memoir}'s \cs{subcaptionref}; v) provide +to emulate the functionality of \cls{memoir}'s \cs{subcaptionref}; iv) provide that \cs{footnote}, \cs{verbfootnote}, \cs{sidefootnote}, and \cs{pagenote} get a proper \opt{currentcounter} set; and v) set counter types for counters -\texttt{sidefootnote} and \texttt{pagenote}. Naturally, the sheer number of -features that required some specific support implies that some gymnastics were -needed here. But the most sensitive changes are: i) a local redefinition of -\cs{label} inside the environments \env{sidecaption} and \env{sidecontcaption} -and the commands \cs{bitwonumcaption}, \cs{bionenumcaption}, and -\cs{bicaption}; and ii) the use of \pkg{ltcmdhooks} command hooks on -\cs{bitwonumcaption}, \cs{bionenumcaption}, \cs{bicaption}, -\cs{@memsubcaption}, \cs{@makefntext}, and \cs{@makesidefntext}. +\texttt{sidefootnote} and \texttt{pagenote}. The most sensitive changes are +the use of \pkg{ltcmdhooks} command hooks on \cs{@memsubcaption}, +\cs{@makefntext}, and \cs{@makesidefntext}. \DescribeOption{amsmath} % -\pkg{amsmath}'s display math environments have their contents processed twice, -once for measuring and the second does the final typesetting. Hence, -\pkg{amsmath} needs to handle \cs{label} specially inside these environments, -otherwise we'd have duplicate labels all around, and indeed it does redefine -\cs{label} locally inside them. Alas, the same treatment is not granted to -\cs{zlabel}. However, \cs{label} is set basically to \emph{store} the value -of the argument inside the environments, and its global meaning is kept in -\cs{ltx@label} which is called at the appropriate time to actually set the -label. So, what \pkg{zref-clever} does is redefine \cs{ltx@label} to set -\texttt{both} a regular \cs{label} and a \cs{zlabel} for the same \meta{label} -(which does not generate a duplicate label problem since the referencing -systems are independent). Therefore, you must use \cs{label} (not -\cs{zlabel}) inside \pkg{amsmath}'s display math environments, and this -compatibility module arranges that you can also refer to that label with -\pkg{zref} and, thus, with \cs{zcref} as well. The following environments are -subject to this usage restriction: \env{equation}, \env{align}, \env{alignat}, -\env{flalign}, \env{xalignat}, \env{gather}, \env{multline}, and their -respective starred versions. In particular, the same is not the case for the -\env{subequations} environment, inside which \cs{zlabel} works as usual (to -refer to the main equation number, that is, right after -\texttt{\cs{begin}\{subequations\}}). See the \zcref{how:amsmath} for an -usage example. The module also ensures proper \opt{currentcounter} values are -in place for the display math environments, for which it uses environment -hooks, and sets the font of equation references to \cs{upshape}, following -\pkg{amsmath}'s \cs{eqref}. Finally, the module also provides a -\texttt{subeq} property, for display math environments used inside the -\env{subequations} environment, which can be used to refer to them directly -with the \opt{ref} option, or to build terse ranges with the \opt{endrange} -option. Note that \pkg{zref-clever} is not the only package to redefine -\cs{ltx@label}, and compatibility problems may arise if this module is used -with such packages or with document classes that do the same. In case of -trouble, you can load \pkg{zref-clever} with option \texttt{nocompat=amsmath} -and either use the standard referencing system's facilities to refer to -\pkg{amsmath}'s equations or check the code documentation for the technique -used for this (which is pretty standard) and adapt it to your case. Given -that any trouble that may arise here is one of the proper ``timing'' of the -redefinition, it should not be particularly complicated to make such -adjustments. +The module ensures proper \opt{currentcounter} values are in place for the +display math environments, for which it uses environment hooks. The module +also provides a \texttt{subeq} property, for display math environments used +inside the \env{subequations} environment, which can be used to refer to them +directly with the \opt{ref} option, or to build terse ranges with the +\opt{endrange} option. \DescribeOption{mathtools} % \pkg{mathtools} has a feature to show the numbers only for those equations @@ -2330,33 +2406,14 @@ side. \DescribeOption{breqn} % This compatibility module only sets proper \opt{currentcounter} values for the environments \env{dgroup}, \env{dmath}, \env{dseries}, and \env{darray}, and -uses environment hooks for the purpose. Note that these environments offer a -\opt{label} option for label setting, but implements it in a way that is -somewhat tricky to grab for our purposes, so we don't do it. However, -\pkg{breqn}'s documentation says the following about the use of \cs{label} -inside its environments: \textquote{Use of the normal \cs{label} command - instead of the \opt{label} option works, I think, most of the time - (untested)}. My light testing suggests the same is true for \cs{zlabel}, -which can then be used directly in these environments. But the ``second -class'' status for this use is the one granted by \pkg{breqn}, there's not -much we can do here. If you have any trouble with this, you may wish to check -\zcref{wkrnd:breqn}. +uses environment hooks for the purpose. See the \zcref{how:breqn} for an +usage example. \DescribeOption{listings} % -Being \env{lstlisting}s environments what they are, one cannot simply place a -label inside them without special treatment. \pkg{listings} arranges to this -by providing a \opt{label} option for setting a label for the whole -environment, and a properly escaped label command inside the environment can -be used to refer to the line number. While the later can also be used to set -a \cs{zlabel} to make line number references, the \opt{label} option is -catered to the standard labels exclusively. Hence, this compatibility module -uses the same label name -- which luckily and atypically is stored in a -variable -- and sets a \cs{zlabel} as well. This is done by using -\pkg{listings}' \texttt{PreInit} hook, se we don't have to redefine or tamper -with anything for the purpose. Besides this, the module also sets appropriate -\opt{countertype}, \opt{counterresetby} and \opt{currentcounter} values for -the \pkg{listings}' counters: \texttt{lstlisting} and \texttt{lstnumber}. See -the \zcref{how:listings} for an usage example. +The module sets appropriate \opt{countertype}, \opt{counterresetby} and +\opt{currentcounter} values for the \pkg{listings}' counters: +\texttt{lstlisting} and \texttt{lstnumber}. See the \zcref{how:listings} for +an usage example. \DescribeOption{enumitem} % \LaTeX{}'s \env{enumerate} environment requires some special treatment from @@ -2407,54 +2464,6 @@ sort, but from \pkg{zref-clever}'s perspective, their status is ``not supported''. -\subsection*{\pkg{breqn}} - -As mentioned in \opt{breqn}'s compatibility module (\zcref{sec:comp-modules}), -\pkg{breqn}'s math environments \env{dgroup}, \env{dmath}, \env{dseries}, and -\env{darray} offer a \opt{label} option (plus \opt{labelprefix}) for the -purpose of label setting. Setting a \cs{zlabel} alongside with a regular -\cs{label} based on that option requires redefining some of \pkg{breqn} -internals. Also, \pkg{breqn} does not use \cs{refstepcounter} to increment -the equation counters and, as a result, fails to set \pkg{hyperref} anchors -for the equations (thus affecting standard labels too). The example below -also provides to that.\footnote{The later work-around thanks to Heiko - Oberdiek, at \url{https://tex.stackexchange.com/a/241150}.} - - -\begin{zcworkaround}[caption={\pkg{breqn}},label={wkrnd:breqn}] -\documentclass{article} -\usepackage{zref-clever} -\usepackage{breqn} -\makeatletter -\define@key{breqn}{label}{% - \edef\next@label{% - \noexpand\label{\next@label@pre#1}% - \noexpand\zlabel{\next@label@pre#1}}% - \let\next@label@pre\@empty} -\makeatother -\usepackage{hyperref} -\usepackage{etoolbox} -\makeatletter -\patchcmd\eq@setnumber{\stepcounter}{\refstepcounter}{}{% - \errmessage{Patching \noexpand\eq@setnumber failed}} -\makeatother -\begin{document} -\section{Section 1} -\begin{dmath}[label={eq:1}] - f(x)=\frac{1}{x} \condition{for $x\neq 0$} -\end{dmath} -\begin{dmath}[labelprefix={eq:},label={2}] - H_2^2 = x_1^2 + x_1 x_2 + x_2^2 - q_1 - q_2 -\end{dmath} -\zcref{eq:1, eq:2} -\end{document} -\end{zcworkaround} - -Of course, you can always adapt things to your needs and, e.g., make the -\opt{label} option set just \cs{zlabel} instead of both labels, or create a -separate \opt{zlabel} option. - - \subsection*{\cls{beamer}} \cls{beamer} does some really atypical things with regard to cross-references. @@ -2536,16 +2545,13 @@ A couple of caveats though. First, there's probably still some work to be done there in defining and setting reference types for \cls{beamer} specific document objects, e.g. overlays. But it can be done by the standard user interface of \pkg{zref-clever}. Second, since \cls{beamer}'s anchoring system -does not provide for uniqueness of anchors as \pkg{hyperref} does, the -procedure used by \pkg{zref-clever} in its \opt{amsmath} compatibility module -of setting both \cs{label} and \cs{zlabel} in \pkg{amsmath}'s display math -environments will result in duplicate anchors for labels set in them, with -corresponding \pkg{hyperref} warnings of ``destination with the same -identifier has been already used, duplicate ignored''. The warning is -actually harmless in this case, since both labels are set in the same place, -and thus have identical anchors. But, if it bothers you enough, you can look -at the \opt{amsmath} compatibility module in the code documentation, and -adjust things so that it sets only a \cs{zlabel}. +does not provide for uniqueness of anchors as \pkg{hyperref} does, if you +(need to) use \cs{label} to set both \cs{label} and \cs{zlabel}, relying on +the \opt{labelhook} option, this will result in duplicate anchors for labels +set in them, with corresponding \pkg{hyperref} warnings of ``destination with +the same identifier has been already used, duplicate ignored''. The warning +is actually harmless in this case, since both labels are set in the same +place, and thus have identical anchors, it is nevertheless there. \section{Acknowledgments} @@ -2589,6 +2595,7 @@ were generously provided by (in chronological order): % 2022-01-12: https://chat.stackexchange.com/transcript/message/60129233#60129233 % 2022-04-09: https://github.com/latex3/hyperref/issues/229#issuecomment-1093870142 % 2023-01-02: https://tex.stackexchange.com/q/670399 (comments) + % 2023-06-01: https://github.com/latex3/latex2e/pull/956 Phelype Oleinik, % 2021-08-20: https://tex.stackexchange.com/q/611370 (comments) % 2021-09-09: https://tex.stackexchange.com/a/614704 @@ -2596,6 +2603,7 @@ were generously provided by (in chronological order): % 2021-10-21: https://github.com/latex3/latex2e/pull/699 % 2022-01-12: https://tex.stackexchange.com/questions/629946/#comment1571118_629946 % 2022-01-11: https://tex.stackexchange.com/questions/633341/#comment1579825_633347 + % 2023-06-01: https://github.com/latex3/latex2e/pull/1020 Enrico Gregorio, % 2021-08-20: https://tex.stackexchange.com/a/611385 % 2021-08-20: https://tex.stackexchange.com/q/611370/#comment1529282_611385 @@ -2637,9 +2645,11 @@ were generously provided by (in chronological order): % and following discussion. Thomas F. Sturm, % 2023-02-09: https://github.com/T-F-S/tcolorbox/issues/206 + % 2023-05-12: https://github.com/T-F-S/tcolorbox/issues/230 and Yukai Chou. % 'muzimuzhi' % 2023-02-18: https://github.com/gusbrs/zref-clever/pull/14 % 2023-02-18: https://github.com/gusbrs/zref-clever/pull/15 + % 2023-05-11: https://github.com/T-F-S/tcolorbox/issues/230 The package's language files have been provided or improved thanks to: Denis Bitouzé (French), diff --git a/macros/latex/contrib/zref-clever/zref-clever.dtx b/macros/latex/contrib/zref-clever/zref-clever.dtx index cee60860c3..fff75c1b44 100644 --- a/macros/latex/contrib/zref-clever/zref-clever.dtx +++ b/macros/latex/contrib/zref-clever/zref-clever.dtx @@ -22,7 +22,7 @@ % % This work consists of the files zref-clever.dtx, % zref-clever.ins, -% zref-clever.tex, +% zref-clever-doc.tex, % zref-clever-code.tex, % and the files generated from them. % @@ -131,12 +131,11 @@ % % Taking a stance on backward compatibility of the package. During initial % development, we have used freely recent features of the kernel (albeit -% refraining from \pkg{l3candidates}, even though I'd have loved to have used -% \cs{bool_case_true:}\dots{}). We presume \pkg{xparse} (which made to the -% kernel in the 2020-10-01 release), and \pkg{expl3} as well (which made to -% the kernel in the 2020-02-02 release). We also just use UTF-8 for the +% refraining from \pkg{l3candidates}). We presume \pkg{xparse} (which made to +% the kernel in the 2020-10-01 release), and \pkg{expl3} as well (which made +% to the kernel in the 2020-02-02 release). We also just use UTF-8 for the % language files (which became the default input encoding in the 2018-04-01 -% release). Finally, a couple of changes came with the 2021-11-15 kernel +% release). Also, 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} (by \contributor{Phelype Oleinik} at @@ -144,18 +143,23 @@ % \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. +% Fischer} at \url{https://github.com/latex3/latex2e/issues/687}). Finally, +% and critically, the new \texttt{label} hook introduced in the 2023-06-01 +% release, alongside the corresponding new hooks with arguments, just +% simplifies and improves label setting so much, by allowing \cs{zlabel} to be +% set with \cs{label}, that it is definitely a must for \pkg{zref-clever}, so +% we require that too. Hence we make the cut at the 2023-06-01 kernel +% release. % % \begin{macrocode} +\NeedsTeXFormat{LaTeX2e} \providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion} -\IfFormatAtLeastTF{2021-11-15} +\IfFormatAtLeastTF{2023-06-01} {} {% \PackageError{zref-clever}{LaTeX kernel too old} {% - 'zref-clever' requires a LaTeX kernel 2021-11-15 or newer.% + 'zref-clever' requires a LaTeX kernel 2023-06-01 or newer.% \MessageBreak Loading will abort!% }% \endinput @@ -165,7 +169,7 @@ % % Identify the package. % \begin{macrocode} -\ProvidesExplPackage {zref-clever} {2023-02-21} {0.3.6} +\ProvidesExplPackage {zref-clever} {2023-06-14} {0.4.0} {Clever LaTeX cross-references based on zref} % \end{macrocode} % @@ -3927,6 +3931,36 @@ % \end{macrocode} % % +% \subsubsection*{\opt{labelhook} option} +% +% \begin{macrocode} +\bool_new:N \l_@@_labelhook_bool +\keys_define:nn { zref-clever/label } + { + labelhook .bool_set:N = \l_@@_labelhook_bool , + labelhook .initial:n = true , + labelhook .default:n = true , + } +% \end{macrocode} +% +% We \emph{must} use the lower level \cs{zref@label} in this context, and +% hence also handle protection with \cs{zref@wrapper@babel}, because +% \cs{zlabel} makes itself no-op when \cs{label} is equal to \cs{ltx@gobble}, +% and that's precisely the case inside the \pkg{amsmath}'s \env{multline} +% environment (and possibly elsewhere?). See +% \url{https://tex.stackexchange.com/a/402297} and +% \url{https://github.com/ho-tex/zref/issues/4}. +% +% \begin{macrocode} +\AddToHookWithArguments { label } + { + \bool_if:NT \l_@@_labelhook_bool + { \zref@wrapper@babel \zref@label {#1} } + } +% \end{macrocode} +% +% +% % \subsubsection*{\opt{nocompat} option} % % @@ -4007,8 +4041,8 @@ % % This is a set of options related to reference typesetting which receive % equal treatment and, hence, are handled in batch. Since we are dealing with -% options to be passed to \cs{zcref} or to \cs{zcsetup} or at load time, only -% ``not necessarily type-specific'' options are pertinent here. +% options to be passed to \cs{zcref} or to \cs{zcsetup}, only ``not +% necessarily type-specific'' options are pertinent here. % % % \begin{macrocode} @@ -7774,39 +7808,10 @@ % related features, mostly dealing with captions, subfloats, and notes. Some % of them are implemented in ways which make difficult the use of \pkg{zref}, % particularly \cs{zlabel}, short of redefining the whole stuff ourselves. -% Hopefully, these features are specialized enough to make \pkg{zref-clever} -% useful enough with \cls{memoir} without much friction, but unless some -% support is added upstream, it is difficult not to be a little intrusive -% here. +% Fortunately, however, the kernel's new \texttt{label} hook, and the +% \opt{labelhook} option, make things somewhat easier. % % \begin{enumerate} -% \item Caption functionality which receives \meta{label} as optional -% argument, namely: -% \begin{enumerate} -% \item The \env{sidecaption} and \env{sidecontcaption} environments. These -% environments \emph{store} the label in an internal macro, -% \cs{m@mscaplabel}, at the begin environment code (more precisely in -% \cs[replace=false]{@@sidecaption}), but both the call to -% \cs{refstepcounter} and the expansion of \cs{m@mscaplabel} take place at -% \cs{endsidecaption}. For this reason, hooks are not particularly -% helpful, and there is not any easy way to grab the \meta{label} argument -% to start with. I can see two ways to deal with these environments, none -% of which I really like. First, map through \cs{m@mscaplabel} until -% \cs{label} is found, then grab the next token which is the \meta{label}. -% This can be used to set a \cs{zlabel} either with a kernel environment -% hook, or with \cs{@mem@scap@afterhook} (the former requires running -% \cs{refstepcounter} on our own, since the \texttt{env/.../end} hook -% comes before this is done by \cs{endsidecaption}). Second, locally -% redefine \cs{label} to set both labels inside the environments. -% \item The bilingual caption commands: \cs{bitwonumcaption}, -% \cs{bionenumcaption}, and \cs{bicaption}. These commands do not support -% setting the label in their arguments (the labels do get set, but they -% end up included in the \texttt{title} property of the label too). So we -% do the same for them as for \env{sidecaption}, just taking care of -% grouping, since we can't count on the convenience of the environment -% hook (luckily for us, they are scoped themselves, so we can add an extra -% group there). -% \end{enumerate} % \item The \cs{subcaptionref} command, which makes a reference to the % subcaption without the number of the main caption (e.g. ``(b)'', instead % of ``2.3(b)''), for labels set inside the \meta{subtitle} argument of the @@ -7860,36 +7865,6 @@ } , } % \end{macrocode} -% Support for caption \cls{memoir} features that require that \meta{label} be -% supplied as an optional argument. -% \begin{macrocode} - \cs_new_protected:Npn \@@_memoir_both_labels: - { - \cs_set_eq:NN \@@_memoir_orig_label:n \label - \cs_set:Npn \@@_memoir_label_and_zlabel:n ##1 - { - \@@_memoir_orig_label:n {##1} - \zlabel{##1} - } - \cs_set_eq:NN \label \@@_memoir_label_and_zlabel:n - } - \AddToHook { env / sidecaption / begin } - { \@@_memoir_both_labels: } - \AddToHook { env / sidecontcaption / begin } - { \@@_memoir_both_labels: } - \AddToHook{ cmd / bitwonumcaption / before } - { \group_begin: \@@_memoir_both_labels: } - \AddToHook{ cmd / bitwonumcaption / after } - { \group_end: } - \AddToHook{ cmd / bionenumcaption / before } - { \group_begin: \@@_memoir_both_labels: } - \AddToHook{ cmd / bionenumcaption / after } - { \group_end: } - \AddToHook{ cmd / bicaption / before } - { \group_begin: \@@_memoir_both_labels: } - \AddToHook{ cmd / bicaption / after } - { \group_end: } -% \end{macrocode} % Support for \texttt{subcaption} reference. % \begin{macrocode} \zref@newprop { subcaption } @@ -7930,7 +7905,8 @@ % % \subsection{\opt{amsmath}} % -% About this, see \url{https://tex.stackexchange.com/a/402297}. +% About this, see \url{https://tex.stackexchange.com/a/402297} and +% \url{https://github.com/ho-tex/zref/issues/4}. % % \begin{macrocode} \@@_compat_module:nn { amsmath } @@ -7938,69 +7914,6 @@ \@@_if_package_loaded:nT { amsmath } { % \end{macrocode} -% First, we define a function for label setting inside \pkg{amsmath} math -% environments, we want it to set both \cs{zlabel} and \cs{label}. We may -% ``get a ride'', but not steal the place altogether. This makes for -% potentially redundant labels, but seems a good compromise. We \emph{must} -% use the lower level \cs{zref@label} in this context, and hence also handle -% protection with \cs{zref@wrapper@babel}, because \cs{zlabel} makes itself -% no-op when \cs{label} is equal to \cs{ltx@gobble}, and that's precisely the -% case inside the \env{multline} environment (and, damn!, I took a beating of -% this detail\dots{}). See also \url{https://github.com/ho-tex/zref/issues/4} -% and \url{https://github.com/latex3/latex2e/issues/272}. -% \begin{macrocode} - \cs_set_nopar:Npn \@@_ltxlabel:n #1 - { - \@@_orig_ltxlabel:n {#1} - \zref@wrapper@babel \zref@label {#1} - } -% \end{macrocode} -% Then we must store the original value of \cs{ltx@label}, which is the macro -% actually responsible for setting the labels inside \pkg{amsmath}'s math -% environments. And, after that, redefine it to be \cs{@@_ltxlabel:n} -% instead. We must handle \pkg{hyperref} here, which comes very late in the -% preamble, and which loads \pkg{nameref} at \texttt{begindocument} (though -% this has changed recently 2022-05-16, see -% \url{https://github.com/latex3/hyperref/commit/a011ba9308a1b047dc151796de557da0bb22abaa}), -% which in turn, lets \cs{ltx@label} be \cs{label}. This has to come after -% \pkg{nameref}. Other classes packages also redefine \cs{ltx@label}, which -% may cause some trouble. A \texttt{grep} on \texttt{texmf-dist} returns hits -% for: \file{thm-restate.sty}, \file{smartref.sty}, \file{jmlrbook.cls}, -% \file{cleveref.sty}, \file{cryptocode.sty}, \file{nameref.sty}, -% \file{easyeqn.sty}, \file{empheq.sty}, \file{ntheorem.sty}, -% \file{nccmath.sty}, \file{nwejm.cls}, \file{nwejmart.cls}, -% \file{aguplus.sty}, \file{aguplus.cls}, \file{agupp.sty}, -% \file{amsmath.hyp}, \file{amsmath.sty} (surprise!), \file{amsmath.4ht}, -% \file{nameref.4ht}, \file{frenchle.sty}, \file{french.sty}, plus -% corresponding documentations and different versions of the same packages. -% That's not too many, but not ``just a few'' either. The critical ones are -% explicitly handled here (\pkg{amsmath} itself, and \pkg{nameref}). A number -% of those I'm really not acquainted with. For \pkg{cleveref}, in particular, -% this procedure is not compatible with it. If we happen to come later than -% it and override its definition, this may be a substantial problem for -% \pkg{cleveref}, since it will find the label, but it won't contain the data -% it is expecting. However, this should normally not occur, if the user has -% followed the documented recommendation for \pkg{cleveref} to load it last, -% or at least very late, and besides I don't see much of an use case for using -% both \pkg{cleveref} and \pkg{zref-clever} together. I have documented in -% the user manual that this module may cause potential issues, and how to work -% around them. And I have made an upstream feature request for a hook, so -% that this could be made more cleanly at -% \url{https://github.com/latex3/hyperref/issues/212}. -% \begin{macrocode} - \@@_if_package_loaded:nTF { hyperref } - { - \AddToHook { package / nameref / after } - { - \cs_new_eq:NN \@@_orig_ltxlabel:n \ltx@label - \cs_set_eq:NN \ltx@label \@@_ltxlabel:n - } - } - { - \cs_new_eq:NN \@@_orig_ltxlabel:n \ltx@label - \cs_set_eq:NN \ltx@label \@@_ltxlabel:n - } -% \end{macrocode} % The \env{subequations} environment uses \texttt{parentequation} and % \texttt{equation} as counters, but only the later is subject to % \cs{refstepcounter}. What happens is: at the start, \texttt{equation} is @@ -8145,11 +8058,7 @@ % From the \pkg{breqn} documentation: \textquote{Use of the normal \cs{label} % command instead of the \opt{label} option works, I think, most of the time % (untested)}. Indeed, light testing suggests it does work for \cs{zlabel} -% just as well. However, if it happens not to work, there was no easy -% alternative handle I could find. In particular, it does not seem viable to -% leverage the \opt{label=} option without hacking the package internals, even -% if the case of doing so would not be specially tricky, just ``not very -% civil''. +% just as well. % % \begin{macrocode} \@@_compat_module:nn { breqn } @@ -8223,19 +8132,6 @@ counterresetby = { lstnumber = lstlisting } , } % \end{macrocode} -% Set (also) a \cs{zlabel} with the label received in the \texttt{label=} -% option from the \texttt{lstlisting} environment. The \emph{only} place to -% set this label is the \texttt{PreInit} hook. This hook, comes right after -% \cs{lst@MakeCaption} in \cs{lst@Init}, which runs \cs{refstepcounter} on -% \texttt{lstlisting}, so we must come after it. Also \pkg{listings} itself -% sets \cs{@currentlabel} to \cs{thelstnumber} in the \texttt{Init} hook, -% which comes right after the \texttt{PreInit} one in \cs{lst@Init}. Since, -% if we add to \texttt{Init} here, we go to the end of it, we'd be seeing the -% wrong \cs{@currentlabel} at that point. -% \begin{macrocode} - \lst@AddToHook { PreInit } - { \tl_if_empty:NF \lst@label { \zlabel { \lst@label } } } -% \end{macrocode} % Set \texttt{currentcounter} to \texttt{lstnumber} in the \texttt{Init} hook, % since \pkg{listings} itself sets \cs{@currentlabel} to \cs{thelstnumber} % here. Note that \pkg{listings} \emph{does use} \cs{refstepcounter} on diff --git a/macros/latex/contrib/zref-clever/zref-clever.ins b/macros/latex/contrib/zref-clever/zref-clever.ins index d4f77dcf36..668d25788f 100644 --- a/macros/latex/contrib/zref-clever/zref-clever.ins +++ b/macros/latex/contrib/zref-clever/zref-clever.ins @@ -22,7 +22,7 @@ % % This work consists of the files zref-clever.dtx, % zref-clever.ins, -% zref-clever.tex, +% zref-clever-doc.tex, % zref-clever-code.tex, % and the files generated from them. % @@ -68,7 +68,7 @@ This work is "maintained" (as per LPPL maintenance status) by This work consists of the files zref-clever.dtx, zref-clever.ins, - zref-clever.tex, + zref-clever-doc.tex, zref-clever-code.tex, and the files generated from them. diff --git a/macros/latex/contrib/zref-clever/zref-clever.pdf b/macros/latex/contrib/zref-clever/zref-clever.pdf Binary files differdeleted file mode 100644 index 4a4bfb147f..0000000000 --- a/macros/latex/contrib/zref-clever/zref-clever.pdf +++ /dev/null diff --git a/macros/latex/contrib/zref-vario/CHANGELOG.md b/macros/latex/contrib/zref-vario/CHANGELOG.md index 2f0b419280..876440be3e 100644 --- a/macros/latex/contrib/zref-vario/CHANGELOG.md +++ b/macros/latex/contrib/zref-vario/CHANGELOG.md @@ -1,6 +1,12 @@ # Changelog -## [Unreleased](https://github.com/gusbrs/zref-vario/compare/v0.1.7...HEAD) +## [Unreleased](https://github.com/gusbrs/zref-vario/compare/v0.1.8...HEAD) + +## [v0.1.8](https://github.com/gusbrs/zref-vario/compare/v0.1.7...v0.1.8) (2023-06-14) + +### Changed +- Improvements to User manual. +- Simplify and improve regression tests. ## [v0.1.7](https://github.com/gusbrs/zref-vario/compare/v0.1.6...v0.1.7) (2023-01-03) diff --git a/macros/latex/contrib/zref-vario/zref-vario-code.pdf b/macros/latex/contrib/zref-vario/zref-vario-code.pdf Binary files differindex e5aa9feaa1..b035eabb67 100644 --- a/macros/latex/contrib/zref-vario/zref-vario-code.pdf +++ b/macros/latex/contrib/zref-vario/zref-vario-code.pdf diff --git a/macros/latex/contrib/zref-vario/zref-vario-code.tex b/macros/latex/contrib/zref-vario/zref-vario-code.tex index 914208b02e..d1774f8f21 100644 --- a/macros/latex/contrib/zref-vario/zref-vario-code.tex +++ b/macros/latex/contrib/zref-vario/zref-vario-code.tex @@ -22,7 +22,7 @@ % % This work consists of the files zref-vario.dtx, % zref-vario.ins, -% zref-vario.tex, +% zref-vario-doc.tex, % zref-vario-code.tex, % and the files generated from them. % diff --git a/macros/latex/contrib/zref-vario/zref-vario.pdf b/macros/latex/contrib/zref-vario/zref-vario-doc.pdf Binary files differindex ef33353401..0119708112 100644 --- a/macros/latex/contrib/zref-vario/zref-vario.pdf +++ b/macros/latex/contrib/zref-vario/zref-vario-doc.pdf diff --git a/macros/latex/contrib/zref-vario/zref-vario.tex b/macros/latex/contrib/zref-vario/zref-vario-doc.tex index 859519a2ef..0923b299ae 100644 --- a/macros/latex/contrib/zref-vario/zref-vario.tex +++ b/macros/latex/contrib/zref-vario/zref-vario-doc.tex @@ -22,7 +22,7 @@ % % This work consists of the files zref-vario.dtx, % zref-vario.ins, -% zref-vario.tex, +% zref-vario-doc.tex, % zref-vario-code.tex, % and the files generated from them. % @@ -278,6 +278,7 @@ options. Language independent default values are provided for the \pkg{varioref}, which are adequate for most use cases), so you may omit them. But, if you need to adjust them, the default values can be overridden by setting the corresponding options in \cs{zvLanguageSetup}. +\cs{zvLanguageSetup} is preamble only. \begin{function}{\zvhyperlink} \begin{syntax} @@ -347,6 +348,7 @@ generously provided by (in chronological order): David Carlisle, % 2023-01-02: https://chat.stackexchange.com/transcript/message/62684358#62684358 % and following discussion. + % 2023-02-10: https://tex.stackexchange.com/a/674846 and Joseph Wright. % 2023-01-02: https://chat.stackexchange.com/transcript/message/62684358#62684358 % and following discussion. diff --git a/macros/latex/contrib/zref-vario/zref-vario.dtx b/macros/latex/contrib/zref-vario/zref-vario.dtx index 1e07c94694..e029af643c 100644 --- a/macros/latex/contrib/zref-vario/zref-vario.dtx +++ b/macros/latex/contrib/zref-vario/zref-vario.dtx @@ -22,7 +22,7 @@ % % This work consists of the files zref-vario.dtx, % zref-vario.ins, -% zref-vario.tex, +% zref-vario-doc.tex, % zref-vario-code.tex, % and the files generated from them. % @@ -126,9 +126,14 @@ % \end{macrocode} % % +% \begin{macrocode} +\NeedsTeXFormat{LaTeX2e} +% \end{macrocode} +% +% % Identify the package. % \begin{macrocode} -\ProvidesExplPackage {zref-vario} {2023-01-03} {0.1.7} +\ProvidesExplPackage {zref-vario} {2023-06-14} {0.1.8} {Extended LaTeX page cross-references with varioref and zref-clever} % \end{macrocode} % diff --git a/macros/latex/contrib/zref-vario/zref-vario.ins b/macros/latex/contrib/zref-vario/zref-vario.ins index bdc92fffdb..211c1ff0b2 100644 --- a/macros/latex/contrib/zref-vario/zref-vario.ins +++ b/macros/latex/contrib/zref-vario/zref-vario.ins @@ -22,7 +22,7 @@ % % This work consists of the files zref-vario.dtx, % zref-vario.ins, -% zref-vario.tex, +% zref-vario-doc.tex, % zref-vario-code.tex, % and the files generated from them. % @@ -68,7 +68,7 @@ This work is "maintained" (as per LPPL maintenance status) by This work consists of the files zref-vario.dtx, zref-vario.ins, - zref-vario.tex, + zref-vario-doc.tex, zref-vario-code.tex, and the files generated from them. |