[latex3-commits] [latex3/latex2e] latexlab/rcb, sockets: talk about socket inputs not arguments (I didn't want to take the analogy as far as talking about "pins") (9e7c9506)
github at latex-project.org
github at latex-project.org
Sun Aug 6 00:10:56 CEST 2023
Repository : https://github.com/latex3/latex2e
On branches: latexlab/rcb,sockets
Link : https://github.com/latex3/latex2e/commit/9e7c95067fa61240a98a62e1cf34709b0495b0b3
>---------------------------------------------------------------
commit 9e7c95067fa61240a98a62e1cf34709b0495b0b3
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Sun Aug 6 00:10:56 2023 +0200
talk about socket inputs not arguments (I didn't want to take the analogy as far as talking about "pins")
>---------------------------------------------------------------
9e7c95067fa61240a98a62e1cf34709b0495b0b3
base/ltsockets.dtx | 86 ++++++++++++++++++++++--------------------
base/testfiles/sockets-000.tlg | 16 ++++----
base/testfiles/sockets-001.tlg | 2 +-
base/testfiles/sockets-002.tlg | 4 +-
4 files changed, 56 insertions(+), 52 deletions(-)
diff --git a/base/ltsockets.dtx b/base/ltsockets.dtx
index d4078e51..82e7f3a2 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 d1487df9..f577da65 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 b96deb5f..131263c1 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 9afbeb7e..ccbb5ef9 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 <return>.
...
@@ -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}
More information about the latex3-commits
mailing list.