Cannot set leftmargin via \SetTemplateKeys{block}{display}

[mbertucci47]

I am trying to implement margin setting for keytheorems with tagging enabled and ran into trouble overriding the block settings locally with \SetTemplateKeys. The following MWE shows the issue:

\DocumentMetadata
  {
    lang=en-US,
    pdfversion=2.0,
    pdfstandard=ua-2,
    testphase={phase-III,math,table,title,firstaid}
  }
\documentclass{article} 

\usepackage{kantlipsum}

\SetTemplateKeys{block}{display}{
  leftmargin=2cm, % does nothing
  rightmargin=2cm, % this works
  }

\begin{document}

\kant[1][1-2]
\kant[2][1-2]
\begin{enumerate}%[leftmargin=2cm] % this works
\item abc
\item \kant[1][1-2]
\kant[2][1-2]
\end{enumerate}
    
\end{document}

If leftmargin or rightmargin is set in the optional argument of enumerate then it works as expected. The same is true for rightmargin if set with \SetTemplateKeys{block}{display}. But leftmargin set in \SetTemplateKeys has no effect. It doesn't matter if this is executed in the preamble or right before the environment.

Am I trying to use this the wrong way? Or is this a bug in the block code? Even in the first case, it's odd that rightmargin does something while leftmargin does not.

[u-fischer]

The block still calls the legacy commands, in this case \@listi and that contains
\leftmargin\leftmargini.

[mbertucci47]

@u-fischer I see, thanks. I understand these interfaces are a work in progress. So is there any way to change the settings besides either passing the key directly to enumerate or redefining \@listi? I guess setting \leftmargini but that assumes I know the current listdepth is 1.

[FrankMittelbach]

I think we have conflicting goals here. I think that the block implementation has to make use of the legacy list environments because they are all over the place in existing document classes and as long as those aren't updated (and many will not) this means that either we keep it (which allows for tagging even of those classes) or drop it (which means we rule out those as being usable going forward) without a full replacement of their code.

So my tendency is to just document this as a restriction.

[mbertucci47]

@FrankMittelbach I'm a little confused. Isn't the point of separating the block and list templates to remove any connection between them? At least for kernel commands where you have full control, shouldn't there be a trueblock or something that uses its own parameters completely separate from the list parameters?

[FrankMittelbach]

@FrankMittelbach I'm a little confused. Isn't the point of separating the block and list templates to remove any connection between them? At least for kernel commands where you have full control, shouldn't there be a trueblock or something that uses its own parameters completely separate from the list parameters?

@mbertucci47 yes the idea is to separate both and for new classes that do not also implement \@listi and friends that would be the case (and the intention is to offer such classes eventually). However, the goal also is to make existing classes work evne if they do not get updated and that means honoring their \@listi settings somehow. That means you can't overwrite their settings as cleanly is you could otherwise but if we don't do that then their settings would be ignored which means tagging or no tagging would result in possibly severe layout differences.

Some of that behavior might eventually be controlled with something like compatibility={...} in \DocumentMetadata but we are not quite there yet.

[senthilmm]

I am not sure whether this is a viable solution.

\DocumentMetadata
{
lang=en-US,
pdfversion=2.0,
pdfstandard=ua-2,
testphase={phase-III,math,table,title,firstaid}
}
\documentclass{article}

\usepackage{kantlipsum}

%\SetTemplateKeys{block}{display}{
% leftmargin=2cm, % does nothing
% rightmargin=2cm, % this works
% }

\DeclareInstance{block}{list-1}{display}{leftmargin=2cm}

\begin{document}

\kant[1][1-2]
\kant[2][1-2]

\begin{enumerate}%[leftmargin=2cm] % this works
\item abc
\item \kant[1][1-2]
\kant[2][1-2]
\end{enumerate}

\end{document}

[mbertucci47]

@senthilmm Yes that does work, thanks. @FrankMittelbach is it supported behavior to call something like \DeclareInstance{block}{list-1}{display}{leftmargin=2cm} locally to change the behavior of a single environment? Something essentially equivalent to

\begingroup
\DeclareInstance{block}{list-1}{display}{leftmargin=2cm}
\begin{enumerate}
\item abc
\item \kant[1][1-2]
\kant[2][1-2]
\end{enumerate}
\endgroup

[FrankMittelbach]

It works but better would be to use \EditInstance in this case.

@mbertucci47 your use of \SetTemplateKeys is simply wrong and not supported on that point, I didn't realized this initially and looking at the documentation it is clear why you thought it is the right thing to dso. The docu is simply wrong and insufficient (but perhaps we put in some checks to make sure that one gets an error rather than strange behavior).
\SetTemplateKeysoverwrite value in the key structure but since execution of a template/instance also alters the key structure, you get this puzzling behavor: a key that is not explicitly set by the template (either as an explicit value or as a default value) can be altered on top-level, but keys that are set by the template can not (or rather can but wil then be overwritten again).

The real and basically perhaps the only purpose of that command is inside a template after the keys have been assigned, e.g., if an environment offers an optional argument to specify keys that argument is then passed to the \SetTemplateKeys to overwrite what the template normally does, hence \begin{enumerate}[leftmargin=2cm] works.
This is why I said the documentation is wrong and misleading (besides the fact that the example wouldn't work).

[mbertucci47]

@FrankMittelbach Thanks for the explanation, it clarified a lot. I have one followup question. If rightmargin is also changed for list-1, it seems to also affect nested lists. Compare the following examples.

\DocumentMetadata
  {
    lang=en-US,
    pdfversion=2.0,
    pdfstandard=ua-2,
    testphase={phase-III,math,table,title,firstaid}
  }
\documentclass{article}

\usepackage{kantlipsum}

\begin{document}

\begin{enumerate}
\item \kant[1][1-2]
\begin{enumerate}
\item \kant[1][1-2]
\end{enumerate}
\end{enumerate}

\begingroup
\EditInstance{block}{list-1}{leftmargin=2cm,rightmargin=1cm}
\begin{enumerate}
\item \kant[1][1-2]
\begin{enumerate}
\item \kant[1][1-2]
\end{enumerate}
\end{enumerate}
\endgroup

\begingroup
\EditInstance{block}{list-1}{leftmargin=2cm}
\begin{enumerate}
\item \kant[1][1-2]
\begin{enumerate}
\item \kant[1][1-2]
\end{enumerate}
\end{enumerate}
\endgroup

\end{document}

If nothing is specified for rightmargin then the nested list just adapts to the outer list right margin. But if rightmargin is specified, the nested list adds that value to its already adjusted right margin. Is this intended or is the rightmargin value leaking into the nested list incorrectly? I would have thought this is controlled by list-2 which hasn't been changed. And the same effect is not observed with leftmargin.

It's possible this should be a new issue, just let me know and I'll open one.

[FrankMittelbach]

If nothing is specified for rightmargin then the nested list just adapts to the outer list right margin. But if rightmargin is specified, the nested list adds that value to its already adjusted right margin. Is this intended or is the rightmargin value leaking into the nested list incorrectly? I would have thought this is controlled by list-2 which hasn't been changed. And the same effect is not observed with leftmargin.

This is because of the dependencies with the legacy list setting. What happens with lists is the following:
When entering a new nesting level

• the corresponding \@list<level>, e.g., \@listiiis executed
• then the instance values overwrite
• then any local optional argument settings overwrite

Now the defaults in size10.cloand the like have

\def\@listii {\leftmargin\leftmarginii
              \labelwidth\leftmarginii
              \advance\labelwidth-\labelsep
              \topsep    4\p@ \@plus2\p@ \@minus\p@
              \parsep    2\p@ \@plus\p@  \@minus\p@
              \itemsep   \parsep}

So leftmargin is set to \leftmarginii so your value of 2cm isn't any longer active.
However \rightmargin is not touched by the settings and list-2 sets rightmargin=\rightmargin (which means inherit from previous level) so it now remains 1cm-

So to prevent that you would need to specify rightmargin=0pt on list-2 as well.

Same would happen in standard 2e right now if one adds a value into \@listi without also adjusting \@listii etc.

This certainly needs a good documentation and going forward I hope we will see classes not using \@listibut just the instance setups and then things become more sane for changing. Another adjustment that I'm contemplating is a key that allows you to supress the use of \@listi and friends so that all values only depend on what is specified on the instances.

[mbertucci47]

@FrankMittelbach Again, thanks for the detailed explanation. To me that procedure is counterintuitive; I wonder why lists were set up that way (I guess by Leslie Lamport?). I was especially surprised because as I mentioned, I'm trying to implement margin-changing for tagged theorems and the problem is still there when you replace list-1 with theoremblock-0 and have a list inside a theorem. Of course, you already said the new theorem code still uses the list parameters so I should have known better.

[FrankMittelbach]

@mbertucci47 can you explain in a bit more detail what you try to achieve? Eg with an example of intended output?
This clearly goes beyond the initial issue, but we might well continue here I think.