Set template keys docu

[FrankMittelbach]

Internal housekeeping

Status of pull request

• Feedback wanted
• Ready to merge

Checklist of required changes before merge will be approved

• [n/a] Test file(s) added
• [n/a] Version and date string updated in changed source files
• [n/a] Relevant \changes entries in source included
• [n/a] Relevant changes.txt updated
• [n/a] Rollback provided (if necessary)?
• [n/a] ltnewsX.tex (and/or latexchanges.tex) updated

One thing to consider: change name from \SetTemplateKeys to \OverwriteTemplateKeys, which seems to me sits better with \AssignTemplateKeys(as it is theny clear what the order would be). It is not used in texmf (other than in latex-lab) so that could be a breaking change without problems.

[FrankMittelbach]

more exactly there is one usage in keytheorems by @mbertucci47 and I think we can arrange a smooth transition if we decide on a name change.

[josephwright]

\SetTemplateKeys was modelled ultimately on \setkeys (which is why we have \keys_set:nn, etc.) - but if the overall feeling is an alternative name is better, I see no problem changing. If we do, there needs to be an adjustment in xtemplate (which is 'frozen' so does need to keep the existing name available).

[FrankMittelbach]

\SetTemplateKeys was modelled ultimately on \setkeys (which is why we have \keys_set:nn, etc.) - but if the overall feeling is an alternative name is better, I see no problem changing. If we do, there needs to be an adjustment in xtemplate (which is 'frozen' so does need to keep the existing name available).

Maybe it should be called \SetKnownTemplateKeys then, because that's what it is and then a confusion with \AssignTemplateKeysis less likely (imo).

[josephwright]

Maybe it should be called \SetKnownTemplateKeys then, because that's what it is and then a confusion with \AssignTemplateKeysis less likely (imo).

I thought that the fact this says 'template keys' suggested it would only handle known ones - but again no objection to a change.

[FrankMittelbach]

Maybe it should be called \SetKnownTemplateKeys then, because that's what it is and then a confusion with \AssignTemplateKeysis less likely (imo).

I thought that the fact this says 'template keys' suggested it would only handle known ones - but again no objection to a change.

why would it? It could be a wrapper for \keys_set:nn as you wrote (and the name currently implies) and that would complain about unkown keys, wouldn't it?

[u-fischer]

I don't quite like \OverwriteTemplateKeys. It doesn't clarify for me that the command should be used inside a template better than \SetTemplateKeys. Actually "overwrite" sounds for me more like a global forced change and so is more confusing than the \Set-command.
\SetKnownTemplateKeys is an option, but it mainly tells me that it won't error if unknown keys are passed to the command.

[FrankMittelbach]

I don't quite like \OverwriteTemplateKeys. It doesn't clarify for me that the command should be used inside a template better than \SetTemplateKeys. Actually "overwrite" sounds for me more like a global forced change and so is more confusing than the \Set-command. \SetKnownTemplateKeys is an option, but it mainly tells me that it won't error if unknown keys are passed to the command.

Nothing really tells that it should only be used in the template code and it would be hard to get that into the name (which is why that is explicitly documented now) but using "Known" helps when reading code where it is in the right place, then you immediately see why it could get keys that do not fit for that particular template without ding harm and it fits with the underlying command which is \keys_set_known:nnN. But I'm not insisting on a change, just think that it might be result in a slightly better code reading.

[u-fischer]

but using "Known" helps when reading code where it is in the right place

yes how unknown keys are handled is certainly a question that would come to my mind, and it would fit better the definition as the underlying command is \keys_set_known:nnN. Side question: should the list of unknown, unprocessed keys be made publicitly available somehow?

[FrankMittelbach]

but using "Known" helps when reading code where it is in the right place

yes how unknown keys are handled is certainly a question that would come to my mind, and it would fit better the definition as the underlying command is \keys_set_known:nnN. Side question: should the list of unknown, unprocessed keys be made publicitly available somehow?

It would be nice, but rather hard, if even possible, to implement. For example, the key/vals to \begin{enumerate} are passed on to 3 or 4 templates making up the list, but also to the item template for the individual items in the list. Such scenarios make it imho infeasable to try to keep track of this. But if anybody sees a good way ...?

[FrankMittelbach]

I have now updated and extended the documentation as well as moved the empty test inside the command, so I think it is ready for another review. What remains open is the csname. Are we good with \SetKnownTemplateKeys or should we keep the old name?

[u-fischer]

It would be nice, but rather hard, if even possible, to implement. For example, the key/vals to \begin{enumerate} are passed on to 3 or 4 templates making up the list, but also to the item template for the individual items in the list. Such scenarios make it imho infeasable to try to keep track of this. But if anybody sees a good way ...

I didn't mean a general tracking. \SetTemplateKeys does a \keys_set_known:nnN { template / #1 / #2 } {#3} \l_@@_tmp_clist, and I wondered if this could be a public clist instead of an internal one, e.g. for checks in cases one knows that only known keys should be passed or if one want to pass the rest to an internal template. Or perhaps \SetKnownTemplateKeys could use four argument and the last one stores the remaining keys while \SetTemplateKeys stays at is?

[FrankMittelbach]

It would be nice, but rather hard, if even possible, to implement. For example, the key/vals to \begin{enumerate} are passed on to 3 or 4 templates making up the list, but also to the item template for the individual items in the list. Such scenarios make it imho infeasable to try to keep track of this. But if anybody sees a good way ...

I didn't mean a general tracking. \SetTemplateKeys does a \keys_set_known:nnN { template / #1 / #2 } {#3} \l_@@_tmp_clist, and I wondered if this could be a public clist instead of an internal one, e.g. for checks in cases one knows that only known keys should be passed or if one want to pass the rest to an internal template. Or perhaps \SetKnownTemplateKeys could use four argument and the last one stores the remaining keys while \SetTemplateKeys stays at is?

ok, back to the drawing board then. what about this?

\ExplSyntaxOn

% error on unknown keys
\cs_set_protected:Npn \SetTemplateKeys #1#2#3
  {
    \tl_if_empty:oF {#3}
      {
        \keys_set:no { template / #1 / #2 } {#3}
      }
  }
  
 % supports unknown keys and returns them for further processing 
\cs_new_protected:Npn \SetKnownTemplateKeys #1#2#3#4
  {
    \tl_if_empty:oF {#3}
      {
        \keys_set_known:noN { template / #1 / #2 } {#3} #4
      }
  }

\SetKnownTemplateKeys {block}{display} {a=a, b=b, c=c} \foo
\show\foo
\SetKnownTemplateKeys {list}{display} {\foo} \bar
\show\bar

% process remaining keys (should be empty after that
% Or to be used when you know that you shouldn't have unknown ones
\SetTemplateKeys {para}{std} {\bar}

It would be for sure a breaking change, but I guess not a bad one.

[u-fischer]

one would have to check the block code and adapt the uses there but beside this this looks fine imho.

[FrankMittelbach]

one would have to check the block code and adapt the uses there but beside this this looks fine imho.

sure, the block code is already adapted as part of the PR (but it needs a corresponding change then)

[mbertucci47]

@FrankMittelbach I've already removed the usage in keytheorems and use \EditInstance instead

[FrankMittelbach]

@FrankMittelbach I've already removed the usage in keytheorems and use \EditInstance instead

ah, so much the better, then there is no usage of the current command other than in latex-lab, makes life easy. Btw, what to you think of the new docs and the suggested change/extension?

[mbertucci47]

I like the documentation changes. I'm not sure I fully understand the discussion about known/unknown keys, but I'm not a fan of the lack of error when an unknown key is passed to, say, \begin{enumerate}. It's too easy to misremember leftmargin as left-margin or left margin and be confused why nothing is changing.

[josephwright]

I like the documentation changes. I'm not sure I fully understand the discussion about known/unknown keys, but I'm not a fan of the lack of error when an unknown key is passed to, say, \begin{enumerate}. It's too easy to misremember leftmargin as left-margin or left margin and be confused why nothing is changing.

The problem is that as @FrankMittelbach has indicated, you might need several templates for a complex case like this. So how do you decide where to issue a warning? We really don't want users to have to work out which template is which for setting keys - we looked at prefixing all keys, and it doesn't make a good interface.

[Skillmon]

Nothing really tells that it should only be used in the template code and it would be hard to get that into the name (which is why that is explicitly documented now) but using "Known" helps when reading code where it is in the right place, then you immediately see why it could get keys that do not fit for that particular template without ding harm and it fits with the underlying command which is \keys_set_known:nnN. But I'm not insisting on a change, just think that it might be result in a slightly better code reading.

Not that I have much to say about this, but if this should only be used inside template code how about something like \SetThisTemplatesKeys or \SetTemplateInstanceKeys? (Please ignore if this sounds stupid)

[car222222]

@FrankMittelbach @josephwright
It seems that this is still ongoing, so I shall not review it until it is finalised.

[FrankMittelbach]

Not that I have much to say about this, but if this should only be used inside template code how about something like \SetThisTemplatesKeys or \SetTemplateInstanceKeys? (Please ignore if this sounds stupid)

Using "This" in the name would help with identifying where it should be, but assuming it is in the right place, the important info for somebody reading the code is whether it only deals with known, keys (and ignores the rest) or whether it handles everything in its argument (and complains if it finds some unknown ones). and putting in "Known" as well makes the name really horrible in my eyes.

Thus I think it is better to find a name that it good for somebody reading the code and document where to put it for those writing the code, hence my current names.

[FrankMittelbach]

@FrankMittelbach @josephwright It seems that this is still ongoing, so I shall not review it until it is finalised.

I think it is ready enough for your review (otherwise you might find it got merged)

The only open question for me is whether or not top fully dop \SetTemplateKeyswhich would mean a slight rewrite and dropping a footnote.

[josephwright]

I think we could probably drop \SetTemplateKeys here as we have a clearer name

[car222222]

Quite a lot here by now.

[car222222]

Thanks for waiting!

[car222222]

Not sure what was meant here:

whether or not top fully dop \SetTemplateKeys

Maybe it should read :
whether to simply drop \SetTemplateKeys

[davidcarlisle]

Having both \SetKnownTemplateKeys and \SetTemplateKeysis a little awkward but as discussion in this PR shows the use cases aren't totally clear until more experience with using these in the wild emerges. Keeping both seems wise for now. approving with no change

[FrankMittelbach]

Quite a lot here by now.

@car222222 I think I address them all (with one or the other question)

[FrankMittelbach]

One could call it \SetAllTemplateKeys perhaps but I think the distinction is basically clear: one sets what it understands the other tries all and complains of it doesn't understand some keys

[car222222]

I have not yet looked at the latest version: do you want me to check the most recent changes?
I see nothing here to suggest that there even is now such a new version: the last edits recorded here are these from about a week ago:
"Make a proper error message and document . . .".

[u-fischer]

In a new example in the tagging project I came across this example:

\DocumentMetadata{uncompress,testphase=latest}
\documentclass{article}
\usepackage{paralist}
\usepackage{multicol}

\begin{document}
\begin{enumerate}[\bfseries 1.]
 \begin{multicols}{4}
  \item $s = t^2$
  \item $s = 9.8t^2$
  \item $s = -16t^2 + 2t$
  \item $s = t^3$
 \end{multicols}
 \item By equation
 \end{enumerate}
\end{document}

This compiles in main and develop, compared to the original the numbers are not in bold but the layout and the tagging looks ok).

In this branch this now errors:

! Package block Error: Some keys specified on the enumerate environment are
(block)                unknown.

[FrankMittelbach]

In a new example in the tagging project I came across this example:

\DocumentMetadata{uncompress,testphase=latest}
\documentclass{article}
\usepackage{paralist}
\usepackage{multicol}

\begin{document}
\begin{enumerate}[\bfseries 1.]
 \begin{multicols}{4}
  \item $s = t^2$
  \item $s = 9.8t^2$
  \item $s = -16t^2 + 2t$
  \item $s = t^3$
 \end{multicols}
 \item By equation
 \end{enumerate}
\end{document}

This compiles in main and develop, compared to the original the numbers are not in bold but the layout and the tagging looks ok).

In this branch this now errors:

! Package block Error: Some keys specified on the enumerate environment are
(block)                unknown.

well, paralist overwrites enumerate, thus even privously it only worked by chance (tagging because evenually it called the list environment I guess). And according to the compatibility table paralist is incompatible (and now this shows a bit clearer).

Besides: I don't think that putting multicols in the middle can beconsidered correct syntax, but that isn't the problem here.

[u-fischer]

well, paralist overwrites enumerate, thus even privously it only worked by chance (tagging because evenually it called the list environment I guess). And according to the compatibility table paralist is incompatible (and now this shows a bit clearer).

Yes, but should it already be an error? Or should we only warn at the current state that these keys have not been processed?

Besides: I don't think that putting multicols in the middle can beconsidered correct syntax, but that isn't the problem here.

It's creepy ;-) But it seems to work as intended.

[car222222]

Ok, now I have found the "8 commits 7 days ago".
This surprisingly contains stuff from a lot more than 7 days ago and only 2/3 days ago . . . very strange.

[car222222]

I added some replies:
see the "6 files changed" above.

I can still,see many problems with the explanations, in both linguistic details and more fundamentally.

But since the code is now as agreed, next to release this now.

I anyway need to look again at how this whole area has evolved, in the light of the complexities of current usages.

. . . one day!

[FrankMittelbach]

It's creepy ;-) But it seems to work as intended.

aus Falschem folgt Beliebiges

[FrankMittelbach]

Ok, now I have found the "8 commits 7 days ago". This surprisingly contains stuff from a lot more than 7 days ago and only 2/3 days ago . . . very strange.

I only wanted to point out that there have been commits. One of them is bringing the banch up to speed with unrelated development already in the -dev branch, so if you look at the individual commits you will see a lot more.

[FrankMittelbach]

I added some replies: see the "6 files changed" above.

sorry don't see any new replies from you (and I also got no email notices, which I normally get)

I can still,see many problems with the explanations, in both linguistic details and more fundamentally.

But since the code is now as agreed, next to release this now.

I anyway need to look again at how this whole area has evolved, in the light of the complexities of current usages.

. . . one day!

well, one day look at the whole thing, it seems that on the level of review of snippets that is just not workable (as you then do not see the explanations that are nearby (which may or may not be sufficient, but that can't be assest from then bits that have changed.).