[latex3-commits] [latex3/tagpdf] taggingsocket: improve tagging socket documentation (6522fab)

[github at latex-project.org]

Repository : https://github.com/latex3/tagpdf
On branch  : taggingsocket
Link       : https://github.com/latex3/tagpdf/commit/6522fabb82092e98b3b2073458f11e62f1a07347

>---------------------------------------------------------------

commit 6522fabb82092e98b3b2073458f11e62f1a07347
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date:   Wed Oct 23 11:31:25 2024 +0200

    improve tagging socket documentation


>---------------------------------------------------------------

6522fabb82092e98b3b2073458f11e62f1a07347
 tagpdf-user.dtx | 35 ++++++++++++++++-------------------
 1 file changed, 16 insertions(+), 19 deletions(-)

diff --git a/tagpdf-user.dtx b/tagpdf-user.dtx
index 0dac077..867b1f8 100644
--- a/tagpdf-user.dtx
+++ b/tagpdf-user.dtx
@@ -283,27 +283,24 @@
 %   \verb=\UseSocket{tagsupport/foo}=
 % \end{quote}.
 %
-%  Beside being slightly shorter, the big advantage is that this way
-%  we can change \cs{UseTaggingSocket} to do nothing by switching a boolean
-%  instead of changing the plugs of the tagging support sockets back and forth.
+% Beside being slightly shorter, the big advantage is that this way
+% we can change \cs{UseTaggingSocket} to do nothing by switching a boolean
+% instead of changing the plugs of the tagging support sockets back and forth.
 %
-% Usually, these sockets have exactly two plugs defined. 
-% When using \cs{UseTaggingSocket} the first plug is always 
-% used if tagging is suspended.
-% For the sockets with zero and one argument
-% this is the \texttt{noop} plug, so they gobble the 
-% argument in such a case. The assigned plug use when tagging is enable.
-% The socket with two arguments
-% will drop the first argument and pass the second unchanged if 
-% tagging is not activated and when tagging is activated it
-% will process them as defined by the assigned plug.
-% There may be more plugs, e.g., tagging with special debugging, etc., 
-% but right now it is usually just on or off.
+% Usually, these sockets have (beside the default plug defined for every socket)
+% one additional plug defined and directly assigned. This plug is used when 
+% tagging is active. 
+% When tagging is suspended they all have the same predefined behaviour:
+% The sockets with zero arguments do nothing. The sockets with one argument
+% gobble their argument. The sockets with two arguments
+% will drop their first argument and pass the second unchanged.
+% There may be more plugs, e.g., tagging with special debugging or special behaviour
+% depending on the class or PDF version etc., but right now it is usually just on or off.
 %
-%  It is possible to use the tagging support sockets with
-%  \cs{UseSocket} directly, but in this case the socket remains active
-%  if e.g. \cs{SuspendTagging} is in force. There may be reasons for doing
-%  that but in general we expect to always use \cs{UseTaggingSocket}.
+% It is possible to use the tagging support sockets with
+% \cs{UseSocket} directly, but in this case the socket remains active
+% if e.g. \cs{SuspendTagging} is in force. There may be reasons for doing
+% that but in general we expect to always use \cs{UseTaggingSocket}.
 %
 %  The L3 programming layer versions \cs{tag_socket_use:n}, and
 %  \cs{tag_socket_use:nn}, \cs{tag_socket_use:nnn}