[latex3-commits] [latex3/latex2e] mk/taggingsocket: Make two argument tagging sockets preserve the second arg when suspended (eca91bcea)
github at latex-project.org
github at latex-project.org
Sun Oct 27 11:34:22 CET 2024
Repository : https://github.com/latex3/latex2e
On branch : mk/taggingsocket
Link : https://github.com/latex3/latex2e/commit/eca91bceae87ffa72179451d6237488249d4711f
>---------------------------------------------------------------
commit eca91bceae87ffa72179451d6237488249d4711f
Author: Marcel Fabian Krüger <tex at 2krueger.de>
Date: Mon Oct 21 00:32:34 2024 +0200
Make two argument tagging sockets preserve the second arg when suspended
Synchronized with 7a2b09d51edb7ee5619c45e33e126e48f1d3b406 in tagpdf.
>---------------------------------------------------------------
eca91bceae87ffa72179451d6237488249d4711f
base/changes.txt | 4 +++
base/lttagging.dtx | 73 +++++++++++++++++++++++++++---------------------------
2 files changed, 41 insertions(+), 36 deletions(-)
diff --git a/base/changes.txt b/base/changes.txt
index feeb2fd15..7361e2bf0 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,10 @@ to completeness or accuracy and it contains some references to files that are
not part of the distribution.
================================================================================
+2024-10-21 Marcel Krüger <Marcel.Krueger at latex-project.org>
+ * lttagging.dtx
+ Adapt two argument tagging sockets to preserve second argument when the socket is disabled.
+
2024-10-26 Yukai Chou <muzimuzhi at gmail.com>
* ltcounts.dtx (subsection{Environment Counter Macros}):
Fully expand counter name in \theH<counter> commands (gh/1508)
diff --git a/base/lttagging.dtx b/base/lttagging.dtx
index 74735a376..6c67c3d6b 100644
--- a/base/lttagging.dtx
+++ b/base/lttagging.dtx
@@ -33,7 +33,7 @@
%<*driver>
% \fi
\ProvidesFile{lttagging.dtx}
- [2024/10/11 v1.0j LaTeX Kernel (tagging support)]
+ [2024/10/21 v1.0k LaTeX Kernel (tagging support)]
% \iffalse
\documentclass{l3doc}
\GetFileInfo{lttagging.dtx}
@@ -107,45 +107,45 @@
% \DescribeMacro\UseTaggingSocket
% \DescribeMacro\tag_socket_use:n
% \DescribeMacro\tag_socket_use:nn
-% To support tagging in packages we use sockets with names starting
-% with \texttt{tagsupport/}. Usually, these sockets have exactly two
-% plugs defined:
-% \plug{noop} (when no tagging is requested or tagging is not wanted
-% for some reason) and a second plug that enables the tagging. There
-% may be more, e.g., tagging with special debugging, etc., but right
-% now it is usually just on or off.
-%
-% Given that we sometimes have to suspend tagging, it would be fairly
-% inefficient to put different plugs into these sockets whenever that
-% happens. We therefore offer \cs{UseTaggingSocket} which is like
-% \cs{UseSocket} except that the socket name is specified without
-% \texttt{tagsupport/}, i.e.,
+% \DescribeMacro\tag_socket_use:nnn
+% Given that we sometimes have to suspend tagging, it would be fairly
+% inefficient to put different plugs into these sockets whenever that
+% happens. We therefore offer \cs{UseTaggingSocket} which is like
+% \cs{UseSocket} except that is expects a socket starting with
+% \texttt{tagsupport/} but the socket name is specified without
+% this prefix, i.e.,
% \begin{quote}
% \verb=\UseTaggingSocket{foo}= $\to$
% \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 when tagging is
-% suspended with \cs{SuspendTagging} instead of changing the plugs of
-% the tagging support sockets back and forth.
+% \end{quote}.
%
-% This means that with \cs{SuspendTagging} in force all socket
-% arguments are ignored (including the case when there is a single
-% one), i.e., all sockets used with \cs{UseTaggingSocket} behave as
-% if the \text{noop} plug is assigned.
+% 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} instead of \cs{UseTaggingSocket}, but in this case
-% the socket remains active if \cs{SuspendTagging} is in force. There
-% may be reasons for doing that, but in general we expect to always
-% use \cs{UseTaggingSocket}.
+% \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} are slightly more efficient than
+% 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, so in code that
-% is using the L3 programming layer we recommend to use them instead
-% of the CamelCase command.
+% many arguments the socket takes when disabling it.
%
%
% \MaybeStop{}
@@ -170,6 +170,7 @@
%
% \begin{macro}{\tag_socket_use:n,
% \tag_socket_use:nn,
+% \tag_socket_use:nnn,
% \UseTaggingSocket,
% }
% Again this is not the final definition for the kernel; it is just
@@ -187,19 +188,19 @@
%
% Dummy definitions in the kernel.
% These definitions will get updated in \pkg{tagpdf}.
+% The default in the kernel is just to get rid of the first argument, the second is preserved if present:
+% \changes{v1.0k}{2024/10/21}{Changed behavior of two argument tagging sockets when disabled.}
% \begin{macrocode}
\cs_new_protected:Npn \tag_socket_use:n #1 { }
\cs_new_protected:Npn \tag_socket_use:nn #1#2 { }
-% \end{macrocode}
-% The default in the kernel is just to get rid of the argument:
-% \begin{macrocode}
+\cs_new_protected:Npn \tag_socket_use:nnn #1#2#3 { #3 }
\cs_new_protected:Npn \UseTaggingSocket #1 {
\int_case:nnF
{ \int_use:c { c__socket_tagsupport/#1_args_int } }
{
0 \prg_do_nothing:
1 \use_none:n
- 2 \use_none:nn
+ 2 \use_ii:nn
% \end{macrocode}
% We do not expect tagging sockets with more than one or two
% arguments, so for now we only provide those.
More information about the latex3-commits
mailing list.