diff --git a/base/ltsockets.dtx b/base/ltsockets.dtx index d4078e514..82e7f3a2b 100644 --- a/base/ltsockets.dtx +++ b/base/ltsockets.dtx @@ -31,8 +31,8 @@ %%% From File: ltsockets.dtx % % \begin{macrocode} -\def\ltsocketsversion{0.8c} -\def\ltsocketsdate{2023-07-27} +\def\ltsocketsversion{0.9a} +\def\ltsocketsdate{2023-08-05} % \end{macrocode} % %<*driver> @@ -231,17 +231,18 @@ % reference to a named socket at this point. % This is done by first declaring the named socket with: % \begin{quote} -% \cs{NewSocket}\marg{socket-name}\marg{number-of-arguments} +% \cs{NewSocket}\marg{socket-name}\marg{number-of-inputs} % \end{quote} % This is then referenced at the point where the replaceable code block % should be executed with: % \begin{quote} % \cs{UseSocket}\marg{socket-name} % \end{quote} -% or, if the socket should take a number of arguments with +% or, if the socket should take a number of inputs (additional +% arguments beside the name) with % \begin{quote} % \cs{UseSocket}\marg{socket-name}\marg{arg\textsubscript{1}}\ldots -% \marg{arg\textsubscript{\meta{number-of-arguments}}} +% \marg{arg\textsubscript{\meta{number-of-inputs}}} % \end{quote} % % In addition, several code blocks (a.k.a.\ plugs) implementing different logic for this @@ -260,7 +261,7 @@ % environment can alter a socket without the need to restore the % previous setting manually. % -% If the socket takes arguments, then those need to be provided to +% If the socket takes inputs, then those need to be provided to % \cs{UseSocket} and in that case they can be referenced in the \meta{code} % argument of \cs{NewSocketPlug} with \verb=#1=, \verb=#2=, etc. % @@ -276,7 +277,7 @@ % % % We start by declaring a new socket named \socket{foo} that expects -% two arguments: +% two inputs: %\begin{verbatim} % \NewSocket{foo}{2} %\end{verbatim} @@ -284,7 +285,7 @@ % % Such a declaration has do be unique across the whole \LaTeX{} % run. Thus, if another package attempts to use the same name -% (regardless of the number of arguments) it will generate an error: +% (regardless of the number of inputs) it will generate an error: %\begin{verbatim} % \NewSocket{foo}{2} % \NewSocket{foo}{1} @@ -323,11 +324,11 @@ % \begin{verbatim} % \UseSocket{foo}{hello}{world} % \end{verbatim} -% produces nothing because the default plug for sockets with 2 arguments -% is \plug{noop} (which grabs the arguments and thows them +% produces nothing because the default plug for sockets with 2 inputs +% is \plug{noop} (which grabs the additional arguments and thows them % away).\footnote{If socket \socket{foo} would have been a socket with one -% argument, then the default plug would be \plug{identity}, in which case -% the argument would remain without braces and gets typeset!} +% input, then the default plug would be \plug{identity}, in which case +% the socket input would remain without braces and gets typeset!} % % \UseSocket{foo}{hello}{world} ^^A nothing happens % @@ -367,7 +368,7 @@ % to this on the terminal or in the transcript file: % \begin{verbatim} % Socket foo: -% number of arguments = 2 +% number of inputs = 2 % available plugs = noop, plug-A, plug-B % current plug = plug-B % definition = \protected\long macro:#1#2->\begin {quote}\sffamily @@ -384,7 +385,7 @@ % % \item % From a functional point of view sockets are like simple \TeX{} macros, -% i.e., they expect 0 to 9 mandatory arguments and get replaced by +% i.e., they expect 0 to 9 mandatory arguments (the socket inputs) and get replaced by % their \enquote{expansion} % % \item @@ -473,8 +474,8 @@ % the same plug name with different sockets (where based on the % socket different actions may be associated with the plug % name). For example \plug{noop} is a plug name declared for every -% socket, yet it action \enquote{grab the socket arguments and throw -% them away} obviously differs depending on how many arguments the +% socket, yet it action \enquote{grab the socket inputs and throw +% them away} obviously differs depending on how many inputs the % socket has. % % \item @@ -529,18 +530,19 @@ % % \begin{function}{\NewSocket,\socket_new:nn} % \begin{syntax} -% \cs{NewSocket} \Arg{socket-name}\Arg{number-of-arguments} -% \cs{socket_new:nn}\Arg{socket-name}\Arg{number-of-arguments} +% \cs{NewSocket} \Arg{socket-name}\Arg{number-of-inputs} +% \cs{socket_new:nn}\Arg{socket-name}\Arg{number-of-inputs} % \end{syntax} % Declares a new socket with name \meta{socket-name} having -% \meta{number-of-arguments} arguments. There is automatically a +% \meta{number-of-inputs} inputs. There is automatically a % plug {noop} declared for it, which does nothing, i.e., it gobbles -% the socket argument. This is made the default plug except for -% sockets with one argument which use \plug{identity} as their default. +% the socket inputs (if any). This is made the default plug except for +% sockets with one input which additionally define the plug +% \plug{identity} and assign that as their default. % -% This \plug{identity} plug simply returns the socket argument without +% This \plug{identity} plug simply returns the socket input without % its outer braces. -% The use case for this are situations like this: +% The use case for this plug are situations like this: % \begin{quote} % \cs{UseSocket}\verb={tagsupport/footnote}=\Arg{code} % \end{quote} @@ -549,6 +551,8 @@ % activate tagging all that is necessary is to change the plug to % say \plug{tagpdf} so % that it surrounds \meta{code} by some tagging magic. +% This is the most common use case for sockets with one input, which +% is why they have this special default. % % The socket documentation should describe its purpose, its inputs and the % expected results as discussed above. @@ -602,14 +606,14 @@ % was declared! % % The different L3 programming layer commands are really doing the -% same thing: they grab as many arguments as defined for the socket +% same thing: they grab as many arguments as defined as inputs for the socket % and then pass them to the plug. The different names are only there % to make the code more readable, i.e., to indicate how many -% arguments are grabbed (note that no runtime check is made to +% arguments are grabbed in total (note that no runtime check is made to % verify that this is actually true). We only provide them for -% sockets with up to 3 arguments (most likely the one with one argument would +% sockets with up to 3 inputs (most likely those with zero or one input would % have been sufficient). If you happen to have a socket with more -% arguments, use \cs{socket_use:nw}. +% inputs, use \cs{socket_use:nw}. % \end{function} % % @@ -741,9 +745,9 @@ % % Declaring a socket creates a str to hold the name (a pointer) to the % code that should be used when the socket is executed, and an integer to -% hold the number of arguments of that socket. Initially, an +% hold the number of inputs of that socket. Initially, an % ``empty'' code chunk is created and assigned so the socket -% does nothing by default other than swallowing its arguments (if any). +% 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 } @@ -767,7 +771,7 @@ } { \socket_assign_plug:nn {#1} { noop } } \@@_debug_term:n - { Socket~ '#1'~ declared~ with~ #2~ argument(s) } + { Socket~ '#1'~ declared~ with~ #2~ input(s) } } { \msg_error:nn { socket } { not-top-level } @@ -786,7 +790,7 @@ \typeout{ Socket~ #1:} \str_if_exist:cTF { l_@@_#1_plug_str } { - \typeout{ \@spaces number~ of~ arguments~ =~ + \typeout{ \@spaces number~ of~ inputs~ =~ \int_use:c { c_@@_#1_args_int } } \typeout{ \@spaces available~plugs~ =~ \seq_use:cnnn { l_@@_#1_plugs_seq }{,~}{,~}{,~} } @@ -908,11 +912,11 @@ % runtime check for speed reasons! % % This command is named -% \cs{socket_use:nw} because we don't know how many arguments the +% \cs{socket_use:nw} because we don't know how many inputs the % socket has until we have looked at the socket name (in argument \verb=#1=). % But, of course, the developer knows so we also offer a few aliases \cs{socket_use:nn}, -% etc.\ so that one can indicate the correct number of arguments in -% L3 layer code. +% etc.\ so that one can indicate the correct number of arguments +% (socket inputs plus one) in the L3 layer code. % % \begin{macrocode} \cs_new_protected:Npn \socket_use:nw #1 { @@ -923,16 +927,16 @@ } % \end{macrocode} % To make code a bit more readable we also define functions that -% indicate how many arguments the socket takes. However, this is just for -% code documentation internally: they all do the same and the number +% indicate how many arguments are picked up. However, this is just for +% code documentation: internally they all do the same and the number % of arguments isn't checked by default. % \begin{macrocode} -\cs_new_eq:NN \socket_use:n \socket_use:nw % socket with no args -\cs_new_eq:NN \socket_use:nn \socket_use:nw % socket with one arg -\cs_new_eq:NN \socket_use:nnn \socket_use:nw % socket with two args -\cs_new_eq:NN \socket_use:nnnn \socket_use:nw % socket with three args +\cs_new_eq:NN \socket_use:n \socket_use:nw % socket with no inputs +\cs_new_eq:NN \socket_use:nn \socket_use:nw % socket with one input +\cs_new_eq:NN \socket_use:nnn \socket_use:nw % socket with two inputs +\cs_new_eq:NN \socket_use:nnnn \socket_use:nw % socket with three inputs % \end{macrocode} -% The above commands could be changed to check how many arguments +% The above commands could be changed to check how many inputs % the socket is declared with (for example, when checking is in % force). % \fmi{Implement?} diff --git a/base/testfiles/sockets-000.tlg b/base/testfiles/sockets-000.tlg index d1487df9e..f577da656 100644 --- a/base/testfiles/sockets-000.tlg +++ b/base/testfiles/sockets-000.tlg @@ -1,7 +1,7 @@ This is a generated file for the l3build validation system. Don't change this file in any respect. Socket foo0: - number of arguments = 0 + number of inputs = 0 available plugs = noop current plug = noop definition = \protected\long macro:-> @@ -13,7 +13,7 @@ command, so I can't give any explicit help. Pretend that you're Hercule Poirot: Examine all clues, and deduce the truth by order and method. Socket foo1: - number of arguments = 1 + number of inputs = 1 available plugs = noop, identity current plug = identity definition = \protected\long macro:#1->#1 @@ -22,7 +22,7 @@ Socket foo1: l. ...\ShowSocket {foo1} (That was another \errmessage.) Socket foo2: - number of arguments = 2 + number of inputs = 2 available plugs = noop current plug = noop definition = \protected\long macro:#1#2-> @@ -31,7 +31,7 @@ Socket foo2: l. ...\ShowSocket {foo2} (That was another \errmessage.) Socket foo3: - number of arguments = 3 + number of inputs = 3 available plugs = noop current plug = noop definition = \protected\long macro:#1#2#3-> @@ -44,22 +44,22 @@ AAA 99= 88 ? ---------------------- Socket bar0: - number of arguments = 0 + number of inputs = 0 available plugs = noop current plug = noop definition = \protected\long macro:-> Socket bar1: - number of arguments = 1 + number of inputs = 1 available plugs = noop, identity current plug = identity definition = \protected\long macro:#1->#1 Socket bar2: - number of arguments = 2 + number of inputs = 2 available plugs = noop current plug = noop definition = \protected\long macro:#1#2-> Socket bar3: - number of arguments = 3 + number of inputs = 3 available plugs = noop current plug = noop definition = \protected\long macro:#1#2#3-> diff --git a/base/testfiles/sockets-001.tlg b/base/testfiles/sockets-001.tlg index b96deb5f1..131263c1d 100644 --- a/base/testfiles/sockets-001.tlg +++ b/base/testfiles/sockets-001.tlg @@ -31,7 +31,7 @@ sensible to do so. Use the L3 programming layer function \socket_set_plug:nnn if you really have to. ---------------------- Socket foo: - number of arguments = 0 + number of inputs = 0 available plugs = noop, default current plug = noop definition = \protected\long macro:->\typeout {modified noop} diff --git a/base/testfiles/sockets-002.tlg b/base/testfiles/sockets-002.tlg index 9afbeb7ef..ccbb5ef92 100644 --- a/base/testfiles/sockets-002.tlg +++ b/base/testfiles/sockets-002.tlg @@ -9,7 +9,7 @@ It is not allowed to declare sockets inside a group. Move the declaration to the top-level. [Sockets] ==> Plug 'noop' for socket 'foo' declared. [Sockets] ==> Replacing plug '' with 'noop' in socket 'foo'. -[Sockets] ==> Socket 'foo' declared with 0 argument(s) +[Sockets] ==> Socket 'foo' declared with 0 input(s) ! LaTeX socket Error: Socket 'foo' already declared! For immediate help type H . ... @@ -36,7 +36,7 @@ if you really have to. [Sockets] ==> Plug 'noop' for socket 'foo' changed. ---------------------- Socket foo: - number of arguments = 0 + number of inputs = 0 available plugs = noop, default current plug = noop definition = \protected\long macro:->\typeout {modified noop}