diff --git a/base/changes.txt b/base/changes.txt index c6da05755..663354dfe 100644 --- a/base/changes.txt +++ b/base/changes.txt @@ -6,6 +6,11 @@ to completeness or accuracy and it contains some references to files that are not part of the distribution. ================================================================================ +2024-12-27 Frank Mittelbach + + * ltsockets.dtx: + Add conditionals for sockets, plugs, and assignments (gh/1577) + 2024-12-25 Frank Mittelbach * doc.dtx (subsection{Producing the actual index entries}): diff --git a/base/doc/ltnews41.tex b/base/doc/ltnews41.tex index fbe8cac83..93c5ab933 100644 --- a/base/doc/ltnews41.tex +++ b/base/doc/ltnews41.tex @@ -233,6 +233,17 @@ \subsection{Fixing the spacing after display math} \section{New or improved commands} +\subsection{Socket and plug conditionals} + +It is sometimes necessary/helpful to know if a particular socket or +plug exists (or is assigned to a certain socket) and based on that +take different actions. With the current release we added +conditionals, such as \cs{IfSocketExistsTF}, to support such +scenarios. Corresponding L3 programming layer conditionals are also +provided. +% +\githubissue{1577} + \section{Code improvements} \subsection{Refinement of \cs{MakeTitlecase}} diff --git a/base/ltsockets.dtx b/base/ltsockets.dtx index a977f8f6a..38a979e1b 100644 --- a/base/ltsockets.dtx +++ b/base/ltsockets.dtx @@ -33,7 +33,7 @@ %<*driver> % \fi \ProvidesFile{ltsockets.dtx} - [2024/10/27 v0.9b LaTeX Kernel (Sockets)] + [2024/12/27 v0.9c LaTeX Kernel (Sockets)] % \iffalse % \documentclass{l3doc} @@ -645,6 +645,43 @@ % \cs{LogSocket} and \cs{socket_log:n} only differ in that they don't stop. % \end{function} % +% +% It is sometimes necessary/helpful to know if a particular socket or +% plug exists (or is assigned to a certain socket) and based on that +% take different actions. +% +% \begin{function}[EXP]{\IfSocketExistsTF,\socket_if_exist:nTF} +% \begin{syntax} +% \cs{IfSocketExistsTF} \Arg{socket-name} \Arg{true code} \Arg{false code} +% \end{syntax} +% If socket \meta{socket-name} exists then execute \meta{true code} +% otherwise \meta{false code}. Variants with only \texttt{T} or +% \texttt{F} are also available. +% \end{function} +% +% \begin{function}[EXP]{\IfSocketPlugExistsTF,\socket_if_plug_exist:nnTF} +% \begin{syntax} +% \cs{IfSocketPlugExistsTF} \Arg{socket-name} \Arg{plug-name} +% \qquad \Arg{true code} \Arg{false code} +% \end{syntax} +% If plug \meta{plug-name} for socket \meta{socket-name} exists then +% execute \meta{true code} otherwise \meta{false code}. Variants +% with only \texttt{T} or \texttt{F} are also available. +% \end{function} +% +% \begin{function}[EXP]{\IfSocketPlugAssignedTF,\socket_if_plug_assigned:nnTF} +% \begin{syntax} +% \cs{IfSocketPlugAssignedTF} \Arg{socket-name} \Arg{plug-name} +% \qquad \Arg{true code} \Arg{false code} +% \end{syntax} +% If plug \meta{plug-name} is assigned to socket \meta{socket-name} +% then execute \meta{true code} otherwise \meta{false +% code}. Variants with only \texttt{T} or \texttt{F} are also +% available. +% \end{function} +% +% +% % % \begin{function}{\DebugSocketsOn,\DebugSocketsOff, % \socket_debug_on:,\socket_debug_off:} @@ -654,6 +691,8 @@ % Turns debugging of sockets on or off. % \end{function} % +% +% % \subsubsection{Rationale for error handling} % % The errors during the declarations are produced to help with @@ -766,7 +805,7 @@ % does nothing by default other than swallowing its inputs (if any). % \begin{macrocode} \cs_new_protected:Npn \socket_new:nn #1 #2 { - \str_if_exist:cTF { l_@@_#1_plug_str } + \socket_if_exist:nTF {#1} { \msg_error:nnn { socket } { already-declared } {#1} } @@ -796,7 +835,23 @@ } % \end{macrocode} % \end{macro} -% +% +% +% +% \begin{macro}[pTF, EXP] { \socket_if_exist:n } +% Conditional testing the existance of a socket. +% The argument is fully expanded as part of the csname generation. +% \changes{v0.9c}{2024/12/27}{Conditionals for sockets, plugs, and +% assignments (gh/1577)} +% \begin{macrocode} +\prg_new_conditional:Npnn \socket_if_exist:n #1 { p , T , F , TF } + { \str_if_exist:cTF { l_@@_#1_plug_str } + \prg_return_true: + \prg_return_false: + } +% \end{macrocode} +% \end{macro} +% % % \begin{macro}{\socket_log:n,\socket_show:n} % Show the current state of the socket --- for now this is just a @@ -804,7 +859,7 @@ % \begin{macrocode} \cs_new_protected:Npn \socket_log:n #1 { \typeout{ Socket~ #1:} - \str_if_exist:cTF { l_@@_#1_plug_str } + \socket_if_exist:nTF {#1} { \typeout{ \@spaces number~ of~ inputs~ =~ \int_use:c { c_@@_#1_args_int } } @@ -842,9 +897,9 @@ % the number of arguments from the saved int. % \begin{macrocode} \cs_new_protected:Npn \socket_new_plug:nnn #1#2#3 { - \str_if_exist:cTF { l_@@_#1_plug_str } + \socket_if_exist:nTF {#1} { - \cs_if_exist:cTF { @@_#1_plug_#2:w } + \socket_if_plug_exist:nnTF {#1} {#2} { \msg_error:nnnn { socket } { plug-already-declared } {#1} {#2} } @@ -863,9 +918,7 @@ { Plug~ '#2'~ for~ socket~ '#1'~ declared. } } } - { - \msg_error:nnn { socket } { undeclared } {#1} - } + { \msg_error:nnn { socket } { undeclared } {#1} } } % \end{macrocode} % Changing the plug of an existing socket is rather similar, except @@ -873,9 +926,9 @@ % sequence. % \begin{macrocode} \cs_new_protected:Npn \socket_set_plug:nnn #1#2#3 { - \str_if_exist:cTF { l_@@_#1_plug_str } + \socket_if_exist:nTF {#1} { - \cs_if_exist:cTF { @@_#1_plug_#2:w } + \socket_if_plug_exist:nnTF {#1} {#2} { \cs_generate_from_arg_count:cNnn { @@_#1_plug_#2:w } @@ -889,14 +942,28 @@ \msg_error:nnnn { socket } { plug-undeclared } {#1} {#2} } } - { - \msg_error:nnn { socket } { undeclared } {#1} - } + { \msg_error:nnn { socket } { undeclared } {#1} } } % \end{macrocode} % \end{macro} % -% +% +% +% \begin{macro}[pTF, EXP] { \socket_if_plug_exist:nn } +% Conditional testing the existance of a plug. +% Both arguments are fully expanded as part of the csname generation. +% \changes{v0.9c}{2024/12/27}{Conditionals for sockets, plugs, and +% assignments (gh/1577)} +% \begin{macrocode} +\prg_new_conditional:Npnn \socket_if_plug_exist:nn #1#2 { p , T , F , TF } + { \cs_if_exist:cTF { @@_#1_plug_#2:w } + \prg_return_true: + \prg_return_false: + } +% \end{macrocode} +% \end{macro} +% +% % % \begin{macro}{\socket_assign_plug:nn} % @@ -904,9 +971,9 @@ % the socket string. The assignment is local to the current group. % \begin{macrocode} \cs_new_protected:Npn \socket_assign_plug:nn #1 #2 { - \str_if_exist:cTF { l_@@_#1_plug_str } + \socket_if_exist:nTF {#1} { - \cs_if_exist:cTF { @@_#1_plug_#2:w } + \socket_if_plug_exist:nnTF {#1} {#2} { \@@_debug_term:n { Replacing~ plug~ '\str_use:c { l_@@_#1_plug_str }'~ @@ -921,7 +988,25 @@ } % \end{macrocode} % \end{macro} -% +% +% +% +% \begin{macro}[pTF, EXP] { \socket_if_plug_assigned:nn } +% Conditional testing the assignment of a plug. +% Both arguments are fully expanded. +% \changes{v0.9c}{2024/12/27}{Conditionals for sockets, plugs, and +% assignments (gh/1577)} +% \begin{macrocode} +\prg_new_conditional:Npnn \socket_if_plug_assigned:nn #1#2 { p , T , F , TF } + { \exp_args:Ne + \str_if_eq:nvTF {#2} { l__socket_#1_plug_str } + \prg_return_true: + \prg_return_false: + } +% \end{macrocode} +% \end{macro} +% +% % % \begin{macro}{\socket_use:nw,\socket_use:n,\socket_use:nn,\socket_use:nnn,\socket_use:nnnn} % @@ -1044,6 +1129,32 @@ % \end{macro} % % +% \begin{macro}{\IfSocketExistsTF,\IfSocketExistsT,\IfSocketExistsF, +% \IfSocketPlugExistsTF,\IfSocketPlugExistsT, +% \IfSocketPlugExistsF, +% \IfSocketPlugAssignedTF,\IfSocketPlugAssignedT, +% \IfSocketPlugAssignedF} +% A bunch of conditionals: +% \changes{v0.9c}{2024/12/27}{Conditionals for sockets, plugs, and +% assignments (gh/1577)} +% \begin{macrocode} +\cs_new_eq:NN \IfSocketExistsTF \socket_if_exist:nTF +\cs_new_eq:NN \IfSocketExistsT \socket_if_exist:nT +\cs_new_eq:NN \IfSocketExistsF \socket_if_exist:nF +% \end{macrocode} +% +% \begin{macrocode} +\cs_new_eq:NN \IfSocketPlugExistsTF \socket_if_plug_exist:nnTF +\cs_new_eq:NN \IfSocketPlugExistsT \socket_if_plug_exist:nnT +\cs_new_eq:NN \IfSocketPlugExistsF \socket_if_plug_exist:nnF +% \end{macrocode} +% +% \begin{macrocode} +\cs_new_eq:NN \IfSocketPlugAssignedTF \socket_if_plug_assigned:nnTF +\cs_new_eq:NN \IfSocketPlugAssignedT \socket_if_plug_assigned:nnT +\cs_new_eq:NN \IfSocketPlugAssignedF \socket_if_plug_assigned:nnF +% \end{macrocode} +% \end{macro} % % \begin{macrocode} % @@ -1061,6 +1172,16 @@ %\let \DebugSocketsOn \@undefined %\let \DebugSocketsOff \@undefined % +%\let \IfSocketExistsTF \@undefined +%\let \IfSocketExistsT \@undefined +%\let \IfSocketExistsF \@undefined +%\let \IfSocketPlugExistsTF \@undefined +%\let \IfSocketPlugExistsT \@undefined +%\let \IfSocketPlugExistsF \@undefined +%\let \IfSocketPlugAssignedTF \@undefined +%\let \IfSocketPlugAssignedT \@undefined +%\let \IfSocketPlugAssignedF \@undefined +% %\EndModuleRelease % \end{macrocode} % diff --git a/base/testfiles/sockets-002.luatex.tlg b/base/testfiles/sockets-002.luatex.tlg index 5b4246b18..7e88f68e4 100644 --- a/base/testfiles/sockets-002.luatex.tlg +++ b/base/testfiles/sockets-002.luatex.tlg @@ -52,3 +52,15 @@ modified noop A socket plug ---------------------- A socket plug +---------------------- +should be true +should be false +true +---------------------- +should be true +should be false +true +---------------------- +should be true +should be false +true diff --git a/base/testfiles/sockets-002.lvt b/base/testfiles/sockets-002.lvt index 6f5ef0a94..720907948 100644 --- a/base/testfiles/sockets-002.lvt +++ b/base/testfiles/sockets-002.lvt @@ -47,4 +47,22 @@ \UseSocket{foo} +\typeout{----------------------} +\IfSocketExistsTF{foo}{\typeout{should be true}}{\typeout{false}} +\IfSocketExistsTF{bar}{\typeout{true}}{\typeout{should be false}} +\IfSocketExistsT{foo}{\typeout{true}} +\IfSocketExistsF{foo}{\typeout{false}} + +\typeout{----------------------} +\IfSocketPlugExistsTF{foo}{default}{\typeout{should be true}}{\typeout{false}} +\IfSocketPlugExistsTF{foo}{undefined}{\typeout{true}}{\typeout{should be false}} +\IfSocketPlugExistsT{foo}{default}{\typeout{true}} +\IfSocketPlugExistsF{foo}{default}{\typeout{false}} + +\typeout{----------------------} +\IfSocketPlugAssignedTF{foo}{default}{\typeout{should be true}}{\typeout{false}} +\IfSocketPlugAssignedTF{foo}{noop}{\typeout{true}}{\typeout{should be false}} +\IfSocketPlugAssignedT{foo}{default}{\typeout{true}} +\IfSocketPlugAssignedF{foo}{default}{\typeout{false}} + \END diff --git a/base/testfiles/sockets-002.tlg b/base/testfiles/sockets-002.tlg index c5db70213..eea303032 100644 --- a/base/testfiles/sockets-002.tlg +++ b/base/testfiles/sockets-002.tlg @@ -52,3 +52,15 @@ modified noop A socket plug ---------------------- A socket plug +---------------------- +should be true +should be false +true +---------------------- +should be true +should be false +true +---------------------- +should be true +should be false +true diff --git a/required/latex-lab/changes.txt b/required/latex-lab/changes.txt index 90ee0834d..9024e96df 100644 --- a/required/latex-lab/changes.txt +++ b/required/latex-lab/changes.txt @@ -1,3 +1,9 @@ +2024-12-27 Frank Mittelbach + + * latex-lab-table.dtx,latex-lab-toc-kernel-changes.dtx, + latex-lab-footnotes.dtx,latex-lab-float.dtx: + Use new socket conditional. + 2024-12-21 Ulrike Fischer * documentmetadata-support.dtx: added "latest" as a testphase value. * remove now unneeded tests. diff --git a/required/latex-lab/latex-lab-float.dtx b/required/latex-lab/latex-lab-float.dtx index 0bbf7b7eb..284416817 100644 --- a/required/latex-lab/latex-lab-float.dtx +++ b/required/latex-lab/latex-lab-float.dtx @@ -16,8 +16,8 @@ % % for those people who are interested or want to report an issue. % -\def\ltlabfloatdate{2024-11-21} -\def\ltlabfloatversion{0.81g} +\def\ltlabfloatdate{2024-12-27} +\def\ltlabfloatversion{0.81h} %<*driver> \documentclass{l3doc} \EnableCrossrefs @@ -297,7 +297,7 @@ % \subsection{Tagging sockets} % For now we test if the sockets are already defined % \begin{macrocode} -\str_if_exist:cF { l__socket_tagsupport/float/begin_plug_str } +\socket_if_exist:nF {tagsupport/float/begin} { \NewSocket{tagsupport/float/hmode/begin}{0} \NewSocket{tagsupport/float/hmode/end}{0} @@ -540,7 +540,7 @@ % First some temporary sockets. % These sockets are in lttagging. % \begin{macrocode} -\str_if_exist:cF { l__socket_tagsupport/caption/begin_plug_str } +\socket_if_exist:nF {tagsupport/caption/begin} { \NewSocket{tagsupport/caption/begin}{1} \NewSocket{tagsupport/caption/end}{0} @@ -551,7 +551,7 @@ % These socket are currently defined in tagpdf. % \changes{v0.81g}{2024-11-21}{add missing argument to socket} % \begin{macrocode} -\str_if_exist:cF { l__socket_tagsupport/para/begin_plug_str } +\socket_if_exist:nF {tagsupport/para/begin} { \NewSocket{tagsupport/para/begin}{0} \NewSocket{tagsupport/para/end}{0} diff --git a/required/latex-lab/latex-lab-footnotes.dtx b/required/latex-lab/latex-lab-footnotes.dtx index f4ad7edd9..42348ff26 100644 --- a/required/latex-lab/latex-lab-footnotes.dtx +++ b/required/latex-lab/latex-lab-footnotes.dtx @@ -17,8 +17,8 @@ % % for those people who are interested or want to report an issue. % -\def\ltlabfootnotedate{2024-09-30} -\def\ltlabfootnoteversion{0.8g} +\def\ltlabfootnotedate{2024-12-27} +\def\ltlabfootnoteversion{0.8h} %<*driver> \documentclass{l3doc} @@ -1177,7 +1177,7 @@ % \begin{macro}{\fnote_footnotetext:n} % We temporarily test for the tagging socket until it is in the next release: % \begin{macrocode} -\str_if_exist:cF { l__socket_tagsupport/para/restore_plug_str } +\socket_if_exist:nF {tagsupport/para/restore} { \NewSocket{tagsupport/para/restore}{0} \NewSocketPlug{tagsupport/para/restore}{default} diff --git a/required/latex-lab/latex-lab-table.dtx b/required/latex-lab/latex-lab-table.dtx index c65667e8e..a91a95d1b 100644 --- a/required/latex-lab/latex-lab-table.dtx +++ b/required/latex-lab/latex-lab-table.dtx @@ -16,8 +16,8 @@ % % for those people who are interested or want to report an issue. % -\def\ltlabtbldate{2024-09-18} -\def\ltlabtblversion{0.85n} +\def\ltlabtbldate{2024-12-27} +\def\ltlabtblversion{0.85o} %<*driver> \documentclass{l3doc} \EnableCrossrefs @@ -359,7 +359,7 @@ % The following two sockets are defined in lttagging, but we check % for their existence until the release 11/2024. % \begin{macrocode} -\str_if_exist:cF { l__socket_tagsupport/tbl/init/celldata_plug_str } +\socket_if_exist:nF {tagsupport/tbl/init/celldata} { \NewSocket{tagsupport/tbl/init/celldata}{0} \NewSocket{tagsupport/tbl/restore/celldata}{0} diff --git a/required/latex-lab/latex-lab-toc-kernel-changes.dtx b/required/latex-lab/latex-lab-toc-kernel-changes.dtx index 2934a2616..5d1b72174 100644 --- a/required/latex-lab/latex-lab-toc-kernel-changes.dtx +++ b/required/latex-lab/latex-lab-toc-kernel-changes.dtx @@ -17,8 +17,8 @@ % for those people who are interested or want to report an issue. % % dates for latex-lab-kernel-changes.sty (pulled from various sources, see ins) -\def\ltlabkerneldate{2024-07-11} -\def\ltlabkernelversion{0.85d} +\def\ltlabkerneldate{2024-12-27} +\def\ltlabkernelversion{0.85e} %<*driver> \documentclass{l3doc} \EnableCrossrefs @@ -154,7 +154,7 @@ % the next main release, so for now we test if they are in the % format and if not define them now. % \begin{macrocode} -\str_if_exist:cF { l__socket_tagsupport/toc/contentsline/before_plug_str } +\socket_if_exist:nF {tagsupport/toc/contentsline/before} { \NewSocket{tagsupport/toc/contentsline/before}{1} \NewSocket{tagsupport/toc/contentsline/after}{1} @@ -203,7 +203,7 @@ % the next main release, so for now we test if they are in the % format and if not define them now. % \begin{macrocode} -\str_if_exist:cF { l__socket_tagsupport/toc/starttoc/before_plug_str } +\socket_if_exist:nF {tagsupport/toc/starttoc/before} { \NewSocket{tagsupport/toc/starttoc/before}{1} \NewSocket{tagsupport/toc/starttoc/after}{1} @@ -270,7 +270,7 @@ % the next main release, so for now we test if they are in the % format and if not define them now. % \begin{macrocode} -\str_if_exist:cF { l__socket_tagsupport/toc/leaders/before_plug_str } +\socket_if_exist:nF {tagsupport/toc/leaders/before} { \NewSocket{tagsupport/toc/leaders/before}{0} \NewSocket{tagsupport/toc/leaders/after}{0} diff --git a/required/latex-lab/latex-lab-toc.dtx b/required/latex-lab/latex-lab-toc.dtx index 83df680bf..711f4f640 100644 --- a/required/latex-lab/latex-lab-toc.dtx +++ b/required/latex-lab/latex-lab-toc.dtx @@ -16,7 +16,7 @@ % % for those people who are interested or want to report an issue. % -\def\ltlabtocdate{2024-12-12} +\def\ltlabtocdate{2024-12-27} \def\ltlabtocversion{0.85e} %<*driver> \documentclass{l3doc} @@ -341,7 +341,7 @@ % \end{plugdecl} % % \subsection{Tagging of the content} -% This need discussion. +% This needs discussion. % % \begin{macrocode} \AddToHook{contentsline/text/before}[tagpdf]{% diff --git a/required/tools/changes.txt b/required/tools/changes.txt index 9adf49717..0f6b0821e 100644 --- a/required/tools/changes.txt +++ b/required/tools/changes.txt @@ -5,6 +5,11 @@ completeness or accuracy and it contains some references to files that are not part of the distribution. ======================================================================= +2024-12-27 Frank Mittelbach + + * multicol.dtx (subsection{Tagging support}): + Use new socket conditional. + 2024-12-22 David Carlisle * xr.dtx: additional documentation of problems with @@ -26,6 +31,7 @@ are not part of the distribution. Added another socket to support tagging. 2024-11-10 Frank Mittelbach + * multicol.dtx (subsection{Supporting the new mark mechanism}): Drop the legacy support for marks and use the new mark mechanism throughout. diff --git a/required/tools/multicol.dtx b/required/tools/multicol.dtx index 1cb322ea6..863c6a1a5 100644 --- a/required/tools/multicol.dtx +++ b/required/tools/multicol.dtx @@ -99,7 +99,7 @@ % \ProvidesFile{multicol.drv} % \fi % \ProvidesFile{multicol.dtx} - [2024/11/21 v2.0a multicolumn formatting (FMi)] + [2024/11/27 v2.0a multicolumn formatting (FMi)] % % % @@ -4628,7 +4628,7 @@ % float sockets. By now they are part of the kernel and their plugs % are currently defined by \pkg{tagpdf}. % \begin{macrocode} -%\str_if_exist:cF { l__socket_tagsupport/float/end_plug_str } +%\IfSocketExistsF {tagsupport/float/end} % { % \NewSocket{tagsupport/float/end}{0} % \NewSocket{tagsupport/float/hmode/end}{0}