talk about socket inputs not arguments (I didn't want to take the ana…

…logy as far as talking about "pins")

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,15 +277,15 @@
 % 
 % 
 % We start by declaring a new socket named \socket{foo} that expects
-% two arguments:
+% two inputs:
 %\begin{verbatim}
 %      \NewSocket{foo}{2}
 %\end{verbatim}
 % \NewSocket{foo}{2}
 % 
 % 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?} 

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->

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}

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}