[latex3-commits] [latex3/latex2e] latex-lab-item: doc update (492105ce)

[github at latex-project.org]

Repository : https://github.com/latex3/latex2e
On branch  : latex-lab-item
Link       : https://github.com/latex3/latex2e/commit/492105ce7f0008d3ca9dda2b8a965445b9bcfa1f

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

commit 492105ce7f0008d3ca9dda2b8a965445b9bcfa1f
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Thu Oct 3 09:17:16 2024 +0000

    doc update


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

492105ce7f0008d3ca9dda2b8a965445b9bcfa1f
 required/latex-lab/changes.txt         |  4 ++++
 required/latex-lab/latex-lab-block.dtx | 30 +++++++++++++++++++++++++++++-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/required/latex-lab/changes.txt b/required/latex-lab/changes.txt
index 8dbe56d1..2a091efe 100644
--- a/required/latex-lab/changes.txt
+++ b/required/latex-lab/changes.txt
@@ -1,3 +1,7 @@
+2024-10-03  Frank Mittelbach  <Frank.Mittelbach at latex-project.org>
+	* latex-lab-block.dtx (subsubsection{Implementation of list templates ...}):
+	Pass user keys on list to \item for evaluation
+
 2024-10-02  Ulrike Fischer <Ulrike.Fischer at latex-project.org>
 	* latex-lab-math.dtx (subsection{Sockets}):
 	disable paratagging in inline math (tagging/711)
diff --git a/required/latex-lab/latex-lab-block.dtx b/required/latex-lab/latex-lab-block.dtx
index 16449f81..ee550467 100644
--- a/required/latex-lab/latex-lab-block.dtx
+++ b/required/latex-lab/latex-lab-block.dtx
@@ -2150,7 +2150,20 @@
 %
 %
 %  \begin{macro}{\@@_evaluate_saved_user_keys:nn}
-%    
+%    Keys set on individual list environments may be intended to alter
+%    the behavior of the template instance that defines the \cs{item}
+%    command. If meant to alter only a single \cs{item} command one
+%    would specify them in the optional argument of the \cs{item}, but
+%    if they should alter all items the right place would be the list
+%    environment. For this reason we need to store the values and then
+%    set them inside the \cs{item} template code using
+%    \cs{SetTemplateKeys} in the appropriate context (template type
+%    and template name). This is done in
+%    \cs{@@_evaluate_saved_user_keys:nn}. The context is provided in
+%    the two arguments (because different list environments may use
+%    different \cs{item} instances based on different templates. By
+%    default the command does
+%    nothing because most environments do not have user key settings.
 %    \begin{macrocode}
 \cs_new_eq:NN \@@_evaluate_saved_user_keys:nn \use_none:nn
 %    \end{macrocode}
@@ -2193,6 +2206,14 @@
 {
   \@@_debug_typeout:n{template:list:std}
 %
+%    \end{macrocode}
+%    We start by looking at the user supplied keys in \texttt{\#1}. If
+%    there aren't any we reset \cs{\@@_evaluate_saved_user_keys:nn} to
+%    do nothing. Otherwise we evaluate and set the keys in the contect
+%    of the current list template. In addition we prepare
+%    \cs{\@@_evaluate_saved_user_keys:nn} for execution in the
+%    template for \cs{item}.
+%    \begin{macrocode}
   \tl_if_empty:nTF {#1}
      { \cs_set_eq:NN \@@_evaluate_saved_user_keys:nn \use_none:nn }
      {
@@ -2368,6 +2389,13 @@
 %    was given.
 %    \begin{macrocode}
     \tl_set_eq:NN \l_@@_label_given_tl \c_novalue_tl
+%    \end{macrocode}
+%    First we evaluate and set any keys specified on the list
+%    environment by calling
+%    \cs{\cs{\@@_evaluate_saved_user_keys:nn}. Then we do the same
+%    with all keys specified on this \cs{item} command (which may
+%    overwrite one or the other setting just made).
+%    \begin{macrocode}
     \@@_evaluate_saved_user_keys:nn {item}{std} 
     \tl_if_empty:nF{#1}{ \SetTemplateKeys{item}{std}{#1} }
 %    \end{macrocode}