[latex3-commits] [latex3/latex2e] mk/taggingsocket: Resync documentation with tagpdf (aad6f309b)

[github at latex-project.org]

Repository : https://github.com/latex3/latex2e
On branch  : mk/taggingsocket
Link       : https://github.com/latex3/latex2e/commit/aad6f309bb4063c89333d564a9ee6e6203c406a6

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

commit aad6f309bb4063c89333d564a9ee6e6203c406a6
Author: Marcel Fabian Krüger <tex at 2krueger.de>
Date:   Sun Oct 27 11:33:30 2024 +0100

    Resync documentation with tagpdf


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

aad6f309bb4063c89333d564a9ee6e6203c406a6
 base/lttagging.dtx | 50 ++++++++++++++++++++++----------------------------
 1 file changed, 22 insertions(+), 28 deletions(-)

diff --git a/base/lttagging.dtx b/base/lttagging.dtx
index 6301b9ed1..6fb2dc3c9 100644
--- a/base/lttagging.dtx
+++ b/base/lttagging.dtx
@@ -121,34 +121,28 @@
 %   \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.
-%
-% 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.
-%
-%  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}.
-%
-%  For special cases like in some \cs{halign} contexts we need a fully expandable
-%  version of the commend. For these cases, \cs{UseExpandableTaggingSocket} can be
-%  used.
-%
-%  The L3 programming layer versions \cs{tag_socket_use_expandable:n},
-%  \cs{tag_socket_use:n}, \cs{tag_socket_use:nn}, and \cs{tag_socket_use:nnn}
+% 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 (beside the default plug defined for every socket)
+% one additional plug defined and directly assigned. This plug is used when
+% tagging is active.
+% 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.
+%
+% 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.
+%
+% 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}
 %  are slightly more efficient than
 %  \cs{UseTaggingSocket} because they do not have to determine how
 %  many arguments the socket takes when disabling it.