Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Set template keys docu #1614

Merged
merged 12 commits into from
Jan 20, 2025
Merged

Set template keys docu #1614

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
777828a
typo
FrankMittelbach Jan 4, 2025
7fa577d
Merge branch 'develop' into SetTemplateKeys
FrankMittelbach Jan 7, 2025
d8a89b8
reordered and changed docu
FrankMittelbach Jan 8, 2025
ead96db
testing for empty in \SetTemplateKays; more docu; changelog; open: cs…
FrankMittelbach Jan 8, 2025
f9d3183
update to \SetKnownTemplateKeys et al; new handling of user supplied …
FrankMittelbach Jan 8, 2025
fd3c0d2
missing decl
FrankMittelbach Jan 8, 2025
8c510ca
Make a proper error message and document why \SetTemplateKeys may not…
FrankMittelbach Jan 13, 2025
e25ddc1
Merge branch 'develop' into SetTemplateKeys
FrankMittelbach Jan 13, 2025
3b9dad5
Merge branch 'develop' into SetTemplateKeys
FrankMittelbach Jan 18, 2025
631d962
update after review
FrankMittelbach Jan 18, 2025
47e018b
updating and reorganizing docu after review
FrankMittelbach Jan 20, 2025
508ba51
typo
FrankMittelbach Jan 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions base/changes.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@ to completeness or accuracy and it contains some references to files that are
not part of the distribution.
================================================================================

2025-01-08 Frank Mittelbach <Frank.Mittelbach@latex-project.org>

* lttemplates.dtx (subsection{User functions}):
Speed up common case of \SetTemplateKeys, i.e., when the
key/val list is empty.

2025-01-03 Frank Mittelbach <Frank.Mittelbach@latex-project.org>

* lthooks.dtx (subsubsection{Updating code for hooks}):
Expand Down
97 changes: 58 additions & 39 deletions base/lttemplates.dtx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
%<*driver>
% \fi
\ProvidesFile{lttemplates.dtx}
[2024-11-17 v1.0d LaTeX Kernel (Prototype document functions)]
[2025-01-08 v1.0e LaTeX Kernel (Prototype document functions)]
% \iffalse
\documentclass{l3doc}
\GetFileInfo{lttemplates.dtx}
Expand Down Expand Up @@ -320,7 +320,7 @@
% \toprule
% \multicolumn{1}{l}{Key-type} & Description of binding \\
% \midrule
% \ & Boolean variable, \emph{e.g}.~\cs{l_tmpa_bool} \\
% boolean & Boolean variable, \emph{e.g}.~\cs{l_tmpa_bool} \\
% choice
% & List of choice implementations
% (see Section~\ref{sec:choices-key}) \\
Expand Down Expand Up @@ -351,12 +351,57 @@
% In the final argument of \cs{DeclareTemplateCode} the assignment of
% keys defined by the template may be delayed by including the command
% \cs{AssignTemplateKeys}. If this is \emph{not} present, keys are assigned
% immediately before the template code. If \cs{AssignTemplateKeys} is
% immediately before the template code. If an
% \cs{AssignTemplateKeys} command is
% present, assignment is delayed until this point. Note that the
% command must be \emph{directly} present in the code, not placed
% within a nested command/macro.
% \end{function}
%

% \begin{function}{\SetTemplateKeys}
% \begin{syntax}
% \cs{SetTemplateKeys} \Arg{type} \Arg{template} \Arg{keyvals}
% \end{syntax}

% In the final argument of \cs{DeclareTemplateCode} one can
% also overwrite the current template key value settings by using the command
% \cs{SetTemplateKeys}, i.e., after the template default
% values and the values from the instance have been assigned.
%
% The main use case for this command is the situation where there
% is an argument (normally \texttt{\#1}) to the template in which
% a key/value list can be specified that overwrites the normal
% settings. In that case one could use
%\begin{quote}
% \verb/\SetTemplateKeys/\Arg{type}\Arg{template}\verb/{#1}/
%\end{quote}
% to process this key/value list inside the template.
%
% If the \meta{keyvals} argument contains keys not known to the
% \meta{template} they are simply ignored without generating an
% error. This way it is possible to apply the same \meta{keyvals}
% specified by the user on a document-level command or environment
% to several templates if their combination makes up that command
% or environment. For example, a list, such as \env{enumerate}, is
% made up from a \texttt{blockenv}, \texttt{block}, \texttt{list},
% and a \texttt{para} template and in the single user-supplied
% optional argument to \verb=\begin{enumerate}= key/values for
% either of them might get specified. In fact, in that particular
% example, that key/val list is also saved and then applied to each
% \cs{item} which is implemented through an \texttt{item}
% template. This way, one can specify one-off settings to all items
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better:
. . . to all the items

I cannot follow this bit:
. . . which is implemented through . . .

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I cannot follow this bit: . . . which is implemented through . . .

The \item command is implement using its own template (through = is implemented using its own template and not using direct coding, for example)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what you mean here!
Whatever, please add some such explanation.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry no idea what I should write in addition. I wonder if the problem is that you look at isolated snippets (because unfortunately that's what the typical review interface is offering you).

FrankMittelbach marked this conversation as resolved.
Show resolved Hide resolved
% of a single whole list (on the environment level), as well as to
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe:
in the whole of a single list . . .

The parenthetical remark is not understandable.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

dropped "whole" but can't see anything wrong with the (...)
and "to all items" -> "for all items"

% individual items within a list (by specifying them in the
FrankMittelbach marked this conversation as resolved.
Show resolved Hide resolved
% optional argument of an \cs{item}).
%
% The \cs{SetTemplateKeys} command is not supported outside of a template declaration
% and if used elsewhere has unpredictable results.
% If both \cs{AssignTemplateKeys} and \cs{SetTemplateKeys} are used
% they should be executed in that order.
% \end{function}
%

% \begin{function}{\DeclareTemplateCopy}
% \begin{syntax}
% \cs{DeclareTemplateCopy}
Expand Down Expand Up @@ -517,7 +562,7 @@
% is the same as creating an instance using \cs{DeclareInstance}
% and immediately using it with \cs{UseInstance}, but without the
% instance having any further existence. It is therefore useful where
FrankMittelbach marked this conversation as resolved.
Show resolved Hide resolved
% a template needs to be used once.
% a template needs to be used only once.
%
% This function can also be used as the argument to \texttt{instance}
% key types:
Expand Down Expand Up @@ -565,39 +610,6 @@
% template untouched.
% \end{function}
%
% \section{\emph{Ad hoc} adjustment of templates}
%
% \begin{function}{\SetTemplateKeys}
% \begin{syntax}
% \cs{SetTemplateKeys} \Arg{type} \Arg{template} \Arg{keyvals}
% \end{syntax}
% At point of use it may be useful to apply changed to individual instances.
% This is supported as each template key is made available for adjustment
% using \cs{SetTemplateKeys}.
% \end{function}
%
% For example, after
% \begin{verbatim}
% \NewTypeType{MyObj}{0}
% \DeclareTemplateInterface{MyObj}{TemplateA}{0}
% {
% akey: tokenlist ,
% bkey: function{2}
% }
% \DeclareTemplateCode{MyObj}{TemplateA}{0}
% {
% akey = SomeTokens ,
% bkey = \func:nn ,
% }
% \end{verbatim}
% the template keys could be adjusted in an \emph{ad hoc} fashion using
% \begin{verbatim}
% \SetTemplateKeys{MyObj}{TemplateA}
% {
% akey = OtherTokens ,
% bkey = \AltFunc:nn
% }
% \end{verbatim}
%
% \section{Getting information about templates and instances}
%
Expand Down Expand Up @@ -2620,10 +2632,17 @@
% \end{macro}
%
% \begin{macro}{\SetTemplateKeys}
% A friendly wrapper
% A friendly wrapper, with some speed up for the common case of the
% third argument being empty.
% \changes{2025-01-08}{v1.0d}{Test for empty key/val list to speed up processing}
% \begin{macrocode}
\cs_new_protected:Npn \SetTemplateKeys #1#2#3
{ \keys_set_known:nnN { template / #1 / #2 } {#3} \l_@@_tmp_clist }
{
\tl_if_empty:nF {#3}
{
\keys_set_known:nnN { template / #1 / #2 } {#3} \l_@@_tmp_clist
}
}
% \end{macrocode}
% \end{macro}
%
Expand Down
12 changes: 6 additions & 6 deletions required/latex-lab/latex-lab-block.dtx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
%
% https://www.latex-project.org/lppl.txt
%
\def\ltlabblockdate{2025-01-06}
\def\ltlabblockversion{0.8x}
\def\ltlabblockdate{2025-01-08}
\def\ltlabblockversion{0.8y}
%<*driver>
\documentclass[kernel]{l3doc}
\usepackage{amstext}
Expand Down Expand Up @@ -1109,7 +1109,7 @@
{
\@@_debug_typeout:n{\l_@@_env_name_tl -env-start}
%
\tl_if_empty:nF {#1} { \SetTemplateKeys{blockenv}{display}{#1} }
\SetTemplateKeys{blockenv}{display}{#1}
%
% \end{macrocode}
% We need to know later if we have nested blockenvs inside
Expand Down Expand Up @@ -1443,7 +1443,7 @@
para-class = \l__tag_para_attr_class_tl ,
}
{
\tl_if_empty:nF {#1} { \SetTemplateKeys{para}{std}{#1} }
\SetTemplateKeys{para}{std}{#1}
\skip_set:Nn \@rightskip \rightskip
}
% \end{macrocode}
Expand Down Expand Up @@ -1485,7 +1485,7 @@
parindent = \l_@@_parindent_dim ,
}
{
\tl_if_empty:nF {#1} { \SetTemplateKeys{block}{display}{#1} }
\SetTemplateKeys{block}{display}{#1}
% \end{macrocode}
% \fmi{generalize heading usage (or drop?)}
% \begin{macrocode}
Expand Down Expand Up @@ -1954,7 +1954,7 @@
% to make use of user keys on the list level}
% \begin{macrocode}
\@@_evaluate_saved_user_keys:nn {item}{std}
\tl_if_empty:nF{#1}{ \SetTemplateKeys{item}{std}{#1} }
\SetTemplateKeys{item}{std}{#1}
% \end{macrocode}
%
% If no optional argument was given then \cs{l_@@_label_given_tl}
Expand Down
Loading